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 licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     The various values for the path format: this mainly affects the path
  12     separator but also whether or not the path has the drive part
  13     (as under Windows).
  14
  15     See wxFileName for more info.
  16 */
  17 enum wxPathFormat
  18 {
  19     wxPATH_NATIVE = 0,      //!< the path format for the current platform.
  20     wxPATH_UNIX,
  21     wxPATH_BEOS = wxPATH_UNIX,
  22     wxPATH_MAC,
  23     wxPATH_DOS,
  24     wxPATH_WIN = wxPATH_DOS,
  25     wxPATH_OS2 = wxPATH_DOS,
  26     wxPATH_VMS,
  27
  28     wxPATH_MAX   //!< Not a valid value for specifying path format
  29 };
  30
  31 /**
  32     Different conventions for human readable sizes.
  33
  34     @see wxFileName::GetHumanReadableSize().
  35
  36     @since 2.9.1
  37 */
  38 enum wxSizeConvention
  39 {
  40     /// 1024 bytes = 1KB.
  41     wxSIZE_CONV_TRADITIONAL,
  42
  43     /// 1024 bytes = 1KiB.
  44     wxSIZE_CONV_IEC,
  45
  46     /// 1000 bytes = 1KB.
  47     wxSIZE_CONV_SI
  48 };
  49
  50
  51 /**
  52     The kind of normalization to do with the file name: these values can be
  53     or'd together to perform several operations at once.
  54     See wxFileName::Normalize() for more info.
  55 */
  56 enum wxPathNormalize
  57 {
  58     //! Replace environment variables with their values.
  59     //! wxFileName understands both Unix and Windows (but only under Windows) environment
  60     //! variables expansion: i.e. @c "$var", @c "$(var)" and @c "${var}" are always understood
  61     //! and in addition under Windows @c "%var%" is also.
  62     wxPATH_NORM_ENV_VARS = 0x0001,
  63
  64     wxPATH_NORM_DOTS     = 0x0002,  //!< Squeeze all @c ".." and @c ".".
  65     wxPATH_NORM_TILDE    = 0x0004,  //!< Replace @c "~" and @c "~user" (Unix only).
  66     wxPATH_NORM_CASE     = 0x0008,  //!< If the platform is case insensitive, make lowercase the path.
  67     wxPATH_NORM_ABSOLUTE = 0x0010,  //!< Make the path absolute.
  68     wxPATH_NORM_LONG =     0x0020,  //!< Expand the path to the "long" form (Windows only).
  69     wxPATH_NORM_SHORTCUT = 0x0040,  //!< Resolve the shortcut, if it is a shortcut (Windows only).
  70
  71     //! A value indicating all normalization flags except for @c wxPATH_NORM_CASE.
  72     wxPATH_NORM_ALL      = 0x00ff & ~wxPATH_NORM_CASE
  73 };
  74
  75 /**
  76     Flags for wxFileName::Rmdir().
  77  */
  78 enum
  79 {
  80     /// Delete the specified directory and its subdirectories if they are empty.
  81     wxPATH_RMDIR_FULL = 1,
  82
  83     /**
  84       Delete the specified directory and all the files and subdirectories in it
  85       recursively.
  86
  87       This flag is obviously @b dangerous and should be used with care and
  88       after asking the user for confirmation.
  89      */
  90     wxPATH_RMDIR_RECURSIVE = 2
  91 };
  92
  93 /**
  94     The return value of wxFileName::GetSize() in case of error.
  95 */
  96 wxULongLong wxInvalidSize;
  97
  98
  99 /**
 100     @class wxFileName
 101
 102     wxFileName encapsulates a file name.
 103
 104     This class serves two purposes: first, it provides the functions to split the
 105     file names into components and to recombine these components in the full file
 106     name which can then be passed to the OS file functions
 107     (and @ref group_funcmacro_file "wxWidgets functions" wrapping them).
 108     Second, it includes the functions for working with the files itself. Note that
 109     to change the file data you should use wxFile class instead.
 110     wxFileName provides functions for working with the file attributes.
 111
 112     When working with directory names (i.e. without filename and extension)
 113     make sure not to misuse the file name part of this class with the last
 114     directory. Instead initialize the wxFileName instance like this:
 115
 116     @code
 117     wxFileName dirname( "C:\mydir", "" );
 118     MyMethod( dirname.GetPath() );
 119     @endcode
 120
 121     The same can be done using the static method wxFileName::DirName():
 122
 123     @code
 124     wxFileName dirname = wxFileName::DirName( "C:\mydir" );
 125     MyMethod( dirname.GetPath() );
 126     @endcode
 127
 128     Accordingly, methods dealing with directories or directory names like
 129     wxFileName::IsDirReadable() use wxFileName::GetPath() whereas methods dealing
 130     with file names like wxFileName::IsFileReadable() use wxFileName::GetFullPath().
 131
 132     If it is not known whether a string contains a directory name or a complete
 133     file name (such as when interpreting user input) you need to use the static
 134     function wxFileName::DirExists() (or its identical variants wxDir::Exists() and
 135     wxDirExists()) and construct the wxFileName instance accordingly.
 136     This will only work if the directory actually exists, of course:
 137
 138     @code
 139     wxString user_input;
 140     // get input from user
 141
 142     wxFileName fname;
 143     if (wxDirExists(user_input))
 144         fname.AssignDir( user_input );
 145     else
 146         fname.Assign( user_input );
 147     @endcode
 148
 149     Please note that many wxFileName methods accept the path format argument
 150     which is by @c wxPATH_NATIVE by default meaning to use the path format
 151     native for the current platform.
 152     The path format affects the operation of wxFileName functions in several ways:
 153     first and foremost, it defines the path separator character to use, but it
 154     also affects other things such as whether the path has the drive part or not.
 155     See wxPathFormat for more info.
 156
 157
 158     @section filename_format File name format
 159
 160     wxFileName currently supports the file names in the Unix, DOS/Windows,
 161     Mac OS and VMS formats. Although these formats are quite different,
 162     wxFileName tries to treat them all in the same generic way.
 163     It supposes that all file names consist of the following parts: the volume
 164     (also known as drive under Windows or device under VMS), the path which is
 165     a sequence of directory names separated by the path separators and the full
 166     filename itself which, in turn, is composed from the base file name and the
 167     extension. All of the individual components of the file name may be empty
 168     and, for example, the volume name is always empty under Unix, but if they
 169     are all empty simultaneously, the filename object is considered to be in an
 170     invalid state and wxFileName::IsOk() returns false for it.
 171
 172     File names can be case-sensitive or not, the function wxFileName::IsCaseSensitive()
 173     allows to determine this. The rules for determining whether the file name is
 174     absolute or relative also depend on the file name format and the only portable way
 175     to answer this question is to use wxFileName::IsAbsolute() or wxFileName::IsRelative()
 176     method.
 177
 178     Note that on Windows,"X:" refers to the current working directory on drive X.
 179     Therefore, a wxFileName instance constructed from for example "X:dir/file.ext"
 180     treats the portion beyond drive separator as being relative to that directory.
 181     To ensure that the filename is absolute, you may use wxFileName::MakeAbsolute().
 182     There is also an inverse function wxFileName::MakeRelativeTo() which undoes
 183     what wxFileName::Normalize(wxPATH_NORM_DOTS) does.
 184     Other functions returning information about the file format provided by this
 185     class are wxFileName::GetVolumeSeparator(), wxFileName::IsPathSeparator().
 186
 187
 188     @section filename_construction File name construction
 189
 190     You can initialize a wxFileName instance using one of the following functions:
 191
 192     @li wxFileName::wxFileName()
 193     @li wxFileName::Assign()
 194     @li wxFileName::AssignCwd()
 195     @li wxFileName::AssignDir()
 196     @li wxFileName::AssignHomeDir()
 197     @li wxFileName::AssignTempFileName()
 198     @li wxFileName::DirName()
 199     @li wxFileName::FileName()
 200     @li wxFileName::operator=()
 201
 202
 203     @section filename_tests File name tests
 204
 205     Before doing other tests, you should use wxFileName::IsOk() to verify that
 206     the filename is well defined. If it is, FileExists() can be used to test whether
 207     a file with such name exists and wxFileName::DirExists() can be used to test
 208     for directory existence.
 209     File names should be compared using the wxFileName::SameAs() method or
 210     wxFileName::operator==(). For testing basic access modes, you can use:
 211
 212     @li wxFileName::IsDirWritable()
 213     @li wxFileName::IsDirReadable()
 214     @li wxFileName::IsFileWritable()
 215     @li wxFileName::IsFileReadable()
 216     @li wxFileName::IsFileExecutable()
 217
 218
 219     @section filename_components File name components
 220
 221     These functions allow to examine and modify the individual directories
 222     of the path:
 223
 224     @li wxFileName::AppendDir()
 225     @li wxFileName::InsertDir()
 226     @li wxFileName::GetDirCount()
 227     @li wxFileName::PrependDir()
 228     @li wxFileName::RemoveDir()
 229     @li wxFileName::RemoveLastDir()
 230
 231     To change the components of the file name individually you can use the
 232     following functions:
 233
 234     @li wxFileName::GetExt()
 235     @li wxFileName::GetName()
 236     @li wxFileName::GetVolume()
 237     @li wxFileName::HasExt()
 238     @li wxFileName::HasName()
 239     @li wxFileName::HasVolume()
 240     @li wxFileName::SetExt()
 241     @li wxFileName::ClearExt()
 242     @li wxFileName::SetEmptyExt()
 243     @li wxFileName::SetName()
 244     @li wxFileName::SetVolume()
 245
 246     You can initialize a wxFileName instance using one of the following functions:
 247
 248
 249     @section filename_operations File name operations
 250
 251     These methods allow to work with the file creation, access and modification
 252     times. Note that not all filesystems under all platforms implement these times
 253     in the same way. For example, the access time under Windows has a resolution of
 254     one day (so it is really the access date and not time). The access time may be
 255     updated when the file is executed or not depending on the platform.
 256
 257     @li wxFileName::GetModificationTime()
 258     @li wxFileName::GetTimes()
 259     @li wxFileName::SetTimes()
 260     @li wxFileName::Touch()
 261
 262     Other file system operations functions are:
 263
 264     @li wxFileName::Mkdir()
 265     @li wxFileName::Rmdir()
 266
 267
 268     @library{wxbase}
 269     @category{file}
 270 */
 271 class wxFileName
 272 {
 273 public:
 274     /**
 275         Default constructor.
 276     */
 277     wxFileName();
 278
 279     /**
 280         Copy constructor.
 281     */
 282     wxFileName(const wxFileName& filename);
 283
 284     /**
 285         Constructor taking a full filename.
 286
 287         If it terminates with a '/', a directory path is constructed
 288         (the name will be empty), otherwise a file name and extension
 289         are extracted from it.
 290     */
 291     wxFileName(const wxString& fullpath,
 292                wxPathFormat format = wxPATH_NATIVE);
 293
 294     /**
 295         Constructor a directory name and file name.
 296     */
 297     wxFileName(const wxString& path, const wxString& name,
 298                wxPathFormat format = wxPATH_NATIVE);
 299
 300     /**
 301         Constructor from a directory name, base file name and extension.
 302     */
 303     wxFileName(const wxString& path, const wxString& name,
 304                const wxString& ext,
 305                wxPathFormat format = wxPATH_NATIVE);
 306
 307     /**
 308         Constructor from a volume name, a directory name, base file name and extension.
 309     */
 310     wxFileName(const wxString& volume, const wxString& path,
 311                const wxString& name,
 312                const wxString& ext,
 313                wxPathFormat format = wxPATH_NATIVE);
 314
 315     /**
 316         Appends a directory component to the path. This component should contain a
 317         single directory name level, i.e. not contain any path or volume separators nor
 318         should it be empty, otherwise the function does nothing (and generates an
 319         assert failure in debug build).
 320     */
 321     void AppendDir(const wxString& dir);
 322
 323     /**
 324         Creates the file name from another filename object.
 325     */
 326     void Assign(const wxFileName& filepath);
 327
 328     /**
 329         Creates the file name from a full file name with a path.
 330     */
 331     void Assign(const wxString& fullpath,
 332                 wxPathFormat format = wxPATH_NATIVE);
 333
 334     /**
 335         Creates the file name from volume, path, name and extension.
 336     */
 337     void Assign(const wxString& volume, const wxString& path,
 338                 const wxString& name,
 339                 const wxString& ext,
 340                 bool hasExt,
 341                 wxPathFormat format = wxPATH_NATIVE);
 342
 343     /**
 344         Creates the file name from volume, path, name and extension.
 345     */
 346     void Assign(const wxString& volume, const wxString& path,
 347                 const wxString& name,
 348                 const wxString& ext,
 349                 wxPathFormat format = wxPATH_NATIVE);
 350
 351     /**
 352         Creates the file name from file path and file name.
 353     */
 354     void Assign(const wxString& path, const wxString& name,
 355                 wxPathFormat format = wxPATH_NATIVE);
 356
 357     /**
 358         Creates the file name from path, name and extension.
 359     */
 360     void Assign(const wxString& path, const wxString& name,
 361                 const wxString& ext,
 362                 wxPathFormat format = wxPATH_NATIVE);
 363
 364     /**
 365         Makes this object refer to the current working directory on the specified
 366         volume (or current volume if @a volume is empty).
 367
 368         @see GetCwd()
 369     */
 370     void AssignCwd(const wxString& volume = wxEmptyString);
 371
 372     /**
 373         Sets this file name object to the given directory name.
 374         The name and extension will be empty.
 375     */
 376     void AssignDir(const wxString& dir,
 377                    wxPathFormat format = wxPATH_NATIVE);
 378
 379     /**
 380         Sets this file name object to the home directory.
 381     */
 382     void AssignHomeDir();
 383
 384     /**
 385         The function calls CreateTempFileName() to create a temporary file
 386         and sets this object to the name of the file.
 387
 388         If a temporary file couldn't be created, the object is put into
 389         an invalid state (see IsOk()).
 390     */
 391     void AssignTempFileName(const wxString& prefix);
 392
 393     /**
 394         The function calls CreateTempFileName() to create a temporary
 395         file name and open @a fileTemp with it.
 396
 397         If the file couldn't be opened, the object is put into
 398         an invalid state (see IsOk()).
 399     */
 400     void AssignTempFileName(const wxString& prefix, wxFile* fileTemp);
 401
 402     /**
 403         The function calls CreateTempFileName() to create a temporary
 404         file name and open @a fileTemp with it.
 405
 406         If the file couldn't be opened, the object is put into
 407         an invalid state (see IsOk()).
 408     */
 409     void AssignTempFileName(const wxString& prefix, wxFFile* fileTemp);
 410
 411     /**
 412         Reset all components to default, uninitialized state.
 413     */
 414     void Clear();
 415
 416     /**
 417         Removes the extension from the file name resulting in a
 418         file name with no trailing dot.
 419
 420         @see SetExt(), SetEmptyExt()
 421     */
 422     void ClearExt();
 423
 424
 425     /**
 426         Returns a temporary file name starting with the given @e prefix.
 427         If @a prefix is an absolute path and ends in a separator, the
 428         temporary file is created in this directory; if it is an absolute
 429         filepath or there is no separator, the temporary file is created in its
 430         path, with the 'name' segment prepended to the temporary filename;
 431         otherwise it is created in the default system directory for temporary
 432         files or in the current directory.
 433
 434         If the function succeeds, the temporary file is actually created.
 435         If @a fileTemp is not @NULL, this wxFile will be opened using the name of
 436         the temporary file. Where possible this is done in an atomic way to ensure that
 437         no race condition occurs between creating the temporary file name and opening
 438         it, which might lead to a security compromise on multiuser systems.
 439         If @a fileTemp is @NULL, the file is created but not opened.
 440         Under Unix, the temporary file will have read and write permissions for the
 441         owner only, to minimize security problems.
 442
 443         @param prefix
 444             Location to use for the temporary file name construction. If @a prefix
 445             is a directory it must have a terminal separator
 446         @param fileTemp
 447             The file to open, or @NULL just to get the name
 448
 449         @return The full temporary filepath, or an empty string on error.
 450     */
 451     static wxString CreateTempFileName(const wxString& prefix,
 452                                        wxFile* fileTemp = NULL);
 453
 454     /**
 455         This is the same as CreateTempFileName(const wxString &prefix, wxFile *fileTemp)
 456         but takes a wxFFile parameter instead of wxFile.
 457     */
 458     static wxString CreateTempFileName(const wxString& prefix,
 459                                        wxFFile* fileTemp = NULL);
 460
 461
 462     /**
 463         Returns @true if the directory with this name exists.
 464
 465         Notice that this function tests the directory part of this object,
 466         i.e. the string returned by GetPath(), and not the full path returned
 467         by GetFullPath().
 468
 469         @see FileExists(), Exists()
 470     */
 471     bool DirExists() const;
 472
 473     /**
 474         Returns @true if the directory with name @a dir exists.
 475
 476         @see FileExists(), Exists()
 477     */
 478     static bool DirExists(const wxString& dir);
 479
 480     /**
 481         Returns the object corresponding to the directory with the given name.
 482         The @a dir parameter may have trailing path separator or not.
 483     */
 484     static wxFileName DirName(const wxString& dir,
 485                               wxPathFormat format = wxPATH_NATIVE);
 486
 487     /**
 488         Turns off symlink dereferencing.
 489
 490         By default, all operations in this class work on the target of a
 491         symbolic link (symlink) if the path of the file is actually a symlink.
 492         Using this method allows to turn off this "symlink following" behaviour
 493         and apply the operations to this path itself, even if it is a symlink.
 494
 495         The following methods are currently affected by this option:
 496             - GetTimes() (but not SetTimes() as there is no portable way to
 497               change the time of symlink itself).
 498             - Existence checks: FileExists(), DirExists() and Exists() (notice
 499               that static versions of these methods always follow symlinks).
 500             - IsSameAs().
 501
 502         @see ShouldFollowLink()
 503
 504         @since 2.9.5
 505     */
 506     void DontFollowLink();
 507
 508      /**
 509         Calls the static overload of this function with the full path of this
 510         object.
 511
 512         @since 2.9.4
 513      */
 514     bool Exists() const;
 515
 516     /**
 517         Returns @true if either a file or a directory or something else with
 518         this name exists in the file system.
 519
 520         This method is equivalent to @code FileExists() || DirExists() @endcode
 521         under most systems but under Unix it also returns true if the file
 522         identifies a special file system object such as a device, a socket or a
 523         FIFO.
 524
 525         @since 2.9.4
 526
 527         @see FileExists(), DirExists()
 528      */
 529     static bool Exists(const wxString& path);
 530
 531     /**
 532         Returns @true if the file with this name exists.
 533
 534         @see DirExists(), Exists()
 535     */
 536     bool FileExists() const;
 537
 538     /**
 539         Returns @true if the file with name @a file exists.
 540
 541         @see DirExists(), Exists()
 542     */
 543     static bool FileExists(const wxString& file);
 544
 545     /**
 546         Returns the file name object corresponding to the given @e file. This
 547         function exists mainly for symmetry with DirName().
 548     */
 549     static wxFileName FileName(const wxString& file,
 550                                wxPathFormat format = wxPATH_NATIVE);
 551
 552     /**
 553         Retrieves the value of the current working directory on the specified volume.
 554         If the volume is empty, the program's current working directory is returned for
 555         the current volume.
 556
 557         @return The string containing the current working directory or an empty
 558                 string on error.
 559
 560         @see AssignCwd()
 561     */
 562     static wxString GetCwd(const wxString& volume = wxEmptyString);
 563
 564     /**
 565         Returns the number of directories in the file name.
 566     */
 567     size_t GetDirCount() const;
 568
 569     /**
 570         Returns the directories in string array form.
 571     */
 572     const wxArrayString& GetDirs() const;
 573
 574     /**
 575         Returns the file name extension.
 576     */
 577     wxString GetExt() const;
 578
 579     /**
 580         Returns the characters that can't be used in filenames and directory names
 581         for the specified format.
 582     */
 583     static wxString GetForbiddenChars(wxPathFormat format = wxPATH_NATIVE);
 584
 585     /**
 586         Returns the canonical path format for this platform.
 587     */
 588     static wxPathFormat GetFormat(wxPathFormat format = wxPATH_NATIVE);
 589
 590     /**
 591         Returns the full name (including extension but excluding directories).
 592     */
 593     wxString GetFullName() const;
 594
 595     /**
 596         Returns the full path with name and extension.
 597     */
 598     wxString GetFullPath(wxPathFormat format = wxPATH_NATIVE) const;
 599
 600     /**
 601         Returns the home directory.
 602     */
 603     static wxString GetHomeDir();
 604
 605     //@{
 606     /**
 607         Returns the representation of the file size in a human-readable form.
 608
 609         In the first version, the size of this file is used. In the second one,
 610         the specified size @a bytes is used.
 611
 612         If the file size could not be retrieved or @a bytes is ::wxInvalidSize
 613         or zero, the @c failmsg string is returned.
 614
 615         Otherwise the returned string is a floating-point number with @c
 616         precision decimal digits followed by the abbreviation of the unit used.
 617         By default the traditional, although incorrect, convention of using SI
 618         units for multiples of 1024 is used, i.e. returned string will use
 619         suffixes of B, KB, MB, GB, TB for bytes, kilobytes, megabytes,
 620         gigabytes and terabytes respectively. With the IEC convention the names
 621         of the units are changed to B, KiB, MiB, GiB and TiB for bytes,
 622         kibibytes, mebibytes, gibibytes and tebibytes. Finally, with SI
 623         convention the same B, KB, MB, GB and TB suffixes are used but in their
 624         correct SI meaning, i.e. as multiples of 1000 and not 1024.
 625
 626         Support for the different size conventions is new in wxWidgets 2.9.1,
 627         in previous versions only the traditional convention was implemented.
 628     */
 629     wxString
 630     GetHumanReadableSize(const wxString& failmsg = _("Not available"),
 631                          int precision = 1,
 632                          wxSizeConvention conv = wxSIZE_CONV_TRADITIONAL) const;
 633
 634     static wxString
 635     GetHumanReadableSize(const wxULongLong& bytes,
 636                          const wxString& nullsize = _("Not available"),
 637                          int precision = 1,
 638                          wxSizeConvention conv = wxSIZE_CONV_TRADITIONAL);
 639     //@}
 640
 641     /**
 642         Return the long form of the path (returns identity on non-Windows platforms).
 643     */
 644     wxString GetLongPath() const;
 645
 646     /**
 647         Returns the last time the file was last modified.
 648     */
 649     wxDateTime GetModificationTime() const;
 650
 651     /**
 652         Returns the name part of the filename (without extension).
 653
 654         @see GetFullName()
 655     */
 656     wxString GetName() const;
 657
 658     /**
 659         Returns the path part of the filename (without the name or extension).
 660
 661         The possible flags values are:
 662
 663         - @b wxPATH_GET_VOLUME:
 664         Return the path with the volume (does nothing for the filename formats
 665         without volumes), otherwise the path without volume part is returned.
 666
 667         - @b wxPATH_GET_SEPARATOR:
 668         Return the path with the trailing separator, if this flag is not given
 669         there will be no separator at the end of the path.
 670
 671         - @b wxPATH_NO_SEPARATOR:
 672         Don't include the trailing separator in the returned string. This is
 673         the default (the value of this flag is 0) and exists only for symmetry
 674         with wxPATH_GET_SEPARATOR.
 675
 676         @note If the path is a toplevel one (e.g. @c "/" on Unix or @c "C:\" on
 677               Windows), then the returned path will contain trailing separator
 678               even with @c wxPATH_NO_SEPARATOR.
 679     */
 680     wxString GetPath(int flags = wxPATH_GET_VOLUME,
 681                      wxPathFormat format = wxPATH_NATIVE) const;
 682
 683     /**
 684         Returns the usually used path separator for this format.
 685         For all formats but @c wxPATH_DOS there is only one path separator anyhow,
 686         but for DOS there are two of them and the native one, i.e. the backslash
 687         is returned by this method.
 688
 689         @see GetPathSeparators()
 690     */
 691     static wxUniChar GetPathSeparator(wxPathFormat format = wxPATH_NATIVE);
 692
 693     /**
 694         Returns the string containing all the path separators for this format.
 695         For all formats but @c wxPATH_DOS this string contains only one character
 696         but for DOS and Windows both @c '/' and @c '\' may be used as separators.
 697
 698         @see GetPathSeparator()
 699     */
 700     static wxString GetPathSeparators(wxPathFormat format = wxPATH_NATIVE);
 701
 702     /**
 703         Returns the string of characters which may terminate the path part.
 704         This is the same as GetPathSeparators() except for VMS
 705         path format where ] is used at the end of the path part.
 706     */
 707     static wxString GetPathTerminators(wxPathFormat format = wxPATH_NATIVE);
 708
 709     /**
 710         Returns the path with the trailing separator, useful for appending the name
 711         to the given path.
 712
 713         This is the same as calling
 714         @code
 715         GetPath(wxPATH_GET_VOLUME | wxPATH_GET_SEPARATOR, format)
 716         @endcode
 717     */
 718     wxString GetPathWithSep(wxPathFormat format = wxPATH_NATIVE) const;
 719
 720     /**
 721         Return the short form of the path (returns identity on non-Windows platforms).
 722     */
 723     wxString GetShortPath() const;
 724
 725     /**
 726         Returns the size of the file If the file does not exist or its size could
 727         not be read (because e.g. the file is locked by another process) the returned
 728         value is ::wxInvalidSize.
 729     */
 730     wxULongLong GetSize() const;
 731
 732     /**
 733         Returns the size of the file If the file does not exist or its size could
 734         not be read (because e.g. the file is locked by another process) the returned
 735         value is ::wxInvalidSize.
 736     */
 737     static wxULongLong GetSize(const wxString& filename);
 738
 739     /**
 740         Returns the directory used for temporary files.
 741     */
 742     static wxString GetTempDir();
 743
 744     /**
 745         Returns the last access, last modification and creation times.
 746         The last access time is updated whenever the file is read or written
 747         (or executed in the case of Windows), last modification time is only
 748         changed when the file is written to.
 749         Finally, the creation time is indeed the time when the file was created
 750         under Windows and the inode change time under Unix (as it is impossible to
 751         retrieve the real file creation time there anyhow) which can also be changed
 752         by many operations after the file creation.
 753
 754         If no filename or extension is specified in this instance of wxFileName
 755         (and therefore IsDir() returns @true) then this function will return the
 756         directory times of the path specified by GetPath(), otherwise the file
 757         times of the file specified by GetFullPath().
 758         Any of the pointers may be @NULL if the corresponding time is not needed.
 759
 760         @return @true on success, @false if we failed to retrieve the times.
 761     */
 762     bool GetTimes(wxDateTime* dtAccess, wxDateTime* dtMod,
 763                   wxDateTime* dtCreate) const;
 764
 765     /**
 766         Returns the string containing the volume for this file name, empty if it
 767         doesn't have one or if the file system doesn't support volumes at all
 768         (for example, Unix).
 769     */
 770     wxString GetVolume() const;
 771
 772     /**
 773         Returns the string separating the volume from the path for this format.
 774     */
 775     static wxString GetVolumeSeparator(wxPathFormat format = wxPATH_NATIVE);
 776
 777      /**
 778         This function builds a volume path string, for example "C:\\".
 779
 780         Implemented for the platforms which use drive letters, i.e. DOS, MSW
 781         and OS/2 only.
 782
 783         @since 2.9.0
 784
 785         @param drive
 786             The drive letter, 'A' through 'Z' or 'a' through 'z'.
 787
 788         @param flags
 789             @c wxPATH_NO_SEPARATOR or @c wxPATH_GET_SEPARATOR to omit or include
 790             the trailing path separator, the default is to include it.
 791
 792         @return Volume path string.
 793     */
 794     static wxString GetVolumeString(char drive, int flags = wxPATH_GET_SEPARATOR);
 795
 796     /**
 797         Returns @true if an extension is present.
 798     */
 799     bool HasExt() const;
 800
 801     /**
 802         Returns @true if a name is present.
 803     */
 804     bool HasName() const;
 805
 806     /**
 807         Returns @true if a volume specifier is present.
 808     */
 809     bool HasVolume() const;
 810
 811     /**
 812         Inserts a directory component before the zero-based position in the directory
 813         list. Please see AppendDir() for important notes.
 814     */
 815     void InsertDir(size_t before, const wxString& dir);
 816
 817     /**
 818         Returns @true if this filename is absolute.
 819     */
 820     bool IsAbsolute(wxPathFormat format = wxPATH_NATIVE) const;
 821
 822     /**
 823         Returns @true if the file names of this type are case-sensitive.
 824     */
 825     static bool IsCaseSensitive(wxPathFormat format = wxPATH_NATIVE);
 826
 827     /**
 828         Returns @true if this object represents a directory, @false otherwise
 829         (i.e. if it is a file).
 830
 831         Note that this method doesn't test whether the directory or file really
 832         exists, you should use DirExists() or FileExists() for this.
 833     */
 834     bool IsDir() const;
 835
 836     /**
 837         Returns @true if the directory component of this instance is an existing
 838         directory and this process has read permissions on it. Read permissions
 839         on a directory mean that you can list the directory contents but it
 840         doesn't imply that you have read permissions on the files contained.
 841     */
 842     bool IsDirReadable() const;
 843
 844     /**
 845         Returns @true if the given @e dir is an existing directory and this process
 846         has read permissions on it. Read permissions on a directory mean that you
 847         can list the directory contents but it doesn't imply that you have read
 848         permissions on the files contained.
 849     */
 850     static bool IsDirReadable(const wxString& dir);
 851
 852     /**
 853         Returns @true if the directory component of this instance
 854         is an existing directory and this process has write permissions on it.
 855         Write permissions on a directory mean that you can create new files in the
 856         directory.
 857     */
 858     bool IsDirWritable() const;
 859
 860     /**
 861         Returns @true if the  given @a dir is an existing directory and this
 862         process has write permissions on it.
 863         Write permissions on a directory mean that you can create new files in the
 864         directory.
 865     */
 866     static bool IsDirWritable(const wxString& dir);
 867
 868     /**
 869         Returns @true if a file with this name exists and if this process has execute
 870         permissions on it.
 871     */
 872     bool IsFileExecutable() const;
 873
 874     /**
 875         Returns @true if a file with this name exists and if this process has execute
 876         permissions on it.
 877     */
 878     static bool IsFileExecutable(const wxString& file);
 879
 880     /**
 881         Returns @true if a file with this name exists and if this process has read
 882         permissions on it.
 883     */
 884     bool IsFileReadable() const;
 885
 886     /**
 887         Returns @true if a file with this name exists and if this process has read
 888         permissions on it.
 889     */
 890     static bool IsFileReadable(const wxString& file);
 891
 892     /**
 893         Returns @true if a file with this name exists and if this process has write
 894         permissions on it.
 895     */
 896     bool IsFileWritable() const;
 897
 898     /**
 899         Returns @true if a file with this name exists and if this process has write
 900         permissions on it.
 901     */
 902     static bool IsFileWritable(const wxString& file);
 903
 904     /**
 905         Returns @true if the filename is valid, @false if it is not initialized yet.
 906         The assignment functions and Clear() may reset the object to the uninitialized,
 907         invalid state (the former only do it on failure).
 908     */
 909     bool IsOk() const;
 910
 911     /**
 912         Returns @true if the char is a path separator for this format.
 913     */
 914     static bool IsPathSeparator(wxChar ch,
 915                                 wxPathFormat format = wxPATH_NATIVE);
 916
 917     /**
 918         Returns @true if the volume part of the path is a unique volume name.
 919
 920         This function will always return @false if the path format is not
 921         wxPATH_DOS.
 922
 923         Unique volume names are Windows volume identifiers which remain the same
 924         regardless of where the volume is actually mounted. Example of a path
 925         using a volume name could be
 926         @code
 927             \\?\Volume{8089d7d7-d0ac-11db-9dd0-806d6172696f}\Program Files\setup.exe
 928         @endcode
 929
 930         @since 2.9.1
 931     */
 932     static bool IsMSWUniqueVolumeNamePath(const wxString& path,
 933                                           wxPathFormat format = wxPATH_NATIVE);
 934
 935     /**
 936         Returns @true if this filename is not absolute.
 937     */
 938     bool IsRelative(wxPathFormat format = wxPATH_NATIVE) const;
 939
 940     /**
 941         On Mac OS, gets the common type and creator for the given extension.
 942
 943         @onlyfor{wxosx}
 944     */
 945     static bool MacFindDefaultTypeAndCreator(const wxString& ext,
 946                                             wxUint32* type,
 947                                             wxUint32* creator);
 948
 949     /**
 950         On Mac OS, registers application defined extensions and their default type
 951         and creator.
 952
 953         @onlyfor{wxosx}
 954     */
 955     static void MacRegisterDefaultTypeAndCreator(const wxString& ext,
 956                                                 wxUint32 type,
 957                                                 wxUint32 creator);
 958
 959     /**
 960         On Mac OS, looks up the appropriate type and creator from the registration
 961         and then sets it.
 962
 963         @onlyfor{wxosx}
 964     */
 965     bool MacSetDefaultTypeAndCreator();
 966
 967     /**
 968         Make the file name absolute.
 969         This is a shortcut for
 970         @code
 971         wxFileName::Normalize(wxPATH_NORM_DOTS | wxPATH_NORM_ABSOLUTE |
 972                               wxPATH_NORM_TILDE, cwd, format)
 973         @endcode
 974
 975         @see MakeRelativeTo(), Normalize(), IsAbsolute()
 976     */
 977     bool MakeAbsolute(const wxString& cwd = wxEmptyString,
 978                       wxPathFormat format = wxPATH_NATIVE);
 979
 980     /**
 981         This function tries to put this file name in a form relative to
 982         @a pathBase.
 983         In other words, it returns the file name which should be used to access
 984         this file if the current directory were pathBase.
 985
 986         @param pathBase
 987             The directory to use as root, current directory is used by default
 988         @param format
 989             The file name format, native by default
 990
 991         @return @true if the file name has been changed, @false if we failed to do
 992                 anything with it (currently this only happens if the file name
 993                 is on a volume different from the volume specified by @a pathBase).
 994
 995         @see Normalize()
 996     */
 997     bool MakeRelativeTo(const wxString& pathBase = wxEmptyString,
 998                         wxPathFormat format = wxPATH_NATIVE);
 999
1000     /**
1001         Creates a directory.
1002
1003         @param perm
1004             The permissions for the newly created directory.
1005             See the ::wxPosixPermissions enumeration for more info.
1006         @param flags
1007             If the flags contain @c wxPATH_MKDIR_FULL flag, try to create each
1008             directory in the path and also don't return an error if the target
1009             directory already exists.
1010
1011         @return Returns @true if the directory was successfully created, @false
1012                 otherwise.
1013     */
1014     bool Mkdir(int perm = wxS_DIR_DEFAULT, int flags = 0) const;
1015
1016     /**
1017         Creates a directory.
1018
1019         @param dir
1020             The directory to create
1021         @param perm
1022             The permissions for the newly created directory.
1023             See the ::wxPosixPermissions enumeration for more info.
1024         @param flags
1025             If the flags contain @c wxPATH_MKDIR_FULL flag, try to create each
1026             directory in the path and also don't return an error if the target
1027             directory already exists.
1028
1029         @return Returns @true if the directory was successfully created, @false
1030                 otherwise.
1031     */
1032     static bool Mkdir(const wxString& dir, int perm = wxS_DIR_DEFAULT,
1033                       int flags = 0);
1034
1035     /**
1036         Normalize the path.
1037
1038         With the default flags value, the path will be made absolute, without
1039         any ".." and "." and all environment variables will be expanded in it.
1040
1041         Notice that in some rare cases normalizing a valid path may result in
1042         an invalid wxFileName object. E.g. normalizing "./" path using
1043         wxPATH_NORM_DOTS but not wxPATH_NORM_ABSOLUTE will result in a
1044         completely empty and thus invalid object. As long as there is a non
1045         empty file name the result of normalization will be valid however.
1046
1047         @param flags
1048             The kind of normalization to do with the file name. It can be
1049             any or-combination of the ::wxPathNormalize enumeration values.
1050         @param cwd
1051             If not empty, this directory will be used instead of current
1052             working directory in normalization (see @c wxPATH_NORM_ABSOLUTE).
1053         @param format
1054             The file name format to use when processing the paths, native by default.
1055
1056         @return @true if normalization was successfully or @false otherwise.
1057     */
1058     bool Normalize(int flags = wxPATH_NORM_ALL,
1059                    const wxString& cwd = wxEmptyString,
1060                    wxPathFormat format = wxPATH_NATIVE);
1061
1062     /**
1063         Prepends a directory to the file path.
1064         Please see AppendDir() for important notes.
1065     */
1066     void PrependDir(const wxString& dir);
1067
1068     /**
1069         Removes the specified directory component from the path.
1070
1071         @see GetDirCount()
1072     */
1073     void RemoveDir(size_t pos);
1074
1075     /**
1076         Removes last directory component from the path.
1077     */
1078     void RemoveLastDir();
1079
1080     /**
1081         If the path contains the value of the environment variable named @a envname
1082         then this function replaces it with the string obtained from
1083         wxString::Format(replacementFmtString, value_of_envname_variable).
1084
1085         This function is useful to make the path shorter or to make it dependent
1086         from a certain environment variable.
1087         Normalize() with @c wxPATH_NORM_ENV_VARS can perform the opposite of this
1088         function (depending on the value of @a replacementFmtString).
1089
1090         The name and extension of this filename are not modified.
1091
1092         Example:
1093         @code
1094             wxFileName fn("/usr/openwin/lib/someFile");
1095             fn.ReplaceEnvVariable("OPENWINHOME");
1096                     // now fn.GetFullPath() == "$OPENWINHOME/lib/someFile"
1097         @endcode
1098
1099         @since 2.9.0
1100
1101         @return @true if the operation was successful (which doesn't mean
1102                 that something was actually replaced, just that ::wxGetEnv
1103                 didn't fail).
1104     */
1105     bool ReplaceEnvVariable(const wxString& envname,
1106                             const wxString& replacementFmtString = "$%s",
1107                             wxPathFormat format = wxPATH_NATIVE);
1108
1109     /**
1110         Replaces, if present in the path, the home directory for the given user
1111         (see ::wxGetHomeDir) with a tilde (~).
1112
1113         Normalize() with @c wxPATH_NORM_TILDE performs the opposite of this
1114         function.
1115
1116         The name and extension of this filename are not modified.
1117
1118         @since 2.9.0
1119
1120         @return @true if the operation was successful (which doesn't mean
1121                 that something was actually replaced, just that ::wxGetHomeDir
1122                 didn't fail).
1123     */
1124     bool ReplaceHomeDir(wxPathFormat format = wxPATH_NATIVE);
1125
1126
1127     /**
1128         Deletes the specified directory from the file system.
1129
1130         @param flags
1131             Can contain one of wxPATH_RMDIR_FULL or wxPATH_RMDIR_RECURSIVE. By
1132             default contains neither so the directory will not be removed
1133             unless it is empty.
1134
1135         @return Returns @true if the directory was successfully deleted, @false
1136                 otherwise.
1137     */
1138     bool Rmdir(int flags = 0) const;
1139
1140     /**
1141         Deletes the specified directory from the file system.
1142
1143         @param dir
1144             The directory to delete
1145         @param flags
1146             Can contain one of wxPATH_RMDIR_FULL or wxPATH_RMDIR_RECURSIVE. By
1147             default contains neither so the directory will not be removed
1148             unless it is empty.
1149
1150         @return Returns @true if the directory was successfully deleted, @false
1151                 otherwise.
1152     */
1153     static bool Rmdir(const wxString& dir, int flags = 0);
1154
1155     /**
1156         Compares the filename using the rules of this platform.
1157     */
1158     bool SameAs(const wxFileName& filepath,
1159                 wxPathFormat format = wxPATH_NATIVE) const;
1160
1161     /**
1162         Changes the current working directory.
1163     */
1164     bool SetCwd() const;
1165
1166     /**
1167         Changes the current working directory.
1168     */
1169     static bool SetCwd(const wxString& cwd);
1170
1171     /**
1172         Sets the extension of the file name to be an empty extension.
1173         This is different from having no extension at all as the file
1174         name will have a trailing dot after a call to this method.
1175
1176         @see SetExt(), ClearExt()
1177     */
1178     void SetEmptyExt();
1179
1180     /**
1181         Sets the extension of the file name.
1182
1183         Setting an empty string as the extension will remove the extension
1184         resulting in a file name without a trailing dot, unlike a call to
1185         SetEmptyExt().
1186
1187         @see SetEmptyExt(), ClearExt()
1188     */
1189     void SetExt(const wxString& ext);
1190
1191     /**
1192         The full name is the file name and extension (but without the path).
1193     */
1194     void SetFullName(const wxString& fullname);
1195
1196     /**
1197         Sets the name part (without extension).
1198
1199         @see SetFullName()
1200     */
1201     void SetName(const wxString& name);
1202
1203     /**
1204         Sets the path.
1205
1206         The @a path argument includes both the path and the volume, if
1207         supported by @a format.
1208
1209         Calling this function doesn't affect the name and extension components,
1210         to change them as well you can use Assign() or just an assignment
1211         operator.
1212
1213         @see GetPath()
1214      */
1215     void SetPath(const wxString& path, wxPathFormat format = wxPATH_NATIVE);
1216
1217     /**
1218         Sets the file creation and last access/modification times (any of the pointers
1219         may be @NULL).
1220     */
1221     bool SetTimes(const wxDateTime* dtAccess,
1222                   const wxDateTime* dtMod,
1223                   const wxDateTime* dtCreate) const;
1224
1225     /**
1226         Sets the volume specifier.
1227     */
1228     void SetVolume(const wxString& volume);
1229
1230     /**
1231         Return whether some operations will follow symlink.
1232
1233         By default, file operations "follow symlink", i.e. operate on its
1234         target and not on the symlink itself. See DontFollowLink() for more
1235         information.
1236
1237         @since 2.9.5
1238     */
1239     bool ShouldFollowLink() const;
1240
1241     //@{
1242     /**
1243         This function splits a full file name into components: the volume (with the
1244         first version) path (including the volume in the second version), the base name
1245         and the extension.
1246
1247         Any of the output parameters (@e volume, @e path, @a name or @e ext) may
1248         be @NULL if you are not interested in the value of a particular component.
1249         Also, @a fullpath may be empty on entry.
1250         On return, @a path contains the file path (without the trailing separator),
1251         @a name contains the file name and @a ext contains the file extension
1252         without leading dot. All three of them may be empty if the corresponding
1253         component is. The old contents of the strings pointed to by these parameters
1254         will be overwritten in any case (if the pointers are not @NULL).
1255
1256         Note that for a filename "foo." the extension is present, as indicated by the
1257         trailing dot, but empty. If you need to cope with such cases, you should use
1258         @a hasExt instead of relying on testing whether @a ext is empty or not.
1259     */
1260     static void SplitPath(const wxString& fullpath,
1261                           wxString* volume,
1262                           wxString* path,
1263                           wxString* name,
1264                           wxString* ext,
1265                           bool* hasExt = NULL,
1266                           wxPathFormat format = wxPATH_NATIVE);
1267     static void SplitPath(const wxString& fullpath,
1268                           wxString* volume,
1269                           wxString* path,
1270                           wxString* name,
1271                           wxString* ext,
1272                           wxPathFormat format);
1273     static void SplitPath(const wxString& fullpath,
1274                           wxString* path,
1275                           wxString* name,
1276                           wxString* ext,
1277                           wxPathFormat format = wxPATH_NATIVE);
1278     //@}
1279
1280     /**
1281         Splits the given @a fullpath into the volume part (which may be empty) and
1282         the pure path part, not containing any volume.
1283
1284         @see SplitPath()
1285     */
1286     static void SplitVolume(const wxString& fullpath,
1287                             wxString* volume,
1288                             wxString* path,
1289                             wxPathFormat format = wxPATH_NATIVE);
1290
1291
1292     /**
1293         Strip the file extension.
1294
1295         This function does more than just removing everything after the last
1296         period from the string, for example it will return the string ".vimrc"
1297         unchanged because the part after the period is not an extension but the
1298         file name in this case. You can use wxString::BeforeLast() to really
1299         get just the part before the last period (but notice that that function
1300         returns empty string if period is not present at all unlike this
1301         function which returns the @a fullname unchanged in this case).
1302
1303         @param fullname
1304            File path including name and, optionally, extension.
1305
1306         @return
1307             File path without extension
1308
1309         @since 2.9.0
1310     */
1311     static wxString StripExtension(const wxString& fullname);
1312
1313     /**
1314         Sets the access and modification times to the current moment.
1315     */
1316     bool Touch() const;
1317
1318     /**
1319         Returns @true if the filenames are different. The string @e filenames
1320         is interpreted as a path in the native filename format.
1321     */
1322     bool operator!=(const wxFileName& filename) const;
1323
1324     /**
1325         Returns @true if the filenames are different. The string @e filenames
1326         is interpreted as a path in the native filename format.
1327     */
1328     bool operator!=(const wxString& filename) const;
1329
1330     /**
1331         Returns @true if the filenames are equal. The string @e filenames is
1332         interpreted as a path in the native filename format.
1333     */
1334     bool operator==(const wxFileName& filename) const;
1335
1336     /**
1337         Returns @true if the filenames are equal. The string @e filenames is
1338         interpreted as a path in the native filename format.
1339     */
1340     bool operator==(const wxString& filename) const;
1341
1342     /**
1343         Assigns the new value to this filename object.
1344     */
1345     wxFileName& operator=(const wxFileName& filename);
1346
1347     /**
1348         Assigns the new value to this filename object.
1349     */
1350     wxFileName& operator=(const wxString& filename);
1351 };