interface/filename.h

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