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