line basis. It also understands the differences in line termination characters
under different platforms and will not do anything bad to files with "non
native" line termination sequences - in fact, it can be also used to modify the
-text files and chaneg the line termination characters from one type (say DOS) to
+text files and change the line termination characters from one type (say DOS) to
another (say Unix).
-One word of warning: the class is not at all optimized for big files and so it
-will load the file entirely into memory when opened. Of course, you should not
+One word of warning: the class is not at all optimized for big files and thus
+it will load the file entirely into memory when opened. Of course, you should not
work in this way with large files (as an estimation, anything over 1 Megabyte is
surely too big for this class). On the other hand, it is not a serious
-limitation for the small files like configuration files or programs sources
+limitation for small files like configuration files or program sources
which are well handled by wxTextFile.
The typical things you may do with wxTextFile in order are:
\begin{itemize}\itemsep=0pt
-\item Create and open it: this is done with \helpref{Open}{wxtextfileopen}
-function which opens the file (name may be specified either as Open argument or
-in the constructor), reads its contents in memory and closes it. If all of these
-operations are successful, Open() will return TRUE and FALSE on error.
+\item Create and open it: this is done with either
+\helpref{Create}{wxtextfilecreate} or \helpref{Open}{wxtextfileopen}
+function which opens the file (name may be specified either as the argument to
+these functions or in the constructor), reads its contents in memory (in the
+case of {\tt Open()}) and closes it.
\item Work with the lines in the file: this may be done either with "direct
-access" functions like \helpref{GetLineCount}{wxtextfilegetlinecount} and
+access" functions like \helpref{GetLineCount}{wxtextfilegetlinecount} and
\helpref{GetLine}{wxtextfilegetline} ({\it operator[]} does exactly the same
but looks more like array addressing) or with "sequential access" functions
which include \helpref{GetFirstLine}{wxtextfilegetfirstline}/
\item Add/remove lines to the file: \helpref{AddLine}{wxtextfileaddline} and
\helpref{InsertLine}{wxtextfileinsertline} add new lines while
\helpref{RemoveLine}{wxtextfileremoveline} deletes the existing ones.
-\item Save your changes: notice that the changes you do to the file will {\bf
-not} be saved automatically, calling \helpref{Close}{wxtextfileclose} or doing
-nothing discards them! To save the chanegs you must explicitly call
+\helpref{Clear}{wxtextfileclear} resets the file to empty.
+\item Save your changes: notice that the changes you make to the file will {\bf
+not} be saved automatically; calling \helpref{Close}{wxtextfileclose} or doing
+nothing discards them! To save the changes you must explicitly call
\helpref{Write}{wxtextfilewrite} - here, you may also change the line
termination type if you wish.
\end{itemize}
No base class
+\wxheading{Include files}
+
+<wx/textfile.h>
+
\wxheading{Data structures}
The following constants identify the line termination type:
+
\begin{verbatim}
enum wxTextFileType
{
\constfunc{}{wxTextFile}{\void}
-Default constructor, use Open(string) to initialize the object.
+Default constructor, use \helpref{Create}{wxtextfilecreate} or
+\helpref{Open}{wxtextfileopen} with a file name parameter to initialize the object.
\membersection{wxTextFile::wxTextFile}\label{wxtextfilector}
Constructor does not load the file into memory, use Open() to do it.
-\membersection{wxTextFile::Exists}\label{wxtextfileexists}
-
-\constfunc{bool}{Exists}{\void}
-
-Return TRUE if file exists - the name of the file should have been specified
-in the constructor before calling Exists().
-
-\membersection{wxTextFile::Open}\label{wxtextfileopen}
+\membersection{wxTextFile::\destruct{wxTextFile}}\label{wxtextfiledtor}
-\constfunc{bool}{Open}{\void}
+\constfunc{}{\destruct{wxTextFile}}{\void}
-Open() opens the file with the name which was given in the \helpref{constructor}{wxtextfilector}
-and also loads file in memory on success.
+Destructor does nothing.
-\membersection{wxTextFile::Open}\label{wxtextfileopenname}
+\membersection{wxTextFile::AddLine}\label{wxtextfileaddline}
-\constfunc{bool}{Open}{\param{const wxString\& }{strFile}}
+\constfunc{void}{AddLine}{\param{const wxString\& }{str}, \param{wxTextFileType }{type = typeDefault}}
-Same as \helpref{Open()}{wxtextfileopen} but allows to specify the file name
-(must be used if the default constructor was used to create the object).
+Adds a line to the end of file.
\membersection{wxTextFile::Close}\label{wxtextfileclose}
Closes the file and frees memory, {\bf losing all changes}. Use \helpref{Write()}{wxtextfilewrite}
if you want to save them.
+\membersection{wxTextFile::Create}\label{wxtextfilecreate}
+
+\constfunc{bool}{Create}{\void}
+
+\constfunc{bool}{Create}{\param{const wxString\& }{strFile}}
+
+Creates the file with the given name or the name which was given in the
+\helpref{constructor}{wxtextfilector}. The array of file lines is initially
+empty.
+
+It will fail if the file already exists, \helpref{Open}{wxtextfileopen} should
+be used in this case.
+
+\membersection{wxTextFile::Exists}\label{wxtextfileexists}
+
+\constfunc{bool}{Exists}{\void}
+
+Return true if file exists - the name of the file should have been specified
+in the constructor before calling Exists().
+
\membersection{wxTextFile::IsOpened}\label{wxtextfileisopened}
\constfunc{bool}{IsOpened}{\void}
-Returns TRUE if the file is currently opened.
+Returns true if the file is currently opened.
\membersection{wxTextFile::GetLineCount}\label{wxtextfilegetlinecount}
\constfunc{void}{GoToLine}{\param{size\_t }{n}}
Changes the value returned by \helpref{GetCurrentLine}{wxtextfilegetcurrentline}
-and used by \helpref{GetFirstLine()}{wxtextfilegetfirstline}()/\helpref{GetNextLine()}{wxtextfilegetnextline}.
+and used by \helpref{GetFirstLine()}{wxtextfilegetfirstline}/\helpref{GetNextLine()}{wxtextfilegetnextline}.
\membersection{wxTextFile::Eof}\label{wxtextfileeof}
\constfunc{bool}{Eof}{\void}
-Returns TRUE if the current line is the last one.
+Returns true if the current line is the last one.
+
+\membersection{wxTextFile::GetEOL}\label{wxtextfilegeteol}
+
+\constfunc{static const char*}{GetEOL}{\param{wxTextFileType }{type = typeDefault}}
+
+Get the line termination string corresponding to given constant. {\it typeDefault} is
+the value defined during the compilation and corresponds to the native format
+of the platform, i.e. it will be wxTextFileType\_Dos under Windows,
+wxTextFileType\_Unix under Unix (including Mac OS X when compiling with the
+Apple Developer Tools) and wxTextFileType\_Mac under Mac OS (including
+Mac OS X when compiling with CodeWarrior).
\membersection{wxTextFile::GetFirstLine}\label{wxtextfilegetfirstline}
write something like:
\begin{verbatim}
-for ( str = GetFirstLine(); !Eof(); str = GetNextLine() )
+wxTextFile file;
+...
+for ( str = file.GetFirstLine(); !file.Eof(); str = file.GetNextLine() )
{
// do something with the current line in str
}
+// do something with the last line in str
\end{verbatim}
\membersection{wxTextFile::GetNextLine}\label{wxtextfilegetnextline}
\func{wxString\&}{GetLastLine}{\void}
-Gets the last line of the file.
+Gets the last line of the file. Together with
+\helpref{GetPrevLine}{wxtextfilegetprevline} it allows to enumerate the lines
+in the file from the end to the beginning like this:
+
+\begin{verbatim}
+wxTextFile file;
+...
+for ( str = file.GetLastLine();
+ file.GetCurrentLine() > 0;
+ str = file.GetPrevLine() )
+{
+ // do something with the current line in str
+}
+// do something with the first line in str
+\end{verbatim}
\membersection{wxTextFile::GetLineType}\label{wxtextfilegetlinetype}
Get the name of the file.
-\membersection{wxTextFile::AddLine}\label{wxtextfileaddline}
-
-\constfunc{void}{AddLine}{\param{const wxString\& }{str}, \param{wxTextFileType }{type = typeDefault}}
-
-Adds a line to the end of file.
-
\membersection{wxTextFile::InsertLine}\label{wxtextfileinsertline}
\constfunc{void}{InsertLine}{\param{const wxString\& }{str}, \param{size\_t }{n}, \param{wxTextFileType }{type = typeDefault}}
Insert a line before the line number {\it n}.
+\membersection{wxTextFile::Open}\label{wxtextfileopen}
+
+\constfunc{bool}{Open}{\param{wxMBConv\&}{ conv = wxConvUTF8}}
+
+\constfunc{bool}{Open}{\param{const wxString\& }{strFile}, \param{wxMBConv\&}{ conv = wxConvUTF8}}
+
+Open() opens the file with the given name or the name which was given in the
+\helpref{constructor}{wxtextfilector} and also loads file in memory on
+success. It will fail if the file does not exist,
+\helpref{Create}{wxtextfilecreate} should be used in this case.
+
+The {\it conv} argument is only meaningful in Unicode build of wxWidgets when
+it is used to convert the file to wide character representation.
+
\membersection{wxTextFile::RemoveLine}\label{wxtextfileremoveline}
\constfunc{void}{RemoveLine}{\param{size\_t }{n}}
-Delete one line from the file.
-
-\membersection{wxTextFile::Write}\label{wxtextfilewrite}
+Delete line number {\it n} from the file.
-\constfunc{bool}{Write}{\param{wxTextFileType }{typeNew = wxTextFileType\_None}}
+\membersection{wxTextFile::Clear}\label{wxtextfileclear}
-Change the file on disk. The {\it typeNew} parameter allows to change the
-file format (default argument means "don't change type") and may be used to
-convert, for example, DOS files to Unix.
+\constfunc{void}{Clear}{\void}
-\membersection{wxTextFile::GetEOL}\label{wxtextfilegeteol}
+Delete all lines from the file, set current line number to 0.
-\constfunc{static const char*}{GetEOL}{\param{wxTextFileType }{type = typeDefault}}
+\membersection{wxTextFile::Write}\label{wxtextfilewrite}
-Get the line termination string corresponding to given constant. {\it typeDefault} is
-the value defined during the compilation and corresponds to the native format of the
-platform, i.e. it will be wxTextFileType\_Dos under Windows, wxTextFileType\_Unix under
-Unix and wxTextFileType\_Mac under Mac.
+\constfunc{bool}{Write}{\param{wxTextFileType }{typeNew = wxTextFileType\_None}, \param{wxMBConv\&}{ conv = wxConvUTF8}}
-\membersection{wxTextFile::\destruct{wxTextFile}}\label{wxtextfiledtor}
+Change the file on disk. The {\it typeNew} parameter allows you to change the
+file format (default argument means "don't change type") and may be used to
+convert, for example, DOS files to Unix.
-\constfunc{}{\destruct{wxTextFile}}{\void}
+The {\it conv} argument is only meaningful in Unicode build of wxWidgets when
+it is used to convert all lines to multibyte representation before writing them
+them to physical file.
-Destructor does nothing.
+Returns true if operation succeeded, false if it failed.
projects / wxWidgets.git / blobdiff