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