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