%% Created: 30.11.01
%% RCS-ID: $Id$
%% Copyright: (c) 2001 Vadim Zeitlin
-%% License: wxWindows license
+%% License: wxWidgets license
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{\class{wxFileName}}\label{wxfilename}
wxFileName encapsulates a file name. This class serves two purposes: first, it
provides the functions to split the file names into components and to recombine
these components in the full file name which can then be passed to the OS file
-functions (and \helpref{wxWindows functions}{filefunctions} wrapping them).
+functions (and \helpref{wxWidgets functions}{filefunctions} wrapping them).
Second, it includes the functions for working with the files itself. Note that
to change the file data you should use \helpref{wxFile}{wxfile} class instead.
wxFileName provides functions for working with the file attributes.
No base class
+\wxheading{Include files}
+
+<wx/filename.h>
+
\wxheading{Data structures}
Many wxFileName methods accept the path format argument which is by\rtfsp
{
wxPATH_NATIVE = 0, // the path format for the current platform
wxPATH_UNIX,
+ wxPATH_BEOS = wxPATH_UNIX,
wxPATH_MAC,
wxPATH_DOS,
+ wxPATH_WIN = wxPATH_DOS,
+ wxPATH_OS2 = wxPATH_DOS,
wxPATH_VMS,
- wxPATH_BEOS = wxPATH_UNIX,
- wxPATH_WIN = wxPATH_DOS,
- wxPATH_OS2 = wxPATH_DOS
+ wxPATH_MAX // Not a valid value for specifying path format
}
\end{verbatim}
\latexignore{\rtfignore{\wxheading{Function groups}}}
+
\membersection{File name format}
wxFileName currently supports the file names in the Unix, DOS/Windows, Mac OS
on the file name format and the only portable way to answer to this question is
to use \helpref{IsAbsolute}{wxfilenameisabsolute} method. To ensure that the
filename is absolute you may use \helpref{MakeAbsolute}{wxfilenamemakeabsolute}.
-There is also an inverse function
+There is also an inverse function
\helpref{MakeRelativeTo}{wxfilenamemakerelativeto} which undoes what
\helpref{Normalize(wxPATH\_NORM\_DOTS)}{wxfilenamenormalize} does.
\helpref{IsRelative}{wxfilenameisrelative}
+
\membersection{File name construction}
TODO.
+
\membersection{File tests}
Before doing the other tests you should use \helpref{IsOk}{wxfilenameisok} to
File names should be compared using \helpref{SameAs}{wxfilenamesameas} method
or \helpref{$==$}{wxfilenameoperatorequal}.
+
\membersection{File name components}
These functions allow to examine and modify the directories of the path:
\helpref{SetName}{wxfilenamesetname}\\
\helpref{SetVolume}{wxfilenamesetvolume}\\
+
\membersection{Operations}
These methods allow to work with the file creation, access and modification
\latexignore{\rtfignore{\wxheading{Members}}}
+
\membersection{wxFileName::wxFileName}\label{wxfilenamewxfilename}
\func{}{wxFileName}{\void}
Constructor from a volume name, a directory name, base file name and extension.
+
\membersection{wxFileName::AppendDir}\label{wxfilenameappenddir}
\func{void}{AppendDir}{\param{const wxString\& }{dir}}
-Appends a directory to the path.
+Appends a directory component to the path. This component should contain a
+single directory name level, i.e. not contain any path or volume separators nor
+should it be empty, otherwise the function does nothing (and generates an
+assert failure in debug build).
+
\membersection{wxFileName::Assign}\label{wxfilenameassign}
Creates the file name from various combinations of data.
+
\membersection{wxFileName::AssignCwd}\label{wxfilenameassigncwd}
-\func{void}{AssignCwd}{\param{const wxString\& }{volume = ""}}
+\func{static void}{AssignCwd}{\param{const wxString\& }{volume = wxEmptyString}}
Makes this object refer to the current working directory on the specified
volume (or current volume if {\it volume} is empty).
\helpref{GetCwd}{wxfilenamegetcwd}
+
\membersection{wxFileName::AssignDir}\label{wxfilenameassigndir}
\func{void}{AssignDir}{\param{const wxString\& }{dir}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
Sets this file name object to the given directory name. The name and extension
will be empty.
+
\membersection{wxFileName::AssignHomeDir}\label{wxfilenameassignhomedir}
\func{void}{AssignHomeDir}{\void}
Sets this file name object to the home directory.
+
\membersection{wxFileName::AssignTempFileName}\label{wxfilenameassigntempfilename}
\func{void}{AssignTempFileName}{\param{const wxString\& }{prefix}, \param{wxFile *}{fileTemp = {\tt NULL}}}
temporary file couldn't be created, the object is put into the\rtfsp
\helpref{invalid}{wxfilenameisok} state.
+
\membersection{wxFileName::Clear}\label{wxfilenameclear}
\func{void}{Clear}{\void}
Reset all components to default, uninitialized state.
+
\membersection{wxFileName::CreateTempFileName}\label{wxfilenamecreatetempfilename}
\func{static wxString}{CreateTempFileName}{\param{const wxString\& }{prefix}, \param{wxFile *}{fileTemp = {\tt NULL}}}
The full temporary file name or an empty string on error.
+
\membersection{wxFileName::DirExists}\label{wxfilenamedirexists}
\constfunc{bool}{DirExists}{\void}
\func{static bool}{DirExists}{\param{const wxString\& }{dir}}
-Returns true if the directory with this name exists.
+Returns {\tt true} if the directory with this name exists.
+
\membersection{wxFileName::DirName}\label{wxfilenamedirname}
-\func{wxFileName}{DirName}{\param{const wxString\& }{dir}}
+\func{static wxFileName}{DirName}{\param{const wxString\& }{dir}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
+
+Returns the object corresponding to the directory with the given name.
+The {\it dir} parameter may have trailing path separator or not.
+
-Returns the directory name.
\membersection{wxFileName::FileExists}\label{wxfilenamefileexists}
\func{static bool}{FileExists}{\param{const wxString\& }{file}}
-Returns true if the file with this name exists.
+Returns {\tt true} if the file with this name exists.
\wxheading{See also}
\helpref{DirExists}{wxfilenamedirexists}
+
+
\membersection{wxFileName::FileName}\label{wxfilenamefilename}
-\func{wxFileName}{FileName}{\param{const wxString\& }{file}}
+\func{static wxFileName}{FileName}{\param{const wxString\& }{file}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
+
+Returns the file name object corresponding to the given {\it file}. This
+function exists mainly for symmetry with \helpref{DirName}{wxfilenamedirname}.
+
-Static pseudo constructors.
\membersection{wxFileName::GetCwd}\label{wxfilenamegetcwd}
-\func{wxString}{GetCwd}{\param{const wxString\& }{volume = ""}}
+\func{static wxString}{GetCwd}{\param{const wxString\& }{volume = ""}}
Retrieves the value of the current working directory on the specified volume. If
the volume is empty, the programs current working directory is returned for the
\helpref{AssignCwd}{wxfilenameassigncwd}
+
\membersection{wxFileName::GetDirCount}\label{wxfilenamegetdircount}
\constfunc{size\_t}{GetDirCount}{\void}
Returns the number of directories in the file name.
+
\membersection{wxFileName::GetDirs}\label{wxfilenamegetdirs}
\constfunc{const wxArrayString\&}{GetDirs}{\void}
Returns the directories in string array form.
+
\membersection{wxFileName::GetExt}\label{wxfilenamegetext}
\constfunc{wxString}{GetExt}{\void}
Returns the file name extension.
+
+\membersection{wxFileName::GetForbiddenChars}\label{wxfilenamegetforbiddenchars}
+
+\func{static wxString}{GetForbiddenChars}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
+
+Returns the characters that can't be used in filenames and directory names for the specified format.
+
+
\membersection{wxFileName::GetFormat}\label{wxfilenamegetformat}
-\func{wxPathFormat}{GetFormat}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
+\func{static wxPathFormat}{GetFormat}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
Returns the canonical path format for this platform.
+
\membersection{wxFileName::GetFullName}\label{wxfilenamegetfullname}
\constfunc{wxString}{GetFullName}{\void}
Returns the full name (including extension but excluding directories).
+
\membersection{wxFileName::GetFullPath}\label{wxfilenamegetfullpath}
\constfunc{wxString}{GetFullPath}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
Returns the full path with name and extension.
+
\membersection{wxFileName::GetHomeDir}\label{wxfilenamegethomedir}
-\func{wxString}{GetHomeDir}{\void}
+\func{static wxString}{GetHomeDir}{\void}
Returns the home directory.
+
\membersection{wxFileName::GetLongPath}\label{wxfilenamegetlongpath}
\constfunc{wxString}{GetLongPath}{\void}
Return the long form of the path (returns identity on non-Windows platforms)
+
\membersection{wxFileName::GetModificationTime}\label{wxfilenamegetmodificationtime}
\constfunc{wxDateTime}{GetModificationTime}{\void}
Returns the last time the file was last modified.
+
\membersection{wxFileName::GetName}\label{wxfilenamegetname}
\constfunc{wxString}{GetName}{\void}
Returns the name part of the filename.
+
\membersection{wxFileName::GetPath}\label{wxfilenamegetpath}
-\constfunc{wxString}{GetPath}{\param{int }{flags = $0$}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
+\constfunc{wxString}{GetPath}{\param{int }{flags = {\tt wxPATH\_GET\_VOLUME}}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
Returns the path part of the filename (without the name or extension). The
possible flags values are:
\twocolwidtha{5cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf wxPATH\_GET\_VOLUME}}{Return the path with the volume (does
-nothing for the filename formats without volumes)}
+nothing for the filename formats without volumes), otherwise the path without
+volume part is returned.}
\twocolitem{{\bf wxPATH\_GET\_SEPARATOR}}{Return the path with the trailing
separator, if this flag is not given there will be no separator at the end of
the path.}
\end{twocollist}
+
\membersection{wxFileName::GetPathSeparator}\label{wxfilenamegetpathseparator}
-\func{wxChar}{GetPathSeparator}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
+\func{static wxChar}{GetPathSeparator}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
Returns the usually used path separator for this format. For all formats but
{\tt wxPATH\_DOS} there is only one path separator anyhow, but for DOS there
\helpref{GetPathSeparators}{wxfilenamegetpathseparators}
+
\membersection{wxFileName::GetPathSeparators}\label{wxfilenamegetpathseparators}
-\func{wxString}{GetPathSeparators}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
+\func{static wxString}{GetPathSeparators}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
Returns the string containing all the path separators for this format. For all
formats but {\tt wxPATH\_DOS} this string contains only one character but for
\helpref{GetPathSeparator}{wxfilenamegetpathseparator}
+
+\membersection{wxFileName::GetPathTerminators}\label{wxfilenamegetpathterminators}
+
+\func{static wxString}{GetPathTerminators}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
+
+Returns the string of characters which may terminate the path part. This is the
+same as \helpref{GetPathSeparators}{wxfilenamegetpathseparators} except for VMS
+path format where $]$ is used at the end of the path part.
+
+
\membersection{wxFileName::GetShortPath}\label{wxfilenamegetshortpath}
\constfunc{wxString}{GetShortPath}{\void}
Return the short form of the path (returns identity on non-Windows platforms).
+
\membersection{wxFileName::GetTimes}\label{wxfilenamegettimes}
\constfunc{bool}{GetTimes}{\param{wxDateTime* }{dtAccess}, \param{wxDateTime* }{dtMod}, \param{wxDateTime* }{dtCreate}}
{\tt true} on success, {\tt false} if we failed to retrieve the times.
+
\membersection{wxFileName::GetVolume}\label{wxfilenamegetvolume}
\constfunc{wxString}{GetVolume}{\void}
-Returns the string containing the volume for this file name, mepty if it
+Returns the string containing the volume for this file name, empty if it
doesn't have one or if the file system doesn't support volumes at all (for
example, Unix).
+
\membersection{wxFileName::GetVolumeSeparator}\label{wxfilenamegetvolumeseparator}
-\func{wxString}{GetVolumeSeparator}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
+\func{static wxString}{GetVolumeSeparator}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
Returns the string separating the volume from the path for this format.
+
\membersection{wxFileName::HasExt}\label{wxfilenamehasext}
\constfunc{bool}{HasExt}{\void}
-Returns true if an extension is present.
+Returns {\tt true} if an extension is present.
+
\membersection{wxFileName::HasName}\label{wxfilenamehasname}
\constfunc{bool}{HasName}{\void}
-Returns true if a name is present.
+Returns {\tt true} if a name is present.
+
\membersection{wxFileName::HasVolume}\label{wxfilenamehasvolume}
\constfunc{bool}{HasVolume}{\void}
-Returns true if a volume specifier is present.
+Returns {\tt true} if a volume specifier is present.
+
\membersection{wxFileName::InsertDir}\label{wxfilenameinsertdir}
\func{void}{InsertDir}{\param{int }{before}, \param{const wxString\& }{dir}}
-Inserts a directory before the zero-based position in the directory list.
+Inserts a directory component before the zero-based position in the directory
+list. Please see \helpref{AppendDir}{wxfilenameappenddir} for important notes.
+
\membersection{wxFileName::IsAbsolute}\label{wxfilenameisabsolute}
\func{bool}{IsAbsolute}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
-Returns true if this filename is absolute.
+Returns {\tt true} if this filename is absolute.
+
\membersection{wxFileName::IsCaseSensitive}\label{wxfilenameiscasesensitive}
-\func{bool}{IsCaseSensitive}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
+\func{static bool}{IsCaseSensitive}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
+
+Returns {\tt true} if the file names of this type are case-sensitive.
-Returns true if the file names of this type are case-sensitive.
\membersection{wxFileName::IsOk}\label{wxfilenameisok}
\helpref{Clear}{wxfilenameclear} may reset the object to the uninitialized,
invalid state (the former only do it on failure).
+
\membersection{wxFileName::IsPathSeparator}\label{wxfilenameispathseparator}
-\func{bool}{IsPathSeparator}{\param{wxChar }{ch}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
+\func{static bool}{IsPathSeparator}{\param{wxChar }{ch}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
Returns {\tt true} if the char is a path separator for this format.
+
\membersection{wxFileName::IsRelative}\label{wxfilenameisrelative}
\func{bool}{IsRelative}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
Returns {\tt true} if this filename is not absolute.
+
\membersection{wxFileName::IsDir}\label{wxfilenameisdir}
\constfunc{bool}{IsDir}{\void}
\helpref{DirExists}{wxfilenamedirexists} or
\helpref{FileExists}{wxfilenamefileexists} for this.
+
\membersection{wxFileName::MakeAbsolute}\label{wxfilenamemakeabsolute}
\func{bool}{MakeAbsolute}{\param{const wxString\& }{cwd = wxEmptyString}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
\helpref{Normalize}{wxfilenamenormalize},
\helpref{IsAbsolute}{wxfilenameisabsolute}
+
\membersection{wxFileName::MakeRelativeTo}\label{wxfilenamemakerelativeto}
-\func{bool}{MakeRelativeTo}{\param{const wxString\& }{pathBase = ""}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
+\func{bool}{MakeRelativeTo}{\param{const wxString\& }{pathBase = wxEmptyString}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
This function tries to put this file name in a form relative to {\it pathBase}.
In other words, it returns the file name which should be used to access this
\helpref{Normalize}{wxfilenamenormalize}
+
\membersection{wxFileName::Mkdir}\label{wxfilenamemkdir}
\func{bool}{Mkdir}{\param{int }{perm = 0777}, \param{int }{flags = $0$}}
Returns {\tt true} if the directory was successfully created, {\tt false}
otherwise.
+
\membersection{wxFileName::Normalize}\label{wxfilenamenormalize}
\func{bool}{Normalize}{\param{int }{flags = wxPATH\_NORM\_ALL}, \param{const wxString\& }{cwd = wxEmptyString}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
\docparam{flags}{The kind of normalization to do with the file name. It can be
any or-combination of the following constants:
+
\begin{twocollist}
\twocolitem{{\bf wxPATH\_NORM\_ENV\_VARS}}{replace env vars with their values}
\twocolitem{{\bf wxPATH\_NORM\_DOTS}}{squeeze all .. and . and prepend cwd}
\twocolitem{{\bf wxPATH\_NORM\_TILDE}}{Unix only: replace ~ and ~user}
-\twocolitem{{\bf wxPATH\_NORM\_CASE}}{if case insensitive => tolower}
+\twocolitem{{\bf wxPATH\_NORM\_CASE}}{if filesystem is case insensitive, transform to tolower case}
\twocolitem{{\bf wxPATH\_NORM\_ABSOLUTE}}{make the path absolute}
\twocolitem{{\bf wxPATH\_NORM\_LONG}}{make the path the long form}
-\twocolitem{{\bf wxPATH\_NORM\_ALL}}{all of previous flags}
+\twocolitem{{\bf wxPATH\_NORM\_SHORTCUT}}{resolve if it is a shortcut (Windows only)}
+\twocolitem{{\bf wxPATH\_NORM\_ALL}}{all of previous flags except \texttt{wxPATH\_NORM\_CASE}}
\end{twocollist}
-}
+}%
\docparam{cwd}{If not empty, this directory will be used instead of current
working directory in normalization.}
\docparam{format}{The file name format, native by default.}
+
\membersection{wxFileName::PrependDir}\label{wxfilenameprependdir}
\func{void}{PrependDir}{\param{const wxString\& }{dir}}
-Prepends a directory name.
+Prepends a directory to the file path. Please see
+\helpref{AppendDir}{wxfilenameappenddir} for important notes.
+
+
\membersection{wxFileName::RemoveDir}\label{wxfilenameremovedir}
Removes a directory name.
+
\membersection{wxFileName::Rmdir}\label{wxfilenamermdir}
\func{bool}{Rmdir}{\void}
Deletes the specified directory from the file system.
+
\membersection{wxFileName::SameAs}\label{wxfilenamesameas}
\constfunc{bool}{SameAs}{\param{const wxFileName\& }{filepath}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
Compares the filename using the rules of this platform.
+
\membersection{wxFileName::SetCwd}\label{wxfilenamesetcwd}
\func{bool}{SetCwd}{\void}
Changes the current working directory.
+
\membersection{wxFileName::SetExt}\label{wxfilenamesetext}
\func{void}{SetExt}{\param{const wxString\& }{ext}}
Sets the extension of this file name.
+
\membersection{wxFileName::SetFullName}\label{wxfilenamesetfullname}
\func{void}{SetFullName}{\param{const wxString\& }{fullname}}
The full name is the file name and extension (but without the path).
+
\membersection{wxFileName::SetName}\label{wxfilenamesetname}
\func{void}{SetName}{\param{const wxString\& }{name}}
Sets the name.
+
\membersection{wxFileName::SetTimes}\label{wxfilenamesettimes}
\func{bool}{SetTimes}{\param{const wxDateTime* }{dtAccess}, \param{const wxDateTime* }{dtMod}, \param{const wxDateTime* }{dtCreate}}
Sets the file creation and last access/modification times (any of the pointers may be NULL).
+
\membersection{wxFileName::SetVolume}\label{wxfilenamesetvolume}
\func{void}{SetVolume}{\param{const wxString\& }{volume}}
Sets the volume specifier.
+
\membersection{wxFileName::SplitPath}\label{wxfilenamesplitpath}
\func{static void}{SplitPath}{\param{const wxString\& }{fullpath}, \param{wxString* }{volume}, \param{wxString* }{path}, \param{wxString* }{name}, \param{wxString* }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
component is. The old contents of the strings pointed to by these parameters
will be overwritten in any case (if the pointers are not {\tt NULL}).
+
+\membersection{wxFileName::SplitVolume}\label{wxfilenamesplitvolume}
+
+\func{static void}{SplitVolume}{\param{const wxString\& }{fullpath}, \param{wxString* }{volume}, \param{wxString* }{path}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
+
+Splits the given \arg{fullpath} into the volume part (which may be empty) and
+the pure path part, not containing any volume.
+
+\wxheading{See also}
+
+\helpref{SplitPath}{wxfilenamesplitpath}
+
+
\membersection{wxFileName::Touch}\label{wxfilenametouch}
\func{bool}{Touch}{\void}
Sets the access and modification times to the current moment.
+
\membersection{wxFileName::operator=}\label{wxfilenameoperatorassign}
\func{wxFileName\& operator}{operator=}{\param{const wxFileName\& }{filename}}
Assigns the new value to this filename object.
+
\membersection{wxFileName::operator==}\label{wxfilenameoperatorequal}
\constfunc{bool operator}{operator==}{\param{const wxFileName\& }{filename}}
Returns {\tt true} if the filenames are equal. The string {\it filenames} is
interpreted as a path in the native filename format.
+
\membersection{wxFileName::operator!=}\label{wxfilenameoperatornotequal}
\constfunc{bool operator}{operator!=}{\param{const wxFileName\& }{filename}}
projects / wxWidgets.git / blobdiff