]>
Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: filename.h | |
e54c96f1 | 3 | // Purpose: interface of wxFileName |
23324ae1 FM |
4 | // Author: wxWidgets team |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
0b70c946 | 9 | |
eadd3970 FM |
10 | /** |
11 | The various values for the path format: this mainly affects the path | |
0b70c946 FM |
12 | separator but also whether or not the path has the drive part |
13 | (as under Windows). | |
14 | ||
15 | See wxFileName for more info. | |
16 | */ | |
17 | enum wxPathFormat | |
18 | { | |
19 | wxPATH_NATIVE = 0, //!< the path format for the current platform. | |
20 | wxPATH_UNIX, | |
21 | wxPATH_BEOS = wxPATH_UNIX, | |
22 | wxPATH_MAC, | |
23 | wxPATH_DOS, | |
24 | wxPATH_WIN = wxPATH_DOS, | |
25 | wxPATH_OS2 = wxPATH_DOS, | |
26 | wxPATH_VMS, | |
27 | ||
28 | wxPATH_MAX //!< Not a valid value for specifying path format | |
29 | }; | |
30 | ||
31 | ||
eadd3970 FM |
32 | /** |
33 | The kind of normalization to do with the file name: these values can be | |
0b70c946 FM |
34 | or'd together to perform several operations at once. |
35 | See wxFileName::Normalize() for more info. | |
36 | */ | |
37 | enum wxPathNormalize | |
38 | { | |
395f3aa8 FM |
39 | //! Replace environment variables with their values. |
40 | //! wxFileName understands both Unix and Windows (but only under Windows) environment | |
41 | //! variables expansion: i.e. @c "$var", @c "$(var)" and @c "${var}" are always understood | |
42 | //! and in addition under Windows @c "%var%" is also. | |
43 | wxPATH_NORM_ENV_VARS = 0x0001, | |
44 | ||
eadd3970 FM |
45 | wxPATH_NORM_DOTS = 0x0002, //!< Squeeze all @c ".." and @c "." and prepend the current working directory. |
46 | wxPATH_NORM_TILDE = 0x0004, //!< Replace @c "~" and @c "~user" (Unix only). | |
47 | wxPATH_NORM_CASE = 0x0008, //!< If the platform is case insensitive, make lowercase the path. | |
48 | wxPATH_NORM_ABSOLUTE = 0x0010, //!< Make the path absolute. | |
49 | wxPATH_NORM_LONG = 0x0020, //!< Expand the path to the "long" form (Windows only). | |
50 | wxPATH_NORM_SHORTCUT = 0x0040, //!< Resolve the shortcut, if it is a shortcut (Windows only). | |
51 | ||
52 | //! A value indicating all normalization flags except for @c wxPATH_NORM_CASE. | |
0b70c946 FM |
53 | wxPATH_NORM_ALL = 0x00ff & ~wxPATH_NORM_CASE |
54 | }; | |
55 | ||
110c5094 VZ |
56 | /** |
57 | Flags for wxFileName::Rmdir(). | |
58 | */ | |
59 | enum | |
60 | { | |
61 | /// Delete the specified directory and its subdirectories if they are empty. | |
62 | wxPATH_RMDIR_FULL = 1, | |
63 | ||
64 | /** | |
65 | Delete the specified directory and all the files and subdirectories in it | |
66 | recursively. | |
67 | ||
68 | This flag is obviously @b dangerous and should be used with care and | |
69 | after asking the user for confirmation. | |
70 | */ | |
71 | wxPATH_RMDIR_RECURSIVE = 2 | |
72 | }; | |
73 | ||
0b70c946 FM |
74 | /** |
75 | The return value of wxFileName::GetSize() in case of error. | |
76 | */ | |
77 | wxULongLong wxInvalidSize; | |
78 | ||
79 | ||
23324ae1 FM |
80 | /** |
81 | @class wxFileName | |
7c913512 | 82 | |
76e9224e FM |
83 | wxFileName encapsulates a file name. |
84 | ||
85 | This class serves two purposes: first, it provides the functions to split the | |
86 | file names into components and to recombine these components in the full file | |
87 | name which can then be passed to the OS file functions | |
88 | (and @ref group_funcmacro_file "wxWidgets functions" wrapping them). | |
23324ae1 FM |
89 | Second, it includes the functions for working with the files itself. Note that |
90 | to change the file data you should use wxFile class instead. | |
91 | wxFileName provides functions for working with the file attributes. | |
7c913512 | 92 | |
23324ae1 FM |
93 | When working with directory names (i.e. without filename and extension) |
94 | make sure not to misuse the file name part of this class with the last | |
95 | directory. Instead initialize the wxFileName instance like this: | |
7c913512 | 96 | |
23324ae1 FM |
97 | @code |
98 | wxFileName dirname( "C:\mydir", "" ); | |
99 | MyMethod( dirname.GetPath() ); | |
100 | @endcode | |
7c913512 | 101 | |
0b70c946 | 102 | The same can be done using the static method wxFileName::DirName(): |
7c913512 | 103 | |
23324ae1 FM |
104 | @code |
105 | wxFileName dirname = wxFileName::DirName( "C:\mydir" ); | |
106 | MyMethod( dirname.GetPath() ); | |
107 | @endcode | |
7c913512 | 108 | |
0b70c946 FM |
109 | Accordingly, methods dealing with directories or directory names like |
110 | wxFileName::IsDirReadable() use wxFileName::GetPath() whereas methods dealing | |
111 | with file names like wxFileName::IsFileReadable() use wxFileName::GetFullPath(). | |
7c913512 | 112 | |
0b70c946 FM |
113 | If it is not known wether a string contains a directory name or a complete |
114 | file name (such as when interpreting user input) you need to use the static | |
115 | function wxFileName::DirExists() (or its identical variants wxDir::Exists() and | |
116 | wxDirExists()) and construct the wxFileName instance accordingly. | |
117 | This will only work if the directory actually exists, of course: | |
7c913512 | 118 | |
23324ae1 FM |
119 | @code |
120 | wxString user_input; | |
121 | // get input from user | |
7c913512 | 122 | |
23324ae1 FM |
123 | wxFileName fname; |
124 | if (wxDirExists(user_input)) | |
125 | fname.AssignDir( user_input ); | |
126 | else | |
127 | fname.Assign( user_input ); | |
128 | @endcode | |
7c913512 | 129 | |
0b70c946 FM |
130 | Please note that many wxFileName methods accept the path format argument |
131 | which is by @c wxPATH_NATIVE by default meaning to use the path format | |
132 | native for the current platform. | |
133 | The path format affects the operation of wxFileName functions in several ways: | |
134 | first and foremost, it defines the path separator character to use, but it | |
135 | also affects other things such as whether the path has the drive part or not. | |
136 | See wxPathFormat for more info. | |
137 | ||
138 | ||
139 | @section filename_format File name format | |
140 | ||
141 | wxFileName currently supports the file names in the Unix, DOS/Windows, | |
142 | Mac OS and VMS formats. Although these formats are quite different, | |
143 | wxFileName tries to treat them all in the same generic way. | |
144 | It supposes that all file names consist of the following parts: the volume | |
145 | (also known as drive under Windows or device under VMS), the path which is | |
146 | a sequence of directory names separated by the path separators and the full | |
147 | filename itself which, in turn, is composed from the base file name and the | |
148 | extension. All of the individual components of the file name may be empty | |
149 | and, for example, the volume name is always empty under Unix, but if they | |
150 | are all empty simultaneously, the filename object is considered to be in an | |
151 | invalid state and wxFileName::IsOk() returns false for it. | |
152 | ||
153 | File names can be case-sensitive or not, the function wxFileName::IsCaseSensitive() | |
154 | allows to determine this. The rules for determining whether the file name is | |
155 | absolute or relative also depend on the file name format and the only portable way | |
156 | to answer this question is to use wxFileName::IsAbsolute() or wxFileName::IsRelative() | |
157 | method. | |
158 | ||
159 | Note that on Windows,"X:" refers to the current working directory on drive X. | |
160 | Therefore, a wxFileName instance constructed from for example "X:dir/file.ext" | |
161 | treats the portion beyond drive separator as being relative to that directory. | |
162 | To ensure that the filename is absolute, you may use wxFileName::MakeAbsolute(). | |
163 | There is also an inverse function wxFileName::MakeRelativeTo() which undoes | |
164 | what wxFileName::Normalize(wxPATH_NORM_DOTS) does. | |
165 | Other functions returning information about the file format provided by this | |
166 | class are wxFileName::GetVolumeSeparator(), wxFileName::IsPathSeparator(). | |
167 | ||
168 | ||
169 | @section filename_construction File name construction | |
170 | ||
171 | You can initialize a wxFileName instance using one of the following functions: | |
172 | ||
173 | @li wxFileName::wxFileName() | |
174 | @li wxFileName::Assign() | |
175 | @li wxFileName::AssignCwd() | |
176 | @li wxFileName::AssignDir() | |
177 | @li wxFileName::AssignHomeDir() | |
f95032ca | 178 | @li wxFileName::AssignTempFileName() |
0b70c946 FM |
179 | @li wxFileName::DirName() |
180 | @li wxFileName::FileName() | |
181 | @li wxFileName::operator=() | |
182 | ||
183 | ||
184 | @section filename_tests File name tests | |
185 | ||
186 | Before doing other tests, you should use wxFileName::IsOk() to verify that | |
187 | the filename is well defined. If it is, FileExists() can be used to test whether | |
188 | a file with such name exists and wxFileName::DirExists() can be used to test | |
189 | for directory existence. | |
190 | File names should be compared using the wxFileName::SameAs() method or | |
191 | wxFileName::operator==(). For testing basic access modes, you can use: | |
192 | ||
193 | @li wxFileName::IsDirWritable() | |
194 | @li wxFileName::IsDirReadable() | |
195 | @li wxFileName::IsFileWritable() | |
196 | @li wxFileName::IsFileReadable() | |
197 | @li wxFileName::IsFileExecutable() | |
198 | ||
199 | ||
200 | @section filename_components File name components | |
201 | ||
202 | These functions allow to examine and modify the individual directories | |
203 | of the path: | |
204 | ||
205 | @li wxFileName::AppendDir() | |
206 | @li wxFileName::InsertDir() | |
207 | @li wxFileName::GetDirCount() | |
208 | @li wxFileName::PrependDir() | |
209 | @li wxFileName::RemoveDir() | |
210 | @li wxFileName::RemoveLastDir() | |
211 | ||
212 | To change the components of the file name individually you can use the | |
213 | following functions: | |
214 | ||
215 | @li wxFileName::GetExt() | |
216 | @li wxFileName::GetName() | |
217 | @li wxFileName::GetVolume() | |
218 | @li wxFileName::HasExt() | |
219 | @li wxFileName::HasName() | |
220 | @li wxFileName::HasVolume() | |
221 | @li wxFileName::SetExt() | |
222 | @li wxFileName::ClearExt() | |
223 | @li wxFileName::SetEmptyExt() | |
224 | @li wxFileName::SetName() | |
225 | @li wxFileName::SetVolume() | |
226 | ||
227 | You can initialize a wxFileName instance using one of the following functions: | |
228 | ||
229 | ||
230 | @section filename_operations File name operations | |
231 | ||
232 | These methods allow to work with the file creation, access and modification | |
233 | times. Note that not all filesystems under all platforms implement these times | |
234 | in the same way. For example, the access time under Windows has a resolution of | |
235 | one day (so it is really the access date and not time). The access time may be | |
236 | updated when the file is executed or not depending on the platform. | |
237 | ||
238 | @li wxFileName::GetModificationTime() | |
239 | @li wxFileName::GetTimes() | |
240 | @li wxFileName::SetTimes() | |
241 | @li wxFileName::Touch() | |
242 | ||
243 | Other file system operations functions are: | |
244 | ||
245 | @li wxFileName::Mkdir() | |
246 | @li wxFileName::Rmdir() | |
ca4bcd88 RR |
247 | |
248 | ||
23324ae1 FM |
249 | @library{wxbase} |
250 | @category{file} | |
23324ae1 | 251 | */ |
7c913512 | 252 | class wxFileName |
23324ae1 FM |
253 | { |
254 | public: | |
23324ae1 | 255 | /** |
ca4bcd88 | 256 | Default constructor. |
23324ae1 FM |
257 | */ |
258 | wxFileName(); | |
0b70c946 | 259 | |
ca4bcd88 RR |
260 | /** |
261 | Copy constructor. | |
262 | */ | |
7c913512 | 263 | wxFileName(const wxFileName& filename); |
0b70c946 | 264 | |
ca4bcd88 | 265 | /** |
0b70c946 FM |
266 | Constructor taking a full filename. |
267 | ||
268 | If it terminates with a '/', a directory path is constructed | |
269 | (the name will be empty), otherwise a file name and extension | |
270 | are extracted from it. | |
ca4bcd88 | 271 | */ |
7c913512 FM |
272 | wxFileName(const wxString& fullpath, |
273 | wxPathFormat format = wxPATH_NATIVE); | |
0b70c946 | 274 | |
ca4bcd88 RR |
275 | /** |
276 | Constructor a directory name and file name. | |
277 | */ | |
7c913512 FM |
278 | wxFileName(const wxString& path, const wxString& name, |
279 | wxPathFormat format = wxPATH_NATIVE); | |
0b70c946 | 280 | |
ca4bcd88 RR |
281 | /** |
282 | Constructor from a directory name, base file name and extension. | |
283 | */ | |
7c913512 FM |
284 | wxFileName(const wxString& path, const wxString& name, |
285 | const wxString& ext, | |
286 | wxPathFormat format = wxPATH_NATIVE); | |
0b70c946 | 287 | |
ca4bcd88 RR |
288 | /** |
289 | Constructor from a volume name, a directory name, base file name and extension. | |
290 | */ | |
7c913512 FM |
291 | wxFileName(const wxString& volume, const wxString& path, |
292 | const wxString& name, | |
293 | const wxString& ext, | |
294 | wxPathFormat format = wxPATH_NATIVE); | |
23324ae1 FM |
295 | |
296 | /** | |
297 | Appends a directory component to the path. This component should contain a | |
298 | single directory name level, i.e. not contain any path or volume separators nor | |
299 | should it be empty, otherwise the function does nothing (and generates an | |
300 | assert failure in debug build). | |
301 | */ | |
302 | void AppendDir(const wxString& dir); | |
303 | ||
23324ae1 | 304 | /** |
ca4bcd88 | 305 | Creates the file name from another filename object. |
23324ae1 FM |
306 | */ |
307 | void Assign(const wxFileName& filepath); | |
0b70c946 | 308 | |
ca4bcd88 RR |
309 | /** |
310 | Creates the file name from a full file name with a path. | |
311 | */ | |
7c913512 FM |
312 | void Assign(const wxString& fullpath, |
313 | wxPathFormat format = wxPATH_NATIVE); | |
0b70c946 | 314 | |
ca4bcd88 RR |
315 | /** |
316 | Creates the file name from volumne, path, name and extension. | |
317 | */ | |
7c913512 FM |
318 | void Assign(const wxString& volume, const wxString& path, |
319 | const wxString& name, | |
320 | const wxString& ext, | |
321 | bool hasExt, | |
322 | wxPathFormat format = wxPATH_NATIVE); | |
0b70c946 | 323 | |
ca4bcd88 RR |
324 | /** |
325 | Creates the file name from volumne, path, name and extension. | |
326 | */ | |
7c913512 FM |
327 | void Assign(const wxString& volume, const wxString& path, |
328 | const wxString& name, | |
329 | const wxString& ext, | |
330 | wxPathFormat format = wxPATH_NATIVE); | |
0b70c946 | 331 | |
ca4bcd88 RR |
332 | /** |
333 | Creates the file name from file path and file name. | |
334 | */ | |
7c913512 FM |
335 | void Assign(const wxString& path, const wxString& name, |
336 | wxPathFormat format = wxPATH_NATIVE); | |
0b70c946 | 337 | |
ca4bcd88 RR |
338 | /** |
339 | Creates the file name from path, name and extension. | |
340 | */ | |
7c913512 FM |
341 | void Assign(const wxString& path, const wxString& name, |
342 | const wxString& ext, | |
343 | wxPathFormat format = wxPATH_NATIVE); | |
23324ae1 FM |
344 | |
345 | /** | |
346 | Makes this object refer to the current working directory on the specified | |
4cc4bfaf | 347 | volume (or current volume if @a volume is empty). |
3c4f71cc | 348 | |
4cc4bfaf | 349 | @see GetCwd() |
23324ae1 | 350 | */ |
382f12e4 | 351 | void AssignCwd(const wxString& volume = wxEmptyString); |
23324ae1 FM |
352 | |
353 | /** | |
0b70c946 FM |
354 | Sets this file name object to the given directory name. |
355 | The name and extension will be empty. | |
23324ae1 FM |
356 | */ |
357 | void AssignDir(const wxString& dir, | |
358 | wxPathFormat format = wxPATH_NATIVE); | |
359 | ||
360 | /** | |
361 | Sets this file name object to the home directory. | |
362 | */ | |
363 | void AssignHomeDir(); | |
364 | ||
365 | /** | |
0b70c946 FM |
366 | The function calls CreateTempFileName() to create a temporary file |
367 | and sets this object to the name of the file. | |
a44f3b5a | 368 | |
0b70c946 | 369 | If a temporary file couldn't be created, the object is put into |
f95032ca RR |
370 | an invalid state (see IsOk()). |
371 | */ | |
372 | void AssignTempFileName(const wxString& prefix); | |
373 | ||
374 | /** | |
375 | The function calls CreateTempFileName() to create a temporary | |
376 | file name and open @a fileTemp with it. | |
377 | ||
378 | If the file couldn't be opened, the object is put into | |
379 | an invalid state (see IsOk()). | |
23324ae1 | 380 | */ |
a44f3b5a | 381 | void AssignTempFileName(const wxString& prefix, wxFile* fileTemp); |
f95032ca RR |
382 | |
383 | /** | |
384 | The function calls CreateTempFileName() to create a temporary | |
385 | file name and open @a fileTemp with it. | |
386 | ||
387 | If the file couldn't be opened, the object is put into | |
388 | an invalid state (see IsOk()). | |
389 | */ | |
a44f3b5a | 390 | void AssignTempFileName(const wxString& prefix, wxFFile* fileTemp); |
23324ae1 FM |
391 | |
392 | /** | |
393 | Reset all components to default, uninitialized state. | |
394 | */ | |
395 | void Clear(); | |
396 | ||
397 | /** | |
7c913512 | 398 | Removes the extension from the file name resulting in a |
23324ae1 | 399 | file name with no trailing dot. |
3c4f71cc | 400 | |
4cc4bfaf | 401 | @see SetExt(), SetEmptyExt() |
23324ae1 | 402 | */ |
2bd56258 | 403 | void ClearExt(); |
23324ae1 | 404 | |
882678eb | 405 | //@{ |
23324ae1 | 406 | /** |
0b70c946 FM |
407 | Returns a temporary file name starting with the given @e prefix. |
408 | If the @a prefix is an absolute path, the temporary file is created in this | |
23324ae1 FM |
409 | directory, otherwise it is created in the default system directory for the |
410 | temporary files or in the current directory. | |
0b70c946 FM |
411 | |
412 | If the function succeeds, the temporary file is actually created. | |
413 | If @a fileTemp is not @NULL, this file will be opened using the name of | |
23324ae1 FM |
414 | the temporary file. When possible, this is done in an atomic way ensuring that |
415 | no race condition occurs between the temporary file name generation and opening | |
416 | it which could often lead to security compromise on the multiuser systems. | |
4cc4bfaf | 417 | If @a fileTemp is @NULL, the file is only created, but not opened. |
23324ae1 FM |
418 | Under Unix, the temporary file will have read and write permissions for the |
419 | owner only to minimize the security problems. | |
3c4f71cc | 420 | |
7c913512 | 421 | @param prefix |
4cc4bfaf | 422 | Prefix to use for the temporary file name construction |
7c913512 | 423 | @param fileTemp |
4cc4bfaf | 424 | The file to open or @NULL to just get the name |
3c4f71cc | 425 | |
d29a9a8a | 426 | @return The full temporary file name or an empty string on error. |
23324ae1 FM |
427 | */ |
428 | static wxString CreateTempFileName(const wxString& prefix, | |
4cc4bfaf | 429 | wxFile* fileTemp = NULL); |
882678eb FM |
430 | static wxString CreateTempFileName(const wxString& prefix, |
431 | wxFFile* fileTemp = NULL); | |
432 | //@} | |
23324ae1 | 433 | |
23324ae1 FM |
434 | /** |
435 | Returns @true if the directory with this name exists. | |
436 | */ | |
0b70c946 FM |
437 | bool DirExists() const; |
438 | ||
ca4bcd88 RR |
439 | /** |
440 | Returns @true if the directory with this name exists. | |
441 | */ | |
0b70c946 | 442 | static bool DirExists(const wxString& dir); |
23324ae1 FM |
443 | |
444 | /** | |
445 | Returns the object corresponding to the directory with the given name. | |
4cc4bfaf | 446 | The @a dir parameter may have trailing path separator or not. |
23324ae1 FM |
447 | */ |
448 | static wxFileName DirName(const wxString& dir, | |
449 | wxPathFormat format = wxPATH_NATIVE); | |
450 | ||
451 | /** | |
ca4bcd88 | 452 | Returns @true if the file with this name exists. |
3c4f71cc | 453 | |
ca4bcd88 | 454 | @see DirExists() |
23324ae1 | 455 | */ |
0b70c946 FM |
456 | bool FileExists() const; |
457 | ||
23324ae1 FM |
458 | /** |
459 | Returns @true if the file with this name exists. | |
3c4f71cc | 460 | |
4cc4bfaf | 461 | @see DirExists() |
23324ae1 | 462 | */ |
0b70c946 | 463 | static bool FileExists(const wxString& file); |
23324ae1 FM |
464 | |
465 | /** | |
466 | Returns the file name object corresponding to the given @e file. This | |
467 | function exists mainly for symmetry with DirName(). | |
468 | */ | |
469 | static wxFileName FileName(const wxString& file, | |
470 | wxPathFormat format = wxPATH_NATIVE); | |
471 | ||
472 | /** | |
0b70c946 FM |
473 | Retrieves the value of the current working directory on the specified volume. |
474 | If the volume is empty, the program's current working directory is returned for | |
475 | the current volume. | |
3c4f71cc | 476 | |
d29a9a8a | 477 | @return The string containing the current working directory or an empty |
0b70c946 | 478 | string on error. |
3c4f71cc | 479 | |
4cc4bfaf | 480 | @see AssignCwd() |
23324ae1 | 481 | */ |
0b70c946 | 482 | static wxString GetCwd(const wxString& volume = wxEmptyString); |
23324ae1 FM |
483 | |
484 | /** | |
485 | Returns the number of directories in the file name. | |
486 | */ | |
328f5751 | 487 | size_t GetDirCount() const; |
23324ae1 FM |
488 | |
489 | /** | |
490 | Returns the directories in string array form. | |
491 | */ | |
0b70c946 | 492 | const wxArrayString& GetDirs() const; |
23324ae1 FM |
493 | |
494 | /** | |
495 | Returns the file name extension. | |
496 | */ | |
328f5751 | 497 | wxString GetExt() const; |
23324ae1 FM |
498 | |
499 | /** | |
0b70c946 FM |
500 | Returns the characters that can't be used in filenames and directory names |
501 | for the specified format. | |
23324ae1 FM |
502 | */ |
503 | static wxString GetForbiddenChars(wxPathFormat format = wxPATH_NATIVE); | |
504 | ||
505 | /** | |
506 | Returns the canonical path format for this platform. | |
507 | */ | |
508 | static wxPathFormat GetFormat(wxPathFormat format = wxPATH_NATIVE); | |
509 | ||
510 | /** | |
511 | Returns the full name (including extension but excluding directories). | |
512 | */ | |
328f5751 | 513 | wxString GetFullName() const; |
23324ae1 FM |
514 | |
515 | /** | |
516 | Returns the full path with name and extension. | |
517 | */ | |
328f5751 | 518 | wxString GetFullPath(wxPathFormat format = wxPATH_NATIVE) const; |
23324ae1 FM |
519 | |
520 | /** | |
521 | Returns the home directory. | |
522 | */ | |
523 | static wxString GetHomeDir(); | |
524 | ||
23324ae1 | 525 | /** |
2bd56258 | 526 | Returns the size of the file in a human-readable form. |
0b70c946 | 527 | |
2bd56258 RR |
528 | If the size could not be retrieved the @c failmsg string |
529 | is returned. In case of success, the returned string is | |
530 | a floating-point number with @c precision decimal digits | |
531 | followed by the size unit (B, kB, MB, GB, TB: respectively | |
532 | bytes, kilobytes, megabytes, gigabytes, terabytes). | |
23324ae1 FM |
533 | */ |
534 | wxString GetHumanReadableSize(const wxString& failmsg = "Not available", | |
0b70c946 FM |
535 | int precision = 1) const; |
536 | ||
2bd56258 RR |
537 | /** |
538 | Returns the size of the given number of bytes in a human-readable form. | |
0b70c946 FM |
539 | |
540 | If @a bytes is ::wxInvalidSize or zero, then @a nullsize is returned. | |
541 | ||
542 | In case of success, the returned string is a floating-point number with | |
543 | @a precision decimal digits followed by the size unit (B, kB, MB, GB, | |
2bd56258 RR |
544 | TB: respectively bytes, kilobytes, megabytes, gigabytes, terabytes). |
545 | */ | |
0b70c946 FM |
546 | static wxString GetHumanReadableSize(const wxULongLong& bytes, |
547 | const wxString& nullsize = "Not available", | |
548 | int precision = 1); | |
23324ae1 FM |
549 | |
550 | /** | |
0b70c946 | 551 | Return the long form of the path (returns identity on non-Windows platforms). |
23324ae1 | 552 | */ |
328f5751 | 553 | wxString GetLongPath() const; |
23324ae1 FM |
554 | |
555 | /** | |
556 | Returns the last time the file was last modified. | |
557 | */ | |
328f5751 | 558 | wxDateTime GetModificationTime() const; |
23324ae1 FM |
559 | |
560 | /** | |
561 | Returns the name part of the filename (without extension). | |
3c4f71cc | 562 | |
4cc4bfaf | 563 | @see GetFullName() |
23324ae1 | 564 | */ |
328f5751 | 565 | wxString GetName() const; |
23324ae1 FM |
566 | |
567 | /** | |
35c2aa4f VZ |
568 | Returns the path part of the filename (without the name or extension). |
569 | ||
570 | The possible flags values are: | |
3c4f71cc | 571 | |
eadd3970 | 572 | - @b wxPATH_GET_VOLUME: |
35c2aa4f VZ |
573 | Return the path with the volume (does nothing for the filename formats |
574 | without volumes), otherwise the path without volume part is returned. | |
3c4f71cc | 575 | |
0b70c946 | 576 | - @b wxPATH_GET_SEPARATOR: |
35c2aa4f VZ |
577 | Return the path with the trailing separator, if this flag is not given |
578 | there will be no separator at the end of the path. | |
579 | ||
0b70c946 | 580 | - @b wxPATH_NO_SEPARATOR: |
35c2aa4f VZ |
581 | Don't include the trailing separator in the returned string. This is |
582 | the default (the value of this flag is 0) and exists only for symmetry | |
583 | with wxPATH_GET_SEPARATOR. | |
23324ae1 FM |
584 | */ |
585 | wxString GetPath(int flags = wxPATH_GET_VOLUME, | |
328f5751 | 586 | wxPathFormat format = wxPATH_NATIVE) const; |
23324ae1 FM |
587 | |
588 | /** | |
0b70c946 FM |
589 | Returns the usually used path separator for this format. |
590 | For all formats but @c wxPATH_DOS there is only one path separator anyhow, | |
591 | but for DOS there are two of them and the native one, i.e. the backslash | |
592 | is returned by this method. | |
3c4f71cc | 593 | |
4cc4bfaf | 594 | @see GetPathSeparators() |
23324ae1 | 595 | */ |
920b92a3 | 596 | static wxUniChar GetPathSeparator(wxPathFormat format = wxPATH_NATIVE); |
23324ae1 FM |
597 | |
598 | /** | |
0b70c946 FM |
599 | Returns the string containing all the path separators for this format. |
600 | For all formats but @c wxPATH_DOS this string contains only one character | |
601 | but for DOS and Windows both @c '/' and @c '\' may be used as separators. | |
3c4f71cc | 602 | |
4cc4bfaf | 603 | @see GetPathSeparator() |
23324ae1 FM |
604 | */ |
605 | static wxString GetPathSeparators(wxPathFormat format = wxPATH_NATIVE); | |
606 | ||
607 | /** | |
0b70c946 FM |
608 | Returns the string of characters which may terminate the path part. |
609 | This is the same as GetPathSeparators() except for VMS | |
23324ae1 FM |
610 | path format where ] is used at the end of the path part. |
611 | */ | |
612 | static wxString GetPathTerminators(wxPathFormat format = wxPATH_NATIVE); | |
613 | ||
614 | /** | |
0b70c946 FM |
615 | Returns the path with the trailing separator, useful for appending the name |
616 | to the given path. | |
617 | ||
618 | This is the same as calling | |
619 | @code | |
620 | GetPath(wxPATH_GET_VOLUME | wxPATH_GET_SEPARATOR, format) | |
621 | @endcode | |
23324ae1 | 622 | */ |
328f5751 | 623 | wxString GetPathWithSep(wxPathFormat format = wxPATH_NATIVE) const; |
23324ae1 FM |
624 | |
625 | /** | |
626 | Return the short form of the path (returns identity on non-Windows platforms). | |
627 | */ | |
328f5751 | 628 | wxString GetShortPath() const; |
23324ae1 | 629 | |
23324ae1 | 630 | /** |
ca4bcd88 RR |
631 | Returns the size of the file If the file does not exist or its size could |
632 | not be read (because e.g. the file is locked by another process) the returned | |
0b70c946 | 633 | value is ::wxInvalidSize. |
23324ae1 | 634 | */ |
adaaa686 | 635 | wxULongLong GetSize() const; |
0b70c946 | 636 | |
ca4bcd88 RR |
637 | /** |
638 | Returns the size of the file If the file does not exist or its size could | |
639 | not be read (because e.g. the file is locked by another process) the returned | |
0b70c946 | 640 | value is ::wxInvalidSize. |
ca4bcd88 | 641 | */ |
882678eb | 642 | static wxULongLong GetSize(const wxString& filename); |
23324ae1 FM |
643 | |
644 | /** | |
645 | Returns the directory used for temporary files. | |
646 | */ | |
647 | static wxString GetTempDir(); | |
648 | ||
649 | /** | |
0b70c946 FM |
650 | Returns the last access, last modification and creation times. |
651 | The last access time is updated whenever the file is read or written | |
652 | (or executed in the case of Windows), last modification time is only | |
653 | changed when the file is written to. | |
654 | Finally, the creation time is indeed the time when the file was created | |
23324ae1 FM |
655 | under Windows and the inode change time under Unix (as it is impossible to |
656 | retrieve the real file creation time there anyhow) which can also be changed | |
657 | by many operations after the file creation. | |
0b70c946 | 658 | |
23324ae1 | 659 | If no filename or extension is specified in this instance of wxFileName |
0b70c946 FM |
660 | (and therefore IsDir() returns @true) then this function will return the |
661 | directory times of the path specified by GetPath(), otherwise the file | |
662 | times of the file specified by GetFullPath(). | |
663 | Any of the pointers may be @NULL if the corresponding time is not needed. | |
3c4f71cc | 664 | |
d29a9a8a | 665 | @return @true on success, @false if we failed to retrieve the times. |
23324ae1 FM |
666 | */ |
667 | bool GetTimes(wxDateTime* dtAccess, wxDateTime* dtMod, | |
328f5751 | 668 | wxDateTime* dtCreate) const; |
23324ae1 FM |
669 | |
670 | /** | |
671 | Returns the string containing the volume for this file name, empty if it | |
0b70c946 FM |
672 | doesn't have one or if the file system doesn't support volumes at all |
673 | (for example, Unix). | |
23324ae1 | 674 | */ |
328f5751 | 675 | wxString GetVolume() const; |
23324ae1 FM |
676 | |
677 | /** | |
678 | Returns the string separating the volume from the path for this format. | |
679 | */ | |
680 | static wxString GetVolumeSeparator(wxPathFormat format = wxPATH_NATIVE); | |
681 | ||
35c2aa4f VZ |
682 | /** |
683 | This function builds a volume path string, for example "C:\\". | |
684 | ||
685 | Implemented for the platforms which use drive letters, i.e. DOS, MSW | |
686 | and OS/2 only. | |
687 | ||
688 | @since 2.9.0 | |
689 | ||
690 | @param drive | |
0b70c946 | 691 | The drive letter, 'A' through 'Z' or 'a' through 'z'. |
35c2aa4f VZ |
692 | |
693 | @param flags | |
0b70c946 FM |
694 | @c wxPATH_NO_SEPARATOR or @c wxPATH_GET_SEPARATOR to omit or include |
695 | the trailing path separator, the default is to include it. | |
35c2aa4f VZ |
696 | |
697 | @return Volume path string. | |
698 | */ | |
699 | static wxString GetVolumeString(char drive, int flags = wxPATH_GET_SEPARATOR); | |
700 | ||
23324ae1 FM |
701 | /** |
702 | Returns @true if an extension is present. | |
703 | */ | |
328f5751 | 704 | bool HasExt() const; |
23324ae1 FM |
705 | |
706 | /** | |
707 | Returns @true if a name is present. | |
708 | */ | |
328f5751 | 709 | bool HasName() const; |
23324ae1 FM |
710 | |
711 | /** | |
712 | Returns @true if a volume specifier is present. | |
713 | */ | |
328f5751 | 714 | bool HasVolume() const; |
23324ae1 FM |
715 | |
716 | /** | |
717 | Inserts a directory component before the zero-based position in the directory | |
718 | list. Please see AppendDir() for important notes. | |
719 | */ | |
720 | void InsertDir(size_t before, const wxString& dir); | |
721 | ||
722 | /** | |
723 | Returns @true if this filename is absolute. | |
724 | */ | |
2bd56258 | 725 | bool IsAbsolute(wxPathFormat format = wxPATH_NATIVE) const; |
23324ae1 FM |
726 | |
727 | /** | |
728 | Returns @true if the file names of this type are case-sensitive. | |
729 | */ | |
730 | static bool IsCaseSensitive(wxPathFormat format = wxPATH_NATIVE); | |
731 | ||
732 | /** | |
733 | Returns @true if this object represents a directory, @false otherwise | |
0b70c946 FM |
734 | (i.e. if it is a file). |
735 | ||
736 | Note that this method doesn't test whether the directory or file really | |
737 | exists, you should use DirExists() or FileExists() for this. | |
23324ae1 | 738 | */ |
328f5751 | 739 | bool IsDir() const; |
23324ae1 | 740 | |
23324ae1 | 741 | /** |
2bd56258 RR |
742 | Returns @true if the directory component of this instance is an existing |
743 | directory and this process has read permissions on it. Read permissions | |
744 | on a directory mean that you can list the directory contents but it | |
23324ae1 FM |
745 | doesn't imply that you have read permissions on the files contained. |
746 | */ | |
2bd56258 | 747 | bool IsDirReadable() const; |
0b70c946 | 748 | |
2bd56258 RR |
749 | /** |
750 | Returns @true if the given @e dir is an existing directory and this process | |
751 | has read permissions on it. Read permissions on a directory mean that you | |
752 | can list the directory contents but it doesn't imply that you have read | |
753 | permissions on the files contained. | |
754 | */ | |
755 | static bool IsDirReadable(const wxString& dir); | |
23324ae1 | 756 | |
23324ae1 | 757 | /** |
2bd56258 | 758 | Returns @true if the directory component of this instance |
23324ae1 FM |
759 | is an existing directory and this process has write permissions on it. |
760 | Write permissions on a directory mean that you can create new files in the | |
761 | directory. | |
762 | */ | |
2bd56258 | 763 | bool IsDirWritable() const; |
0b70c946 | 764 | |
2bd56258 | 765 | /** |
0b70c946 FM |
766 | Returns @true if the given @a dir is an existing directory and this |
767 | process has write permissions on it. | |
2bd56258 RR |
768 | Write permissions on a directory mean that you can create new files in the |
769 | directory. | |
770 | */ | |
771 | static bool IsDirWritable(const wxString& dir); | |
23324ae1 | 772 | |
23324ae1 FM |
773 | /** |
774 | Returns @true if a file with this name exists and if this process has execute | |
775 | permissions on it. | |
776 | */ | |
2bd56258 | 777 | bool IsFileExecutable() const; |
0b70c946 | 778 | |
2bd56258 RR |
779 | /** |
780 | Returns @true if a file with this name exists and if this process has execute | |
781 | permissions on it. | |
782 | */ | |
783 | static bool IsFileExecutable(const wxString& file); | |
23324ae1 | 784 | |
23324ae1 FM |
785 | /** |
786 | Returns @true if a file with this name exists and if this process has read | |
787 | permissions on it. | |
788 | */ | |
2bd56258 | 789 | bool IsFileReadable() const; |
0b70c946 | 790 | |
2bd56258 RR |
791 | /** |
792 | Returns @true if a file with this name exists and if this process has read | |
793 | permissions on it. | |
794 | */ | |
795 | static bool IsFileReadable(const wxString& file); | |
23324ae1 | 796 | |
23324ae1 FM |
797 | /** |
798 | Returns @true if a file with this name exists and if this process has write | |
799 | permissions on it. | |
800 | */ | |
2bd56258 | 801 | bool IsFileWritable() const; |
0b70c946 | 802 | |
2bd56258 RR |
803 | /** |
804 | Returns @true if a file with this name exists and if this process has write | |
805 | permissions on it. | |
806 | */ | |
807 | static bool IsFileWritable(const wxString& file); | |
23324ae1 FM |
808 | |
809 | /** | |
0b70c946 FM |
810 | Returns @true if the filename is valid, @false if it is not initialized yet. |
811 | The assignment functions and Clear() may reset the object to the uninitialized, | |
23324ae1 FM |
812 | invalid state (the former only do it on failure). |
813 | */ | |
328f5751 | 814 | bool IsOk() const; |
23324ae1 FM |
815 | |
816 | /** | |
817 | Returns @true if the char is a path separator for this format. | |
818 | */ | |
819 | static bool IsPathSeparator(wxChar ch, | |
820 | wxPathFormat format = wxPATH_NATIVE); | |
821 | ||
822 | /** | |
823 | Returns @true if this filename is not absolute. | |
824 | */ | |
2bd56258 | 825 | bool IsRelative(wxPathFormat format = wxPATH_NATIVE) const; |
23324ae1 FM |
826 | |
827 | /** | |
828 | On Mac OS, gets the common type and creator for the given extension. | |
829 | */ | |
830 | static bool MacFindDefaultTypeAndCreator(const wxString& ext, | |
0b70c946 FM |
831 | wxUint32* type, |
832 | wxUint32* creator); | |
23324ae1 FM |
833 | |
834 | /** | |
0b70c946 FM |
835 | On Mac OS, registers application defined extensions and their default type |
836 | and creator. | |
23324ae1 FM |
837 | */ |
838 | static void MacRegisterDefaultTypeAndCreator(const wxString& ext, | |
0b70c946 FM |
839 | wxUint32 type, |
840 | wxUint32 creator); | |
23324ae1 FM |
841 | |
842 | /** | |
0b70c946 FM |
843 | On Mac OS, looks up the appropriate type and creator from the registration |
844 | and then sets it. | |
23324ae1 FM |
845 | */ |
846 | bool MacSetDefaultTypeAndCreator(); | |
847 | ||
848 | /** | |
0b70c946 FM |
849 | Make the file name absolute. |
850 | This is a shortcut for | |
851 | @code | |
852 | wxFileName::Normalize(wxPATH_NORM_DOTS | wxPATH_NORM_ABSOLUTE | | |
853 | wxPATH_NORM_TILDE, cwd, format) | |
854 | @endcode | |
3c4f71cc | 855 | |
4cc4bfaf | 856 | @see MakeRelativeTo(), Normalize(), IsAbsolute() |
23324ae1 FM |
857 | */ |
858 | bool MakeAbsolute(const wxString& cwd = wxEmptyString, | |
859 | wxPathFormat format = wxPATH_NATIVE); | |
860 | ||
861 | /** | |
7c913512 | 862 | This function tries to put this file name in a form relative to |
0b70c946 FM |
863 | @a pathBase. |
864 | In other words, it returns the file name which should be used to access | |
865 | this file if the current directory were pathBase. | |
3c4f71cc | 866 | |
76e9224e | 867 | @param pathBase |
0b70c946 | 868 | The directory to use as root, current directory is used by default |
7c913512 | 869 | @param format |
0b70c946 | 870 | The file name format, native by default |
3c4f71cc | 871 | |
d29a9a8a | 872 | @return @true if the file name has been changed, @false if we failed to do |
0b70c946 FM |
873 | anything with it (currently this only happens if the file name |
874 | is on a volume different from the volume specified by @a pathBase). | |
3c4f71cc | 875 | |
4cc4bfaf | 876 | @see Normalize() |
23324ae1 FM |
877 | */ |
878 | bool MakeRelativeTo(const wxString& pathBase = wxEmptyString, | |
879 | wxPathFormat format = wxPATH_NATIVE); | |
880 | ||
23324ae1 | 881 | /** |
ca4bcd88 | 882 | Creates a directory. |
0b70c946 FM |
883 | |
884 | @param perm | |
f41d6c8c | 885 | The permissions for the newly created directory. |
b91c4601 | 886 | See the ::wxPosixPermissions enumeration for more info. |
ca4bcd88 | 887 | @param flags |
0b70c946 FM |
888 | If the flags contain @c wxPATH_MKDIR_FULL flag, try to create each |
889 | directory in the path and also don't return an error if the target | |
890 | directory already exists. | |
ca4bcd88 RR |
891 | |
892 | @return Returns @true if the directory was successfully created, @false | |
0b70c946 | 893 | otherwise. |
ca4bcd88 | 894 | */ |
f41d6c8c | 895 | bool Mkdir(int perm = wxS_DIR_DEFAULT, int flags = 0); |
0b70c946 | 896 | |
ca4bcd88 RR |
897 | /** |
898 | Creates a directory. | |
0b70c946 | 899 | |
7c913512 | 900 | @param dir |
f41d6c8c | 901 | The directory to create |
76e9224e | 902 | @param perm |
f41d6c8c | 903 | The permissions for the newly created directory. |
b91c4601 | 904 | See the ::wxPosixPermissions enumeration for more info. |
7c913512 | 905 | @param flags |
f41d6c8c | 906 | If the flags contain @c wxPATH_MKDIR_FULL flag, try to create each |
0b70c946 FM |
907 | directory in the path and also don't return an error if the target |
908 | directory already exists. | |
3c4f71cc | 909 | |
d29a9a8a | 910 | @return Returns @true if the directory was successfully created, @false |
0b70c946 | 911 | otherwise. |
23324ae1 | 912 | */ |
f41d6c8c | 913 | static bool Mkdir(const wxString& dir, int perm = wxS_DIR_DEFAULT, |
7c913512 | 914 | int flags = 0); |
23324ae1 FM |
915 | |
916 | /** | |
917 | Normalize the path. With the default flags value, the path will be | |
918 | made absolute, without any ".." and "." and all environment | |
919 | variables will be expanded in it. | |
3c4f71cc | 920 | |
7c913512 | 921 | @param flags |
4cc4bfaf | 922 | The kind of normalization to do with the file name. It can be |
992ff331 | 923 | any or-combination of the ::wxPathNormalize enumeration values. |
4cc4bfaf FM |
924 | @param cwd |
925 | If not empty, this directory will be used instead of current | |
0b70c946 | 926 | working directory in normalization (see @c wxPATH_NORM_ABSOLUTE). |
7c913512 | 927 | @param format |
4cc4bfaf | 928 | The file name format to use when processing the paths, native by default. |
3c4f71cc | 929 | |
d29a9a8a | 930 | @return @true if normalization was successfully or @false otherwise. |
23324ae1 FM |
931 | */ |
932 | bool Normalize(int flags = wxPATH_NORM_ALL, | |
933 | const wxString& cwd = wxEmptyString, | |
934 | wxPathFormat format = wxPATH_NATIVE); | |
935 | ||
23324ae1 | 936 | /** |
0b70c946 FM |
937 | Prepends a directory to the file path. |
938 | Please see AppendDir() for important notes. | |
23324ae1 FM |
939 | */ |
940 | void PrependDir(const wxString& dir); | |
941 | ||
942 | /** | |
943 | Removes the specified directory component from the path. | |
3c4f71cc | 944 | |
4cc4bfaf | 945 | @see GetDirCount() |
23324ae1 FM |
946 | */ |
947 | void RemoveDir(size_t pos); | |
948 | ||
949 | /** | |
950 | Removes last directory component from the path. | |
951 | */ | |
952 | void RemoveLastDir(); | |
953 | ||
395f3aa8 FM |
954 | /** |
955 | If the path contains the value of the environment variable named @a envname | |
956 | then this function replaces it with the string obtained from | |
957 | wxString::Format(replacementFmtString, value_of_envname_variable). | |
958 | ||
959 | This function is useful to make the path shorter or to make it dependent | |
960 | from a certain environment variable. | |
961 | Normalize() with @c wxPATH_NORM_ENV_VARS can perform the opposite of this | |
962 | function (depending on the value of @a replacementFmtString). | |
963 | ||
964 | The name and extension of this filename are not modified. | |
965 | ||
966 | Example: | |
967 | @code | |
968 | wxFileName fn("/usr/openwin/lib/someFile"); | |
969 | fn.ReplaceEnvVariable("OPENWINHOME"); | |
970 | // now fn.GetFullPath() == "$OPENWINHOME/lib/someFile" | |
971 | @endcode | |
972 | ||
973 | @since 2.9.0 | |
974 | ||
975 | @return @true if the operation was successful (which doesn't mean | |
976 | that something was actually replaced, just that ::wxGetEnv | |
977 | didn't fail). | |
978 | */ | |
979 | bool ReplaceEnvVariable(const wxString& envname, | |
980 | const wxString& replacementFmtString = "$%s", | |
981 | wxPathFormat format = wxPATH_NATIVE); | |
982 | ||
983 | /** | |
984 | Replaces, if present in the path, the home directory for the given user | |
985 | (see ::wxGetHomeDir) with a tilde (~). | |
986 | ||
987 | Normalize() with @c wxPATH_NORM_TILDE performs the opposite of this | |
988 | function. | |
989 | ||
990 | The name and extension of this filename are not modified. | |
991 | ||
992 | @since 2.9.0 | |
993 | ||
994 | @return @true if the operation was successful (which doesn't mean | |
995 | that something was actually replaced, just that ::wxGetHomeDir | |
996 | didn't fail). | |
997 | */ | |
998 | bool ReplaceHomeDir(wxPathFormat format = wxPATH_NATIVE); | |
999 | ||
1000 | ||
23324ae1 FM |
1001 | /** |
1002 | Deletes the specified directory from the file system. | |
110c5094 VZ |
1003 | |
1004 | @param flags | |
1005 | Can contain one of wxPATH_RMDIR_FULL or wxPATH_RMDIR_RECURSIVE. By | |
1006 | default contains neither so the directory will not be removed | |
1007 | unless it is empty. | |
1008 | ||
1009 | @return Returns @true if the directory was successfully deleted, @false | |
1010 | otherwise. | |
23324ae1 | 1011 | */ |
110c5094 | 1012 | bool Rmdir(int flags = 0); |
0b70c946 | 1013 | |
2bd56258 RR |
1014 | /** |
1015 | Deletes the specified directory from the file system. | |
110c5094 VZ |
1016 | |
1017 | @param dir | |
1018 | The directory to delete | |
1019 | @param flags | |
1020 | Can contain one of wxPATH_RMDIR_FULL or wxPATH_RMDIR_RECURSIVE. By | |
1021 | default contains neither so the directory will not be removed | |
1022 | unless it is empty. | |
1023 | ||
1024 | @return Returns @true if the directory was successfully deleted, @false | |
1025 | otherwise. | |
2bd56258 | 1026 | */ |
110c5094 | 1027 | static bool Rmdir(const wxString& dir, int flags = 0); |
23324ae1 FM |
1028 | |
1029 | /** | |
1030 | Compares the filename using the rules of this platform. | |
1031 | */ | |
1032 | bool SameAs(const wxFileName& filepath, | |
328f5751 | 1033 | wxPathFormat format = wxPATH_NATIVE) const; |
23324ae1 | 1034 | |
23324ae1 FM |
1035 | /** |
1036 | Changes the current working directory. | |
1037 | */ | |
1038 | bool SetCwd(); | |
0b70c946 | 1039 | |
2bd56258 RR |
1040 | /** |
1041 | Changes the current working directory. | |
1042 | */ | |
7c913512 | 1043 | static bool SetCwd(const wxString& cwd); |
23324ae1 FM |
1044 | |
1045 | /** | |
7c913512 FM |
1046 | Sets the extension of the file name to be an empty extension. |
1047 | This is different from having no extension at all as the file | |
23324ae1 | 1048 | name will have a trailing dot after a call to this method. |
3c4f71cc | 1049 | |
4cc4bfaf | 1050 | @see SetExt(), ClearExt() |
23324ae1 FM |
1051 | */ |
1052 | void SetEmptyExt(); | |
1053 | ||
1054 | /** | |
0b70c946 FM |
1055 | Sets the extension of the file name. |
1056 | ||
1057 | Setting an empty string as the extension will remove the extension | |
1058 | resulting in a file name without a trailing dot, unlike a call to | |
23324ae1 | 1059 | SetEmptyExt(). |
3c4f71cc | 1060 | |
4cc4bfaf | 1061 | @see SetEmptyExt(), ClearExt() |
23324ae1 FM |
1062 | */ |
1063 | void SetExt(const wxString& ext); | |
1064 | ||
1065 | /** | |
1066 | The full name is the file name and extension (but without the path). | |
1067 | */ | |
1068 | void SetFullName(const wxString& fullname); | |
1069 | ||
1070 | /** | |
1071 | Sets the name part (without extension). | |
3c4f71cc | 1072 | |
4cc4bfaf | 1073 | @see SetFullName() |
23324ae1 FM |
1074 | */ |
1075 | void SetName(const wxString& name); | |
1076 | ||
1077 | /** | |
1078 | Sets the file creation and last access/modification times (any of the pointers | |
1079 | may be @NULL). | |
1080 | */ | |
1081 | bool SetTimes(const wxDateTime* dtAccess, | |
1082 | const wxDateTime* dtMod, | |
1083 | const wxDateTime* dtCreate); | |
1084 | ||
1085 | /** | |
1086 | Sets the volume specifier. | |
1087 | */ | |
1088 | void SetVolume(const wxString& volume); | |
1089 | ||
1090 | //@{ | |
1091 | /** | |
1092 | This function splits a full file name into components: the volume (with the | |
1093 | first version) path (including the volume in the second version), the base name | |
0b70c946 FM |
1094 | and the extension. |
1095 | ||
1096 | Any of the output parameters (@e volume, @e path, @a name or @e ext) may | |
1097 | be @NULL if you are not interested in the value of a particular component. | |
1098 | Also, @a fullpath may be empty on entry. | |
4cc4bfaf FM |
1099 | On return, @a path contains the file path (without the trailing separator), |
1100 | @a name contains the file name and @a ext contains the file extension | |
23324ae1 FM |
1101 | without leading dot. All three of them may be empty if the corresponding |
1102 | component is. The old contents of the strings pointed to by these parameters | |
1103 | will be overwritten in any case (if the pointers are not @NULL). | |
0b70c946 | 1104 | |
cdbcf4c2 | 1105 | Note that for a filename "foo." the extension is present, as indicated by the |
7c913512 | 1106 | trailing dot, but empty. If you need to cope with such cases, you should use |
4cc4bfaf | 1107 | @a hasExt instead of relying on testing whether @a ext is empty or not. |
23324ae1 | 1108 | */ |
882678eb FM |
1109 | static void SplitPath(const wxString& fullpath, |
1110 | wxString* volume, | |
23324ae1 FM |
1111 | wxString* path, |
1112 | wxString* name, | |
1113 | wxString* ext, | |
882678eb | 1114 | bool* hasExt = NULL, |
23324ae1 | 1115 | wxPathFormat format = wxPATH_NATIVE); |
7c913512 FM |
1116 | static void SplitPath(const wxString& fullpath, |
1117 | wxString* volume, | |
1118 | wxString* path, | |
1119 | wxString* name, | |
1120 | wxString* ext, | |
882678eb | 1121 | wxPathFormat format); |
7c913512 FM |
1122 | static void SplitPath(const wxString& fullpath, |
1123 | wxString* path, | |
1124 | wxString* name, | |
1125 | wxString* ext, | |
1126 | wxPathFormat format = wxPATH_NATIVE); | |
23324ae1 FM |
1127 | //@} |
1128 | ||
1129 | /** | |
4cc4bfaf | 1130 | Splits the given @a fullpath into the volume part (which may be empty) and |
23324ae1 | 1131 | the pure path part, not containing any volume. |
3c4f71cc | 1132 | |
4cc4bfaf | 1133 | @see SplitPath() |
23324ae1 FM |
1134 | */ |
1135 | static void SplitVolume(const wxString& fullpath, | |
1136 | wxString* volume, | |
1137 | wxString* path, | |
1138 | wxPathFormat format = wxPATH_NATIVE); | |
1139 | ||
1140 | /** | |
1141 | Sets the access and modification times to the current moment. | |
1142 | */ | |
1143 | bool Touch(); | |
1144 | ||
23324ae1 FM |
1145 | /** |
1146 | Returns @true if the filenames are different. The string @e filenames | |
1147 | is interpreted as a path in the native filename format. | |
1148 | */ | |
0b70c946 FM |
1149 | bool operator!=(const wxFileName& filename) const; |
1150 | ||
2bd56258 RR |
1151 | /** |
1152 | Returns @true if the filenames are different. The string @e filenames | |
1153 | is interpreted as a path in the native filename format. | |
1154 | */ | |
0b70c946 | 1155 | bool operator!=(const wxString& filename) const; |
23324ae1 | 1156 | |
23324ae1 | 1157 | /** |
0b70c946 FM |
1158 | Returns @true if the filenames are equal. The string @e filenames is |
1159 | interpreted as a path in the native filename format. | |
2bd56258 | 1160 | */ |
0b70c946 | 1161 | bool operator==(const wxFileName& filename) const; |
23324ae1 | 1162 | |
23324ae1 FM |
1163 | /** |
1164 | Returns @true if the filenames are equal. The string @e filenames is | |
1165 | interpreted as a path in the native filename format. | |
1166 | */ | |
0b70c946 FM |
1167 | bool operator==(const wxString& filename) const; |
1168 | ||
2bd56258 | 1169 | /** |
0b70c946 FM |
1170 | Assigns the new value to this filename object. |
1171 | */ | |
1172 | wxFileName& operator=(const wxFileName& filename); | |
1173 | ||
1174 | /** | |
1175 | Assigns the new value to this filename object. | |
2bd56258 | 1176 | */ |
0b70c946 | 1177 | wxFileName& operator=(const wxString& filename); |
23324ae1 | 1178 | }; |