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