]>
git.saurik.com Git - wxWidgets.git/blob - interface/wx/filename.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxFileName
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
12 wxFileName encapsulates a file name. This class serves two purposes: first, it
13 provides the functions to split the file names into components and to recombine
14 these components in the full file name which can then be passed to the OS file
15 functions (and @ref overview_filefunctions "wxWidgets functions" wrapping them).
16 Second, it includes the functions for working with the files itself. Note that
17 to change the file data you should use wxFile class instead.
18 wxFileName provides functions for working with the file attributes.
20 When working with directory names (i.e. without filename and extension)
21 make sure not to misuse the file name part of this class with the last
22 directory. Instead initialize the wxFileName instance like this:
25 wxFileName dirname( "C:\mydir", "" );
26 MyMethod( dirname.GetPath() );
29 The same can be done using the static method wxFileName::DirName:
32 wxFileName dirname = wxFileName::DirName( "C:\mydir" );
33 MyMethod( dirname.GetPath() );
36 Accordingly, methods dealing with directories or directory names
37 like wxFileName::IsDirReadable use
38 wxFileName::GetPath whereas methods dealing
39 with file names like wxFileName::IsFileReadable
40 use wxFileName::GetFullPath.
42 If it is not known wether a string contains a directory name or
43 a complete file name (such as when interpreting user input) you need to use
44 the static function wxFileName::DirExists
45 (or its identical variants wxDir::Exists and
46 wxDirExists()) and construct the wxFileName
47 instance accordingly. This will only work if the directory actually exists,
52 // get input from user
55 if (wxDirExists(user_input))
56 fname.AssignDir( user_input );
58 fname.Assign( user_input );
61 These functions allow to examine and modify the individual directories
71 To change the components of the file name individually you can use the
86 You can initialize a wxFileName instance using one of the following functions:
96 wxFileName currently supports the file names in the Unix, DOS/Windows, Mac OS
97 and VMS formats (Mac OS no longer being maintained as OS X uses the Unix notation).
98 Although these formats are quite different, wxFileName tries to treat them all
99 in the same generic way. It supposes that all file names consist of the following
100 parts: the volume (also known as drive under Windows or device under VMS), the
101 path which is a sequence of directory names separated by the
102 @ref getpathseparators() "path separators"
103 and the full filename itself which, in turn, is composed from the base file name
104 and the extension. All of the individual components of the file name may be empty
105 and, for example, the volume name is always empty under Unix, but if they are all
106 empty simultaneously, the filename object is considered to be in an invalid
107 state and IsOk() returns @false for it.
108 File names can be case-sensitive or not, the function IsCaseSensitive() allows to
109 determine this. The rules for determining whether the file name is absolute or
110 relative also depend on the file name format and the only portable way to answer
111 this question is to use IsAbsolute() or IsRelative() method. Note that on Windows,
112 "X:" refers to the current working directory on drive X. Therefore, a wxFileName
113 instance constructed from for example "X:dir/file.ext" treats the portion beyond
114 drive separator as being relative to that directory. To ensure that the filename
115 is absolute, you may use MakeAbsolute(). There is also an inverse function
116 MakeRelativeTo() which undoes what Normalize(wxPATH_NORM_DOTS) does.
117 Other functions returning information about the file format provided by this
118 class are GetVolumeSeparator(), IsPathSeparator().
120 Before doing other tests, you should use IsOk() to verify that the filename
121 is well defined. If it is, FileExists() can be used to test whether a file
122 with such name exists and DirExists() can be used to test for directory existence.
123 File names should be compared using the SameAs() method or operator=(). For testing
124 basic access modes, you can use:
130 @li IsFileExecutable()
132 These methods allow to work with the file creation, access and modification
133 times. Note that not all filesystems under all platforms implement these times
134 in the same way. For example, the access time under Windows has a resolution of
135 one day (so it is really the access date and not time). The access time may be
136 updated when the file is executed or not depending on the platform.
138 @li GetModificationTime()
143 Other file system operations functions are:
152 @see wxFileName::GetCwd
164 wxFileName(const wxFileName
& filename
);
166 Constructor from a full file name including the path.
168 wxFileName(const wxString
& fullpath
,
169 wxPathFormat format
= wxPATH_NATIVE
);
171 Constructor a directory name and file name.
173 wxFileName(const wxString
& path
, const wxString
& name
,
174 wxPathFormat format
= wxPATH_NATIVE
);
176 Constructor from a directory name, base file name and extension.
178 wxFileName(const wxString
& path
, const wxString
& name
,
180 wxPathFormat format
= wxPATH_NATIVE
);
182 Constructor from a volume name, a directory name, base file name and extension.
184 wxFileName(const wxString
& volume
, const wxString
& path
,
185 const wxString
& name
,
187 wxPathFormat format
= wxPATH_NATIVE
);
190 Appends a directory component to the path. This component should contain a
191 single directory name level, i.e. not contain any path or volume separators nor
192 should it be empty, otherwise the function does nothing (and generates an
193 assert failure in debug build).
195 void AppendDir(const wxString
& dir
);
198 Creates the file name from another filename object.
200 void Assign(const wxFileName
& filepath
);
202 Creates the file name from a full file name with a path.
204 void Assign(const wxString
& fullpath
,
205 wxPathFormat format
= wxPATH_NATIVE
);
207 Creates the file name from volumne, path, name and extension.
209 void Assign(const wxString
& volume
, const wxString
& path
,
210 const wxString
& name
,
213 wxPathFormat format
= wxPATH_NATIVE
);
215 Creates the file name from volumne, path, name and extension.
217 void Assign(const wxString
& volume
, const wxString
& path
,
218 const wxString
& name
,
220 wxPathFormat format
= wxPATH_NATIVE
);
222 Creates the file name from file path and file name.
224 void Assign(const wxString
& path
, const wxString
& name
,
225 wxPathFormat format
= wxPATH_NATIVE
);
227 Creates the file name from path, name and extension.
229 void Assign(const wxString
& path
, const wxString
& name
,
231 wxPathFormat format
= wxPATH_NATIVE
);
234 Makes this object refer to the current working directory on the specified
235 volume (or current volume if @a volume is empty).
239 static void AssignCwd(const wxString
& volume
= wxEmptyString
);
242 Sets this file name object to the given directory name. The name and extension
245 void AssignDir(const wxString
& dir
,
246 wxPathFormat format
= wxPATH_NATIVE
);
249 Sets this file name object to the home directory.
251 void AssignHomeDir();
254 The function calls CreateTempFileName() to
255 create a temporary file and sets this object to the name of the file. If a
256 temporary file couldn't be created, the object is put into the
257 @ref isok() invalid state.
259 void AssignTempFileName(const wxString
& prefix
,
260 wxFile
* fileTemp
= NULL
);
263 Reset all components to default, uninitialized state.
268 Removes the extension from the file name resulting in a
269 file name with no trailing dot.
271 @see SetExt(), SetEmptyExt()
276 Returns a temporary file name starting with the given @e prefix. If
277 the @a prefix is an absolute path, the temporary file is created in this
278 directory, otherwise it is created in the default system directory for the
279 temporary files or in the current directory.
280 If the function succeeds, the temporary file is actually created. If
281 @a fileTemp is not @NULL, this file will be opened using the name of
282 the temporary file. When possible, this is done in an atomic way ensuring that
283 no race condition occurs between the temporary file name generation and opening
284 it which could often lead to security compromise on the multiuser systems.
285 If @a fileTemp is @NULL, the file is only created, but not opened.
286 Under Unix, the temporary file will have read and write permissions for the
287 owner only to minimize the security problems.
290 Prefix to use for the temporary file name construction
292 The file to open or @NULL to just get the name
294 @return The full temporary file name or an empty string on error.
296 static wxString
CreateTempFileName(const wxString
& prefix
,
297 wxFile
* fileTemp
= NULL
);
300 Returns @true if the directory with this name exists.
305 Returns @true if the directory with this name exists.
307 const static bool DirExists(const wxString
& dir
);
310 Returns the object corresponding to the directory with the given name.
311 The @a dir parameter may have trailing path separator or not.
313 static wxFileName
DirName(const wxString
& dir
,
314 wxPathFormat format
= wxPATH_NATIVE
);
317 Returns @true if the file with this name exists.
324 Returns @true if the file with this name exists.
328 const static bool FileExists(const wxString
& file
);
331 Returns the file name object corresponding to the given @e file. This
332 function exists mainly for symmetry with DirName().
334 static wxFileName
FileName(const wxString
& file
,
335 wxPathFormat format
= wxPATH_NATIVE
);
338 Retrieves the value of the current working directory on the specified volume. If
339 the volume is empty, the program's current working directory is returned for the
342 @return The string containing the current working directory or an empty
347 static wxString
GetCwd(const wxString
& volume
= "");
350 Returns the number of directories in the file name.
352 size_t GetDirCount() const;
355 Returns the directories in string array form.
357 const wxArrayString
GetDirs() const;
360 Returns the file name extension.
362 wxString
GetExt() const;
365 Returns the characters that can't be used in filenames and directory names for
366 the specified format.
368 static wxString
GetForbiddenChars(wxPathFormat format
= wxPATH_NATIVE
);
371 Returns the canonical path format for this platform.
373 static wxPathFormat
GetFormat(wxPathFormat format
= wxPATH_NATIVE
);
376 Returns the full name (including extension but excluding directories).
378 wxString
GetFullName() const;
381 Returns the full path with name and extension.
383 wxString
GetFullPath(wxPathFormat format
= wxPATH_NATIVE
) const;
386 Returns the home directory.
388 static wxString
GetHomeDir();
391 Returns the size of the file in a human-readable form.
392 If the size could not be retrieved the @c failmsg string
393 is returned. In case of success, the returned string is
394 a floating-point number with @c precision decimal digits
395 followed by the size unit (B, kB, MB, GB, TB: respectively
396 bytes, kilobytes, megabytes, gigabytes, terabytes).
398 wxString
GetHumanReadableSize(const wxString
& failmsg
= "Not available",
402 Returns the size of the given number of bytes in a human-readable form.
403 If @c bytes is @c wxInvalidSize or zero, then @c nullsize is returned.
404 In case of success, the returned string is a floating-point number with @c
405 precision decimal digits followed by the size unit (B, kB, MB, GB,
406 TB: respectively bytes, kilobytes, megabytes, gigabytes, terabytes).
408 const static wxString
GetHumanReadableSize(const wxULongLong
& bytes
,
409 const wxString
& nullsize
= "Not available",
413 Return the long form of the path (returns identity on non-Windows platforms)
415 wxString
GetLongPath() const;
418 Returns the last time the file was last modified.
420 wxDateTime
GetModificationTime() const;
423 Returns the name part of the filename (without extension).
427 wxString
GetName() const;
430 Returns the path part of the filename (without the name or extension). The
431 possible flags values are:
435 Return the path with the volume (does nothing for the filename formats without
436 volumes), otherwise the path without volume part is returned.
438 @b wxPATH_GET_SEPARATOR
440 Return the path with the trailing separator, if this flag is not given there
441 will be no separator at the end of the path.
443 wxString
GetPath(int flags
= wxPATH_GET_VOLUME
,
444 wxPathFormat format
= wxPATH_NATIVE
) const;
447 Returns the usually used path separator for this format. For all formats but
448 @c wxPATH_DOS there is only one path separator anyhow, but for DOS there
449 are two of them and the native one, i.e. the backslash is returned by this
452 @see GetPathSeparators()
454 static wxChar
GetPathSeparator(wxPathFormat format
= wxPATH_NATIVE
);
457 Returns the string containing all the path separators for this format. For all
458 formats but @c wxPATH_DOS this string contains only one character but for
459 DOS and Windows both @c '/' and @c '\' may be used as
462 @see GetPathSeparator()
464 static wxString
GetPathSeparators(wxPathFormat format
= wxPATH_NATIVE
);
467 Returns the string of characters which may terminate the path part. This is the
468 same as GetPathSeparators() except for VMS
469 path format where ] is used at the end of the path part.
471 static wxString
GetPathTerminators(wxPathFormat format
= wxPATH_NATIVE
);
474 Returns the path with the trailing separator, useful for appending the name to
476 This is the same as calling GetPath()
477 @c (wxPATH_GET_VOLUME | wxPATH_GET_SEPARATOR, format).
479 wxString
GetPathWithSep(wxPathFormat format
= wxPATH_NATIVE
) const;
482 Return the short form of the path (returns identity on non-Windows platforms).
484 wxString
GetShortPath() const;
487 Returns the size of the file If the file does not exist or its size could
488 not be read (because e.g. the file is locked by another process) the returned
489 value is @c wxInvalidSize.
491 wxULongLong
GetSize();
493 Returns the size of the file If the file does not exist or its size could
494 not be read (because e.g. the file is locked by another process) the returned
495 value is @c wxInvalidSize.
497 const static wxULongLong
GetSize(const wxString
& filename
);
500 Returns the directory used for temporary files.
502 static wxString
GetTempDir();
505 Returns the last access, last modification and creation times. The last access
506 time is updated whenever the file is read or written (or executed in the case
507 of Windows), last modification time is only changed when the file is written
508 to. Finally, the creation time is indeed the time when the file was created
509 under Windows and the inode change time under Unix (as it is impossible to
510 retrieve the real file creation time there anyhow) which can also be changed
511 by many operations after the file creation.
512 If no filename or extension is specified in this instance of wxFileName
513 (and therefore IsDir() returns @true) then
514 this function will return the directory times of the path specified by
515 GetPath(), otherwise the file times of the
516 file specified by GetFullPath().
517 Any of the pointers may be @NULL if the corresponding time is not
520 @return @true on success, @false if we failed to retrieve the times.
522 bool GetTimes(wxDateTime
* dtAccess
, wxDateTime
* dtMod
,
523 wxDateTime
* dtCreate
) const;
526 Returns the string containing the volume for this file name, empty if it
527 doesn't have one or if the file system doesn't support volumes at all (for
530 wxString
GetVolume() const;
533 Returns the string separating the volume from the path for this format.
535 static wxString
GetVolumeSeparator(wxPathFormat format
= wxPATH_NATIVE
);
538 Returns @true if an extension is present.
543 Returns @true if a name is present.
545 bool HasName() const;
548 Returns @true if a volume specifier is present.
550 bool HasVolume() const;
553 Inserts a directory component before the zero-based position in the directory
554 list. Please see AppendDir() for important notes.
556 void InsertDir(size_t before
, const wxString
& dir
);
559 Returns @true if this filename is absolute.
561 bool IsAbsolute(wxPathFormat format
= wxPATH_NATIVE
) const;
564 Returns @true if the file names of this type are case-sensitive.
566 static bool IsCaseSensitive(wxPathFormat format
= wxPATH_NATIVE
);
569 Returns @true if this object represents a directory, @false otherwise
570 (i.e. if it is a file). Note that this method doesn't test whether the
571 directory or file really exists, you should use
573 FileExists() for this.
578 Returns @true if the directory component of this instance is an existing
579 directory and this process has read permissions on it. Read permissions
580 on a directory mean that you can list the directory contents but it
581 doesn't imply that you have read permissions on the files contained.
583 bool IsDirReadable() const;
586 Returns @true if the given @e dir is an existing directory and this process
587 has read permissions on it. Read permissions on a directory mean that you
588 can list the directory contents but it doesn't imply that you have read
589 permissions on the files contained.
591 static bool IsDirReadable(const wxString
& dir
);
594 Returns @true if the directory component of this instance
595 is an existing directory and this process has write permissions on it.
596 Write permissions on a directory mean that you can create new files in the
599 bool IsDirWritable() const;
601 Returns @true if the given @e dir
602 is an existing directory and this process has write permissions on it.
603 Write permissions on a directory mean that you can create new files in the
606 static bool IsDirWritable(const wxString
& dir
);
609 Returns @true if a file with this name exists and if this process has execute
612 bool IsFileExecutable() const;
615 Returns @true if a file with this name exists and if this process has execute
618 static bool IsFileExecutable(const wxString
& file
);
621 Returns @true if a file with this name exists and if this process has read
624 bool IsFileReadable() const;
627 Returns @true if a file with this name exists and if this process has read
630 static bool IsFileReadable(const wxString
& file
);
633 Returns @true if a file with this name exists and if this process has write
636 bool IsFileWritable() const;
638 Returns @true if a file with this name exists and if this process has write
641 static bool IsFileWritable(const wxString
& file
);
644 Returns @true if the filename is valid, @false if it is not
645 initialized yet. The assignment functions and
646 Clear() may reset the object to the uninitialized,
647 invalid state (the former only do it on failure).
652 Returns @true if the char is a path separator for this format.
654 static bool IsPathSeparator(wxChar ch
,
655 wxPathFormat format
= wxPATH_NATIVE
);
658 Returns @true if this filename is not absolute.
660 bool IsRelative(wxPathFormat format
= wxPATH_NATIVE
) const;
663 On Mac OS, gets the common type and creator for the given extension.
665 static bool MacFindDefaultTypeAndCreator(const wxString
& ext
,
670 On Mac OS, registers application defined extensions and their default type and
673 static void MacRegisterDefaultTypeAndCreator(const wxString
& ext
,
678 On Mac OS, looks up the appropriate type and creator from the registration and
681 bool MacSetDefaultTypeAndCreator();
684 Make the file name absolute. This is a shortcut for
685 @c wxFileName::Normalize(wxPATH_NORM_DOTS | wxPATH_NORM_ABSOLUTE |
686 wxPATH_NORM_TILDE, cwd, format).
688 @see MakeRelativeTo(), Normalize(), IsAbsolute()
690 bool MakeAbsolute(const wxString
& cwd
= wxEmptyString
,
691 wxPathFormat format
= wxPATH_NATIVE
);
694 This function tries to put this file name in a form relative to
697 In other words, it returns the file name which should be used to access this
698 file if the current directory were pathBase.
701 the directory to use as root, current directory is used by
704 the file name format, native by default
706 @return @true if the file name has been changed, @false if we failed to do
707 anything with it (currently this only happens if the
708 file name is on a volume different from the volume
709 specified by pathBase).
713 bool MakeRelativeTo(const wxString
& pathBase
= wxEmptyString
,
714 wxPathFormat format
= wxPATH_NATIVE
);
720 the permissions for the newly created directory
722 if the flags contain wxPATH_MKDIR_FULL flag,
723 try to create each directory in the path and also don't return an error
724 if the target directory already exists.
726 @return Returns @true if the directory was successfully created, @false
729 bool Mkdir(int perm
= 0777, int flags
= 0);
734 the directory to create
736 the permissions for the newly created directory
738 if the flags contain wxPATH_MKDIR_FULL flag,
739 try to create each directory in the path and also don't return an error
740 if the target directory already exists.
742 @return Returns @true if the directory was successfully created, @false
745 static bool Mkdir(const wxString
& dir
, int perm
= 0777,
749 Normalize the path. With the default flags value, the path will be
750 made absolute, without any ".." and "." and all environment
751 variables will be expanded in it.
754 The kind of normalization to do with the file name. It can be
755 any or-combination of the following constants:
757 - wxPATH_NORM_ENV_VARS: replace env vars with their values
758 - wxPATH_NORM_DOTS: squeeze all .. and . when possible; if
759 there are too many .. and thus they cannot be all removed,
760 @false will be returned
761 - wxPATH_NORM_CASE: if filesystem is case insensitive, transform
763 - wxPATH_NORM_ABSOLUTE: make the path absolute prepending cwd
764 - wxPATH_NORM_LONG: make the path the long form
765 - wxPATH_NORM_SHORTCUT: resolve if it is a shortcut (Windows only)
766 - wxPATH_NORM_TILDE: replace ~ and ~user (Unix only)
767 - wxPATH_NORM_ALL: all of previous flags except wxPATH_NORM_CASE
770 If not empty, this directory will be used instead of current
771 working directory in normalization (see wxPATH_NORM_ABSOLUTE).
773 The file name format to use when processing the paths, native by default.
775 @return @true if normalization was successfully or @false otherwise.
777 bool Normalize(int flags
= wxPATH_NORM_ALL
,
778 const wxString
& cwd
= wxEmptyString
,
779 wxPathFormat format
= wxPATH_NATIVE
);
783 Prepends a directory to the file path. Please see
784 AppendDir() for important notes.
786 void PrependDir(const wxString
& dir
);
789 Removes the specified directory component from the path.
793 void RemoveDir(size_t pos
);
796 Removes last directory component from the path.
798 void RemoveLastDir();
801 Deletes the specified directory from the file system.
805 Deletes the specified directory from the file system.
807 static bool Rmdir(const wxString
& dir
);
810 Compares the filename using the rules of this platform.
812 bool SameAs(const wxFileName
& filepath
,
813 wxPathFormat format
= wxPATH_NATIVE
) const;
816 Changes the current working directory.
820 Changes the current working directory.
822 static bool SetCwd(const wxString
& cwd
);
825 Sets the extension of the file name to be an empty extension.
826 This is different from having no extension at all as the file
827 name will have a trailing dot after a call to this method.
829 @see SetExt(), ClearExt()
834 Sets the extension of the file name. Setting an empty string
835 as the extension will remove the extension resulting in a file
836 name without a trailing dot, unlike a call to
839 @see SetEmptyExt(), ClearExt()
841 void SetExt(const wxString
& ext
);
844 The full name is the file name and extension (but without the path).
846 void SetFullName(const wxString
& fullname
);
849 Sets the name part (without extension).
853 void SetName(const wxString
& name
);
856 Sets the file creation and last access/modification times (any of the pointers
859 bool SetTimes(const wxDateTime
* dtAccess
,
860 const wxDateTime
* dtMod
,
861 const wxDateTime
* dtCreate
);
864 Sets the volume specifier.
866 void SetVolume(const wxString
& volume
);
870 This function splits a full file name into components: the volume (with the
871 first version) path (including the volume in the second version), the base name
872 and the extension. Any of the output parameters (@e volume, @e path,
873 @a name or @e ext) may be @NULL if you are not interested in the
874 value of a particular component. Also, @a fullpath may be empty on entry.
875 On return, @a path contains the file path (without the trailing separator),
876 @a name contains the file name and @a ext contains the file extension
877 without leading dot. All three of them may be empty if the corresponding
878 component is. The old contents of the strings pointed to by these parameters
879 will be overwritten in any case (if the pointers are not @NULL).
880 Note that for a filename "foo." the extension is present, as indicated by the
881 trailing dot, but empty. If you need to cope with such cases, you should use
882 @a hasExt instead of relying on testing whether @a ext is empty or not.
884 static void SplitPath(const wxString
& fullpath
, wxString
* volume
,
889 wxPathFormat format
= wxPATH_NATIVE
);
890 static void SplitPath(const wxString
& fullpath
,
895 wxPathFormat format
= wxPATH_NATIVE
);
896 static void SplitPath(const wxString
& fullpath
,
900 wxPathFormat format
= wxPATH_NATIVE
);
904 Splits the given @a fullpath into the volume part (which may be empty) and
905 the pure path part, not containing any volume.
909 static void SplitVolume(const wxString
& fullpath
,
912 wxPathFormat format
= wxPATH_NATIVE
);
915 Sets the access and modification times to the current moment.
920 Returns @true if the filenames are different. The string @e filenames
921 is interpreted as a path in the native filename format.
923 bool operator operator!=(const wxFileName
& filename
) const;
925 Returns @true if the filenames are different. The string @e filenames
926 is interpreted as a path in the native filename format.
928 bool operator operator!=(const wxString
& filename
) const;
931 Assigns the new value to this filename object.
933 wxFileName
& operator operator=(const wxFileName
& filename
);
935 Assigns the new value to this filename object.
937 wxFileName
& operator operator=(const wxString
& filename
);
940 Returns @true if the filenames are equal. The string @e filenames is
941 interpreted as a path in the native filename format.
943 bool operator operator==(const wxFileName
& filename
) const;
945 Returns @true if the filenames are equal. The string @e filenames is
946 interpreted as a path in the native filename format.
948 bool operator operator==(const wxString
& filename
) const;