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