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 ClearExt();
 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         Returns the size of the file in a human-readable form.
 392         If the size could not be retrieved the @c failmsg string
 393         is returned. In case of success, the returned string is
 394         a floating-point number with @c precision decimal digits
 395         followed by the size unit (B, kB, MB, GB, TB: respectively
 396         bytes, kilobytes, megabytes, gigabytes, terabytes).
 397     */
 398     wxString GetHumanReadableSize(const wxString& failmsg = "Not available",
 399                                   int precision = 1);
 400
 401     /**
 402         Returns the size of the given number of bytes in a human-readable form.
 403         If @c bytes is @c wxInvalidSize or zero, then @c nullsize is returned.
 404         In case of success, the returned string is a floating-point number with @c
 405         precision decimal digits followed by the size unit (B, kB, MB, GB,
 406         TB: respectively bytes, kilobytes, megabytes, gigabytes, terabytes).
 407     */
 408     const static wxString  GetHumanReadableSize(const wxULongLong& bytes,
 409             const wxString& nullsize = "Not available",
 410             int precision = 1);
 411
 412     /**
 413         Return the long form of the path (returns identity on non-Windows platforms)
 414     */
 415     wxString GetLongPath() const;
 416
 417     /**
 418         Returns the last time the file was last modified.
 419     */
 420     wxDateTime GetModificationTime() const;
 421
 422     /**
 423         Returns the name part of the filename (without extension).
 424
 425         @see GetFullName()
 426     */
 427     wxString GetName() const;
 428
 429     /**
 430         Returns the path part of the filename (without the name or extension). The
 431         possible flags values are:
 432
 433         @b wxPATH_GET_VOLUME
 434
 435         Return the path with the volume (does nothing for the filename formats without
 436         volumes), otherwise the path without volume part is returned.
 437
 438         @b wxPATH_GET_SEPARATOR
 439
 440         Return the path with the trailing separator, if this flag is not given there
 441         will be no separator at the end of the path.
 442     */
 443     wxString GetPath(int flags = wxPATH_GET_VOLUME,
 444                      wxPathFormat format = wxPATH_NATIVE) const;
 445
 446     /**
 447         Returns the usually used path separator for this format. For all formats but
 448         @c wxPATH_DOS there is only one path separator anyhow, but for DOS there
 449         are two of them and the native one, i.e. the backslash is returned by this
 450         method.
 451
 452         @see GetPathSeparators()
 453     */
 454     static wxChar GetPathSeparator(wxPathFormat format = wxPATH_NATIVE);
 455
 456     /**
 457         Returns the string containing all the path separators for this format. For all
 458         formats but @c wxPATH_DOS this string contains only one character but for
 459         DOS and Windows both @c '/' and @c '\' may be used as
 460         separators.
 461
 462         @see GetPathSeparator()
 463     */
 464     static wxString GetPathSeparators(wxPathFormat format = wxPATH_NATIVE);
 465
 466     /**
 467         Returns the string of characters which may terminate the path part. This is the
 468         same as GetPathSeparators() except for VMS
 469         path format where ] is used at the end of the path part.
 470     */
 471     static wxString GetPathTerminators(wxPathFormat format = wxPATH_NATIVE);
 472
 473     /**
 474         Returns the path with the trailing separator, useful for appending the name to
 475         the given path.
 476         This is the same as calling GetPath()
 477         @c (wxPATH_GET_VOLUME | wxPATH_GET_SEPARATOR, format).
 478     */
 479     wxString GetPathWithSep(wxPathFormat format = wxPATH_NATIVE) const;
 480
 481     /**
 482         Return the short form of the path (returns identity on non-Windows platforms).
 483     */
 484     wxString GetShortPath() const;
 485
 486     /**
 487         Returns the size of the file If the file does not exist or its size could
 488         not be read (because e.g. the file is locked by another process) the returned
 489         value is @c wxInvalidSize.
 490     */
 491     wxULongLong GetSize();
 492     /**
 493         Returns the size of the file If the file does not exist or its size could
 494         not be read (because e.g. the file is locked by another process) the returned
 495         value is @c wxInvalidSize.
 496     */
 497     const static wxULongLong GetSize(const wxString& filename);
 498
 499     /**
 500         Returns the directory used for temporary files.
 501     */
 502     static wxString GetTempDir();
 503
 504     /**
 505         Returns the last access, last modification and creation times. The last access
 506         time is updated whenever the file is read or written (or executed in the case
 507         of Windows), last modification time is only changed when the file is written
 508         to. Finally, the creation time is indeed the time when the file was created
 509         under Windows and the inode change time under Unix (as it is impossible to
 510         retrieve the real file creation time there anyhow) which can also be changed
 511         by many operations after the file creation.
 512         If no filename or extension is specified in this instance of wxFileName
 513         (and therefore IsDir() returns @true) then
 514         this function will return the directory times of the path specified by
 515         GetPath(), otherwise the file times of the
 516         file specified by GetFullPath().
 517         Any of the pointers may be @NULL if the corresponding time is not
 518         needed.
 519
 520         @return @true on success, @false if we failed to retrieve the times.
 521     */
 522     bool GetTimes(wxDateTime* dtAccess, wxDateTime* dtMod,
 523                   wxDateTime* dtCreate) const;
 524
 525     /**
 526         Returns the string containing the volume for this file name, empty if it
 527         doesn't have one or if the file system doesn't support volumes at all (for
 528         example, Unix).
 529     */
 530     wxString GetVolume() const;
 531
 532     /**
 533         Returns the string separating the volume from the path for this format.
 534     */
 535     static wxString GetVolumeSeparator(wxPathFormat format = wxPATH_NATIVE);
 536
 537     /**
 538         Returns @true if an extension is present.
 539     */
 540     bool HasExt() const;
 541
 542     /**
 543         Returns @true if a name is present.
 544     */
 545     bool HasName() const;
 546
 547     /**
 548         Returns @true if a volume specifier is present.
 549     */
 550     bool HasVolume() const;
 551
 552     /**
 553         Inserts a directory component before the zero-based position in the directory
 554         list. Please see AppendDir() for important notes.
 555     */
 556     void InsertDir(size_t before, const wxString& dir);
 557
 558     /**
 559         Returns @true if this filename is absolute.
 560     */
 561     bool IsAbsolute(wxPathFormat format = wxPATH_NATIVE) const;
 562
 563     /**
 564         Returns @true if the file names of this type are case-sensitive.
 565     */
 566     static bool IsCaseSensitive(wxPathFormat format = wxPATH_NATIVE);
 567
 568     /**
 569         Returns @true if this object represents a directory, @false otherwise
 570         (i.e. if it is a file). Note that this method doesn't test whether the
 571         directory or file really exists, you should use
 572         DirExists() or
 573         FileExists() for this.
 574     */
 575     bool IsDir() const;
 576
 577     /**
 578         Returns @true if the directory component of this instance is an existing
 579         directory and this process has read permissions on it. Read permissions
 580         on a directory mean that you can list the directory contents but it
 581         doesn't imply that you have read permissions on the files contained.
 582     */
 583     bool IsDirReadable() const;
 584
 585     /**
 586         Returns @true if the given @e dir is an existing directory and this process
 587         has read permissions on it. Read permissions on a directory mean that you
 588         can list the directory contents but it doesn't imply that you have read
 589         permissions on the files contained.
 590     */
 591     static bool IsDirReadable(const wxString& dir);
 592
 593     /**
 594         Returns @true if the directory component of this instance
 595         is an existing directory and this process has write permissions on it.
 596         Write permissions on a directory mean that you can create new files in the
 597         directory.
 598     */
 599     bool IsDirWritable() const;
 600     /**
 601         Returns @true if the  given @e dir
 602         is an existing directory and this process has write permissions on it.
 603         Write permissions on a directory mean that you can create new files in the
 604         directory.
 605     */
 606     static bool IsDirWritable(const wxString& dir);
 607
 608     /**
 609         Returns @true if a file with this name exists and if this process has execute
 610         permissions on it.
 611     */
 612     bool IsFileExecutable() const;
 613
 614     /**
 615         Returns @true if a file with this name exists and if this process has execute
 616         permissions on it.
 617     */
 618     static bool IsFileExecutable(const wxString& file);
 619
 620     /**
 621         Returns @true if a file with this name exists and if this process has read
 622         permissions on it.
 623     */
 624     bool IsFileReadable() const;
 625
 626     /**
 627         Returns @true if a file with this name exists and if this process has read
 628         permissions on it.
 629     */
 630     static bool IsFileReadable(const wxString& file);
 631
 632     /**
 633         Returns @true if a file with this name exists and if this process has write
 634         permissions on it.
 635     */
 636     bool IsFileWritable() const;
 637     /**
 638         Returns @true if a file with this name exists and if this process has write
 639         permissions on it.
 640     */
 641     static bool IsFileWritable(const wxString& file);
 642
 643     /**
 644         Returns @true if the filename is valid, @false if it is not
 645         initialized yet. The assignment functions and
 646         Clear() may reset the object to the uninitialized,
 647         invalid state (the former only do it on failure).
 648     */
 649     bool IsOk() const;
 650
 651     /**
 652         Returns @true if the char is a path separator for this format.
 653     */
 654     static bool IsPathSeparator(wxChar ch,
 655                                 wxPathFormat format = wxPATH_NATIVE);
 656
 657     /**
 658         Returns @true if this filename is not absolute.
 659     */
 660     bool IsRelative(wxPathFormat format = wxPATH_NATIVE) const;
 661
 662     /**
 663         On Mac OS, gets the common type and creator for the given extension.
 664     */
 665     static bool MacFindDefaultTypeAndCreator(const wxString& ext,
 666             wxUint32* type,
 667             wxUint32* creator);
 668
 669     /**
 670         On Mac OS, registers application defined extensions and their default type and
 671         creator.
 672     */
 673     static void MacRegisterDefaultTypeAndCreator(const wxString& ext,
 674             wxUint32 type,
 675             wxUint32 creator);
 676
 677     /**
 678         On Mac OS, looks up the appropriate type and creator from the registration and
 679         then sets it.
 680     */
 681     bool MacSetDefaultTypeAndCreator();
 682
 683     /**
 684         Make the file name absolute. This is a shortcut for
 685         @c wxFileName::Normalize(wxPATH_NORM_DOTS | wxPATH_NORM_ABSOLUTE |
 686         wxPATH_NORM_TILDE, cwd, format).
 687
 688         @see MakeRelativeTo(), Normalize(), IsAbsolute()
 689     */
 690     bool MakeAbsolute(const wxString& cwd = wxEmptyString,
 691                       wxPathFormat format = wxPATH_NATIVE);
 692
 693     /**
 694         This function tries to put this file name in a form relative to
 695
 696         @param pathBase.
 697         In other words, it returns the file name which should be used to access this
 698         file if the current directory were pathBase.
 699
 700         pathBase
 701             the directory to use as root, current directory is used by
 702             default
 703         @param format
 704             the file name format, native by default
 705
 706         @return @true if the file name has been changed, @false if we failed to do
 707                  anything with it (currently this only happens if the
 708                  file name is on a volume different from the volume
 709                  specified by pathBase).
 710
 711         @see Normalize()
 712     */
 713     bool MakeRelativeTo(const wxString& pathBase = wxEmptyString,
 714                         wxPathFormat format = wxPATH_NATIVE);
 715
 716     /**
 717         Creates a directory.
 718
 719         @param parm
 720             the permissions for the newly created directory
 721         @param flags
 722             if the flags contain wxPATH_MKDIR_FULL flag,
 723             try to create each directory in the path and also don't return an error
 724             if the target directory already exists.
 725
 726         @return Returns @true if the directory was successfully created, @false
 727                  otherwise.
 728     */
 729     bool Mkdir(int perm = 0777, int flags = 0);
 730     /**
 731         Creates a directory.
 732
 733         @param dir
 734             the directory to create
 735         @param parm
 736             the permissions for the newly created directory
 737         @param flags
 738             if the flags contain wxPATH_MKDIR_FULL flag,
 739             try to create each directory in the path and also don't return an error
 740             if the target directory already exists.
 741
 742         @return Returns @true if the directory was successfully created, @false
 743                  otherwise.
 744     */
 745     static bool Mkdir(const wxString& dir, int perm = 0777,
 746                       int flags = 0);
 747
 748     /**
 749         Normalize the path. With the default flags value, the path will be
 750         made absolute, without any ".." and "." and all environment
 751         variables will be expanded in it.
 752
 753         @param flags
 754             The kind of normalization to do with the file name. It can be
 755             any or-combination of the following constants:
 756
 757             - wxPATH_NORM_ENV_VARS:  replace env vars with their values
 758             - wxPATH_NORM_DOTS:  squeeze all .. and . when possible; if
 759                there are too many .. and thus they cannot be all removed,
 760                @false will be returned
 761             - wxPATH_NORM_CASE: if filesystem is case insensitive, transform
 762                to lower case
 763             - wxPATH_NORM_ABSOLUTE: make the path absolute prepending cwd
 764             - wxPATH_NORM_LONG: make the path the long form
 765             - wxPATH_NORM_SHORTCUT: resolve if it is a shortcut (Windows only)
 766             - wxPATH_NORM_TILDE: replace ~ and ~user (Unix only)
 767             - wxPATH_NORM_ALL: all of previous flags except wxPATH_NORM_CASE
 768
 769         @param cwd
 770             If not empty, this directory will be used instead of current
 771             working directory in normalization (see wxPATH_NORM_ABSOLUTE).
 772         @param format
 773             The file name format to use when processing the paths, native by default.
 774
 775         @return @true if normalization was successfully or @false otherwise.
 776     */
 777     bool Normalize(int flags = wxPATH_NORM_ALL,
 778                    const wxString& cwd = wxEmptyString,
 779                    wxPathFormat format = wxPATH_NATIVE);
 780
 781
 782     /**
 783         Prepends a directory to the file path. Please see
 784         AppendDir() for important notes.
 785     */
 786     void PrependDir(const wxString& dir);
 787
 788     /**
 789         Removes the specified directory component from the path.
 790
 791         @see GetDirCount()
 792     */
 793     void RemoveDir(size_t pos);
 794
 795     /**
 796         Removes last directory component from the path.
 797     */
 798     void RemoveLastDir();
 799
 800     /**
 801         Deletes the specified directory from the file system.
 802     */
 803     bool Rmdir();
 804     /**
 805         Deletes the specified directory from the file system.
 806     */
 807     static bool Rmdir(const wxString& dir);
 808
 809     /**
 810         Compares the filename using the rules of this platform.
 811     */
 812     bool SameAs(const wxFileName& filepath,
 813                 wxPathFormat format = wxPATH_NATIVE) const;
 814
 815     /**
 816         Changes the current working directory.
 817     */
 818     bool SetCwd();
 819     /**
 820         Changes the current working directory.
 821     */
 822     static bool SetCwd(const wxString& cwd);
 823
 824     /**
 825         Sets the extension of the file name to be an empty extension.
 826         This is different from having no extension at all as the file
 827         name will have a trailing dot after a call to this method.
 828
 829         @see SetExt(), ClearExt()
 830     */
 831     void SetEmptyExt();
 832
 833     /**
 834         Sets the extension of the file name. Setting an empty string
 835         as the extension will remove the extension resulting in a file
 836         name without a trailing dot, unlike a call to
 837         SetEmptyExt().
 838
 839         @see SetEmptyExt(), ClearExt()
 840     */
 841     void SetExt(const wxString& ext);
 842
 843     /**
 844         The full name is the file name and extension (but without the path).
 845     */
 846     void SetFullName(const wxString& fullname);
 847
 848     /**
 849         Sets the name part (without extension).
 850
 851         @see SetFullName()
 852     */
 853     void SetName(const wxString& name);
 854
 855     /**
 856         Sets the file creation and last access/modification times (any of the pointers
 857         may be @NULL).
 858     */
 859     bool SetTimes(const wxDateTime* dtAccess,
 860                   const wxDateTime* dtMod,
 861                   const wxDateTime* dtCreate);
 862
 863     /**
 864         Sets the volume specifier.
 865     */
 866     void SetVolume(const wxString& volume);
 867
 868     //@{
 869     /**
 870         This function splits a full file name into components: the volume (with the
 871         first version) path (including the volume in the second version), the base name
 872         and the extension. Any of the output parameters (@e volume, @e path,
 873         @a name or @e ext) may be @NULL if you are not interested in the
 874         value of a particular component. Also, @a fullpath may be empty on entry.
 875         On return, @a path contains the file path (without the trailing separator),
 876         @a name contains the file name and @a ext contains the file extension
 877         without leading dot. All three of them may be empty if the corresponding
 878         component is. The old contents of the strings pointed to by these parameters
 879         will be overwritten in any case (if the pointers are not @NULL).
 880         Note that for a filename "foo." the extension is present, as indicated by the
 881         trailing dot, but empty. If you need to cope with such cases, you should use
 882         @a hasExt instead of relying on testing whether @a ext is empty or not.
 883     */
 884     static void SplitPath(const wxString& fullpath, wxString* volume,
 885                           wxString* path,
 886                           wxString* name,
 887                           wxString* ext,
 888                           bool hasExt = NULL,
 889                           wxPathFormat format = wxPATH_NATIVE);
 890     static void SplitPath(const wxString& fullpath,
 891                           wxString* volume,
 892                           wxString* path,
 893                           wxString* name,
 894                           wxString* ext,
 895                           wxPathFormat format = wxPATH_NATIVE);
 896     static void SplitPath(const wxString& fullpath,
 897                           wxString* path,
 898                           wxString* name,
 899                           wxString* ext,
 900                           wxPathFormat format = wxPATH_NATIVE);
 901     //@}
 902
 903     /**
 904         Splits the given @a fullpath into the volume part (which may be empty) and
 905         the pure path part, not containing any volume.
 906
 907         @see SplitPath()
 908     */
 909     static void SplitVolume(const wxString& fullpath,
 910                             wxString* volume,
 911                             wxString* path,
 912                             wxPathFormat format = wxPATH_NATIVE);
 913
 914     /**
 915         Sets the access and modification times to the current moment.
 916     */
 917     bool Touch();
 918
 919     /**
 920         Returns @true if the filenames are different. The string @e filenames
 921         is interpreted as a path in the native filename format.
 922     */
 923     bool operator operator!=(const wxFileName& filename) const;
 924     /**
 925         Returns @true if the filenames are different. The string @e filenames
 926         is interpreted as a path in the native filename format.
 927     */
 928     bool operator operator!=(const wxString& filename) const;
 929
 930     /**
 931         Assigns the new value to this filename object.
 932     */
 933     wxFileName& operator operator=(const wxFileName& filename);
 934     /**
 935         Assigns the new value to this filename object.
 936     */
 937     wxFileName& operator operator=(const wxString& filename);
 938
 939     /**
 940         Returns @true if the filenames are equal. The string @e filenames is
 941         interpreted as a path in the native filename format.
 942     */
 943     bool operator operator==(const wxFileName& filename) const;
 944     /**
 945         Returns @true if the filenames are equal. The string @e filenames is
 946         interpreted as a path in the native filename format.
 947     */
 948     bool operator operator==(const wxString& filename) const;
 949 };
 950