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