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 /**
  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 wether 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 volumne, 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 volumne, 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 the @a prefix is an absolute path, the temporary file is created in this
 428         directory, otherwise it is created in the default system directory for the
 429         temporary files or in the current directory.
 430
 431         If the function succeeds, the temporary file is actually created.
 432         If @a fileTemp is not @NULL, this file will be opened using the name of
 433         the temporary file. When possible, this is done in an atomic way ensuring that
 434         no race condition occurs between the temporary file name generation and opening
 435         it which could often lead to security compromise on the multiuser systems.
 436         If @a fileTemp is @NULL, the file is only created, but not opened.
 437         Under Unix, the temporary file will have read and write permissions for the
 438         owner only to minimize the security problems.
 439
 440         @param prefix
 441             Prefix to use for the temporary file name construction
 442         @param fileTemp
 443             The file to open or @NULL to just get the name
 444
 445         @return The full temporary file name or an empty string on error.
 446     */
 447     static wxString CreateTempFileName(const wxString& prefix,
 448                                        wxFile* fileTemp = NULL);
 449     static wxString CreateTempFileName(const wxString& prefix,
 450                                        wxFFile* fileTemp = NULL);
 451     //@}
 452
 453     /**
 454         Returns @true if the directory with this name exists.
 455     */
 456     bool DirExists() const;
 457
 458     /**
 459         Returns @true if the directory with this name exists.
 460     */
 461     static bool DirExists(const wxString& dir);
 462
 463     /**
 464         Returns the object corresponding to the directory with the given name.
 465         The @a dir parameter may have trailing path separator or not.
 466     */
 467     static wxFileName DirName(const wxString& dir,
 468                               wxPathFormat format = wxPATH_NATIVE);
 469
 470     /**
 471         Returns @true if the file with this name exists.
 472
 473         @see DirExists()
 474     */
 475     bool FileExists() const;
 476
 477     /**
 478         Returns @true if the file with this name exists.
 479
 480         @see DirExists()
 481     */
 482     static bool FileExists(const wxString& file);
 483
 484     /**
 485         Returns the file name object corresponding to the given @e file. This
 486         function exists mainly for symmetry with DirName().
 487     */
 488     static wxFileName FileName(const wxString& file,
 489                                wxPathFormat format = wxPATH_NATIVE);
 490
 491     /**
 492         Retrieves the value of the current working directory on the specified volume.
 493         If the volume is empty, the program's current working directory is returned for
 494         the current volume.
 495
 496         @return The string containing the current working directory or an empty
 497                 string on error.
 498
 499         @see AssignCwd()
 500     */
 501     static wxString GetCwd(const wxString& volume = wxEmptyString);
 502
 503     /**
 504         Returns the number of directories in the file name.
 505     */
 506     size_t GetDirCount() const;
 507
 508     /**
 509         Returns the directories in string array form.
 510     */
 511     const wxArrayString& GetDirs() const;
 512
 513     /**
 514         Returns the file name extension.
 515     */
 516     wxString GetExt() const;
 517
 518     /**
 519         Returns the characters that can't be used in filenames and directory names
 520         for the specified format.
 521     */
 522     static wxString GetForbiddenChars(wxPathFormat format = wxPATH_NATIVE);
 523
 524     /**
 525         Returns the canonical path format for this platform.
 526     */
 527     static wxPathFormat GetFormat(wxPathFormat format = wxPATH_NATIVE);
 528
 529     /**
 530         Returns the full name (including extension but excluding directories).
 531     */
 532     wxString GetFullName() const;
 533
 534     /**
 535         Returns the full path with name and extension.
 536     */
 537     wxString GetFullPath(wxPathFormat format = wxPATH_NATIVE) const;
 538
 539     /**
 540         Returns the home directory.
 541     */
 542     static wxString GetHomeDir();
 543
 544     //@{
 545     /**
 546         Returns the representation of the file size in a human-readable form.
 547
 548         In the first version, the size of this file is used. In the second one,
 549         the specified size @a bytes is used.
 550
 551         If the file size could not be retrieved or @a bytes is ::wxInvalidSize
 552         or zero, the @c failmsg string is returned.
 553
 554         Otherwise the returned string is a floating-point number with @c
 555         precision decimal digits followed by the abbreviation of the unit used.
 556         By default the traditional, although incorrect, convention of using SI
 557         units for multiples of 1024 is used, i.e. returned string will use
 558         suffixes of B, KB, MB, GB, TB for bytes, kilobytes, megabytes,
 559         gigabytes and terabytes respectively. With the IEC convention the names
 560         of the units are changed to B, KiB, MiB, GiB and TiB fofr bytes,
 561         kibibytes, mebibyes, gibibytes and tebibytes. Finally, with SI
 562         convention the same B, KB, MB, GB and TB suffixes are used but in their
 563         correct SI meaning, i.e. as multiples of 1000 and not 1024.
 564
 565         Support for the different size conventions is new in wxWidgets 2.9.1,
 566         in previous versions only the traditional convention was implemented.
 567     */
 568     wxString
 569     GetHumanReadableSize(const wxString& failmsg = _("Not available"),
 570                          int precision = 1,
 571                          wxSizeConvention conv = wxSIZE_CONV_TRADITIONAL) const;
 572
 573     static wxString
 574     GetHumanReadableSize(const wxULongLong& bytes,
 575                          const wxString& nullsize = _("Not available"),
 576                          int precision = 1,
 577                          wxSizeConvention conv = wxSIZE_CONV_TRADITIONAL);
 578     //@}
 579
 580     /**
 581         Return the long form of the path (returns identity on non-Windows platforms).
 582     */
 583     wxString GetLongPath() const;
 584
 585     /**
 586         Returns the last time the file was last modified.
 587     */
 588     wxDateTime GetModificationTime() const;
 589
 590     /**
 591         Returns the name part of the filename (without extension).
 592
 593         @see GetFullName()
 594     */
 595     wxString GetName() const;
 596
 597     /**
 598         Returns the path part of the filename (without the name or extension).
 599
 600         The possible flags values are:
 601
 602         - @b wxPATH_GET_VOLUME:
 603         Return the path with the volume (does nothing for the filename formats
 604         without volumes), otherwise the path without volume part is returned.
 605
 606         - @b wxPATH_GET_SEPARATOR:
 607         Return the path with the trailing separator, if this flag is not given
 608         there will be no separator at the end of the path.
 609
 610         - @b wxPATH_NO_SEPARATOR:
 611         Don't include the trailing separator in the returned string. This is
 612         the default (the value of this flag is 0) and exists only for symmetry
 613         with wxPATH_GET_SEPARATOR.
 614     */
 615     wxString GetPath(int flags = wxPATH_GET_VOLUME,
 616                      wxPathFormat format = wxPATH_NATIVE) const;
 617
 618     /**
 619         Returns the usually used path separator for this format.
 620         For all formats but @c wxPATH_DOS there is only one path separator anyhow,
 621         but for DOS there are two of them and the native one, i.e. the backslash
 622         is returned by this method.
 623
 624         @see GetPathSeparators()
 625     */
 626     static wxUniChar GetPathSeparator(wxPathFormat format = wxPATH_NATIVE);
 627
 628     /**
 629         Returns the string containing all the path separators for this format.
 630         For all formats but @c wxPATH_DOS this string contains only one character
 631         but for DOS and Windows both @c '/' and @c '\' may be used as separators.
 632
 633         @see GetPathSeparator()
 634     */
 635     static wxString GetPathSeparators(wxPathFormat format = wxPATH_NATIVE);
 636
 637     /**
 638         Returns the string of characters which may terminate the path part.
 639         This is the same as GetPathSeparators() except for VMS
 640         path format where ] is used at the end of the path part.
 641     */
 642     static wxString GetPathTerminators(wxPathFormat format = wxPATH_NATIVE);
 643
 644     /**
 645         Returns the path with the trailing separator, useful for appending the name
 646         to the given path.
 647
 648         This is the same as calling
 649         @code
 650         GetPath(wxPATH_GET_VOLUME | wxPATH_GET_SEPARATOR, format)
 651         @endcode
 652     */
 653     wxString GetPathWithSep(wxPathFormat format = wxPATH_NATIVE) const;
 654
 655     /**
 656         Return the short form of the path (returns identity on non-Windows platforms).
 657     */
 658     wxString GetShortPath() const;
 659
 660     /**
 661         Returns the size of the file If the file does not exist or its size could
 662         not be read (because e.g. the file is locked by another process) the returned
 663         value is ::wxInvalidSize.
 664     */
 665     wxULongLong GetSize() const;
 666
 667     /**
 668         Returns the size of the file If the file does not exist or its size could
 669         not be read (because e.g. the file is locked by another process) the returned
 670         value is ::wxInvalidSize.
 671     */
 672     static wxULongLong GetSize(const wxString& filename);
 673
 674     /**
 675         Returns the directory used for temporary files.
 676     */
 677     static wxString GetTempDir();
 678
 679     /**
 680         Returns the last access, last modification and creation times.
 681         The last access time is updated whenever the file is read or written
 682         (or executed in the case of Windows), last modification time is only
 683         changed when the file is written to.
 684         Finally, the creation time is indeed the time when the file was created
 685         under Windows and the inode change time under Unix (as it is impossible to
 686         retrieve the real file creation time there anyhow) which can also be changed
 687         by many operations after the file creation.
 688
 689         If no filename or extension is specified in this instance of wxFileName
 690         (and therefore IsDir() returns @true) then this function will return the
 691         directory times of the path specified by GetPath(), otherwise the file
 692         times of the file specified by GetFullPath().
 693         Any of the pointers may be @NULL if the corresponding time is not needed.
 694
 695         @return @true on success, @false if we failed to retrieve the times.
 696     */
 697     bool GetTimes(wxDateTime* dtAccess, wxDateTime* dtMod,
 698                   wxDateTime* dtCreate) const;
 699
 700     /**
 701         Returns the string containing the volume for this file name, empty if it
 702         doesn't have one or if the file system doesn't support volumes at all
 703         (for example, Unix).
 704     */
 705     wxString GetVolume() const;
 706
 707     /**
 708         Returns the string separating the volume from the path for this format.
 709     */
 710     static wxString GetVolumeSeparator(wxPathFormat format = wxPATH_NATIVE);
 711
 712      /**
 713         This function builds a volume path string, for example "C:\\".
 714
 715         Implemented for the platforms which use drive letters, i.e. DOS, MSW
 716         and OS/2 only.
 717
 718         @since 2.9.0
 719
 720         @param drive
 721             The drive letter, 'A' through 'Z' or 'a' through 'z'.
 722
 723         @param flags
 724             @c wxPATH_NO_SEPARATOR or @c wxPATH_GET_SEPARATOR to omit or include
 725             the trailing path separator, the default is to include it.
 726
 727         @return Volume path string.
 728     */
 729     static wxString GetVolumeString(char drive, int flags = wxPATH_GET_SEPARATOR);
 730
 731     /**
 732         Returns @true if an extension is present.
 733     */
 734     bool HasExt() const;
 735
 736     /**
 737         Returns @true if a name is present.
 738     */
 739     bool HasName() const;
 740
 741     /**
 742         Returns @true if a volume specifier is present.
 743     */
 744     bool HasVolume() const;
 745
 746     /**
 747         Inserts a directory component before the zero-based position in the directory
 748         list. Please see AppendDir() for important notes.
 749     */
 750     void InsertDir(size_t before, const wxString& dir);
 751
 752     /**
 753         Returns @true if this filename is absolute.
 754     */
 755     bool IsAbsolute(wxPathFormat format = wxPATH_NATIVE) const;
 756
 757     /**
 758         Returns @true if the file names of this type are case-sensitive.
 759     */
 760     static bool IsCaseSensitive(wxPathFormat format = wxPATH_NATIVE);
 761
 762     /**
 763         Returns @true if this object represents a directory, @false otherwise
 764         (i.e. if it is a file).
 765
 766         Note that this method doesn't test whether the directory or file really
 767         exists, you should use DirExists() or FileExists() for this.
 768     */
 769     bool IsDir() const;
 770
 771     /**
 772         Returns @true if the directory component of this instance is an existing
 773         directory and this process has read permissions on it. Read permissions
 774         on a directory mean that you can list the directory contents but it
 775         doesn't imply that you have read permissions on the files contained.
 776     */
 777     bool IsDirReadable() const;
 778
 779     /**
 780         Returns @true if the given @e dir is an existing directory and this process
 781         has read permissions on it. Read permissions on a directory mean that you
 782         can list the directory contents but it doesn't imply that you have read
 783         permissions on the files contained.
 784     */
 785     static bool IsDirReadable(const wxString& dir);
 786
 787     /**
 788         Returns @true if the directory component of this instance
 789         is an existing directory and this process has write permissions on it.
 790         Write permissions on a directory mean that you can create new files in the
 791         directory.
 792     */
 793     bool IsDirWritable() const;
 794
 795     /**
 796         Returns @true if the  given @a dir is an existing directory and this
 797         process has write permissions on it.
 798         Write permissions on a directory mean that you can create new files in the
 799         directory.
 800     */
 801     static bool IsDirWritable(const wxString& dir);
 802
 803     /**
 804         Returns @true if a file with this name exists and if this process has execute
 805         permissions on it.
 806     */
 807     bool IsFileExecutable() const;
 808
 809     /**
 810         Returns @true if a file with this name exists and if this process has execute
 811         permissions on it.
 812     */
 813     static bool IsFileExecutable(const wxString& file);
 814
 815     /**
 816         Returns @true if a file with this name exists and if this process has read
 817         permissions on it.
 818     */
 819     bool IsFileReadable() const;
 820
 821     /**
 822         Returns @true if a file with this name exists and if this process has read
 823         permissions on it.
 824     */
 825     static bool IsFileReadable(const wxString& file);
 826
 827     /**
 828         Returns @true if a file with this name exists and if this process has write
 829         permissions on it.
 830     */
 831     bool IsFileWritable() const;
 832
 833     /**
 834         Returns @true if a file with this name exists and if this process has write
 835         permissions on it.
 836     */
 837     static bool IsFileWritable(const wxString& file);
 838
 839     /**
 840         Returns @true if the filename is valid, @false if it is not initialized yet.
 841         The assignment functions and Clear() may reset the object to the uninitialized,
 842         invalid state (the former only do it on failure).
 843     */
 844     bool IsOk() const;
 845
 846     /**
 847         Returns @true if the char is a path separator for this format.
 848     */
 849     static bool IsPathSeparator(wxChar ch,
 850                                 wxPathFormat format = wxPATH_NATIVE);
 851
 852     /**
 853         Returns @true if the volume part of the path is a unique volume name.
 854
 855         This function will always return @false if the path format is not
 856         wxPATH_DOS.
 857
 858         Unique volume names are Windows volume identifiers which remain the same
 859         regardless of where the volume is actually mounted. Example of a path
 860         using a volume name could be
 861         @code
 862             \\?\Volume{8089d7d7-d0ac-11db-9dd0-806d6172696f}\Program Files\setup.exe
 863         @endcode
 864
 865         @since 2.9.1
 866     */
 867     static bool IsMSWUniqueVolumeNamePath(const wxString& path,
 868                                           wxPathFormat format = wxPATH_NATIVE);
 869
 870     /**
 871         Returns @true if this filename is not absolute.
 872     */
 873     bool IsRelative(wxPathFormat format = wxPATH_NATIVE) const;
 874
 875     /**
 876         On Mac OS, gets the common type and creator for the given extension.
 877     */
 878     static bool MacFindDefaultTypeAndCreator(const wxString& ext,
 879                                             wxUint32* type,
 880                                             wxUint32* creator);
 881
 882     /**
 883         On Mac OS, registers application defined extensions and their default type
 884         and creator.
 885     */
 886     static void MacRegisterDefaultTypeAndCreator(const wxString& ext,
 887                                                 wxUint32 type,
 888                                                 wxUint32 creator);
 889
 890     /**
 891         On Mac OS, looks up the appropriate type and creator from the registration
 892         and then sets it.
 893     */
 894     bool MacSetDefaultTypeAndCreator();
 895
 896     /**
 897         Make the file name absolute.
 898         This is a shortcut for
 899         @code
 900         wxFileName::Normalize(wxPATH_NORM_DOTS | wxPATH_NORM_ABSOLUTE |
 901                               wxPATH_NORM_TILDE, cwd, format)
 902         @endcode
 903
 904         @see MakeRelativeTo(), Normalize(), IsAbsolute()
 905     */
 906     bool MakeAbsolute(const wxString& cwd = wxEmptyString,
 907                       wxPathFormat format = wxPATH_NATIVE);
 908
 909     /**
 910         This function tries to put this file name in a form relative to
 911         @a pathBase.
 912         In other words, it returns the file name which should be used to access
 913         this file if the current directory were pathBase.
 914
 915         @param pathBase
 916             The directory to use as root, current directory is used by default
 917         @param format
 918             The file name format, native by default
 919
 920         @return @true if the file name has been changed, @false if we failed to do
 921                 anything with it (currently this only happens if the file name
 922                 is on a volume different from the volume specified by @a pathBase).
 923
 924         @see Normalize()
 925     */
 926     bool MakeRelativeTo(const wxString& pathBase = wxEmptyString,
 927                         wxPathFormat format = wxPATH_NATIVE);
 928
 929     /**
 930         Creates a directory.
 931
 932         @param perm
 933             The permissions for the newly created directory.
 934             See the ::wxPosixPermissions enumeration for more info.
 935         @param flags
 936             If the flags contain @c wxPATH_MKDIR_FULL flag, try to create each
 937             directory in the path and also don't return an error if the target
 938             directory already exists.
 939
 940         @return Returns @true if the directory was successfully created, @false
 941                 otherwise.
 942     */
 943     bool Mkdir(int perm = wxS_DIR_DEFAULT, int flags = 0) const;
 944
 945     /**
 946         Creates a directory.
 947
 948         @param dir
 949             The directory to create
 950         @param perm
 951             The permissions for the newly created directory.
 952             See the ::wxPosixPermissions enumeration for more info.
 953         @param flags
 954             If the flags contain @c wxPATH_MKDIR_FULL flag, try to create each
 955             directory in the path and also don't return an error if the target
 956             directory already exists.
 957
 958         @return Returns @true if the directory was successfully created, @false
 959                 otherwise.
 960     */
 961     static bool Mkdir(const wxString& dir, int perm = wxS_DIR_DEFAULT,
 962                       int flags = 0);
 963
 964     /**
 965         Normalize the path. With the default flags value, the path will be
 966         made absolute, without any ".." and "." and all environment
 967         variables will be expanded in it.
 968
 969         @param flags
 970             The kind of normalization to do with the file name. It can be
 971             any or-combination of the ::wxPathNormalize enumeration values.
 972         @param cwd
 973             If not empty, this directory will be used instead of current
 974             working directory in normalization (see @c wxPATH_NORM_ABSOLUTE).
 975         @param format
 976             The file name format to use when processing the paths, native by default.
 977
 978         @return @true if normalization was successfully or @false otherwise.
 979     */
 980     bool Normalize(int flags = wxPATH_NORM_ALL,
 981                    const wxString& cwd = wxEmptyString,
 982                    wxPathFormat format = wxPATH_NATIVE);
 983
 984     /**
 985         Prepends a directory to the file path.
 986         Please see AppendDir() for important notes.
 987     */
 988     void PrependDir(const wxString& dir);
 989
 990     /**
 991         Removes the specified directory component from the path.
 992
 993         @see GetDirCount()
 994     */
 995     void RemoveDir(size_t pos);
 996
 997     /**
 998         Removes last directory component from the path.
 999     */
1000     void RemoveLastDir();
1001
1002     /**
1003         If the path contains the value of the environment variable named @a envname
1004         then this function replaces it with the string obtained from
1005         wxString::Format(replacementFmtString, value_of_envname_variable).
1006
1007         This function is useful to make the path shorter or to make it dependent
1008         from a certain environment variable.
1009         Normalize() with @c wxPATH_NORM_ENV_VARS can perform the opposite of this
1010         function (depending on the value of @a replacementFmtString).
1011
1012         The name and extension of this filename are not modified.
1013
1014         Example:
1015         @code
1016             wxFileName fn("/usr/openwin/lib/someFile");
1017             fn.ReplaceEnvVariable("OPENWINHOME");
1018                     // now fn.GetFullPath() == "$OPENWINHOME/lib/someFile"
1019         @endcode
1020
1021         @since 2.9.0
1022
1023         @return @true if the operation was successful (which doesn't mean
1024                 that something was actually replaced, just that ::wxGetEnv
1025                 didn't fail).
1026     */
1027     bool ReplaceEnvVariable(const wxString& envname,
1028                             const wxString& replacementFmtString = "$%s",
1029                             wxPathFormat format = wxPATH_NATIVE);
1030
1031     /**
1032         Replaces, if present in the path, the home directory for the given user
1033         (see ::wxGetHomeDir) with a tilde (~).
1034
1035         Normalize() with @c wxPATH_NORM_TILDE performs the opposite of this
1036         function.
1037
1038         The name and extension of this filename are not modified.
1039
1040         @since 2.9.0
1041
1042         @return @true if the operation was successful (which doesn't mean
1043                 that something was actually replaced, just that ::wxGetHomeDir
1044                 didn't fail).
1045     */
1046     bool ReplaceHomeDir(wxPathFormat format = wxPATH_NATIVE);
1047
1048
1049     /**
1050         Deletes the specified directory from the file system.
1051
1052         @param flags
1053             Can contain one of wxPATH_RMDIR_FULL or wxPATH_RMDIR_RECURSIVE. By
1054             default contains neither so the directory will not be removed
1055             unless it is empty.
1056
1057         @return Returns @true if the directory was successfully deleted, @false
1058                 otherwise.
1059     */
1060     bool Rmdir(int flags = 0) const;
1061
1062     /**
1063         Deletes the specified directory from the file system.
1064
1065         @param dir
1066             The directory to delete
1067         @param flags
1068             Can contain one of wxPATH_RMDIR_FULL or wxPATH_RMDIR_RECURSIVE. By
1069             default contains neither so the directory will not be removed
1070             unless it is empty.
1071
1072         @return Returns @true if the directory was successfully deleted, @false
1073                 otherwise.
1074     */
1075     static bool Rmdir(const wxString& dir, int flags = 0);
1076
1077     /**
1078         Compares the filename using the rules of this platform.
1079     */
1080     bool SameAs(const wxFileName& filepath,
1081                 wxPathFormat format = wxPATH_NATIVE) const;
1082
1083     /**
1084         Changes the current working directory.
1085     */
1086     bool SetCwd() const;
1087
1088     /**
1089         Changes the current working directory.
1090     */
1091     static bool SetCwd(const wxString& cwd);
1092
1093     /**
1094         Sets the extension of the file name to be an empty extension.
1095         This is different from having no extension at all as the file
1096         name will have a trailing dot after a call to this method.
1097
1098         @see SetExt(), ClearExt()
1099     */
1100     void SetEmptyExt();
1101
1102     /**
1103         Sets the extension of the file name.
1104
1105         Setting an empty string as the extension will remove the extension
1106         resulting in a file name without a trailing dot, unlike a call to
1107         SetEmptyExt().
1108
1109         @see SetEmptyExt(), ClearExt()
1110     */
1111     void SetExt(const wxString& ext);
1112
1113     /**
1114         The full name is the file name and extension (but without the path).
1115     */
1116     void SetFullName(const wxString& fullname);
1117
1118     /**
1119         Sets the name part (without extension).
1120
1121         @see SetFullName()
1122     */
1123     void SetName(const wxString& name);
1124
1125     /**
1126         Sets the full path.
1127
1128         The @a path argument includes both the path (and the volume, if
1129         supported by @a format) and the name and extension.
1130
1131         @see GetPath()
1132      */
1133     void SetPath(const wxString& path, wxPathFormat format = wxPATH_NATIVE);
1134
1135     /**
1136         Sets the file creation and last access/modification times (any of the pointers
1137         may be @NULL).
1138     */
1139     bool SetTimes(const wxDateTime* dtAccess,
1140                   const wxDateTime* dtMod,
1141                   const wxDateTime* dtCreate) const;
1142
1143     /**
1144         Sets the volume specifier.
1145     */
1146     void SetVolume(const wxString& volume);
1147
1148     //@{
1149     /**
1150         This function splits a full file name into components: the volume (with the
1151         first version) path (including the volume in the second version), the base name
1152         and the extension.
1153
1154         Any of the output parameters (@e volume, @e path, @a name or @e ext) may
1155         be @NULL if you are not interested in the value of a particular component.
1156         Also, @a fullpath may be empty on entry.
1157         On return, @a path contains the file path (without the trailing separator),
1158         @a name contains the file name and @a ext contains the file extension
1159         without leading dot. All three of them may be empty if the corresponding
1160         component is. The old contents of the strings pointed to by these parameters
1161         will be overwritten in any case (if the pointers are not @NULL).
1162
1163         Note that for a filename "foo." the extension is present, as indicated by the
1164         trailing dot, but empty. If you need to cope with such cases, you should use
1165         @a hasExt instead of relying on testing whether @a ext is empty or not.
1166     */
1167     static void SplitPath(const wxString& fullpath,
1168                           wxString* volume,
1169                           wxString* path,
1170                           wxString* name,
1171                           wxString* ext,
1172                           bool* hasExt = NULL,
1173                           wxPathFormat format = wxPATH_NATIVE);
1174     static void SplitPath(const wxString& fullpath,
1175                           wxString* volume,
1176                           wxString* path,
1177                           wxString* name,
1178                           wxString* ext,
1179                           wxPathFormat format);
1180     static void SplitPath(const wxString& fullpath,
1181                           wxString* path,
1182                           wxString* name,
1183                           wxString* ext,
1184                           wxPathFormat format = wxPATH_NATIVE);
1185     //@}
1186
1187     /**
1188         Splits the given @a fullpath into the volume part (which may be empty) and
1189         the pure path part, not containing any volume.
1190
1191         @see SplitPath()
1192     */
1193     static void SplitVolume(const wxString& fullpath,
1194                             wxString* volume,
1195                             wxString* path,
1196                             wxPathFormat format = wxPATH_NATIVE);
1197
1198
1199     /**
1200         Strip the file extension.
1201
1202         This function does more than just removing everything after the last
1203         period from the string, for example it will return the string ".vimrc"
1204         unchanged because the part after the period is not an extension but the
1205         file name in this case. You can use wxString::BeforeLast() to really
1206         get just the part before the last period (but notice that that function
1207         returns empty string if period is not present at all unlike this
1208         function which returns the @a fullname unchanged in this case).
1209
1210         @param fullname
1211            File path including name and, optionally, extension.
1212
1213         @return
1214             File path without extension
1215
1216         @since 2.9.0
1217     */
1218     static wxString StripExtension(const wxString& fullname);
1219
1220     /**
1221         Sets the access and modification times to the current moment.
1222     */
1223     bool Touch() const;
1224
1225     /**
1226         Returns @true if the filenames are different. The string @e filenames
1227         is interpreted as a path in the native filename format.
1228     */
1229     bool operator!=(const wxFileName& filename) const;
1230
1231     /**
1232         Returns @true if the filenames are different. The string @e filenames
1233         is interpreted as a path in the native filename format.
1234     */
1235     bool operator!=(const wxString& filename) const;
1236
1237     /**
1238         Returns @true if the filenames are equal. The string @e filenames is
1239         interpreted as a path in the native filename format.
1240     */
1241     bool operator==(const wxFileName& filename) const;
1242
1243     /**
1244         Returns @true if the filenames are equal. The string @e filenames is
1245         interpreted as a path in the native filename format.
1246     */
1247     bool operator==(const wxString& filename) const;
1248
1249     /**
1250         Assigns the new value to this filename object.
1251     */
1252     wxFileName& operator=(const wxFileName& filename);
1253
1254     /**
1255         Assigns the new value to this filename object.
1256     */
1257     wxFileName& operator=(const wxString& filename);
1258 };