X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e01a788ee05125b4fefa01a5b11f4088915cb54e..3399af21d10d3f8ce4f39dfb29df5546ab265ef6:/interface/wx/filename.h diff --git a/interface/wx/filename.h b/interface/wx/filename.h index 3f40781ab7..7bbd0cd527 100644 --- a/interface/wx/filename.h +++ b/interface/wx/filename.h @@ -3,7 +3,7 @@ // Purpose: interface of wxFileName // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// @@ -28,6 +28,25 @@ enum wxPathFormat 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, + + /// 1000 bytes = 1KB. + wxSIZE_CONV_SI +}; + /** The kind of normalization to do with the file name: these values can be @@ -110,7 +129,7 @@ wxULongLong wxInvalidSize; wxFileName::IsDirReadable() use wxFileName::GetPath() whereas methods dealing with file names like wxFileName::IsFileReadable() use wxFileName::GetFullPath(). - If it is not known wether a string contains a directory name or a complete + If it is not known whether a string contains a directory name or a complete file name (such as when interpreting user input) you need to use the static function wxFileName::DirExists() (or its identical variants wxDir::Exists() and wxDirExists()) and construct the wxFileName instance accordingly. @@ -313,7 +332,7 @@ public: wxPathFormat format = wxPATH_NATIVE); /** - Creates the file name from volumne, path, name and extension. + Creates the file name from volume, path, name and extension. */ void Assign(const wxString& volume, const wxString& path, const wxString& name, @@ -322,7 +341,7 @@ public: wxPathFormat format = wxPATH_NATIVE); /** - Creates the file name from volumne, path, name and extension. + Creates the file name from volume, path, name and extension. */ void Assign(const wxString& volume, const wxString& path, const wxString& name, @@ -437,7 +456,7 @@ public: 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); @@ -456,7 +475,7 @@ public: bool FileExists() const; /** - Returns @true if the file with this name exists. + Returns @true if the file with name @a file exists. @see DirExists() */ @@ -522,30 +541,41 @@ public: */ 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 for bytes, + kibibytes, mebibytes, 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). @@ -581,6 +611,10 @@ public: Don't include the trailing separator in the returned string. This is the default (the value of this flag is 0) and exists only for symmetry with wxPATH_GET_SEPARATOR. + + @note If the path is a toplevel one (e.g. @c "/" on Unix or @c "C:\" on + Windows), then the returned path will contain trailing separator + even with @c wxPATH_NO_SEPARATOR. */ wxString GetPath(int flags = wxPATH_GET_VOLUME, wxPathFormat format = wxPATH_NATIVE) const; @@ -932,9 +966,16 @@ public: int flags = 0); /** - Normalize the path. With the default flags value, the path will be - made absolute, without any ".." and "." and all environment - variables will be expanded in it. + Normalize the path. + + With the default flags value, the path will be made absolute, without + any ".." and "." and all environment variables will be expanded in it. + + Notice that in some rare cases normalizing a valid path may result in + an invalid wxFileName object. E.g. normalizing "./" path using + wxPATH_NORM_DOTS but not wxPATH_NORM_ABSOLUTE will result in a + completely empty and thus invalid object. As long as there is a non + empty file name the result of normalization will be valid however. @param flags The kind of normalization to do with the file name. It can be