1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxFileName
4 // Author: wxWidgets team
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
11 The various values for the path format: this mainly affects the path
12 separator but also whether or not the path has the drive part
15 See wxFileName for more info.
19 wxPATH_NATIVE
= 0, //!< the path format for the current platform.
21 wxPATH_BEOS
= wxPATH_UNIX
,
24 wxPATH_WIN
= wxPATH_DOS
,
25 wxPATH_OS2
= wxPATH_DOS
,
28 wxPATH_MAX
//!< Not a valid value for specifying path format
32 Different conventions for human readable sizes.
34 @see wxFileName::GetHumanReadableSize().
41 wxSIZE_CONV_TRADITIONAL
,
43 /// 1024 bytes = 1KiB.
52 The kind of normalization to do with the file name: these values can be
53 or'd together to perform several operations at once.
54 See wxFileName::Normalize() for more info.
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,
64 wxPATH_NORM_DOTS
= 0x0002, //!< Squeeze all @c ".." and @c ".".
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).
71 //! A value indicating all normalization flags except for @c wxPATH_NORM_CASE.
72 wxPATH_NORM_ALL
= 0x00ff & ~wxPATH_NORM_CASE
76 Flags for wxFileName::Rmdir().
80 /// Delete the specified directory and its subdirectories if they are empty.
81 wxPATH_RMDIR_FULL
= 1,
84 Delete the specified directory and all the files and subdirectories in it
87 This flag is obviously @b dangerous and should be used with care and
88 after asking the user for confirmation.
90 wxPATH_RMDIR_RECURSIVE
= 2
94 Flags for wxFileName::Exists().
100 wxFILE_EXISTS_REGULAR
= 0x0001, //!< Check for existence of a regular file
101 wxFILE_EXISTS_DIR
= 0x0002, //!< Check for existence of a directory
103 Check for existence of a symlink.
105 Notice that this flag should be used either with
106 ::wxFILE_EXISTS_NO_FOLLOW or with a wxFileName object on which
107 wxFileName::DontFollowLink() had been called, otherwise it would never
108 be satisfied as wxFileName::Exists() would be checking for the
109 existence of the symlink target and not the symlink itself.
111 wxFILE_EXISTS_SYMLINK
= 0x0004,
112 wxFILE_EXISTS_DEVICE
= 0x0008, //!< Check for existence of a device
113 wxFILE_EXISTS_FIFO
= 0x0016, //!< Check for existence of a FIFO
114 wxFILE_EXISTS_SOCKET
= 0x0032, //!< Check for existence of a socket
115 wxFILE_EXISTS_ANY
= 0x0FFF, //!< Check for existence of anything
116 wxFILE_EXISTS_NO_FOLLOW
= 0x1000 //!< Don't dereference a contained symbolic link
120 The return value of wxFileName::GetSize() in case of error.
122 wxULongLong wxInvalidSize
;
128 wxFileName encapsulates a file name.
130 This class serves two purposes: first, it provides the functions to split the
131 file names into components and to recombine these components in the full file
132 name which can then be passed to the OS file functions
133 (and @ref group_funcmacro_file "wxWidgets functions" wrapping them).
134 Second, it includes the functions for working with the files itself. Note that
135 to change the file data you should use wxFile class instead.
136 wxFileName provides functions for working with the file attributes.
138 When working with directory names (i.e. without filename and extension)
139 make sure not to misuse the file name part of this class with the last
140 directory. Instead initialize the wxFileName instance like this:
143 wxFileName dirname( "C:\mydir", "" );
144 MyMethod( dirname.GetPath() );
147 The same can be done using the static method wxFileName::DirName():
150 wxFileName dirname = wxFileName::DirName( "C:\mydir" );
151 MyMethod( dirname.GetPath() );
154 Accordingly, methods dealing with directories or directory names like
155 wxFileName::IsDirReadable() use wxFileName::GetPath() whereas methods dealing
156 with file names like wxFileName::IsFileReadable() use wxFileName::GetFullPath().
158 If it is not known whether a string contains a directory name or a complete
159 file name (such as when interpreting user input) you need to use the static
160 function wxFileName::DirExists() (or its identical variants wxDir::Exists() and
161 wxDirExists()) and construct the wxFileName instance accordingly.
162 This will only work if the directory actually exists, of course:
166 // get input from user
169 if (wxDirExists(user_input))
170 fname.AssignDir( user_input );
172 fname.Assign( user_input );
175 Please note that many wxFileName methods accept the path format argument
176 which is by @c wxPATH_NATIVE by default meaning to use the path format
177 native for the current platform.
178 The path format affects the operation of wxFileName functions in several ways:
179 first and foremost, it defines the path separator character to use, but it
180 also affects other things such as whether the path has the drive part or not.
181 See wxPathFormat for more info.
184 @section filename_format File name format
186 wxFileName currently supports the file names in the Unix, DOS/Windows,
187 Mac OS and VMS formats. Although these formats are quite different,
188 wxFileName tries to treat them all in the same generic way.
189 It supposes that all file names consist of the following parts: the volume
190 (also known as drive under Windows or device under VMS), the path which is
191 a sequence of directory names separated by the path separators and the full
192 filename itself which, in turn, is composed from the base file name and the
193 extension. All of the individual components of the file name may be empty
194 and, for example, the volume name is always empty under Unix, but if they
195 are all empty simultaneously, the filename object is considered to be in an
196 invalid state and wxFileName::IsOk() returns false for it.
198 File names can be case-sensitive or not, the function wxFileName::IsCaseSensitive()
199 allows to determine this. The rules for determining whether the file name is
200 absolute or relative also depend on the file name format and the only portable way
201 to answer this question is to use wxFileName::IsAbsolute() or wxFileName::IsRelative()
204 Note that on Windows,"X:" refers to the current working directory on drive X.
205 Therefore, a wxFileName instance constructed from for example "X:dir/file.ext"
206 treats the portion beyond drive separator as being relative to that directory.
207 To ensure that the filename is absolute, you may use wxFileName::MakeAbsolute().
208 There is also an inverse function wxFileName::MakeRelativeTo() which undoes
209 what wxFileName::Normalize(wxPATH_NORM_DOTS) does.
210 Other functions returning information about the file format provided by this
211 class are wxFileName::GetVolumeSeparator(), wxFileName::IsPathSeparator().
214 @section filename_construction File name construction
216 You can initialize a wxFileName instance using one of the following functions:
218 @li wxFileName::wxFileName()
219 @li wxFileName::Assign()
220 @li wxFileName::AssignCwd()
221 @li wxFileName::AssignDir()
222 @li wxFileName::AssignHomeDir()
223 @li wxFileName::AssignTempFileName()
224 @li wxFileName::DirName()
225 @li wxFileName::FileName()
226 @li wxFileName::operator=()
229 @section filename_tests File name tests
231 Before doing other tests, you should use wxFileName::IsOk() to verify that
232 the filename is well defined. If it is, FileExists() can be used to test whether
233 a file with such name exists and wxFileName::DirExists() can be used to test
234 for directory existence.
235 File names should be compared using the wxFileName::SameAs() method or
236 wxFileName::operator==(). For testing basic access modes, you can use:
238 @li wxFileName::IsDirWritable()
239 @li wxFileName::IsDirReadable()
240 @li wxFileName::IsFileWritable()
241 @li wxFileName::IsFileReadable()
242 @li wxFileName::IsFileExecutable()
245 @section filename_components File name components
247 These functions allow to examine and modify the individual directories
250 @li wxFileName::AppendDir()
251 @li wxFileName::InsertDir()
252 @li wxFileName::GetDirCount()
253 @li wxFileName::PrependDir()
254 @li wxFileName::RemoveDir()
255 @li wxFileName::RemoveLastDir()
257 To change the components of the file name individually you can use the
260 @li wxFileName::GetExt()
261 @li wxFileName::GetName()
262 @li wxFileName::GetVolume()
263 @li wxFileName::HasExt()
264 @li wxFileName::HasName()
265 @li wxFileName::HasVolume()
266 @li wxFileName::SetExt()
267 @li wxFileName::ClearExt()
268 @li wxFileName::SetEmptyExt()
269 @li wxFileName::SetName()
270 @li wxFileName::SetVolume()
272 You can initialize a wxFileName instance using one of the following functions:
275 @section filename_operations File name operations
277 These methods allow to work with the file creation, access and modification
278 times. Note that not all filesystems under all platforms implement these times
279 in the same way. For example, the access time under Windows has a resolution of
280 one day (so it is really the access date and not time). The access time may be
281 updated when the file is executed or not depending on the platform.
283 @li wxFileName::GetModificationTime()
284 @li wxFileName::GetTimes()
285 @li wxFileName::SetTimes()
286 @li wxFileName::Touch()
288 Other file system operations functions are:
290 @li wxFileName::Mkdir()
291 @li wxFileName::Rmdir()
308 wxFileName(const wxFileName
& filename
);
311 Constructor taking a full filename.
313 If it terminates with a '/', a directory path is constructed
314 (the name will be empty), otherwise a file name and extension
315 are extracted from it.
317 wxFileName(const wxString
& fullpath
,
318 wxPathFormat format
= wxPATH_NATIVE
);
321 Constructor a directory name and file name.
323 wxFileName(const wxString
& path
, const wxString
& name
,
324 wxPathFormat format
= wxPATH_NATIVE
);
327 Constructor from a directory name, base file name and extension.
329 wxFileName(const wxString
& path
, const wxString
& name
,
331 wxPathFormat format
= wxPATH_NATIVE
);
334 Constructor from a volume name, a directory name, base file name and extension.
336 wxFileName(const wxString
& volume
, const wxString
& path
,
337 const wxString
& name
,
339 wxPathFormat format
= wxPATH_NATIVE
);
342 Appends a directory component to the path. This component should contain a
343 single directory name level, i.e. not contain any path or volume separators nor
344 should it be empty, otherwise the function does nothing (and generates an
345 assert failure in debug build).
347 void AppendDir(const wxString
& dir
);
350 Creates the file name from another filename object.
352 void Assign(const wxFileName
& filepath
);
355 Creates the file name from a full file name with a path.
357 void Assign(const wxString
& fullpath
,
358 wxPathFormat format
= wxPATH_NATIVE
);
361 Creates the file name from volume, path, name and extension.
363 void Assign(const wxString
& volume
, const wxString
& path
,
364 const wxString
& name
,
367 wxPathFormat format
= wxPATH_NATIVE
);
370 Creates the file name from volume, path, name and extension.
372 void Assign(const wxString
& volume
, const wxString
& path
,
373 const wxString
& name
,
375 wxPathFormat format
= wxPATH_NATIVE
);
378 Creates the file name from file path and file name.
380 void Assign(const wxString
& path
, const wxString
& name
,
381 wxPathFormat format
= wxPATH_NATIVE
);
384 Creates the file name from path, name and extension.
386 void Assign(const wxString
& path
, const wxString
& name
,
388 wxPathFormat format
= wxPATH_NATIVE
);
391 Makes this object refer to the current working directory on the specified
392 volume (or current volume if @a volume is empty).
396 void AssignCwd(const wxString
& volume
= wxEmptyString
);
399 Sets this file name object to the given directory name.
400 The name and extension will be empty.
402 void AssignDir(const wxString
& dir
,
403 wxPathFormat format
= wxPATH_NATIVE
);
406 Sets this file name object to the home directory.
408 void AssignHomeDir();
411 The function calls CreateTempFileName() to create a temporary file
412 and sets this object to the name of the file.
414 If a temporary file couldn't be created, the object is put into
415 an invalid state (see IsOk()).
417 void AssignTempFileName(const wxString
& prefix
);
420 The function calls CreateTempFileName() to create a temporary
421 file name and open @a fileTemp with it.
423 If the file couldn't be opened, the object is put into
424 an invalid state (see IsOk()).
426 void AssignTempFileName(const wxString
& prefix
, wxFile
* fileTemp
);
429 The function calls CreateTempFileName() to create a temporary
430 file name and open @a fileTemp with it.
432 If the file couldn't be opened, the object is put into
433 an invalid state (see IsOk()).
435 void AssignTempFileName(const wxString
& prefix
, wxFFile
* fileTemp
);
438 Reset all components to default, uninitialized state.
443 Removes the extension from the file name resulting in a
444 file name with no trailing dot.
446 @see SetExt(), SetEmptyExt()
452 Returns a temporary file name starting with the given @e prefix.
453 If @a prefix is an absolute path and ends in a separator, the
454 temporary file is created in this directory; if it is an absolute
455 filepath or there is no separator, the temporary file is created in its
456 path, with the 'name' segment prepended to the temporary filename;
457 otherwise it is created in the default system directory for temporary
458 files or in the current directory.
460 If the function succeeds, the temporary file is actually created.
461 If @a fileTemp is not @NULL, this wxFile will be opened using the name of
462 the temporary file. Where possible this is done in an atomic way to ensure that
463 no race condition occurs between creating the temporary file name and opening
464 it, which might lead to a security compromise on multiuser systems.
465 If @a fileTemp is @NULL, the file is created but not opened.
466 Under Unix, the temporary file will have read and write permissions for the
467 owner only, to minimize security problems.
470 Location to use for the temporary file name construction. If @a prefix
471 is a directory it must have a terminal separator
473 The file to open, or @NULL just to get the name
475 @return The full temporary filepath, or an empty string on error.
477 static wxString
CreateTempFileName(const wxString
& prefix
,
478 wxFile
* fileTemp
= NULL
);
481 This is the same as CreateTempFileName(const wxString &prefix, wxFile *fileTemp)
482 but takes a wxFFile parameter instead of wxFile.
484 static wxString
CreateTempFileName(const wxString
& prefix
,
485 wxFFile
* fileTemp
= NULL
);
489 Returns @true if the directory with this name exists.
491 Notice that this function tests the directory part of this object,
492 i.e. the string returned by GetPath(), and not the full path returned
495 @see FileExists(), Exists()
497 bool DirExists() const;
500 Returns @true if the directory with name @a dir exists.
502 @see FileExists(), Exists()
504 static bool DirExists(const wxString
& dir
);
507 Returns the object corresponding to the directory with the given name.
508 The @a dir parameter may have trailing path separator or not.
510 static wxFileName
DirName(const wxString
& dir
,
511 wxPathFormat format
= wxPATH_NATIVE
);
514 Turns off symlink dereferencing.
516 By default, all operations in this class work on the target of a
517 symbolic link (symlink) if the path of the file is actually a symlink.
518 Using this method allows to turn off this "symlink following" behaviour
519 and apply the operations to this path itself, even if it is a symlink.
521 The following methods are currently affected by this option:
522 - GetTimes() (but not SetTimes() as there is no portable way to
523 change the time of symlink itself).
524 - Existence checks: FileExists(), DirExists() and Exists() (notice
525 that static versions of these methods always follow symlinks).
528 @see ShouldFollowLink()
532 void DontFollowLink();
535 Calls the static overload of this function with the full path of this
538 @since 2.9.4 (@a flags is new since 2.9.5)
540 bool Exists(int flags
= wxFILE_EXISTS_ANY
) const;
543 Returns @true if either a file or a directory or something else with
544 this name exists in the file system.
546 Don't dereference @a path if it is a symbolic link and @a flags
547 argument contains ::wxFILE_EXISTS_NO_FOLLOW.
549 This method is equivalent to @code FileExists() || DirExists() @endcode
550 under Windows, but under Unix it also returns true if the file
551 identifies a special file system object such as a device, a socket or a
554 Alternatively you may check for the existence of a file system entry of
555 a specific type by passing the appropriate @a flags (this parameter is
556 new since wxWidgets 2.9.5). E.g. to test for a symbolic link existence
557 you could use ::wxFILE_EXISTS_SYMLINK.
561 @see FileExists(), DirExists()
563 static bool Exists(const wxString
& path
, int flags
= wxFILE_EXISTS_ANY
);
566 Returns @true if the file with this name exists.
568 @see DirExists(), Exists()
570 bool FileExists() const;
573 Returns @true if the file with name @a file exists.
575 @see DirExists(), Exists()
577 static bool FileExists(const wxString
& file
);
580 Returns the file name object corresponding to the given @e file. This
581 function exists mainly for symmetry with DirName().
583 static wxFileName
FileName(const wxString
& file
,
584 wxPathFormat format
= wxPATH_NATIVE
);
587 Retrieves the value of the current working directory on the specified volume.
588 If the volume is empty, the program's current working directory is returned for
591 @return The string containing the current working directory or an empty
596 static wxString
GetCwd(const wxString
& volume
= wxEmptyString
);
599 Returns the number of directories in the file name.
601 size_t GetDirCount() const;
604 Returns the directories in string array form.
606 const wxArrayString
& GetDirs() const;
609 Returns the file name extension.
611 wxString
GetExt() const;
614 Returns the characters that can't be used in filenames and directory names
615 for the specified format.
617 static wxString
GetForbiddenChars(wxPathFormat format
= wxPATH_NATIVE
);
620 Returns the canonical path format for this platform.
622 static wxPathFormat
GetFormat(wxPathFormat format
= wxPATH_NATIVE
);
625 Returns the full name (including extension but excluding directories).
627 wxString
GetFullName() const;
630 Returns the full path with name and extension.
632 wxString
GetFullPath(wxPathFormat format
= wxPATH_NATIVE
) const;
635 Returns the home directory.
637 static wxString
GetHomeDir();
641 Returns the representation of the file size in a human-readable form.
643 In the first version, the size of this file is used. In the second one,
644 the specified size @a bytes is used.
646 If the file size could not be retrieved or @a bytes is ::wxInvalidSize
647 or zero, the @c failmsg string is returned.
649 Otherwise the returned string is a floating-point number with @c
650 precision decimal digits followed by the abbreviation of the unit used.
651 By default the traditional, although incorrect, convention of using SI
652 units for multiples of 1024 is used, i.e. returned string will use
653 suffixes of B, KB, MB, GB, TB for bytes, kilobytes, megabytes,
654 gigabytes and terabytes respectively. With the IEC convention the names
655 of the units are changed to B, KiB, MiB, GiB and TiB for bytes,
656 kibibytes, mebibytes, gibibytes and tebibytes. Finally, with SI
657 convention the same B, KB, MB, GB and TB suffixes are used but in their
658 correct SI meaning, i.e. as multiples of 1000 and not 1024.
660 Support for the different size conventions is new in wxWidgets 2.9.1,
661 in previous versions only the traditional convention was implemented.
664 GetHumanReadableSize(const wxString
& failmsg
= _("Not available"),
666 wxSizeConvention conv
= wxSIZE_CONV_TRADITIONAL
) const;
669 GetHumanReadableSize(const wxULongLong
& bytes
,
670 const wxString
& nullsize
= _("Not available"),
672 wxSizeConvention conv
= wxSIZE_CONV_TRADITIONAL
);
676 Return the long form of the path (returns identity on non-Windows platforms).
678 wxString
GetLongPath() const;
681 Returns the last time the file was last modified.
683 wxDateTime
GetModificationTime() const;
686 Returns the name part of the filename (without extension).
690 wxString
GetName() const;
693 Returns the path part of the filename (without the name or extension).
695 The possible flags values are:
697 - @b wxPATH_GET_VOLUME:
698 Return the path with the volume (does nothing for the filename formats
699 without volumes), otherwise the path without volume part is returned.
701 - @b wxPATH_GET_SEPARATOR:
702 Return the path with the trailing separator, if this flag is not given
703 there will be no separator at the end of the path.
705 - @b wxPATH_NO_SEPARATOR:
706 Don't include the trailing separator in the returned string. This is
707 the default (the value of this flag is 0) and exists only for symmetry
708 with wxPATH_GET_SEPARATOR.
710 @note If the path is a toplevel one (e.g. @c "/" on Unix or @c "C:\" on
711 Windows), then the returned path will contain trailing separator
712 even with @c wxPATH_NO_SEPARATOR.
714 wxString
GetPath(int flags
= wxPATH_GET_VOLUME
,
715 wxPathFormat format
= wxPATH_NATIVE
) const;
718 Returns the usually used path separator for this format.
719 For all formats but @c wxPATH_DOS there is only one path separator anyhow,
720 but for DOS there are two of them and the native one, i.e. the backslash
721 is returned by this method.
723 @see GetPathSeparators()
725 static wxUniChar
GetPathSeparator(wxPathFormat format
= wxPATH_NATIVE
);
728 Returns the string containing all the path separators for this format.
729 For all formats but @c wxPATH_DOS this string contains only one character
730 but for DOS and Windows both @c '/' and @c '\' may be used as separators.
732 @see GetPathSeparator()
734 static wxString
GetPathSeparators(wxPathFormat format
= wxPATH_NATIVE
);
737 Returns the string of characters which may terminate the path part.
738 This is the same as GetPathSeparators() except for VMS
739 path format where ] is used at the end of the path part.
741 static wxString
GetPathTerminators(wxPathFormat format
= wxPATH_NATIVE
);
744 Returns the path with the trailing separator, useful for appending the name
747 This is the same as calling
749 GetPath(wxPATH_GET_VOLUME | wxPATH_GET_SEPARATOR, format)
752 wxString
GetPathWithSep(wxPathFormat format
= wxPATH_NATIVE
) const;
755 Return the short form of the path (returns identity on non-Windows platforms).
757 wxString
GetShortPath() const;
760 Returns the size of the file If the file does not exist or its size could
761 not be read (because e.g. the file is locked by another process) the returned
762 value is ::wxInvalidSize.
764 wxULongLong
GetSize() const;
767 Returns the size of the file If the file does not exist or its size could
768 not be read (because e.g. the file is locked by another process) the returned
769 value is ::wxInvalidSize.
771 static wxULongLong
GetSize(const wxString
& filename
);
774 Returns the directory used for temporary files.
776 static wxString
GetTempDir();
779 Returns the last access, last modification and creation times.
780 The last access time is updated whenever the file is read or written
781 (or executed in the case of Windows), last modification time is only
782 changed when the file is written to.
783 Finally, the creation time is indeed the time when the file was created
784 under Windows and the inode change time under Unix (as it is impossible to
785 retrieve the real file creation time there anyhow) which can also be changed
786 by many operations after the file creation.
788 If no filename or extension is specified in this instance of wxFileName
789 (and therefore IsDir() returns @true) then this function will return the
790 directory times of the path specified by GetPath(), otherwise the file
791 times of the file specified by GetFullPath().
792 Any of the pointers may be @NULL if the corresponding time is not needed.
794 @return @true on success, @false if we failed to retrieve the times.
796 bool GetTimes(wxDateTime
* dtAccess
, wxDateTime
* dtMod
,
797 wxDateTime
* dtCreate
) const;
800 Returns the string containing the volume for this file name, empty if it
801 doesn't have one or if the file system doesn't support volumes at all
804 wxString
GetVolume() const;
807 Returns the string separating the volume from the path for this format.
809 static wxString
GetVolumeSeparator(wxPathFormat format
= wxPATH_NATIVE
);
812 This function builds a volume path string, for example "C:\\".
814 Implemented for the platforms which use drive letters, i.e. DOS, MSW
820 The drive letter, 'A' through 'Z' or 'a' through 'z'.
823 @c wxPATH_NO_SEPARATOR or @c wxPATH_GET_SEPARATOR to omit or include
824 the trailing path separator, the default is to include it.
826 @return Volume path string.
828 static wxString
GetVolumeString(char drive
, int flags
= wxPATH_GET_SEPARATOR
);
831 Returns @true if an extension is present.
836 Returns @true if a name is present.
838 bool HasName() const;
841 Returns @true if a volume specifier is present.
843 bool HasVolume() const;
846 Inserts a directory component before the zero-based position in the directory
847 list. Please see AppendDir() for important notes.
849 void InsertDir(size_t before
, const wxString
& dir
);
852 Returns @true if this filename is absolute.
854 bool IsAbsolute(wxPathFormat format
= wxPATH_NATIVE
) const;
857 Returns @true if the file names of this type are case-sensitive.
859 static bool IsCaseSensitive(wxPathFormat format
= wxPATH_NATIVE
);
862 Returns @true if this object represents a directory, @false otherwise
863 (i.e. if it is a file).
865 Note that this method doesn't test whether the directory or file really
866 exists, you should use DirExists() or FileExists() for this.
871 Returns @true if the directory component of this instance is an existing
872 directory and this process has read permissions on it. Read permissions
873 on a directory mean that you can list the directory contents but it
874 doesn't imply that you have read permissions on the files contained.
876 bool IsDirReadable() const;
879 Returns @true if the given @e dir is an existing directory and this process
880 has read permissions on it. Read permissions on a directory mean that you
881 can list the directory contents but it doesn't imply that you have read
882 permissions on the files contained.
884 static bool IsDirReadable(const wxString
& dir
);
887 Returns @true if the directory component of this instance
888 is an existing directory and this process has write permissions on it.
889 Write permissions on a directory mean that you can create new files in the
892 bool IsDirWritable() const;
895 Returns @true if the given @a dir is an existing directory and this
896 process has write permissions on it.
897 Write permissions on a directory mean that you can create new files in the
900 static bool IsDirWritable(const wxString
& dir
);
903 Returns @true if a file with this name exists and if this process has execute
906 bool IsFileExecutable() const;
909 Returns @true if a file with this name exists and if this process has execute
912 static bool IsFileExecutable(const wxString
& file
);
915 Returns @true if a file with this name exists and if this process has read
918 bool IsFileReadable() const;
921 Returns @true if a file with this name exists and if this process has read
924 static bool IsFileReadable(const wxString
& file
);
927 Returns @true if a file with this name exists and if this process has write
930 bool IsFileWritable() const;
933 Returns @true if a file with this name exists and if this process has write
936 static bool IsFileWritable(const wxString
& file
);
939 Returns @true if the filename is valid, @false if it is not initialized yet.
940 The assignment functions and Clear() may reset the object to the uninitialized,
941 invalid state (the former only do it on failure).
946 Returns @true if the char is a path separator for this format.
948 static bool IsPathSeparator(wxChar ch
,
949 wxPathFormat format
= wxPATH_NATIVE
);
952 Returns @true if the volume part of the path is a unique volume name.
954 This function will always return @false if the path format is not
957 Unique volume names are Windows volume identifiers which remain the same
958 regardless of where the volume is actually mounted. Example of a path
959 using a volume name could be
961 \\?\Volume{8089d7d7-d0ac-11db-9dd0-806d6172696f}\Program Files\setup.exe
966 static bool IsMSWUniqueVolumeNamePath(const wxString
& path
,
967 wxPathFormat format
= wxPATH_NATIVE
);
970 Returns @true if this filename is not absolute.
972 bool IsRelative(wxPathFormat format
= wxPATH_NATIVE
) const;
975 On Mac OS, gets the common type and creator for the given extension.
979 static bool MacFindDefaultTypeAndCreator(const wxString
& ext
,
984 On Mac OS, registers application defined extensions and their default type
989 static void MacRegisterDefaultTypeAndCreator(const wxString
& ext
,
994 On Mac OS, looks up the appropriate type and creator from the registration
999 bool MacSetDefaultTypeAndCreator();
1002 Make the file name absolute.
1003 This is a shortcut for
1005 wxFileName::Normalize(wxPATH_NORM_DOTS | wxPATH_NORM_ABSOLUTE |
1006 wxPATH_NORM_TILDE, cwd, format)
1009 @see MakeRelativeTo(), Normalize(), IsAbsolute()
1011 bool MakeAbsolute(const wxString
& cwd
= wxEmptyString
,
1012 wxPathFormat format
= wxPATH_NATIVE
);
1015 This function tries to put this file name in a form relative to
1017 In other words, it returns the file name which should be used to access
1018 this file if the current directory were pathBase.
1021 The directory to use as root, current directory is used by default
1023 The file name format, native by default
1025 @return @true if the file name has been changed, @false if we failed to do
1026 anything with it (currently this only happens if the file name
1027 is on a volume different from the volume specified by @a pathBase).
1031 bool MakeRelativeTo(const wxString
& pathBase
= wxEmptyString
,
1032 wxPathFormat format
= wxPATH_NATIVE
);
1035 Creates a directory.
1038 The permissions for the newly created directory.
1039 See the ::wxPosixPermissions enumeration for more info.
1041 If the flags contain @c wxPATH_MKDIR_FULL flag, try to create each
1042 directory in the path and also don't return an error if the target
1043 directory already exists.
1045 @return Returns @true if the directory was successfully created, @false
1048 bool Mkdir(int perm
= wxS_DIR_DEFAULT
, int flags
= 0) const;
1051 Creates a directory.
1054 The directory to create
1056 The permissions for the newly created directory.
1057 See the ::wxPosixPermissions enumeration for more info.
1059 If the flags contain @c wxPATH_MKDIR_FULL flag, try to create each
1060 directory in the path and also don't return an error if the target
1061 directory already exists.
1063 @return Returns @true if the directory was successfully created, @false
1066 static bool Mkdir(const wxString
& dir
, int perm
= wxS_DIR_DEFAULT
,
1072 With the default flags value, the path will be made absolute, without
1073 any ".." and "." and all environment variables will be expanded in it.
1075 Notice that in some rare cases normalizing a valid path may result in
1076 an invalid wxFileName object. E.g. normalizing "./" path using
1077 wxPATH_NORM_DOTS but not wxPATH_NORM_ABSOLUTE will result in a
1078 completely empty and thus invalid object. As long as there is a non
1079 empty file name the result of normalization will be valid however.
1082 The kind of normalization to do with the file name. It can be
1083 any or-combination of the ::wxPathNormalize enumeration values.
1085 If not empty, this directory will be used instead of current
1086 working directory in normalization (see @c wxPATH_NORM_ABSOLUTE).
1088 The file name format to use when processing the paths, native by default.
1090 @return @true if normalization was successfully or @false otherwise.
1092 bool Normalize(int flags
= wxPATH_NORM_ALL
,
1093 const wxString
& cwd
= wxEmptyString
,
1094 wxPathFormat format
= wxPATH_NATIVE
);
1097 Prepends a directory to the file path.
1098 Please see AppendDir() for important notes.
1100 void PrependDir(const wxString
& dir
);
1103 Removes the specified directory component from the path.
1107 void RemoveDir(size_t pos
);
1110 Removes last directory component from the path.
1112 void RemoveLastDir();
1115 If the path contains the value of the environment variable named @a envname
1116 then this function replaces it with the string obtained from
1117 wxString::Format(replacementFmtString, value_of_envname_variable).
1119 This function is useful to make the path shorter or to make it dependent
1120 from a certain environment variable.
1121 Normalize() with @c wxPATH_NORM_ENV_VARS can perform the opposite of this
1122 function (depending on the value of @a replacementFmtString).
1124 The name and extension of this filename are not modified.
1128 wxFileName fn("/usr/openwin/lib/someFile");
1129 fn.ReplaceEnvVariable("OPENWINHOME");
1130 // now fn.GetFullPath() == "$OPENWINHOME/lib/someFile"
1135 @return @true if the operation was successful (which doesn't mean
1136 that something was actually replaced, just that ::wxGetEnv
1139 bool ReplaceEnvVariable(const wxString
& envname
,
1140 const wxString
& replacementFmtString
= "$%s",
1141 wxPathFormat format
= wxPATH_NATIVE
);
1144 Replaces, if present in the path, the home directory for the given user
1145 (see ::wxGetHomeDir) with a tilde (~).
1147 Normalize() with @c wxPATH_NORM_TILDE performs the opposite of this
1150 The name and extension of this filename are not modified.
1154 @return @true if the operation was successful (which doesn't mean
1155 that something was actually replaced, just that ::wxGetHomeDir
1158 bool ReplaceHomeDir(wxPathFormat format
= wxPATH_NATIVE
);
1162 Deletes the specified directory from the file system.
1165 Can contain one of wxPATH_RMDIR_FULL or wxPATH_RMDIR_RECURSIVE. By
1166 default contains neither so the directory will not be removed
1169 @return Returns @true if the directory was successfully deleted, @false
1172 bool Rmdir(int flags
= 0) const;
1175 Deletes the specified directory from the file system.
1178 The directory to delete
1180 Can contain one of wxPATH_RMDIR_FULL or wxPATH_RMDIR_RECURSIVE. By
1181 default contains neither so the directory will not be removed
1184 @return Returns @true if the directory was successfully deleted, @false
1187 static bool Rmdir(const wxString
& dir
, int flags
= 0);
1190 Compares the filename using the rules of this platform.
1192 bool SameAs(const wxFileName
& filepath
,
1193 wxPathFormat format
= wxPATH_NATIVE
) const;
1196 Changes the current working directory.
1198 bool SetCwd() const;
1201 Changes the current working directory.
1203 static bool SetCwd(const wxString
& cwd
);
1206 Sets the extension of the file name to be an empty extension.
1207 This is different from having no extension at all as the file
1208 name will have a trailing dot after a call to this method.
1210 @see SetExt(), ClearExt()
1215 Sets the extension of the file name.
1217 Setting an empty string as the extension will remove the extension
1218 resulting in a file name without a trailing dot, unlike a call to
1221 @see SetEmptyExt(), ClearExt()
1223 void SetExt(const wxString
& ext
);
1226 The full name is the file name and extension (but without the path).
1228 void SetFullName(const wxString
& fullname
);
1231 Sets the name part (without extension).
1235 void SetName(const wxString
& name
);
1240 The @a path argument includes both the path and the volume, if
1241 supported by @a format.
1243 Calling this function doesn't affect the name and extension components,
1244 to change them as well you can use Assign() or just an assignment
1249 void SetPath(const wxString
& path
, wxPathFormat format
= wxPATH_NATIVE
);
1252 Sets the file creation and last access/modification times (any of the pointers
1255 bool SetTimes(const wxDateTime
* dtAccess
,
1256 const wxDateTime
* dtMod
,
1257 const wxDateTime
* dtCreate
) const;
1260 Sets the volume specifier.
1262 void SetVolume(const wxString
& volume
);
1265 Return whether some operations will follow symlink.
1267 By default, file operations "follow symlink", i.e. operate on its
1268 target and not on the symlink itself. See DontFollowLink() for more
1273 bool ShouldFollowLink() const;
1277 This function splits a full file name into components: the volume (with the
1278 first version) path (including the volume in the second version), the base name
1281 Any of the output parameters (@e volume, @e path, @a name or @e ext) may
1282 be @NULL if you are not interested in the value of a particular component.
1283 Also, @a fullpath may be empty on entry.
1284 On return, @a path contains the file path (without the trailing separator),
1285 @a name contains the file name and @a ext contains the file extension
1286 without leading dot. All three of them may be empty if the corresponding
1287 component is. The old contents of the strings pointed to by these parameters
1288 will be overwritten in any case (if the pointers are not @NULL).
1290 Note that for a filename "foo." the extension is present, as indicated by the
1291 trailing dot, but empty. If you need to cope with such cases, you should use
1292 @a hasExt instead of relying on testing whether @a ext is empty or not.
1294 static void SplitPath(const wxString
& fullpath
,
1299 bool* hasExt
= NULL
,
1300 wxPathFormat format
= wxPATH_NATIVE
);
1301 static void SplitPath(const wxString
& fullpath
,
1306 wxPathFormat format
);
1307 static void SplitPath(const wxString
& fullpath
,
1311 wxPathFormat format
= wxPATH_NATIVE
);
1315 Splits the given @a fullpath into the volume part (which may be empty) and
1316 the pure path part, not containing any volume.
1320 static void SplitVolume(const wxString
& fullpath
,
1323 wxPathFormat format
= wxPATH_NATIVE
);
1327 Strip the file extension.
1329 This function does more than just removing everything after the last
1330 period from the string, for example it will return the string ".vimrc"
1331 unchanged because the part after the period is not an extension but the
1332 file name in this case. You can use wxString::BeforeLast() to really
1333 get just the part before the last period (but notice that that function
1334 returns empty string if period is not present at all unlike this
1335 function which returns the @a fullname unchanged in this case).
1338 File path including name and, optionally, extension.
1341 File path without extension
1345 static wxString
StripExtension(const wxString
& fullname
);
1348 Sets the access and modification times to the current moment.
1353 Returns @true if the filenames are different. The string @e filenames
1354 is interpreted as a path in the native filename format.
1356 bool operator!=(const wxFileName
& filename
) const;
1359 Returns @true if the filenames are different. The string @e filenames
1360 is interpreted as a path in the native filename format.
1362 bool operator!=(const wxString
& filename
) const;
1365 Returns @true if the filenames are equal. The string @e filenames is
1366 interpreted as a path in the native filename format.
1368 bool operator==(const wxFileName
& filename
) const;
1371 Returns @true if the filenames are equal. The string @e filenames is
1372 interpreted as a path in the native filename format.
1374 bool operator==(const wxString
& filename
) const;
1377 Assigns the new value to this filename object.
1379 wxFileName
& operator=(const wxFileName
& filename
);
1382 Assigns the new value to this filename object.
1384 wxFileName
& operator=(const wxString
& filename
);