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