interface/wx/filename.h

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