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 for ( str = GetFirstLine(); !Eof(); str = GetNextLine() )
 193 {
 194     // do something with the current line in str
 195 }
 196 \end{verbatim}
 197
 198 \membersection{wxTextFile::GetNextLine}\label{wxtextfilegetnextline}
 199
 200 \func{wxString\&}{GetNextLine}{\void}
 201
 202 Gets the next line (see \helpref{GetFirstLine}{wxtextfilegetfirstline} for
 203 the example).
 204
 205 \membersection{wxTextFile::GetPrevLine}\label{wxtextfilegetprevline}
 206
 207 \func{wxString\&}{GetPrevLine}{\void}
 208
 209 Gets the previous line in the file.
 210
 211 \membersection{wxTextFile::GetLastLine}\label{wxtextfilegetlastline}
 212
 213 \func{wxString\&}{GetLastLine}{\void}
 214
 215 Gets the last line of the file.
 216
 217 \membersection{wxTextFile::GetLineType}\label{wxtextfilegetlinetype}
 218
 219 \constfunc{wxTextFileType}{GetLineType}{\param{size\_t }{n}}
 220
 221 Get the type of the line (see also \helpref{GetEOL}{wxtextfilegeteol})
 222
 223 \membersection{wxTextFile::GuessType}\label{wxtextfileguesstype}
 224
 225 \constfunc{wxTextFileType}{GuessType}{\void}
 226
 227 Guess the type of file (which is supposed to be opened). If sufficiently
 228 many lines of the file are in DOS/Unix/Mac format, the corresponding value will
 229 be returned. If the detection mechanism fails wxTextFileType\_None is returned.
 230
 231 \membersection{wxTextFile::GetName}\label{wxtextfilegetname}
 232
 233 \constfunc{const char*}{GetName}{\void}
 234
 235 Get the name of the file.
 236
 237 \membersection{wxTextFile::InsertLine}\label{wxtextfileinsertline}
 238
 239 \constfunc{void}{InsertLine}{\param{const wxString\& }{str}, \param{size\_t }{n}, \param{wxTextFileType }{type = typeDefault}}
 240
 241 Insert a line before the line number {\it n}.
 242
 243 \membersection{wxTextFile::Open}\label{wxtextfileopen}
 244
 245 \constfunc{bool}{Open}{\void}
 246
 247 \constfunc{bool}{Open}{\param{const wxString\& }{strFile}}
 248
 249 Open() opens the file with the given name or the name which was given in the
 250 \helpref{constructor}{wxtextfilector} and also loads file in memory on
 251 success. It will fail if the file does not exist,
 252 \helpref{Create}{wxtextfilecreate} should be used in this case.
 253
 254 \membersection{wxTextFile::RemoveLine}\label{wxtextfileremoveline}
 255
 256 \constfunc{void}{RemoveLine}{\param{size\_t }{n}}
 257
 258 Delete line number {\it n} from the file.
 259
 260 \membersection{wxTextFile::Write}\label{wxtextfilewrite}
 261
 262 \constfunc{bool}{Write}{\param{wxTextFileType }{typeNew = wxTextFileType\_None}}
 263
 264 Change the file on disk. The {\it typeNew} parameter allows you to change the
 265 file format (default argument means "don't change type") and may be used to
 266 convert, for example, DOS files to Unix.
 267
 268 Returns TRUE if operation succeeded, FALSE if it failed.
 269