]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/textfile.h
remove tabs added by error in previous commit
[wxWidgets.git] / interface / wx / textfile.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: textfile.h
3 // Purpose: interface of wxTextFile
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9
10 /**
11 The line termination type (kept wxTextFileType name for compability).
12 */
13 enum wxTextFileType
14 {
15 wxTextFileType_None, //!< incomplete (the last line of the file only)
16 wxTextFileType_Unix, //!< line is terminated with 'LF' = 0xA = 10 = '\\n'
17 wxTextFileType_Dos, //!< line is terminated with 'CR' 'LF'
18 wxTextFileType_Mac, //!< line is terminated with 'CR' = 0xD = 13 = '\\r'
19 wxTextFileType_Os2 //!< line is terminated with 'CR' 'LF'
20 };
21
22 /**
23 @class wxTextFile
24
25 The wxTextFile is a simple class which allows to work with text files on line by
26 line basis. It also understands the differences in line termination characters
27 under different platforms and will not do anything bad to files with "non
28 native" line termination sequences - in fact, it can be also used to modify the
29 text files and change the line termination characters from one type (say DOS) to
30 another (say Unix).
31
32 One word of warning: the class is not at all optimized for big files and thus
33 it will load the file entirely into memory when opened. Of course, you should
34 not work in this way with large files (as an estimation, anything over 1 Megabyte
35 is surely too big for this class). On the other hand, it is not a serious
36 limitation for small files like configuration files or program sources
37 which are well handled by wxTextFile.
38
39 The typical things you may do with wxTextFile in order are:
40
41 - Create and open it: this is done with either wxTextFile::Create or wxTextFile::Open
42 function which opens the file (name may be specified either as the argument to
43 these functions or in the constructor), reads its contents in memory (in the
44 case of wxTextFile::Open()) and closes it.
45 - Work with the lines in the file: this may be done either with "direct
46 access" functions like wxTextFile::GetLineCount and wxTextFile::GetLine
47 (@e operator[] does exactly the same but looks more like array addressing)
48 or with "sequential access" functions which include wxTextFile::GetFirstLine,
49 wxTextFile::GetNextLine and also wxTextFile::GetLastLine, wxTextFile::GetPrevLine.
50 For the sequential access functions the current line number is maintained: it is
51 returned by wxTextFile::GetCurrentLine and may be changed with wxTextFile::GoToLine.
52 - Add/remove lines to the file: wxTextFile::AddLine and wxTextFile::InsertLine
53 add new lines while wxTextFile::RemoveLine deletes the existing ones.
54 wxTextFile::Clear resets the file to empty.
55 - Save your changes: notice that the changes you make to the file will @b not be
56 saved automatically; calling wxTextFile::Close or doing nothing discards them!
57 To save the changes you must explicitly callwxTextFile::Write - here, you may
58 also change the line termination type if you wish.
59
60
61 @library{wxbase}
62 @category{file}
63
64 @see wxFile
65 */
66 class wxTextFile
67 {
68 public:
69 /**
70 Default constructor, use Create() or Open() with a file name parameter to
71 initialize the object.
72 */
73 wxTextFile();
74
75 /**
76 Constructor does not load the file into memory, use Open() to do it.
77 */
78 wxTextFile(const wxString& strFile);
79
80 /**
81 Destructor does nothing.
82 */
83 virtual ~wxTextFile();
84
85 /**
86 Adds a line to the end of file.
87 */
88 void AddLine(const wxString& str,
89 wxTextFileType type = wxTextBuffer::typeDefault);
90
91 /**
92 Delete all lines from the file, set current line number to 0.
93 */
94 void Clear();
95
96 /**
97 Closes the file and frees memory, @b "losing all changes".
98 Use Write() if you want to save them.
99 */
100 bool Close();
101
102 /**
103 Creates the file with the name which was given in the
104 wxTextFile(const wxString&) constructor.
105 The array of file lines is initially empty.
106
107 It will fail if the file already exists, Open() should be used in this case.
108 */
109 bool Create() const;
110
111 /**
112 Creates the file with the given name.
113 The array of file lines is initially empty.
114
115 It will fail if the file already exists, Open() should be used in this case.
116 */
117 bool Create(const wxString& strFile) const;
118
119 /**
120 Returns @true if the current line is the last one.
121 */
122 bool Eof() const;
123
124 /**
125 Return @true if file exists - the name of the file should have been specified
126 in the constructor before calling Exists().
127 */
128 bool Exists() const;
129
130 /**
131 Returns the current line: it has meaning only when you're using
132 GetFirstLine()/GetNextLine() functions, it doesn't get updated when
133 you're using "direct access" functions like GetLine().
134 GetFirstLine() and GetLastLine() also change the value of the current line,
135 as well as GoToLine().
136 */
137 size_t GetCurrentLine() const;
138
139 /**
140 Get the line termination string corresponding to given constant.
141
142 @e typeDefault is the value defined during the compilation and corresponds
143 to the native format of the platform, i.e. it will be @c wxTextFileType_Dos
144 under Windows, @c wxTextFileType_Unix under Unix (including Mac OS X when
145 compiling with the Apple Developer Tools) and @c wxTextFileType_Mac under
146 Mac OS (including Mac OS X when compiling with CodeWarrior).
147 */
148 static const char* GetEOL(wxTextFileType type = typeDefault) const;
149
150 /**
151 This method together with GetNextLine() allows more "iterator-like"
152 traversal of the list of lines, i.e. you may write something like:
153
154 @code
155 wxTextFile file;
156 ...
157 for ( str = file.GetFirstLine(); !file.Eof(); str = file.GetNextLine() )
158 {
159 // do something with the current line in str
160 }
161 // do something with the last line in str
162 @endcode
163 */
164 wxString& GetFirstLine();
165
166 /**
167 Gets the last line of the file.
168
169 Together with GetPrevLine() it allows to enumerate the lines
170 in the file from the end to the beginning like this:
171
172 @code
173 wxTextFile file;
174 ...
175 for ( str = file.GetLastLine();
176 file.GetCurrentLine() > 0;
177 str = file.GetPrevLine() )
178 {
179 // do something with the current line in str
180 }
181 // do something with the first line in str
182 @endcode
183 */
184 wxString& GetLastLine();
185
186 /**
187 Retrieves the line number @a n from the file.
188
189 The returned line may be modified but you shouldn't add line terminator
190 at the end - this will be done by wxTextFile.
191 */
192 wxString& GetLine(size_t n) const;
193
194 /**
195 Get the number of lines in the file.
196 */
197 size_t GetLineCount() const;
198
199 /**
200 Get the type of the line (see also wxTextFile::GetEOL).
201 */
202 wxTextFileType GetLineType(size_t n) const;
203
204 /**
205 Get the name of the file.
206 */
207 const wxString& GetName() const;
208
209 /**
210 Gets the next line (see GetFirstLine() for the example).
211 */
212 wxString& GetNextLine();
213
214 /**
215 Gets the previous line in the file.
216 */
217 wxString& GetPrevLine();
218
219 /**
220 Changes the value returned by GetCurrentLine() and used by GetFirstLine()
221 and GetNextLine().
222 */
223 void GoToLine(size_t n);
224
225 /**
226 Guess the type of file (which is supposed to be opened).
227
228 If sufficiently many lines of the file are in DOS/Unix/Mac format,
229 the corresponding value will be returned.
230 If the detection mechanism fails @c wxTextFileType_None is returned.
231 */
232 wxTextFileType GuessType() const;
233
234 /**
235 Insert a line before the line number @a n.
236 */
237 void InsertLine(const wxString& str, size_t n,
238 wxTextFileType type = wxTextBuffer::typeDefault);
239
240 /**
241 Returns @true if the file is currently opened.
242 */
243 bool IsOpened() const;
244
245 //@{
246 /**
247 Open() opens the file with the given name or the name which was given in the
248 wxTextFile(const wxString&) constructor and also loads file in memory on success.
249
250 It will fail if the file does not exist, Create() should be used in this case.
251
252 The @a conv argument is only meaningful in Unicode build of wxWidgets when
253 it is used to convert the file to wide character representation.
254 */
255 bool Open(const wxMBConv& conv = wxConvAuto()) const;
256 bool Open(const wxString& strFile, const wxMBConv& conv = wxConvAuto()) const;
257 //@}
258
259 /**
260 Delete line number @a n from the file.
261 */
262 void RemoveLine(size_t n);
263
264 /**
265 Change the file on disk.
266
267 The @a typeNew parameter allows you to change the file format
268 (default argument means "don't change type") and may be used to convert,
269 for example, DOS files to Unix.
270
271 The @a conv argument is only meaningful in Unicode build of wxWidgets when
272 it is used to convert all lines to multibyte representation before writing
273 them to physical file.
274
275 @return
276 @true if operation succeeded, @false if it failed.
277 */
278 bool Write(wxTextFileType typeNew = wxTextFileType_None,
279 const wxMBConv& conv = wxConvAuto());
280
281 /**
282 The same as GetLine().
283 */
284 wxString& operator[](size_t n) const;
285 };
286