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