interface/wx/filename.h

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