X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/b2cf617cb8160a92696f1421675963aa00cb0c2b..9379c0d752144826342fa2688a77aa5cccea3d9b:/docs/latex/wx/textfile.tex diff --git a/docs/latex/wx/textfile.tex b/docs/latex/wx/textfile.tex index fb612de7da..c139c6262a 100644 --- a/docs/latex/wx/textfile.tex +++ b/docs/latex/wx/textfile.tex @@ -7,20 +7,21 @@ native" line termination sequences - in fact, it can be also used to modify the 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 \helpref{GetLine}{wxtextfilegetline} ({\it operator[]} does exactly the same @@ -34,6 +35,7 @@ changed with \helpref{GoToLine}{wxtextfilegotoline}. \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. +\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 @@ -73,7 +75,8 @@ 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} @@ -81,26 +84,17 @@ Default constructor, use Open(string) to initialize the object. 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} @@ -109,11 +103,31 @@ Same as \helpref{Open()}{wxtextfileopen} but allows to specify the file name 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} @@ -156,7 +170,18 @@ and used by \helpref{GetFirstLine()}{wxtextfilegetfirstline}/\helpref{GetNextLin \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} @@ -167,10 +192,13 @@ allows more "iterator-like" traversal of the list of lines, i.e. you may 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} @@ -190,7 +218,21 @@ Gets the previous line in the file. \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} @@ -212,46 +254,49 @@ be returned. If the detection mechanism fails wxTextFileType\_None is returned. 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 line number {\it n} from the file. +\membersection{wxTextFile::Clear}\label{wxtextfileclear} + +\constfunc{void}{Clear}{\void} + +Delete all lines from the file, set current line number to 0. + \membersection{wxTextFile::Write}\label{wxtextfilewrite} -\constfunc{bool}{Write}{\param{wxTextFileType }{typeNew = wxTextFileType\_None}} +\constfunc{bool}{Write}{\param{wxTextFileType }{typeNew = wxTextFileType\_None}, \param{wxMBConv\&}{ conv = wxConvUTF8}} 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. -Returns TRUE if operation succeeded, FALSE if it failed. - -\membersection{wxTextFile::GetEOL}\label{wxtextfilegeteol} - -\constfunc{static const char*}{GetEOL}{\param{wxTextFileType }{type = typeDefault}} +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. -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. - -\membersection{wxTextFile::\destruct{wxTextFile}}\label{wxtextfiledtor} - -\constfunc{}{\destruct{wxTextFile}}{\void} - -Destructor does nothing. +Returns true if operation succeeded, false if it failed.