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 of the
 180 platform, i.e. it will be wxTextFileType\_Dos under Windows, wxTextFileType\_Unix under
 181 Unix and wxTextFileType\_Mac under Mac.
 182
 183 \membersection{wxTextFile::GetFirstLine}\label{wxtextfilegetfirstline}
 184
 185 \constfunc{wxString\&}{GetFirstLine}{\void}
 186
 187 This method together with \helpref{GetNextLine()}{wxtextfilegetnextline}
 188 allows more "iterator-like" traversal of the list of lines, i.e. you may
 189 write something like:
 190
 191 \begin{verbatim}
 192 wxTextFile file;
 193 ...
 194 for ( str = file.GetFirstLine(); !file.Eof(); str = file.GetNextLine() )
 195 {
 196     // do something with the current line in str
 197 }
 198 // do something with the last line in str
 199 \end{verbatim}
 200
 201 \membersection{wxTextFile::GetNextLine}\label{wxtextfilegetnextline}
 202
 203 \func{wxString\&}{GetNextLine}{\void}
 204
 205 Gets the next line (see \helpref{GetFirstLine}{wxtextfilegetfirstline} for
 206 the example).
 207
 208 \membersection{wxTextFile::GetPrevLine}\label{wxtextfilegetprevline}
 209
 210 \func{wxString\&}{GetPrevLine}{\void}
 211
 212 Gets the previous line in the file.
 213
 214 \membersection{wxTextFile::GetLastLine}\label{wxtextfilegetlastline}
 215
 216 \func{wxString\&}{GetLastLine}{\void}
 217
 218 Gets the last line of the file. Together with
 219 \helpref{GetPrevLine}{wxtextfilegetprevline} it allows to enumerate the lines
 220 in the file from the end to the beginning like this:
 221
 222 \begin{verbatim}
 223 wxTextFile file;
 224 ...
 225 for ( str = file.GetLastLine();
 226       file.GetCurrentLine() > 0;
 227       str = file.GetPrevLine() )
 228 {
 229     // do something with the current line in str
 230 }
 231 // do something with the first line in str
 232 \end{verbatim}
 233
 234 \membersection{wxTextFile::GetLineType}\label{wxtextfilegetlinetype}
 235
 236 \constfunc{wxTextFileType}{GetLineType}{\param{size\_t }{n}}
 237
 238 Get the type of the line (see also \helpref{GetEOL}{wxtextfilegeteol})
 239
 240 \membersection{wxTextFile::GuessType}\label{wxtextfileguesstype}
 241
 242 \constfunc{wxTextFileType}{GuessType}{\void}
 243
 244 Guess the type of file (which is supposed to be opened). If sufficiently
 245 many lines of the file are in DOS/Unix/Mac format, the corresponding value will
 246 be returned. If the detection mechanism fails wxTextFileType\_None is returned.
 247
 248 \membersection{wxTextFile::GetName}\label{wxtextfilegetname}
 249
 250 \constfunc{const char*}{GetName}{\void}
 251
 252 Get the name of the file.
 253
 254 \membersection{wxTextFile::InsertLine}\label{wxtextfileinsertline}
 255
 256 \constfunc{void}{InsertLine}{\param{const wxString\& }{str}, \param{size\_t }{n}, \param{wxTextFileType }{type = typeDefault}}
 257
 258 Insert a line before the line number {\it n}.
 259
 260 \membersection{wxTextFile::Open}\label{wxtextfileopen}
 261
 262 \constfunc{bool}{Open}{\param{wxMBConv&}{ conv = wxConvLibc}}
 263
 264 \constfunc{bool}{Open}{\param{const wxString\& }{strFile}, \param{wxMBConv&}{ conv = wxConvLibc}}
 265
 266 Open() opens the file with the given name or the name which was given in the
 267 \helpref{constructor}{wxtextfilector} and also loads file in memory on
 268 success. It will fail if the file does not exist,
 269 \helpref{Create}{wxtextfilecreate} should be used in this case.
 270
 271 The {\it conv} argument is only meaningful in Unicode build of wxWindows when
 272 it is used to convert the file to wide character representation.
 273
 274 \membersection{wxTextFile::RemoveLine}\label{wxtextfileremoveline}
 275
 276 \constfunc{void}{RemoveLine}{\param{size\_t }{n}}
 277
 278 Delete line number {\it n} from the file.
 279
 280 \membersection{wxTextFile::Write}\label{wxtextfilewrite}
 281
 282 \constfunc{bool}{Write}{\param{wxTextFileType }{typeNew = wxTextFileType\_None}, \param{wxMBConv&}{ conv = wxConvLibc}}
 283
 284 Change the file on disk. The {\it typeNew} parameter allows you to change the
 285 file format (default argument means "don't change type") and may be used to
 286 convert, for example, DOS files to Unix.
 287
 288 The {\it conv} argument is only meaningful in Unicode build of wxWindows when
 289 it is used to convert all lines to multibyte representation before writing them
 290 them to physical file.
 291
 292 Returns TRUE if operation succeeded, FALSE if it failed.
 293