1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: wxFileName - encapsulates a file path
4 // Author: Robert Roebling, Vadim Zeitlin
8 // Copyright: (c) 2000 Robert Roebling
9 // Licence: wxWindows licence
10 /////////////////////////////////////////////////////////////////////////////
12 #ifndef _WX_FILENAME_H_
13 #define _WX_FILENAME_H_
18 1. support for drives under Windows
19 2. more file operations:
21 b) [acm]time() - get and set
23 3. SameFileAs() function to compare inodes under Unix
26 #include "wx/arrstr.h"
27 #include "wx/filefn.h"
28 #include "wx/datetime.h"
30 #include "wx/longlong.h"
34 class WXDLLIMPEXP_FWD_BASE wxFile
;
38 class WXDLLIMPEXP_FWD_BASE wxFFile
;
41 // this symbol is defined for the platforms where file systems use volumes in
43 #if defined(__WINDOWS__) || defined(__DOS__) || defined(__OS2__)
44 #define wxHAS_FILESYSTEM_VOLUMES
47 // ----------------------------------------------------------------------------
49 // ----------------------------------------------------------------------------
51 // the various values for the path format: this mainly affects the path
52 // separator but also whether or not the path has the drive part (as under
56 wxPATH_NATIVE
= 0, // the path format for the current platform
58 wxPATH_BEOS
= wxPATH_UNIX
,
61 wxPATH_WIN
= wxPATH_DOS
,
62 wxPATH_OS2
= wxPATH_DOS
,
65 wxPATH_MAX
// Not a valid value for specifying path format
68 // different conventions that may be used with GetHumanReadableSize()
71 wxSIZE_CONV_TRADITIONAL
, // 1024 bytes = 1 KB
72 wxSIZE_CONV_IEC
, // 1024 bytes = 1 KiB
73 wxSIZE_CONV_SI
// 1000 bytes = 1 KB
76 // the kind of normalization to do with the file name: these values can be
77 // or'd together to perform several operations at once
80 wxPATH_NORM_ENV_VARS
= 0x0001, // replace env vars with their values
81 wxPATH_NORM_DOTS
= 0x0002, // squeeze all .. and .
82 wxPATH_NORM_TILDE
= 0x0004, // Unix only: replace ~ and ~user
83 wxPATH_NORM_CASE
= 0x0008, // if case insensitive => tolower
84 wxPATH_NORM_ABSOLUTE
= 0x0010, // make the path absolute
85 wxPATH_NORM_LONG
= 0x0020, // make the path the long form
86 wxPATH_NORM_SHORTCUT
= 0x0040, // resolve the shortcut, if it is a shortcut
87 wxPATH_NORM_ALL
= 0x00ff & ~wxPATH_NORM_CASE
90 // what exactly should GetPath() return?
93 wxPATH_NO_SEPARATOR
= 0x0000, // for symmetry with wxPATH_GET_SEPARATOR
94 wxPATH_GET_VOLUME
= 0x0001, // include the volume if applicable
95 wxPATH_GET_SEPARATOR
= 0x0002 // terminate the path with the separator
101 wxPATH_MKDIR_FULL
= 0x0001 // create directories recursively
107 wxPATH_RMDIR_FULL
= 0x0001, // delete with subdirectories if empty
108 wxPATH_RMDIR_RECURSIVE
= 0x0002 // delete all recursively (dangerous!)
114 wxFILE_EXISTS_REGULAR
= 0x0001, // check for existence of a regular file
115 wxFILE_EXISTS_DIR
= 0x0002, // check for existence of a directory
116 wxFILE_EXISTS_SYMLINK
= 0x0004, // check for existence of a symbolic link
117 wxFILE_EXISTS_DEVICE
= 0x0008, // check for existence of a device
118 wxFILE_EXISTS_FIFO
= 0x0016, // check for existence of a FIFO
119 wxFILE_EXISTS_SOCKET
= 0x0032, // check for existence of a socket
120 // gap for future types
121 wxFILE_EXISTS_ANY
= 0x0FFF, // check for existence of anything
122 wxFILE_EXISTS_NO_FOLLOW
= 0x1000 // don't dereference a contained symlink
126 // error code of wxFileName::GetSize()
127 extern WXDLLIMPEXP_DATA_BASE(const wxULongLong
) wxInvalidSize
;
128 #endif // wxUSE_LONGLONG
132 // ----------------------------------------------------------------------------
133 // wxFileName: encapsulates a file path
134 // ----------------------------------------------------------------------------
136 class WXDLLIMPEXP_BASE wxFileName
139 // constructors and assignment
142 wxFileName() { Clear(); }
143 wxFileName(const wxFileName
& filepath
) { Assign(filepath
); }
145 // from a full filename: if it terminates with a '/', a directory path
146 // is contructed (the name will be empty), otherwise a file name and
147 // extension are extracted from it
148 wxFileName( const wxString
& fullpath
, wxPathFormat format
= wxPATH_NATIVE
)
149 { Assign( fullpath
, format
); m_dontFollowLinks
= false; }
151 // from a directory name and a file name
152 wxFileName(const wxString
& path
,
153 const wxString
& name
,
154 wxPathFormat format
= wxPATH_NATIVE
)
155 { Assign(path
, name
, format
); m_dontFollowLinks
= false; }
157 // from a volume, directory name, file base name and extension
158 wxFileName(const wxString
& volume
,
159 const wxString
& path
,
160 const wxString
& name
,
162 wxPathFormat format
= wxPATH_NATIVE
)
163 { Assign(volume
, path
, name
, ext
, format
); m_dontFollowLinks
= false; }
165 // from a directory name, file base name and extension
166 wxFileName(const wxString
& path
,
167 const wxString
& name
,
169 wxPathFormat format
= wxPATH_NATIVE
)
170 { Assign(path
, name
, ext
, format
); m_dontFollowLinks
= false; }
172 // the same for delayed initialization
174 void Assign(const wxFileName
& filepath
);
176 void Assign(const wxString
& fullpath
,
177 wxPathFormat format
= wxPATH_NATIVE
);
179 void Assign(const wxString
& volume
,
180 const wxString
& path
,
181 const wxString
& name
,
184 wxPathFormat format
= wxPATH_NATIVE
);
186 void Assign(const wxString
& volume
,
187 const wxString
& path
,
188 const wxString
& name
,
190 wxPathFormat format
= wxPATH_NATIVE
)
191 { Assign(volume
, path
, name
, ext
, !ext
.empty(), format
); }
193 void Assign(const wxString
& path
,
194 const wxString
& name
,
195 wxPathFormat format
= wxPATH_NATIVE
);
197 void Assign(const wxString
& path
,
198 const wxString
& name
,
200 wxPathFormat format
= wxPATH_NATIVE
);
202 void AssignDir(const wxString
& dir
, wxPathFormat format
= wxPATH_NATIVE
);
204 // assorted assignment operators
206 wxFileName
& operator=(const wxFileName
& filename
)
207 { if (this != &filename
) Assign(filename
); return *this; }
209 wxFileName
& operator=(const wxString
& filename
)
210 { Assign(filename
); return *this; }
212 // reset all components to default, uninitialized state
215 // static pseudo constructors
216 static wxFileName
FileName(const wxString
& file
,
217 wxPathFormat format
= wxPATH_NATIVE
);
218 static wxFileName
DirName(const wxString
& dir
,
219 wxPathFormat format
= wxPATH_NATIVE
);
223 // is the filename valid at all?
226 // we're fine if we have the path or the name or if we're a root dir
227 return m_dirs
.size() != 0 || !m_name
.empty() || !m_relative
||
228 !m_ext
.empty() || m_hasExt
;
231 // does the file with this name exist?
232 bool FileExists() const;
233 static bool FileExists( const wxString
&file
);
235 // does the directory with this name exist?
236 bool DirExists() const;
237 static bool DirExists( const wxString
&dir
);
239 // does anything at all with this name (i.e. file, directory or some
240 // other file system object such as a device, socket, ...) exist?
241 bool Exists(int flags
= wxFILE_EXISTS_ANY
) const;
242 static bool Exists(const wxString
& path
, int flags
= wxFILE_EXISTS_ANY
);
245 // checks on most common flags for files/directories;
246 // more platform-specific features (like e.g. Unix permissions) are not
247 // available in wxFileName
249 bool IsDirWritable() const { return wxIsWritable(GetPath()); }
250 static bool IsDirWritable(const wxString
&path
) { return wxDirExists(path
) && wxIsWritable(path
); }
252 bool IsDirReadable() const { return wxIsReadable(GetPath()); }
253 static bool IsDirReadable(const wxString
&path
) { return wxDirExists(path
) && wxIsReadable(path
); }
255 // NOTE: IsDirExecutable() is not present because the meaning of "executable"
256 // directory is very platform-dependent and also not so useful
258 bool IsFileWritable() const { return wxIsWritable(GetFullPath()); }
259 static bool IsFileWritable(const wxString
&path
) { return wxFileExists(path
) && wxIsWritable(path
); }
261 bool IsFileReadable() const { return wxIsReadable(GetFullPath()); }
262 static bool IsFileReadable(const wxString
&path
) { return wxFileExists(path
) && wxIsReadable(path
); }
264 bool IsFileExecutable() const { return wxIsExecutable(GetFullPath()); }
265 static bool IsFileExecutable(const wxString
&path
) { return wxFileExists(path
) && wxIsExecutable(path
); }
270 // set the file last access/mod and creation times
271 // (any of the pointers may be NULL)
272 bool SetTimes(const wxDateTime
*dtAccess
,
273 const wxDateTime
*dtMod
,
274 const wxDateTime
*dtCreate
) const;
276 // set the access and modification times to the current moment
279 // return the last access, last modification and create times
280 // (any of the pointers may be NULL)
281 bool GetTimes(wxDateTime
*dtAccess
,
283 wxDateTime
*dtCreate
) const;
285 // convenience wrapper: get just the last mod time of the file
286 wxDateTime
GetModificationTime() const
289 (void)GetTimes(NULL
, &dtMod
, NULL
);
292 #endif // wxUSE_DATETIME
294 #if defined( __WXOSX_MAC__ ) && wxOSX_USE_CARBON
295 bool MacSetTypeAndCreator( wxUint32 type
, wxUint32 creator
) ;
296 bool MacGetTypeAndCreator( wxUint32
*type
, wxUint32
*creator
) const;
297 // gets the 'common' type and creator for a certain extension
298 static bool MacFindDefaultTypeAndCreator( const wxString
& ext
, wxUint32
*type
, wxUint32
*creator
) ;
299 // registers application defined extensions and their default type and creator
300 static void MacRegisterDefaultTypeAndCreator( const wxString
& ext
, wxUint32 type
, wxUint32 creator
) ;
301 // looks up the appropriate type and creator from the registration and then sets
302 bool MacSetDefaultTypeAndCreator() ;
305 // various file/dir operations
307 // retrieve the value of the current working directory
308 void AssignCwd(const wxString
& volume
= wxEmptyString
);
309 static wxString
GetCwd(const wxString
& volume
= wxEmptyString
);
311 // change the current working directory
313 static bool SetCwd( const wxString
&cwd
);
315 // get the value of user home (Unix only mainly)
316 void AssignHomeDir();
317 static wxString
GetHomeDir();
319 // get the system temporary directory
320 static wxString
GetTempDir();
322 #if wxUSE_FILE || wxUSE_FFILE
323 // get a temp file name starting with the specified prefix
324 void AssignTempFileName(const wxString
& prefix
);
325 static wxString
CreateTempFileName(const wxString
& prefix
);
329 // get a temp file name starting with the specified prefix and open the
330 // file passed to us using this name for writing (atomically if
332 void AssignTempFileName(const wxString
& prefix
, wxFile
*fileTemp
);
333 static wxString
CreateTempFileName(const wxString
& prefix
,
338 // get a temp file name starting with the specified prefix and open the
339 // file passed to us using this name for writing (atomically if
341 void AssignTempFileName(const wxString
& prefix
, wxFFile
*fileTemp
);
342 static wxString
CreateTempFileName(const wxString
& prefix
,
344 #endif // wxUSE_FFILE
346 // directory creation and removal.
347 bool Mkdir(int perm
= wxS_DIR_DEFAULT
, int flags
= 0) const;
348 static bool Mkdir(const wxString
&dir
, int perm
= wxS_DIR_DEFAULT
,
351 bool Rmdir(int flags
= 0) const;
352 static bool Rmdir(const wxString
&dir
, int flags
= 0);
354 // operations on the path
356 // normalize the path: with the default flags value, the path will be
357 // made absolute, without any ".." and "." and all environment
358 // variables will be expanded in it
360 // this may be done using another (than current) value of cwd
361 bool Normalize(int flags
= wxPATH_NORM_ALL
,
362 const wxString
& cwd
= wxEmptyString
,
363 wxPathFormat format
= wxPATH_NATIVE
);
365 // get a path path relative to the given base directory, i.e. opposite
368 // pass an empty string to get a path relative to the working directory
370 // returns true if the file name was modified, false if we failed to do
371 // anything with it (happens when the file is on a different volume,
373 bool MakeRelativeTo(const wxString
& pathBase
= wxEmptyString
,
374 wxPathFormat format
= wxPATH_NATIVE
);
376 // make the path absolute
378 // this may be done using another (than current) value of cwd
379 bool MakeAbsolute(const wxString
& cwd
= wxEmptyString
,
380 wxPathFormat format
= wxPATH_NATIVE
)
381 { return Normalize(wxPATH_NORM_DOTS
| wxPATH_NORM_ABSOLUTE
|
382 wxPATH_NORM_TILDE
, cwd
, format
); }
385 // If the path is a symbolic link (Unix-only), indicate that all
386 // filesystem operations on this path should be performed on the link
387 // itself and not on the file it points to, as is the case by default.
389 // No effect if this is not a symbolic link.
390 void DontFollowLink()
392 m_dontFollowLinks
= true;
395 // If the path is a symbolic link (Unix-only), returns whether various
396 // file operations should act on the link itself, or on its target.
398 // This does not test if the path is really a symlink or not.
399 bool ShouldFollowLink() const
401 return !m_dontFollowLinks
;
404 #if defined(__WIN32__) && !defined(__WXWINCE__) && wxUSE_OLE
405 // if the path is a shortcut, return the target and optionally,
407 bool GetShortcutTarget(const wxString
& shortcutPath
,
408 wxString
& targetFilename
,
409 wxString
* arguments
= NULL
) const;
413 // if the path contains the value of the environment variable named envname
414 // then this function replaces it with the string obtained from
415 // wxString::Format(replacementFmtString, value_of_envname_variable)
418 // wxFileName fn("/usr/openwin/lib/someFile");
419 // fn.ReplaceEnvVariable("OPENWINHOME");
420 // // now fn.GetFullPath() == "$OPENWINHOME/lib/someFile"
421 bool ReplaceEnvVariable(const wxString
& envname
,
422 const wxString
& replacementFmtString
= "$%s",
423 wxPathFormat format
= wxPATH_NATIVE
);
426 // replaces, if present in the path, the home directory for the given user
427 // (see wxGetHomeDir) with a tilde
428 bool ReplaceHomeDir(wxPathFormat format
= wxPATH_NATIVE
);
433 // compares with the rules of the given platforms format
434 bool SameAs(const wxFileName
& filepath
,
435 wxPathFormat format
= wxPATH_NATIVE
) const;
437 // compare with another filename object
438 bool operator==(const wxFileName
& filename
) const
439 { return SameAs(filename
); }
440 bool operator!=(const wxFileName
& filename
) const
441 { return !SameAs(filename
); }
443 // compare with a filename string interpreted as a native file name
444 bool operator==(const wxString
& filename
) const
445 { return SameAs(wxFileName(filename
)); }
446 bool operator!=(const wxString
& filename
) const
447 { return !SameAs(wxFileName(filename
)); }
449 // are the file names of this type cases sensitive?
450 static bool IsCaseSensitive( wxPathFormat format
= wxPATH_NATIVE
);
452 // is this filename absolute?
453 bool IsAbsolute(wxPathFormat format
= wxPATH_NATIVE
) const;
455 // is this filename relative?
456 bool IsRelative(wxPathFormat format
= wxPATH_NATIVE
) const
457 { return !IsAbsolute(format
); }
459 // Returns the characters that aren't allowed in filenames
460 // on the specified platform.
461 static wxString
GetForbiddenChars(wxPathFormat format
= wxPATH_NATIVE
);
463 // Information about path format
465 // get the string separating the volume from the path for this format,
466 // return an empty string if this format doesn't support the notion of
468 static wxString
GetVolumeSeparator(wxPathFormat format
= wxPATH_NATIVE
);
470 // get the string of path separators for this format
471 static wxString
GetPathSeparators(wxPathFormat format
= wxPATH_NATIVE
);
473 // get the string of path terminators, i.e. characters which terminate the
475 static wxString
GetPathTerminators(wxPathFormat format
= wxPATH_NATIVE
);
477 // get the canonical path separator for this format
478 static wxUniChar
GetPathSeparator(wxPathFormat format
= wxPATH_NATIVE
)
479 { return GetPathSeparators(format
)[0u]; }
481 // is the char a path separator for this format?
482 static bool IsPathSeparator(wxChar ch
, wxPathFormat format
= wxPATH_NATIVE
);
484 // is this is a DOS path which beings with a windows unique volume name
485 // ('\\?\Volume{guid}\')?
486 static bool IsMSWUniqueVolumeNamePath(const wxString
& path
,
487 wxPathFormat format
= wxPATH_NATIVE
);
490 size_t GetDirCount() const { return m_dirs
.size(); }
491 void AppendDir(const wxString
& dir
);
492 void PrependDir(const wxString
& dir
);
493 void InsertDir(size_t before
, const wxString
& dir
);
494 void RemoveDir(size_t pos
);
495 void RemoveLastDir() { RemoveDir(GetDirCount() - 1); }
498 void SetExt( const wxString
&ext
) { m_ext
= ext
; m_hasExt
= !m_ext
.empty(); }
499 void ClearExt() { m_ext
= wxEmptyString
; m_hasExt
= false; }
500 void SetEmptyExt() { m_ext
= wxT(""); m_hasExt
= true; }
501 wxString
GetExt() const { return m_ext
; }
502 bool HasExt() const { return m_hasExt
; }
504 void SetName( const wxString
&name
) { m_name
= name
; }
505 wxString
GetName() const { return m_name
; }
506 bool HasName() const { return !m_name
.empty(); }
508 void SetVolume( const wxString
&volume
) { m_volume
= volume
; }
509 wxString
GetVolume() const { return m_volume
; }
510 bool HasVolume() const { return !m_volume
.empty(); }
512 // full name is the file name + extension (but without the path)
513 void SetFullName(const wxString
& fullname
);
514 wxString
GetFullName() const;
516 const wxArrayString
& GetDirs() const { return m_dirs
; }
518 // flags are combination of wxPATH_GET_XXX flags
519 wxString
GetPath(int flags
= wxPATH_GET_VOLUME
,
520 wxPathFormat format
= wxPATH_NATIVE
) const;
522 // Replace current path with this one
523 void SetPath( const wxString
&path
, wxPathFormat format
= wxPATH_NATIVE
);
525 // Construct full path with name and ext
526 wxString
GetFullPath( wxPathFormat format
= wxPATH_NATIVE
) const;
528 // Return the short form of the path (returns identity on non-Windows platforms)
529 wxString
GetShortPath() const;
531 // Return the long form of the path (returns identity on non-Windows platforms)
532 wxString
GetLongPath() const;
534 // Is this a file or directory (not necessarily an existing one)
535 bool IsDir() const { return m_name
.empty() && m_ext
.empty(); }
539 // get the canonical path format for this platform
540 static wxPathFormat
GetFormat( wxPathFormat format
= wxPATH_NATIVE
);
542 // split a fullpath into the volume, path, (base) name and extension
543 // (all of the pointers can be NULL)
544 static void SplitPath(const wxString
& fullpath
,
550 wxPathFormat format
= wxPATH_NATIVE
);
552 static void SplitPath(const wxString
& fullpath
,
559 SplitPath(fullpath
, volume
, path
, name
, ext
, NULL
, format
);
562 // compatibility version: volume is part of path
563 static void SplitPath(const wxString
& fullpath
,
567 wxPathFormat format
= wxPATH_NATIVE
);
569 // split a path into volume and pure path part
570 static void SplitVolume(const wxString
& fullpathWithVolume
,
573 wxPathFormat format
= wxPATH_NATIVE
);
575 // strip the file extension: "foo.bar" => "foo" (but ".baz" => ".baz")
576 static wxString
StripExtension(const wxString
& fullpath
);
578 #ifdef wxHAS_FILESYSTEM_VOLUMES
579 // return the string representing a file system volume, or drive
580 static wxString
GetVolumeString(char drive
, int flags
= wxPATH_GET_SEPARATOR
);
581 #endif // wxHAS_FILESYSTEM_VOLUMES
586 // returns the size of the given filename
587 wxULongLong
GetSize() const;
588 static wxULongLong
GetSize(const wxString
&file
);
590 // returns the size in a human readable form
592 GetHumanReadableSize(const wxString
& nullsize
= _("Not available"),
594 wxSizeConvention conv
= wxSIZE_CONV_TRADITIONAL
) const;
596 GetHumanReadableSize(const wxULongLong
& sz
,
597 const wxString
& nullsize
= _("Not available"),
599 wxSizeConvention conv
= wxSIZE_CONV_TRADITIONAL
);
600 #endif // wxUSE_LONGLONG
603 // deprecated methods, don't use any more
604 // --------------------------------------
606 #ifndef __DIGITALMARS__
607 wxString
GetPath( bool withSep
, wxPathFormat format
= wxPATH_NATIVE
) const
608 { return GetPath(withSep
? wxPATH_GET_SEPARATOR
: 0, format
); }
610 wxString
GetPathWithSep(wxPathFormat format
= wxPATH_NATIVE
) const
611 { return GetPath(wxPATH_GET_VOLUME
| wxPATH_GET_SEPARATOR
, format
); }
614 // check whether this dir is valid for Append/Prepend/InsertDir()
615 static bool IsValidDirComponent(const wxString
& dir
);
617 // the drive/volume/device specification (always empty for Unix)
620 // the path components of the file
621 wxArrayString m_dirs
;
623 // the file name and extension (empty for directories)
627 // when m_dirs is empty it may mean either that we have no path at all or
628 // that our path is '/', i.e. the root directory
630 // we use m_relative to distinguish between these two cases, it will be
631 // true in the former and false in the latter
633 // NB: the path is not absolute just because m_relative is false, it still
634 // needs the drive (i.e. volume) in some formats (Windows)
637 // when m_ext is empty, it may be because we don't have any extension or
638 // because we have an empty extension
640 // the difference is important as file with name "foo" and without
641 // extension has full name "foo" while with empty extension it is "foo."
644 // by default, symlinks are dereferenced but this flag can be set with
645 // DontFollowLink() to change this and make different operations work on
646 // this file path itself instead of the target of the symlink
647 bool m_dontFollowLinks
;
650 #endif // _WX_FILENAME_H_