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_
16 #include "wx/string.h"
17 #include "wx/arrstr.h"
23 1. support for drives under Windows
24 2. more file operations:
26 b) [acm]time() - get and set
28 d) file permissions with readable accessors for most common bits
29 such as IsReadable() &c
31 3. SameFileAs() function to compare inodes under Unix
34 #include "wx/filefn.h"
35 #include "wx/datetime.h"
38 class WXDLLIMPEXP_BASE wxFile
;
41 // ----------------------------------------------------------------------------
43 // ----------------------------------------------------------------------------
45 // the various values for the path format: this mainly affects the path
46 // separator but also whether or not the path has the drive part (as under
50 wxPATH_NATIVE
= 0, // the path format for the current platform
52 wxPATH_BEOS
= wxPATH_UNIX
,
55 wxPATH_WIN
= wxPATH_DOS
,
56 wxPATH_OS2
= wxPATH_DOS
,
59 wxPATH_MAX
// Not a valid value for specifying path format
62 // the kind of normalization to do with the file name: these values can be
63 // or'd together to perform several operations at once
66 wxPATH_NORM_ENV_VARS
= 0x0001, // replace env vars with their values
67 wxPATH_NORM_DOTS
= 0x0002, // squeeze all .. and . and prepend cwd
68 wxPATH_NORM_TILDE
= 0x0004, // Unix only: replace ~ and ~user
69 wxPATH_NORM_CASE
= 0x0008, // if case insensitive => tolower
70 wxPATH_NORM_ABSOLUTE
= 0x0010, // make the path absolute
71 wxPATH_NORM_LONG
= 0x0020, // make the path the long form
72 wxPATH_NORM_SHORTCUT
= 0x0040, // resolve the shortcut, if it is a shortcut
73 wxPATH_NORM_ALL
= 0x00ff & ~wxPATH_NORM_CASE
76 // what exactly should GetPath() return?
79 wxPATH_GET_VOLUME
= 0x0001, // include the volume if applicable
80 wxPATH_GET_SEPARATOR
= 0x0002 // terminate the path with the separator
86 wxPATH_MKDIR_FULL
= 0x0001 // create directories recursively
89 // ----------------------------------------------------------------------------
90 // wxFileName: encapsulates a file path
91 // ----------------------------------------------------------------------------
93 class WXDLLIMPEXP_BASE wxFileName
96 // constructors and assignment
99 wxFileName() { Clear(); }
100 wxFileName(const wxFileName
& filepath
) { Assign(filepath
); }
102 // from a full filename: if it terminates with a '/', a directory path
103 // is contructed (the name will be empty), otherwise a file name and
104 // extension are extracted from it
105 wxFileName( const wxString
& fullpath
, wxPathFormat format
= wxPATH_NATIVE
)
106 { Assign( fullpath
, format
); }
108 // from a directory name and a file name
109 wxFileName(const wxString
& path
,
110 const wxString
& name
,
111 wxPathFormat format
= wxPATH_NATIVE
)
112 { Assign(path
, name
, format
); }
114 // from a volume, directory name, file base name and extension
115 wxFileName(const wxString
& volume
,
116 const wxString
& path
,
117 const wxString
& name
,
119 wxPathFormat format
= wxPATH_NATIVE
)
120 { Assign(volume
, path
, name
, ext
, format
); }
122 // from a directory name, file base name and extension
123 wxFileName(const wxString
& path
,
124 const wxString
& name
,
126 wxPathFormat format
= wxPATH_NATIVE
)
127 { Assign(path
, name
, ext
, format
); }
129 // the same for delayed initialization
131 void Assign(const wxFileName
& filepath
);
133 void Assign(const wxString
& fullpath
,
134 wxPathFormat format
= wxPATH_NATIVE
);
136 void Assign(const wxString
& volume
,
137 const wxString
& path
,
138 const wxString
& name
,
141 wxPathFormat format
= wxPATH_NATIVE
);
143 void Assign(const wxString
& volume
,
144 const wxString
& path
,
145 const wxString
& name
,
147 wxPathFormat format
= wxPATH_NATIVE
)
148 { Assign(volume
, path
, name
, ext
, !ext
.empty(), format
); }
150 void Assign(const wxString
& path
,
151 const wxString
& name
,
152 wxPathFormat format
= wxPATH_NATIVE
);
154 void Assign(const wxString
& path
,
155 const wxString
& name
,
157 wxPathFormat format
= wxPATH_NATIVE
);
159 void AssignDir(const wxString
& dir
, wxPathFormat format
= wxPATH_NATIVE
);
161 // assorted assignment operators
163 wxFileName
& operator=(const wxFileName
& filename
)
164 { Assign(filename
); return *this; }
166 wxFileName
& operator=(const wxString
& filename
)
167 { Assign(filename
); return *this; }
169 // reset all components to default, uninitialized state
172 // static pseudo constructors
173 static wxFileName
FileName(const wxString
& file
,
174 wxPathFormat format
= wxPATH_NATIVE
);
175 static wxFileName
DirName(const wxString
& dir
,
176 wxPathFormat format
= wxPATH_NATIVE
);
180 // is the filename valid at all?
183 // we're fine if we have the path or the name or if we're a root dir
184 return m_dirs
.size() != 0 || !m_name
.empty() || !m_relative
||
185 !m_ext
.empty() || m_hasExt
;
188 // does the file with this name exists?
189 bool FileExists() const;
190 static bool FileExists( const wxString
&file
);
192 // does the directory with this name exists?
193 bool DirExists() const;
194 static bool DirExists( const wxString
&dir
);
196 // VZ: also need: IsDirWritable(), IsFileExecutable() &c (TODO)
200 // set the file last access/mod and creation times
201 // (any of the pointers may be NULL)
202 bool SetTimes(const wxDateTime
*dtAccess
,
203 const wxDateTime
*dtMod
,
204 const wxDateTime
*dtCreate
);
206 // set the access and modification times to the current moment
209 // return the last access, last modification and create times
210 // (any of the pointers may be NULL)
211 bool GetTimes(wxDateTime
*dtAccess
,
213 wxDateTime
*dtCreate
) const;
215 // convenience wrapper: get just the last mod time of the file
216 wxDateTime
GetModificationTime() const
219 (void)GetTimes(NULL
, &dtMod
, NULL
);
222 #endif // wxUSE_DATETIME
225 bool MacSetTypeAndCreator( wxUint32 type
, wxUint32 creator
) ;
226 bool MacGetTypeAndCreator( wxUint32
*type
, wxUint32
*creator
) ;
227 // gets the 'common' type and creator for a certain extension
228 static bool MacFindDefaultTypeAndCreator( const wxString
& ext
, wxUint32
*type
, wxUint32
*creator
) ;
229 // registers application defined extensions and their default type and creator
230 static void MacRegisterDefaultTypeAndCreator( const wxString
& ext
, wxUint32 type
, wxUint32 creator
) ;
231 // looks up the appropriate type and creator from the registration and then sets
232 bool MacSetDefaultTypeAndCreator() ;
235 // various file/dir operations
237 // retrieve the value of the current working directory
238 void AssignCwd(const wxString
& volume
= wxEmptyString
);
239 static wxString
GetCwd(const wxString
& volume
= wxEmptyString
);
241 // change the current working directory
243 static bool SetCwd( const wxString
&cwd
);
245 // get the value of user home (Unix only mainly)
246 void AssignHomeDir();
247 static wxString
GetHomeDir();
250 // get a temp file name starting with the specified prefix and open the
251 // file passed to us using this name for writing (atomically if
253 void AssignTempFileName(const wxString
& prefix
, wxFile
*fileTemp
= NULL
);
254 static wxString
CreateTempFileName(const wxString
& prefix
,
255 wxFile
*fileTemp
= NULL
);
258 // directory creation and removal.
259 bool Mkdir( int perm
= 0777, int flags
= 0);
260 static bool Mkdir( const wxString
&dir
, int perm
= 0777, int flags
= 0 );
263 static bool Rmdir( const wxString
&dir
);
265 // operations on the path
267 // normalize the path: with the default flags value, the path will be
268 // made absolute, without any ".." and "." and all environment
269 // variables will be expanded in it
271 // this may be done using another (than current) value of cwd
272 bool Normalize(int flags
= wxPATH_NORM_ALL
,
273 const wxString
& cwd
= wxEmptyString
,
274 wxPathFormat format
= wxPATH_NATIVE
);
276 // get a path path relative to the given base directory, i.e. opposite
279 // pass an empty string to get a path relative to the working directory
281 // returns true if the file name was modified, false if we failed to do
282 // anything with it (happens when the file is on a different volume,
284 bool MakeRelativeTo(const wxString
& pathBase
= wxEmptyString
,
285 wxPathFormat format
= wxPATH_NATIVE
);
287 // make the path absolute
289 // this may be done using another (than current) value of cwd
290 bool MakeAbsolute(const wxString
& cwd
= wxEmptyString
,
291 wxPathFormat format
= wxPATH_NATIVE
)
292 { return Normalize(wxPATH_NORM_DOTS
| wxPATH_NORM_ABSOLUTE
|
293 wxPATH_NORM_TILDE
, cwd
, format
); }
295 #if defined(__WIN32__) && !defined(__WXWINCE__) && wxUSE_OLE
296 // if the path is a shortcut, return the target and optionally,
298 bool GetShortcutTarget(const wxString
& shortcutPath
,
299 wxString
& targetFilename
,
300 wxString
* arguments
= NULL
);
305 // compares with the rules of the given platforms format
306 bool SameAs(const wxFileName
& filepath
,
307 wxPathFormat format
= wxPATH_NATIVE
) const;
309 // compare with another filename object
310 bool operator==(const wxFileName
& filename
) const
311 { return SameAs(filename
); }
312 bool operator!=(const wxFileName
& filename
) const
313 { return !SameAs(filename
); }
315 // compare with a filename string interpreted as a native file name
316 bool operator==(const wxString
& filename
) const
317 { return SameAs(wxFileName(filename
)); }
318 bool operator!=(const wxString
& filename
) const
319 { return !SameAs(wxFileName(filename
)); }
321 // are the file names of this type cases sensitive?
322 static bool IsCaseSensitive( wxPathFormat format
= wxPATH_NATIVE
);
324 // is this filename absolute?
325 bool IsAbsolute(wxPathFormat format
= wxPATH_NATIVE
) const;
327 // is this filename relative?
328 bool IsRelative(wxPathFormat format
= wxPATH_NATIVE
) const
329 { return !IsAbsolute(format
); }
331 // Returns the characters that aren't allowed in filenames
332 // on the specified platform.
333 static wxString
GetForbiddenChars(wxPathFormat format
= wxPATH_NATIVE
);
335 // Information about path format
337 // get the string separating the volume from the path for this format,
338 // return an empty string if this format doesn't support the notion of
340 static wxString
GetVolumeSeparator(wxPathFormat format
= wxPATH_NATIVE
);
342 // get the string of path separators for this format
343 static wxString
GetPathSeparators(wxPathFormat format
= wxPATH_NATIVE
);
345 // get the string of path terminators, i.e. characters which terminate the
347 static wxString
GetPathTerminators(wxPathFormat format
= wxPATH_NATIVE
);
349 // get the canonical path separator for this format
350 static wxChar
GetPathSeparator(wxPathFormat format
= wxPATH_NATIVE
)
351 { return GetPathSeparators(format
)[0u]; }
353 // is the char a path separator for this format?
354 static bool IsPathSeparator(wxChar ch
, wxPathFormat format
= wxPATH_NATIVE
);
357 size_t GetDirCount() const { return m_dirs
.size(); }
358 void AppendDir(const wxString
& dir
);
359 void PrependDir(const wxString
& dir
);
360 void InsertDir(size_t before
, const wxString
& dir
);
361 void RemoveDir(size_t pos
);
362 void RemoveLastDir() { RemoveDir(GetDirCount() - 1); }
365 void SetExt( const wxString
&ext
) { m_ext
= ext
; m_hasExt
= !m_ext
.empty(); }
366 void ClearExt() { m_ext
= wxEmptyString
; m_hasExt
= false; }
367 void SetEmptyExt() { m_ext
= wxT(""); m_hasExt
= true; }
368 wxString
GetExt() const { return m_ext
; }
369 bool HasExt() const { return m_hasExt
; }
371 void SetName( const wxString
&name
) { m_name
= name
; }
372 wxString
GetName() const { return m_name
; }
373 bool HasName() const { return !m_name
.empty(); }
375 void SetVolume( const wxString
&volume
) { m_volume
= volume
; }
376 wxString
GetVolume() const { return m_volume
; }
377 bool HasVolume() const { return !m_volume
.empty(); }
379 // full name is the file name + extension (but without the path)
380 void SetFullName(const wxString
& fullname
);
381 wxString
GetFullName() const;
383 const wxArrayString
& GetDirs() const { return m_dirs
; }
385 // flags are combination of wxPATH_GET_XXX flags
386 wxString
GetPath(int flags
= wxPATH_GET_VOLUME
,
387 wxPathFormat format
= wxPATH_NATIVE
) const;
389 // Replace current path with this one
390 void SetPath( const wxString
&path
, wxPathFormat format
= wxPATH_NATIVE
);
392 // Construct full path with name and ext
393 wxString
GetFullPath( wxPathFormat format
= wxPATH_NATIVE
) const;
395 // Return the short form of the path (returns identity on non-Windows platforms)
396 wxString
GetShortPath() const;
398 // Return the long form of the path (returns identity on non-Windows platforms)
399 wxString
GetLongPath() const;
401 // Is this a file or directory (not necessarily an existing one)
402 bool IsDir() const { return m_name
.empty() && m_ext
.empty(); }
406 // get the canonical path format for this platform
407 static wxPathFormat
GetFormat( wxPathFormat format
= wxPATH_NATIVE
);
409 // split a fullpath into the volume, path, (base) name and extension
410 // (all of the pointers can be NULL)
411 static void SplitPath(const wxString
& fullpath
,
417 wxPathFormat format
= wxPATH_NATIVE
);
419 static void SplitPath(const wxString
& fullpath
,
426 SplitPath(fullpath
, volume
, path
, name
, ext
, NULL
, format
);
429 // compatibility version: volume is part of path
430 static void SplitPath(const wxString
& fullpath
,
434 wxPathFormat format
= wxPATH_NATIVE
);
436 // split a path into volume and pure path part
437 static void SplitVolume(const wxString
& fullpathWithVolume
,
440 wxPathFormat format
= wxPATH_NATIVE
);
442 // deprecated methods, don't use any more
443 // --------------------------------------
445 #ifndef __DIGITALMARS__
446 wxString
GetPath( bool withSep
, wxPathFormat format
= wxPATH_NATIVE
) const
447 { return GetPath(withSep
? wxPATH_GET_SEPARATOR
: 0, format
); }
449 wxString
GetPathWithSep(wxPathFormat format
= wxPATH_NATIVE
) const
450 { return GetPath(wxPATH_GET_SEPARATOR
, format
); }
453 // check whether this dir is valid for Append/Prepend/InsertDir()
454 static bool IsValidDirComponent(const wxString
& dir
);
456 // the drive/volume/device specification (always empty for Unix)
459 // the path components of the file
460 wxArrayString m_dirs
;
462 // the file name and extension (empty for directories)
466 // when m_dirs is empty it may mean either that we have no path at all or
467 // that our path is '/', i.e. the root directory
469 // we use m_relative to distinguish between these two cases, it will be
470 // true in the former and false in the latter
472 // NB: the path is not absolute just because m_relative is false, it still
473 // needs the drive (i.e. volume) in some formats (Windows)
476 // when m_ext is empty, it may be because we don't have any extension or
477 // because we have an empty extension
479 // the difference is important as file with name "foo" and without
480 // extension has full name "foo" while with empty extension it is "foo."
484 #endif // _WX_FILENAME_H_