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