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 thus
  11 it 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 small files like configuration files or program 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 either
  21 \helpref{Create}{wxtextfilecreate} or \helpref{Open}{wxtextfileopen}
  22 function which opens the file (name may be specified either as the argument to
  23 these functions or in the constructor), reads its contents in memory (in the
  24 case of {\tt Open()}) and closes it.
  25 \item Work with the lines in the file: this may be done either with "direct
  26 access" functions like \helpref{GetLineCount}{wxtextfilegetlinecount} and
  27 \helpref{GetLine}{wxtextfilegetline} ({\it operator[]} does exactly the same
  28 but looks more like array addressing) or with "sequential access" functions
  29 which include \helpref{GetFirstLine}{wxtextfilegetfirstline}/
  30 \helpref{GetNextLine}{wxtextfilegetnextline} and also
  31 \helpref{GetLastLine}{wxtextfilegetlastline}/\helpref{GetPrevLine}{wxtextfilegetprevline}.
  32 For the sequential access functions the current line number is maintained: it is
  33 returned by \helpref{GetCurrentLine}{wxtextfilegetcurrentline} and may be
  34 changed with \helpref{GoToLine}{wxtextfilegotoline}.
  35 \item Add/remove lines to the file: \helpref{AddLine}{wxtextfileaddline} and
  36 \helpref{InsertLine}{wxtextfileinsertline} add new lines while
  37 \helpref{RemoveLine}{wxtextfileremoveline} deletes the existing ones.
  38 \helpref{Clear}{wxtextfileclear} resets the file to empty.
  39 \item Save your changes: notice that the changes you make to the file will {\bf
  40 not} be saved automatically; calling \helpref{Close}{wxtextfileclose} or doing
  41 nothing discards them! To save the changes you must explicitly call
  42 \helpref{Write}{wxtextfilewrite} - here, you may also change the line
  43 termination type if you wish.
  44 \end{itemize}
  45
  46 \wxheading{Derived from}
  47
  48 No base class
  49
  50 \wxheading{Include files}
  51
  52 <wx/textfile.h>
  53
  54 \wxheading{Library}
  55
  56 \helpref{wxBase}{librarieslist}
  57
  58 \wxheading{Data structures}
  59
  60 The following constants identify the line termination type:
  61
  62 \begin{verbatim}
  63 enum wxTextFileType
  64 {
  65     wxTextFileType_None,  // incomplete (the last line of the file only)
  66     wxTextFileType_Unix,  // line is terminated with 'LF' = 0xA = 10 = '\n'
  67     wxTextFileType_Dos,   //                         'CR' 'LF'
  68     wxTextFileType_Mac    //                         'CR' = 0xD = 13 = '\r'
  69 };
  70 \end{verbatim}
  71
  72 \wxheading{See also}
  73
  74 \helpref{wxFile}{wxfile}
  75
  76 \latexignore{\rtfignore{\wxheading{Members}}}
  77
  78 \membersection{wxTextFile::wxTextFile}\label{wxtextfilectordef}
  79
  80 \constfunc{}{wxTextFile}{\void}
  81
  82 Default constructor, use \helpref{Create}{wxtextfilecreate} or
  83 \helpref{Open}{wxtextfileopen} with a file name parameter to initialize the object.
  84
  85 \membersection{wxTextFile::wxTextFile}\label{wxtextfilector}
  86
  87 \constfunc{}{wxTextFile}{\param{const wxString\& }{strFile}}
  88
  89 Constructor does not load the file into memory, use Open() to do it.
  90
  91 \membersection{wxTextFile::\destruct{wxTextFile}}\label{wxtextfiledtor}
  92
  93 \constfunc{}{\destruct{wxTextFile}}{\void}
  94
  95 Destructor does nothing.
  96
  97 \membersection{wxTextFile::AddLine}\label{wxtextfileaddline}
  98
  99 \constfunc{void}{AddLine}{\param{const wxString\& }{str}, \param{wxTextFileType }{type = typeDefault}}
 100
 101 Adds a line to the end of file.
 102
 103 \membersection{wxTextFile::Close}\label{wxtextfileclose}
 104
 105 \constfunc{bool}{Close}{\void}
 106
 107 Closes the file and frees memory, {\bf losing all changes}. Use \helpref{Write()}{wxtextfilewrite}
 108 if you want to save them.
 109
 110 \membersection{wxTextFile::Create}\label{wxtextfilecreate}
 111
 112 \constfunc{bool}{Create}{\void}
 113
 114 \constfunc{bool}{Create}{\param{const wxString\& }{strFile}}
 115
 116 Creates the file with the given name or the name which was given in the
 117 \helpref{constructor}{wxtextfilector}. The array of file lines is initially
 118 empty.
 119
 120 It will fail if the file already exists, \helpref{Open}{wxtextfileopen} should
 121 be used in this case.
 122
 123 \membersection{wxTextFile::Exists}\label{wxtextfileexists}
 124
 125 \constfunc{bool}{Exists}{\void}
 126
 127 Return true if file exists - the name of the file should have been specified
 128 in the constructor before calling Exists().
 129
 130 \membersection{wxTextFile::IsOpened}\label{wxtextfileisopened}
 131
 132 \constfunc{bool}{IsOpened}{\void}
 133
 134 Returns true if the file is currently opened.
 135
 136 \membersection{wxTextFile::GetLineCount}\label{wxtextfilegetlinecount}
 137
 138 \constfunc{size\_t}{GetLineCount}{\void}
 139
 140 Get the number of lines in the file.
 141
 142 \membersection{wxTextFile::GetLine}\label{wxtextfilegetline}
 143
 144 \constfunc{wxString\&}{GetLine}{\param{size\_t }{n}}
 145
 146 Retrieves the line number {\it n} from the file. The returned line may be
 147 modified but you shouldn't add line terminator at the end - this will be done
 148 by wxTextFile.
 149
 150 \membersection{wxTextFile::operator[]}\label{wxtextfileoperatorarray}
 151
 152 \constfunc{wxString\&}{operator[]}{\param{size\_t }{n}}
 153
 154 The same as \helpref{GetLine}{wxtextfilegetline}.
 155
 156 \membersection{wxTextFile::GetCurrentLine}\label{wxtextfilegetcurrentline}
 157
 158 \constfunc{size\_t}{GetCurrentLine}{\void}
 159
 160 Returns the current line: it has meaning only when you're using
 161 GetFirstLine()/GetNextLine() functions, it doesn't get updated when
 162 you're using "direct access" functions like GetLine(). GetFirstLine() and
 163 GetLastLine() also change the value of the current line, as well as
 164 GoToLine().
 165
 166 \membersection{wxTextFile::GoToLine}\label{wxtextfilegotoline}
 167
 168 \constfunc{void}{GoToLine}{\param{size\_t }{n}}
 169
 170 Changes the value returned by \helpref{GetCurrentLine}{wxtextfilegetcurrentline}
 171 and used by \helpref{GetFirstLine()}{wxtextfilegetfirstline}/\helpref{GetNextLine()}{wxtextfilegetnextline}.
 172
 173 \membersection{wxTextFile::Eof}\label{wxtextfileeof}
 174
 175 \constfunc{bool}{Eof}{\void}
 176
 177 Returns true if the current line is the last one.
 178
 179 \membersection{wxTextFile::GetEOL}\label{wxtextfilegeteol}
 180
 181 \constfunc{static const char*}{GetEOL}{\param{wxTextFileType }{type = typeDefault}}
 182
 183 Get the line termination string corresponding to given constant. {\it typeDefault} is
 184 the value defined during the compilation and corresponds to the native format
 185 of the platform, i.e. it will be wxTextFileType\_Dos under Windows,
 186 wxTextFileType\_Unix under Unix (including Mac OS X when compiling with the
 187 Apple Developer Tools) and wxTextFileType\_Mac under Mac OS (including
 188 Mac OS X when compiling with CodeWarrior).
 189
 190 \membersection{wxTextFile::GetFirstLine}\label{wxtextfilegetfirstline}
 191
 192 \constfunc{wxString\&}{GetFirstLine}{\void}
 193
 194 This method together with \helpref{GetNextLine()}{wxtextfilegetnextline}
 195 allows more "iterator-like" traversal of the list of lines, i.e. you may
 196 write something like:
 197
 198 \begin{verbatim}
 199 wxTextFile file;
 200 ...
 201 for ( str = file.GetFirstLine(); !file.Eof(); str = file.GetNextLine() )
 202 {
 203     // do something with the current line in str
 204 }
 205 // do something with the last line in str
 206 \end{verbatim}
 207
 208 \membersection{wxTextFile::GetNextLine}\label{wxtextfilegetnextline}
 209
 210 \func{wxString\&}{GetNextLine}{\void}
 211
 212 Gets the next line (see \helpref{GetFirstLine}{wxtextfilegetfirstline} for
 213 the example).
 214
 215 \membersection{wxTextFile::GetPrevLine}\label{wxtextfilegetprevline}
 216
 217 \func{wxString\&}{GetPrevLine}{\void}
 218
 219 Gets the previous line in the file.
 220
 221 \membersection{wxTextFile::GetLastLine}\label{wxtextfilegetlastline}
 222
 223 \func{wxString\&}{GetLastLine}{\void}
 224
 225 Gets the last line of the file. Together with
 226 \helpref{GetPrevLine}{wxtextfilegetprevline} it allows to enumerate the lines
 227 in the file from the end to the beginning like this:
 228
 229 \begin{verbatim}
 230 wxTextFile file;
 231 ...
 232 for ( str = file.GetLastLine();
 233       file.GetCurrentLine() > 0;
 234       str = file.GetPrevLine() )
 235 {
 236     // do something with the current line in str
 237 }
 238 // do something with the first line in str
 239 \end{verbatim}
 240
 241 \membersection{wxTextFile::GetLineType}\label{wxtextfilegetlinetype}
 242
 243 \constfunc{wxTextFileType}{GetLineType}{\param{size\_t }{n}}
 244
 245 Get the type of the line (see also \helpref{GetEOL}{wxtextfilegeteol})
 246
 247 \membersection{wxTextFile::GuessType}\label{wxtextfileguesstype}
 248
 249 \constfunc{wxTextFileType}{GuessType}{\void}
 250
 251 Guess the type of file (which is supposed to be opened). If sufficiently
 252 many lines of the file are in DOS/Unix/Mac format, the corresponding value will
 253 be returned. If the detection mechanism fails wxTextFileType\_None is returned.
 254
 255 \membersection{wxTextFile::GetName}\label{wxtextfilegetname}
 256
 257 \constfunc{const char*}{GetName}{\void}
 258
 259 Get the name of the file.
 260
 261 \membersection{wxTextFile::InsertLine}\label{wxtextfileinsertline}
 262
 263 \constfunc{void}{InsertLine}{\param{const wxString\& }{str}, \param{size\_t }{n}, \param{wxTextFileType }{type = typeDefault}}
 264
 265 Insert a line before the line number {\it n}.
 266
 267 \membersection{wxTextFile::Open}\label{wxtextfileopen}
 268
 269 \constfunc{bool}{Open}{\param{const wxMBConv\&}{ conv = wxConvAuto()}}
 270
 271 \constfunc{bool}{Open}{\param{const wxString\& }{strFile}, \param{const wxMBConv\&}{ conv = wxConvAuto()}}
 272
 273 Open() opens the file with the given name or the name which was given in the
 274 \helpref{constructor}{wxtextfilector} and also loads file in memory on
 275 success. It will fail if the file does not exist,
 276 \helpref{Create}{wxtextfilecreate} should be used in this case.
 277
 278 The {\it conv} argument is only meaningful in Unicode build of wxWidgets when
 279 it is used to convert the file to wide character representation.
 280
 281 \membersection{wxTextFile::RemoveLine}\label{wxtextfileremoveline}
 282
 283 \constfunc{void}{RemoveLine}{\param{size\_t }{n}}
 284
 285 Delete line number {\it n} from the file.
 286
 287 \membersection{wxTextFile::Clear}\label{wxtextfileclear}
 288
 289 \constfunc{void}{Clear}{\void}
 290
 291 Delete all lines from the file, set current line number to 0.
 292
 293 \membersection{wxTextFile::Write}\label{wxtextfilewrite}
 294
 295 \constfunc{bool}{Write}{\param{wxTextFileType }{typeNew = wxTextFileType\_None}, \param{const wxMBConv\&}{ conv = wxConvAuto()}}
 296
 297 Change the file on disk. The {\it typeNew} parameter allows you to change the
 298 file format (default argument means "don't change type") and may be used to
 299 convert, for example, DOS files to Unix.
 300
 301 The {\it conv} argument is only meaningful in Unicode build of wxWidgets when
 302 it is used to convert all lines to multibyte representation before writing them
 303 them to physical file.
 304
 305 Returns true if operation succeeded, false if it failed.
 306