docs/latex/wx/textfile.tex

   1 \section{\class{wxTextFile}}\label{wxtextfile}
   2
   3 The wxTextFile is a simple class which allows to work with text files on line by
   4 line basis. It also understands the differences in line termination characters
   5 under different platforms and will not do anything bad to files with "non
   6 native" line termination sequences - in fact, it can be also used to modify the
   7 text files and change the line termination characters from one type (say DOS) to
   8 another (say Unix).
   9
  10 One word of warning: the class is not at all optimized for big files and so it
  11 will load the file entirely into memory when opened. Of course, you should not
  12 work in this way with large files (as an estimation, anything over 1 Megabyte is
  13 surely too big for this class). On the other hand, it is not a serious
  14 limitation for the small files like configuration files or programs sources
  15 which are well handled by wxTextFile.
  16
  17 The typical things you may do with wxTextFile in order are:
  18
  19 \begin{itemize}\itemsep=0pt
  20 \item Create and open it: this is done with \helpref{Open}{wxtextfileopen}
  21 function which opens the file (name may be specified either as Open argument or
  22 in the constructor), reads its contents in memory and closes it. If all of these
  23 operations are successful, Open() will return TRUE and FALSE on error.
  24 \item Work with the lines in the file: this may be done either with "direct
  25 access" functions like \helpref{GetLineCount}{wxtextfilegetlinecount} and
  26 \helpref{GetLine}{wxtextfilegetline} ({\it operator[]} does exactly the same
  27 but looks more like array addressing) or with "sequential access" functions
  28 which include \helpref{GetFirstLine}{wxtextfilegetfirstline}/
  29 \helpref{GetNextLine}{wxtextfilegetnextline} and also
  30 \helpref{GetLastLine}{wxtextfilegetlastline}/\helpref{GetPrevLine}{wxtextfilegetprevline}.
  31 For the sequential access functions the current line number is maintained: it is
  32 returned by \helpref{GetCurrentLine}{wxtextfilegetcurrentline} and may be
  33 changed with \helpref{GoToLine}{wxtextfilegotoline}.
  34 \item Add/remove lines to the file: \helpref{AddLine}{wxtextfileaddline} and
  35 \helpref{InsertLine}{wxtextfileinsertline} add new lines while
  36 \helpref{RemoveLine}{wxtextfileremoveline} deletes the existing ones.
  37 \item Save your changes: notice that the changes you make to the file will {\bf
  38 not} be saved automatically; calling \helpref{Close}{wxtextfileclose} or doing
  39 nothing discards them! To save the changes you must explicitly call
  40 \helpref{Write}{wxtextfilewrite} - here, you may also change the line
  41 termination type if you wish.
  42 \end{itemize}
  43
  44 \wxheading{Derived from}
  45
  46 No base class
  47
  48 \wxheading{Data structures}
  49
  50 The following constants identify the line termination type:
  51 \begin{verbatim}
  52 enum wxTextFileType
  53 {
  54     wxTextFileType_None,  // incomplete (the last line of the file only)
  55     wxTextFileType_Unix,  // line is terminated with 'LF' = 0xA = 10 = '\n'
  56     wxTextFileType_Dos,   //                         'CR' 'LF'
  57     wxTextFileType_Mac    //                         'CR' = 0xD = 13 = '\r'
  58 };
  59 \end{verbatim}
  60
  61 \wxheading{See also}
  62
  63 \helpref{wxFile}{wxfile}
  64
  65 \latexignore{\rtfignore{\wxheading{Members}}}
  66
  67 \membersection{wxTextFile::wxTextFile}\label{wxtextfilectordef}
  68
  69 \constfunc{}{wxTextFile}{\void}
  70
  71 Default constructor, use Open(string) to initialize the object.
  72
  73 \membersection{wxTextFile::wxTextFile}\label{wxtextfilector}
  74
  75 \constfunc{}{wxTextFile}{\param{const wxString\& }{strFile}}
  76
  77 Constructor does not load the file into memory, use Open() to do it.
  78
  79 \membersection{wxTextFile::Exists}\label{wxtextfileexists}
  80
  81 \constfunc{bool}{Exists}{\void}
  82
  83 Return TRUE if file exists - the name of the file should have been specified
  84 in the constructor before calling Exists().
  85
  86 \membersection{wxTextFile::Open}\label{wxtextfileopen}
  87
  88 \constfunc{bool}{Open}{\void}
  89
  90 Open() opens the file with the name which was given in the \helpref{constructor}{wxtextfilector}
  91 and also loads file in memory on success.
  92
  93 \membersection{wxTextFile::Open}\label{wxtextfileopenname}
  94
  95 \constfunc{bool}{Open}{\param{const wxString\& }{strFile}}
  96
  97 Same as \helpref{Open()}{wxtextfileopen} but allows to specify the file name
  98 (must be used if the default constructor was used to create the object).
  99
 100 \membersection{wxTextFile::Close}\label{wxtextfileclose}
 101
 102 \constfunc{bool}{Close}{\void}
 103
 104 Closes the file and frees memory, {\bf losing all changes}. Use \helpref{Write()}{wxtextfilewrite}
 105 if you want to save them.
 106
 107 \membersection{wxTextFile::IsOpened}\label{wxtextfileisopened}
 108
 109 \constfunc{bool}{IsOpened}{\void}
 110
 111 Returns TRUE if the file is currently opened.
 112
 113 \membersection{wxTextFile::GetLineCount}\label{wxtextfilegetlinecount}
 114
 115 \constfunc{size\_t}{GetLineCount}{\void}
 116
 117 Get the number of lines in the file.
 118
 119 \membersection{wxTextFile::GetLine}\label{wxtextfilegetline}
 120
 121 \constfunc{wxString\&}{GetLine}{\param{size\_t }{n}}
 122
 123 Retrieves the line number {\it n} from the file. The returned line may be
 124 modified but you shouldn't add line terminator at the end - this will be done
 125 by wxTextFile.
 126
 127 \membersection{wxTextFile::operator[]}\label{wxtextfileoperatorarray}
 128
 129 \constfunc{wxString\&}{operator[]}{\param{size\_t }{n}}
 130
 131 The same as \helpref{GetLine}{wxtextfilegetline}.
 132
 133 \membersection{wxTextFile::GetCurrentLine}\label{wxtextfilegetcurrentline}
 134
 135 \constfunc{size\_t}{GetCurrentLine}{\void}
 136
 137 Returns the current line: it has meaning only when you're using
 138 GetFirstLine()/GetNextLine() functions, it doesn't get updated when
 139 you're using "direct access" functions like GetLine(). GetFirstLine() and
 140 GetLastLine() also change the value of the current line, as well as
 141 GoToLine().
 142
 143 \membersection{wxTextFile::GoToLine}\label{wxtextfilegotoline}
 144
 145 \constfunc{void}{GoToLine}{\param{size\_t }{n}}
 146
 147 Changes the value returned by \helpref{GetCurrentLine}{wxtextfilegetcurrentline}
 148 and used by \helpref{GetFirstLine()}{wxtextfilegetfirstline}/\helpref{GetNextLine()}{wxtextfilegetnextline}.
 149
 150 \membersection{wxTextFile::Eof}\label{wxtextfileeof}
 151
 152 \constfunc{bool}{Eof}{\void}
 153
 154 Returns TRUE if the current line is the last one.
 155
 156 \membersection{wxTextFile::GetFirstLine}\label{wxtextfilegetfirstline}
 157
 158 \constfunc{wxString\&}{GetFirstLine}{\void}
 159
 160 This method together with \helpref{GetNextLine()}{wxtextfilegetnextline}
 161 allows more "iterator-like" traversal of the list of lines, i.e. you may
 162 write something like:
 163
 164 \begin{verbatim}
 165 for ( str = GetFirstLine(); !Eof(); str = GetNextLine() )
 166 {
 167     // do something with the current line in str
 168 }
 169 \end{verbatim}
 170
 171 \membersection{wxTextFile::GetNextLine}\label{wxtextfilegetnextline}
 172
 173 \func{wxString\&}{GetNextLine}{\void}
 174
 175 Gets the next line (see \helpref{GetFirstLine}{wxtextfilegetfirstline} for
 176 the example).
 177
 178 \membersection{wxTextFile::GetPrevLine}\label{wxtextfilegetprevline}
 179
 180 \func{wxString\&}{GetPrevLine}{\void}
 181
 182 Gets the previous line in the file.
 183
 184 \membersection{wxTextFile::GetLastLine}\label{wxtextfilegetlastline}
 185
 186 \func{wxString\&}{GetLastLine}{\void}
 187
 188 Gets the last line of the file.
 189
 190 \membersection{wxTextFile::GetLineType}\label{wxtextfilegetlinetype}
 191
 192 \constfunc{wxTextFileType}{GetLineType}{\param{size\_t }{n}}
 193
 194 Get the type of the line (see also \helpref{GetEOL}{wxtextfilegeteol})
 195
 196 \membersection{wxTextFile::GuessType}\label{wxtextfileguesstype}
 197
 198 \constfunc{wxTextFileType}{GuessType}{\void}
 199
 200 Guess the type of file (which is supposed to be opened). If sufficiently
 201 many lines of the file are in DOS/Unix/Mac format, the corresponding value will
 202 be returned. If the detection mechanism fails wxTextFileType\_None is returned.
 203
 204 \membersection{wxTextFile::GetName}\label{wxtextfilegetname}
 205
 206 \constfunc{const char*}{GetName}{\void}
 207
 208 Get the name of the file.
 209
 210 \membersection{wxTextFile::AddLine}\label{wxtextfileaddline}
 211
 212 \constfunc{void}{AddLine}{\param{const wxString\& }{str}, \param{wxTextFileType }{type = typeDefault}}
 213
 214 Adds a line to the end of file.
 215
 216 \membersection{wxTextFile::InsertLine}\label{wxtextfileinsertline}
 217
 218 \constfunc{void}{InsertLine}{\param{const wxString\& }{str}, \param{size\_t }{n}, \param{wxTextFileType }{type = typeDefault}}
 219
 220 Insert a line before the line number {\it n}.
 221
 222 \membersection{wxTextFile::RemoveLine}\label{wxtextfileremoveline}
 223
 224 \constfunc{void}{RemoveLine}{\param{size\_t }{n}}
 225
 226 Delete line number {\it n} from the file.
 227
 228 \membersection{wxTextFile::Write}\label{wxtextfilewrite}
 229
 230 \constfunc{bool}{Write}{\param{wxTextFileType }{typeNew = wxTextFileType\_None}}
 231
 232 Change the file on disk. The {\it typeNew} parameter allows you to change the
 233 file format (default argument means "don't change type") and may be used to
 234 convert, for example, DOS files to Unix.
 235
 236 Returns TRUE if operation succeeded, FALSE if it failed.
 237
 238 \membersection{wxTextFile::GetEOL}\label{wxtextfilegeteol}
 239
 240 \constfunc{static const char*}{GetEOL}{\param{wxTextFileType }{type = typeDefault}}
 241
 242 Get the line termination string corresponding to given constant. {\it typeDefault} is
 243 the value defined during the compilation and corresponds to the native format of the
 244 platform, i.e. it will be wxTextFileType\_Dos under Windows, wxTextFileType\_Unix under
 245 Unix and wxTextFileType\_Mac under Mac.
 246
 247 \membersection{wxTextFile::\destruct{wxTextFile}}\label{wxtextfiledtor}
 248
 249 \constfunc{}{\destruct{wxTextFile}}{\void}
 250
 251 Destructor does nothing.
 252