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