// Purpose: interface of wxFileName
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
-/** The various values for the path format: this mainly affects the path
+/**
+ The various values for the path format: this mainly affects the path
separator but also whether or not the path has the drive part
(as under Windows).
wxPATH_MAX //!< Not a valid value for specifying path format
};
+/**
+ Different conventions for human readable sizes.
+
+ @see wxFileName::GetHumanReadableSize().
+
+ @since 2.9.1
+*/
+enum wxSizeConvention
+{
+ /// 1024 bytes = 1KB.
+ wxSIZE_CONV_TRADITIONAL,
+
+ /// 1024 bytes = 1KiB.
+ wxSIZE_CONV_IEC,
-/** The kind of normalization to do with the file name: these values can be
+ /// 1000 bytes = 1KB.
+ wxSIZE_CONV_SI
+};
+
+
+/**
+ The kind of normalization to do with the file name: these values can be
or'd together to perform several operations at once.
See wxFileName::Normalize() for more info.
*/
enum wxPathNormalize
{
- wxPATH_NORM_ENV_VARS = 0x0001, //!< replace env vars with their values.
- wxPATH_NORM_DOTS = 0x0002, //!< squeeze all .. and . and prepend cwd.
- wxPATH_NORM_TILDE = 0x0004, //!< Unix only: replace ~ and ~user.
- wxPATH_NORM_CASE = 0x0008, //!< if case insensitive => tolower.
- wxPATH_NORM_ABSOLUTE = 0x0010, //!< make the path absolute.
- wxPATH_NORM_LONG = 0x0020, //!< make the path the long form.
- wxPATH_NORM_SHORTCUT = 0x0040, //!< resolve the shortcut, if it is a shortcut.
+ //! Replace environment variables with their values.
+ //! wxFileName understands both Unix and Windows (but only under Windows) environment
+ //! variables expansion: i.e. @c "$var", @c "$(var)" and @c "${var}" are always understood
+ //! and in addition under Windows @c "%var%" is also.
+ wxPATH_NORM_ENV_VARS = 0x0001,
+
+ wxPATH_NORM_DOTS = 0x0002, //!< Squeeze all @c ".." and @c ".".
+ wxPATH_NORM_TILDE = 0x0004, //!< Replace @c "~" and @c "~user" (Unix only).
+ wxPATH_NORM_CASE = 0x0008, //!< If the platform is case insensitive, make lowercase the path.
+ wxPATH_NORM_ABSOLUTE = 0x0010, //!< Make the path absolute.
+ wxPATH_NORM_LONG = 0x0020, //!< Expand the path to the "long" form (Windows only).
+ wxPATH_NORM_SHORTCUT = 0x0040, //!< Resolve the shortcut, if it is a shortcut (Windows only).
+
+ //! A value indicating all normalization flags except for @c wxPATH_NORM_CASE.
wxPATH_NORM_ALL = 0x00ff & ~wxPATH_NORM_CASE
};
+/**
+ Flags for wxFileName::Rmdir().
+ */
+enum
+{
+ /// Delete the specified directory and its subdirectories if they are empty.
+ wxPATH_RMDIR_FULL = 1,
+
+ /**
+ Delete the specified directory and all the files and subdirectories in it
+ recursively.
+
+ This flag is obviously @b dangerous and should be used with care and
+ after asking the user for confirmation.
+ */
+ wxPATH_RMDIR_RECURSIVE = 2
+};
+
/**
The return value of wxFileName::GetSize() in case of error.
*/
@li wxFileName::AssignCwd()
@li wxFileName::AssignDir()
@li wxFileName::AssignHomeDir()
+ @li wxFileName::AssignTempFileName()
@li wxFileName::DirName()
@li wxFileName::FileName()
@li wxFileName::operator=()
@see GetCwd()
*/
- static void AssignCwd(const wxString& volume = wxEmptyString);
+ void AssignCwd(const wxString& volume = wxEmptyString);
/**
Sets this file name object to the given directory name.
*/
void AssignHomeDir();
- //@{
/**
The function calls CreateTempFileName() to create a temporary file
and sets this object to the name of the file.
If a temporary file couldn't be created, the object is put into
- an invalid state (see IsOk())
+ an invalid state (see IsOk()).
+ */
+ void AssignTempFileName(const wxString& prefix);
+
+ /**
+ The function calls CreateTempFileName() to create a temporary
+ file name and open @a fileTemp with it.
+
+ If the file couldn't be opened, the object is put into
+ an invalid state (see IsOk()).
*/
void AssignTempFileName(const wxString& prefix, wxFile* fileTemp);
+
+ /**
+ The function calls CreateTempFileName() to create a temporary
+ file name and open @a fileTemp with it.
+
+ If the file couldn't be opened, the object is put into
+ an invalid state (see IsOk()).
+ */
void AssignTempFileName(const wxString& prefix, wxFFile* fileTemp);
- //@}
/**
Reset all components to default, uninitialized state.
*/
void ClearExt();
+ //@{
/**
Returns a temporary file name starting with the given @e prefix.
If the @a prefix is an absolute path, the temporary file is created in this
*/
static wxString CreateTempFileName(const wxString& prefix,
wxFile* fileTemp = NULL);
+ static wxString CreateTempFileName(const wxString& prefix,
+ wxFFile* fileTemp = NULL);
+ //@}
/**
Returns @true if the directory with this name exists.
bool DirExists() const;
/**
- Returns @true if the directory with this name exists.
+ Returns @true if the directory with name @a dir exists.
*/
static bool DirExists(const wxString& dir);
bool FileExists() const;
/**
- Returns @true if the file with this name exists.
+ Returns @true if the file with name @a file exists.
@see DirExists()
*/
*/
static wxString GetHomeDir();
+ //@{
/**
- Returns the size of the file in a human-readable form.
-
- If the size could not be retrieved the @c failmsg string
- is returned. In case of success, the returned string is
- a floating-point number with @c precision decimal digits
- followed by the size unit (B, kB, MB, GB, TB: respectively
- bytes, kilobytes, megabytes, gigabytes, terabytes).
- */
- wxString GetHumanReadableSize(const wxString& failmsg = "Not available",
- int precision = 1) const;
-
- /**
- Returns the size of the given number of bytes in a human-readable form.
-
- If @a bytes is ::wxInvalidSize or zero, then @a nullsize is returned.
-
- In case of success, the returned string is a floating-point number with
- @a precision decimal digits followed by the size unit (B, kB, MB, GB,
- TB: respectively bytes, kilobytes, megabytes, gigabytes, terabytes).
- */
- static wxString GetHumanReadableSize(const wxULongLong& bytes,
- const wxString& nullsize = "Not available",
- int precision = 1);
+ Returns the representation of the file size in a human-readable form.
+
+ In the first version, the size of this file is used. In the second one,
+ the specified size @a bytes is used.
+
+ If the file size could not be retrieved or @a bytes is ::wxInvalidSize
+ or zero, the @c failmsg string is returned.
+
+ Otherwise the returned string is a floating-point number with @c
+ precision decimal digits followed by the abbreviation of the unit used.
+ By default the traditional, although incorrect, convention of using SI
+ units for multiples of 1024 is used, i.e. returned string will use
+ suffixes of B, KB, MB, GB, TB for bytes, kilobytes, megabytes,
+ gigabytes and terabytes respectively. With the IEC convention the names
+ of the units are changed to B, KiB, MiB, GiB and TiB fofr bytes,
+ kibibytes, mebibyes, gibibytes and tebibytes. Finally, with SI
+ convention the same B, KB, MB, GB and TB suffixes are used but in their
+ correct SI meaning, i.e. as multiples of 1000 and not 1024.
+
+ Support for the different size conventions is new in wxWidgets 2.9.1,
+ in previous versions only the traditional convention was implemented.
+ */
+ wxString
+ GetHumanReadableSize(const wxString& failmsg = _("Not available"),
+ int precision = 1,
+ wxSizeConvention conv = wxSIZE_CONV_TRADITIONAL) const;
+
+ static wxString
+ GetHumanReadableSize(const wxULongLong& bytes,
+ const wxString& nullsize = _("Not available"),
+ int precision = 1,
+ wxSizeConvention conv = wxSIZE_CONV_TRADITIONAL);
+ //@}
/**
Return the long form of the path (returns identity on non-Windows platforms).
The possible flags values are:
- - @b wxPATH_GET_VOLUME
+ - @b wxPATH_GET_VOLUME:
Return the path with the volume (does nothing for the filename formats
without volumes), otherwise the path without volume part is returned.
@see GetPathSeparators()
*/
- static wxChar GetPathSeparator(wxPathFormat format = wxPATH_NATIVE);
+ static wxUniChar GetPathSeparator(wxPathFormat format = wxPATH_NATIVE);
/**
Returns the string containing all the path separators for this format.
not be read (because e.g. the file is locked by another process) the returned
value is ::wxInvalidSize.
*/
- const static wxULongLong GetSize(const wxString& filename);
+ static wxULongLong GetSize(const wxString& filename);
/**
Returns the directory used for temporary files.
static bool IsPathSeparator(wxChar ch,
wxPathFormat format = wxPATH_NATIVE);
+ /**
+ Returns @true if the volume part of the path is a unique volume name.
+
+ This function will always return @false if the path format is not
+ wxPATH_DOS.
+
+ Unique volume names are Windows volume identifiers which remain the same
+ regardless of where the volume is actually mounted. Example of a path
+ using a volume name could be
+ @code
+ \\?\Volume{8089d7d7-d0ac-11db-9dd0-806d6172696f}\Program Files\setup.exe
+ @endcode
+
+ @since 2.9.1
+ */
+ static bool IsMSWUniqueVolumeNamePath(const wxString& path,
+ wxPathFormat format = wxPATH_NATIVE);
+
/**
Returns @true if this filename is not absolute.
*/
@return Returns @true if the directory was successfully created, @false
otherwise.
*/
- bool Mkdir(int perm = wxS_DIR_DEFAULT, int flags = 0);
+ bool Mkdir(int perm = wxS_DIR_DEFAULT, int flags = 0) const;
/**
Creates a directory.
@param flags
The kind of normalization to do with the file name. It can be
- any or-combination of the wxPathNormalize enumeration values.
+ any or-combination of the ::wxPathNormalize enumeration values.
@param cwd
If not empty, this directory will be used instead of current
working directory in normalization (see @c wxPATH_NORM_ABSOLUTE).
*/
void RemoveLastDir();
+ /**
+ If the path contains the value of the environment variable named @a envname
+ then this function replaces it with the string obtained from
+ wxString::Format(replacementFmtString, value_of_envname_variable).
+
+ This function is useful to make the path shorter or to make it dependent
+ from a certain environment variable.
+ Normalize() with @c wxPATH_NORM_ENV_VARS can perform the opposite of this
+ function (depending on the value of @a replacementFmtString).
+
+ The name and extension of this filename are not modified.
+
+ Example:
+ @code
+ wxFileName fn("/usr/openwin/lib/someFile");
+ fn.ReplaceEnvVariable("OPENWINHOME");
+ // now fn.GetFullPath() == "$OPENWINHOME/lib/someFile"
+ @endcode
+
+ @since 2.9.0
+
+ @return @true if the operation was successful (which doesn't mean
+ that something was actually replaced, just that ::wxGetEnv
+ didn't fail).
+ */
+ bool ReplaceEnvVariable(const wxString& envname,
+ const wxString& replacementFmtString = "$%s",
+ wxPathFormat format = wxPATH_NATIVE);
+
+ /**
+ Replaces, if present in the path, the home directory for the given user
+ (see ::wxGetHomeDir) with a tilde (~).
+
+ Normalize() with @c wxPATH_NORM_TILDE performs the opposite of this
+ function.
+
+ The name and extension of this filename are not modified.
+
+ @since 2.9.0
+
+ @return @true if the operation was successful (which doesn't mean
+ that something was actually replaced, just that ::wxGetHomeDir
+ didn't fail).
+ */
+ bool ReplaceHomeDir(wxPathFormat format = wxPATH_NATIVE);
+
+
/**
Deletes the specified directory from the file system.
+
+ @param flags
+ Can contain one of wxPATH_RMDIR_FULL or wxPATH_RMDIR_RECURSIVE. By
+ default contains neither so the directory will not be removed
+ unless it is empty.
+
+ @return Returns @true if the directory was successfully deleted, @false
+ otherwise.
*/
- bool Rmdir();
+ bool Rmdir(int flags = 0) const;
/**
Deletes the specified directory from the file system.
+
+ @param dir
+ The directory to delete
+ @param flags
+ Can contain one of wxPATH_RMDIR_FULL or wxPATH_RMDIR_RECURSIVE. By
+ default contains neither so the directory will not be removed
+ unless it is empty.
+
+ @return Returns @true if the directory was successfully deleted, @false
+ otherwise.
*/
- static bool Rmdir(const wxString& dir);
+ static bool Rmdir(const wxString& dir, int flags = 0);
/**
Compares the filename using the rules of this platform.
/**
Changes the current working directory.
*/
- bool SetCwd();
+ bool SetCwd() const;
/**
Changes the current working directory.
*/
void SetName(const wxString& name);
+ /**
+ Sets the full path.
+
+ The @a path argument includes both the path (and the volume, if
+ supported by @a format) and the name and extension.
+
+ @see GetPath()
+ */
+ void SetPath(const wxString& path, wxPathFormat format = wxPATH_NATIVE);
+
/**
Sets the file creation and last access/modification times (any of the pointers
may be @NULL).
*/
bool SetTimes(const wxDateTime* dtAccess,
const wxDateTime* dtMod,
- const wxDateTime* dtCreate);
+ const wxDateTime* dtCreate) const;
/**
Sets the volume specifier.
trailing dot, but empty. If you need to cope with such cases, you should use
@a hasExt instead of relying on testing whether @a ext is empty or not.
*/
- static void SplitPath(const wxString& fullpath, wxString* volume,
+ static void SplitPath(const wxString& fullpath,
+ wxString* volume,
wxString* path,
wxString* name,
wxString* ext,
- bool hasExt = NULL,
+ bool* hasExt = NULL,
wxPathFormat format = wxPATH_NATIVE);
static void SplitPath(const wxString& fullpath,
wxString* volume,
wxString* path,
wxString* name,
wxString* ext,
- wxPathFormat format = wxPATH_NATIVE);
+ wxPathFormat format);
static void SplitPath(const wxString& fullpath,
wxString* path,
wxString* name,
wxString* path,
wxPathFormat format = wxPATH_NATIVE);
+
+ /**
+ Strip the file extension.
+
+ This function does more than just removing everything after the last
+ period from the string, for example it will return the string ".vimrc"
+ unchanged because the part after the period is not an extension but the
+ file name in this case. You can use wxString::BeforeLast() to really
+ get just the part before the last period (but notice that that function
+ returns empty string if period is not present at all unlike this
+ function which returns the @a fullname unchanged in this case).
+
+ @param fullname
+ File path including name and, optionally, extension.
+
+ @return
+ File path without extension
+
+ @since 2.9.0
+ */
+ static wxString StripExtension(const wxString& fullname);
+
/**
Sets the access and modification times to the current moment.
*/
- bool Touch();
+ bool Touch() const;
/**
Returns @true if the filenames are different. The string @e filenames
*/
wxFileName& operator=(const wxString& filename);
};
-
projects / wxWidgets.git / blobdiff