interface/wx/filename.h

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