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