interface/wx/filename.h

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