]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/textfile.tex
Changed test for INT32 to work with latest Cygwin. But might break other versions :-(
[wxWidgets.git] / docs / latex / wx / textfile.tex
CommitLineData
7f561143
VZ
1\section{\class{wxTextFile}}\label{wxtextfile}
2
3The wxTextFile is a simple class which allows to work with text files on line by
4line basis. It also understands the differences in line termination characters
5under different platforms and will not do anything bad to files with "non
6native" line termination sequences - in fact, it can be also used to modify the
631f1bfe 7text files and change the line termination characters from one type (say DOS) to
7f561143
VZ
8another (say Unix).
9
10One word of warning: the class is not at all optimized for big files and so it
11will load the file entirely into memory when opened. Of course, you should not
12work in this way with large files (as an estimation, anything over 1 Megabyte is
13surely too big for this class). On the other hand, it is not a serious
14limitation for the small files like configuration files or programs sources
15which are well handled by wxTextFile.
16
17The typical things you may do with wxTextFile in order are:
dface61c 18
7f561143 19\begin{itemize}\itemsep=0pt
f6bcfd97
BP
20\item Create and open it: this is done with either
21\helpref{Create}{wxtextfilecreate} or \helpref{Open}{wxtextfileopen}
22function which opens the file (name may be specified either as the argument to
23these functions or in the constructor), reads its contents in memory (in the
24case of {\tt Open()}) and closes it.
7f561143 25\item Work with the lines in the file: this may be done either with "direct
631f1bfe 26access" functions like \helpref{GetLineCount}{wxtextfilegetlinecount} and
7f561143
VZ
27\helpref{GetLine}{wxtextfilegetline} ({\it operator[]} does exactly the same
28but looks more like array addressing) or with "sequential access" functions
29which include \helpref{GetFirstLine}{wxtextfilegetfirstline}/
30\helpref{GetNextLine}{wxtextfilegetnextline} and also
dface61c 31\helpref{GetLastLine}{wxtextfilegetlastline}/\helpref{GetPrevLine}{wxtextfilegetprevline}.
7f561143
VZ
32For the sequential access functions the current line number is maintained: it is
33returned by \helpref{GetCurrentLine}{wxtextfilegetcurrentline} and may be
34changed 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.
631f1bfe
JS
38\item Save your changes: notice that the changes you make to the file will {\bf
39not} be saved automatically; calling \helpref{Close}{wxtextfileclose} or doing
40nothing discards them! To save the changes you must explicitly call
7f561143
VZ
41\helpref{Write}{wxtextfilewrite} - here, you may also change the line
42termination type if you wish.
43\end{itemize}
44
7f561143
VZ
45\wxheading{Derived from}
46
47No base class
48
954b8ae6
JS
49\wxheading{Include files}
50
51<wx/textfile.h>
52
7f561143
VZ
53\wxheading{Data structures}
54
55The following constants identify the line termination type:
b2cf617c 56
7f561143
VZ
57\begin{verbatim}
58enum 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'
b82827dd 64};
7f561143
VZ
65\end{verbatim}
66
b82827dd
JS
67\wxheading{See also}
68
69\helpref{wxFile}{wxfile}
70
7f561143
VZ
71\latexignore{\rtfignore{\wxheading{Members}}}
72
73\membersection{wxTextFile::wxTextFile}\label{wxtextfilectordef}
b82827dd 74
7f561143
VZ
75\constfunc{}{wxTextFile}{\void}
76
f6bcfd97
BP
77Default constructor, use \helpref{Create}{wxtextfilecreate} or
78\helpref{Open}{wxtextfileopen} with a file name parameter to initialize the object.
7f561143
VZ
79
80\membersection{wxTextFile::wxTextFile}\label{wxtextfilector}
dface61c 81
7f561143
VZ
82\constfunc{}{wxTextFile}{\param{const wxString\& }{strFile}}
83
84Constructor does not load the file into memory, use Open() to do it.
85
f6bcfd97 86\membersection{wxTextFile::\destruct{wxTextFile}}\label{wxtextfiledtor}
dface61c 87
f6bcfd97 88\constfunc{}{\destruct{wxTextFile}}{\void}
7f561143 89
f6bcfd97 90Destructor does nothing.
7f561143 91
f6bcfd97 92\membersection{wxTextFile::AddLine}\label{wxtextfileaddline}
dface61c 93
f6bcfd97 94\constfunc{void}{AddLine}{\param{const wxString\& }{str}, \param{wxTextFileType }{type = typeDefault}}
7f561143 95
f6bcfd97 96Adds a line to the end of file.
7f561143
VZ
97
98\membersection{wxTextFile::Close}\label{wxtextfileclose}
dface61c 99
7f561143
VZ
100\constfunc{bool}{Close}{\void}
101
102Closes the file and frees memory, {\bf losing all changes}. Use \helpref{Write()}{wxtextfilewrite}
103if you want to save them.
104
f6bcfd97
BP
105\membersection{wxTextFile::Create}\label{wxtextfilecreate}
106
107\constfunc{bool}{Create}{\void}
108
109\constfunc{bool}{Create}{\param{const wxString\& }{strFile}}
110
111Creates 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
113empty.
114
115It will fail if the file already exists, \helpref{Open}{wxtextfileopen} should
116be used in this case.
117
118\membersection{wxTextFile::Exists}\label{wxtextfileexists}
119
120\constfunc{bool}{Exists}{\void}
121
122Return TRUE if file exists - the name of the file should have been specified
123in the constructor before calling Exists().
124
7f561143 125\membersection{wxTextFile::IsOpened}\label{wxtextfileisopened}
dface61c 126
7f561143
VZ
127\constfunc{bool}{IsOpened}{\void}
128
129Returns TRUE if the file is currently opened.
130
131\membersection{wxTextFile::GetLineCount}\label{wxtextfilegetlinecount}
dface61c 132
7f561143
VZ
133\constfunc{size\_t}{GetLineCount}{\void}
134
135Get the number of lines in the file.
136
137\membersection{wxTextFile::GetLine}\label{wxtextfilegetline}
dface61c 138
7f561143
VZ
139\constfunc{wxString\&}{GetLine}{\param{size\_t }{n}}
140
141Retrieves the line number {\it n} from the file. The returned line may be
142modified but you shouldn't add line terminator at the end - this will be done
143by wxTextFile.
144
dface61c
JS
145\membersection{wxTextFile::operator[]}\label{wxtextfileoperatorarray}
146
7f561143
VZ
147\constfunc{wxString\&}{operator[]}{\param{size\_t }{n}}
148
149The same as \helpref{GetLine}{wxtextfilegetline}.
150
151\membersection{wxTextFile::GetCurrentLine}\label{wxtextfilegetcurrentline}
dface61c 152
7f561143
VZ
153\constfunc{size\_t}{GetCurrentLine}{\void}
154
155Returns the current line: it has meaning only when you're using
156GetFirstLine()/GetNextLine() functions, it doesn't get updated when
157you're using "direct access" functions like GetLine(). GetFirstLine() and
158GetLastLine() also change the value of the current line, as well as
159GoToLine().
160
161\membersection{wxTextFile::GoToLine}\label{wxtextfilegotoline}
dface61c 162
7f561143
VZ
163\constfunc{void}{GoToLine}{\param{size\_t }{n}}
164
165Changes the value returned by \helpref{GetCurrentLine}{wxtextfilegetcurrentline}
631f1bfe 166and used by \helpref{GetFirstLine()}{wxtextfilegetfirstline}/\helpref{GetNextLine()}{wxtextfilegetnextline}.
7f561143
VZ
167
168\membersection{wxTextFile::Eof}\label{wxtextfileeof}
dface61c 169
7f561143
VZ
170\constfunc{bool}{Eof}{\void}
171
172Returns TRUE if the current line is the last one.
173
f6bcfd97
BP
174\membersection{wxTextFile::GetEOL}\label{wxtextfilegeteol}
175
176\constfunc{static const char*}{GetEOL}{\param{wxTextFileType }{type = typeDefault}}
177
178Get the line termination string corresponding to given constant. {\it typeDefault} is
bb89dec3
GD
179the value defined during the compilation and corresponds to the native format
180of the platform, i.e. it will be wxTextFileType\_Dos under Windows,
181wxTextFileType\_Unix under Unix (including Mac OS X when compiling with the
182Apple Developer Tools) and wxTextFileType\_Mac under Mac OS (including
183Mac OS X when compiling with CodeWarrior).
f6bcfd97 184
7f561143 185\membersection{wxTextFile::GetFirstLine}\label{wxtextfilegetfirstline}
dface61c 186
7f561143
VZ
187\constfunc{wxString\&}{GetFirstLine}{\void}
188
189This method together with \helpref{GetNextLine()}{wxtextfilegetnextline}
190allows more "iterator-like" traversal of the list of lines, i.e. you may
191write something like:
192
193\begin{verbatim}
3ca6a5f0
BP
194wxTextFile file;
195...
196for ( str = file.GetFirstLine(); !file.Eof(); str = file.GetNextLine() )
7f561143
VZ
197{
198 // do something with the current line in str
199}
3ca6a5f0 200// do something with the last line in str
7f561143
VZ
201\end{verbatim}
202
203\membersection{wxTextFile::GetNextLine}\label{wxtextfilegetnextline}
dface61c 204
7f561143
VZ
205\func{wxString\&}{GetNextLine}{\void}
206
207Gets the next line (see \helpref{GetFirstLine}{wxtextfilegetfirstline} for
208the example).
209
210\membersection{wxTextFile::GetPrevLine}\label{wxtextfilegetprevline}
dface61c 211
7f561143
VZ
212\func{wxString\&}{GetPrevLine}{\void}
213
214Gets the previous line in the file.
215
216\membersection{wxTextFile::GetLastLine}\label{wxtextfilegetlastline}
dface61c 217
7f561143
VZ
218\func{wxString\&}{GetLastLine}{\void}
219
3ca6a5f0
BP
220Gets the last line of the file. Together with
221\helpref{GetPrevLine}{wxtextfilegetprevline} it allows to enumerate the lines
222in the file from the end to the beginning like this:
223
224\begin{verbatim}
225wxTextFile file;
226...
227for ( 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}
7f561143
VZ
235
236\membersection{wxTextFile::GetLineType}\label{wxtextfilegetlinetype}
dface61c 237
7f561143
VZ
238\constfunc{wxTextFileType}{GetLineType}{\param{size\_t }{n}}
239
240Get the type of the line (see also \helpref{GetEOL}{wxtextfilegeteol})
241
242\membersection{wxTextFile::GuessType}\label{wxtextfileguesstype}
dface61c 243
7f561143
VZ
244\constfunc{wxTextFileType}{GuessType}{\void}
245
246Guess the type of file (which is supposed to be opened). If sufficiently
247many lines of the file are in DOS/Unix/Mac format, the corresponding value will
248be returned. If the detection mechanism fails wxTextFileType\_None is returned.
249
250\membersection{wxTextFile::GetName}\label{wxtextfilegetname}
dface61c 251
7f561143
VZ
252\constfunc{const char*}{GetName}{\void}
253
254Get the name of the file.
255
7f561143 256\membersection{wxTextFile::InsertLine}\label{wxtextfileinsertline}
dface61c 257
7f561143
VZ
258\constfunc{void}{InsertLine}{\param{const wxString\& }{str}, \param{size\_t }{n}, \param{wxTextFileType }{type = typeDefault}}
259
260Insert a line before the line number {\it n}.
261
f6bcfd97
BP
262\membersection{wxTextFile::Open}\label{wxtextfileopen}
263
455df0f4 264\constfunc{bool}{Open}{\param{wxMBConv&}{ conv = wxConvLibc}}
f6bcfd97 265
455df0f4 266\constfunc{bool}{Open}{\param{const wxString\& }{strFile}, \param{wxMBConv&}{ conv = wxConvLibc}}
f6bcfd97
BP
267
268Open() 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
270success. It will fail if the file does not exist,
271\helpref{Create}{wxtextfilecreate} should be used in this case.
272
455df0f4
VS
273The {\it conv} argument is only meaningful in Unicode build of wxWindows when
274it is used to convert the file to wide character representation.
275
7f561143 276\membersection{wxTextFile::RemoveLine}\label{wxtextfileremoveline}
dface61c 277
7f561143
VZ
278\constfunc{void}{RemoveLine}{\param{size\_t }{n}}
279
631f1bfe 280Delete line number {\it n} from the file.
7f561143
VZ
281
282\membersection{wxTextFile::Write}\label{wxtextfilewrite}
dface61c 283
455df0f4 284\constfunc{bool}{Write}{\param{wxTextFileType }{typeNew = wxTextFileType\_None}, \param{wxMBConv&}{ conv = wxConvLibc}}
7f561143 285
631f1bfe 286Change the file on disk. The {\it typeNew} parameter allows you to change the
7f561143
VZ
287file format (default argument means "don't change type") and may be used to
288convert, for example, DOS files to Unix.
289
455df0f4
VS
290The {\it conv} argument is only meaningful in Unicode build of wxWindows when
291it is used to convert all lines to multibyte representation before writing them
292them to physical file.
293
189a89ae
VZ
294Returns TRUE if operation succeeded, FALSE if it failed.
295