interface/wx/filename.h

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