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