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