interface/wx/filename.h

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