interface/wx/filename.h

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