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