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