interface/wx/filename.h

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