X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/2569938d392eace21ae617355f9c1a636185f36f..72db8894790c0fc32a8a57e9e2f750e8f95222b1:/docs/latex/wx/filename.tex diff --git a/docs/latex/wx/filename.tex b/docs/latex/wx/filename.tex index 992aead482..4f656c7403 100644 --- a/docs/latex/wx/filename.tex +++ b/docs/latex/wx/filename.tex @@ -65,42 +65,124 @@ enum wxPathNormalize } \end{verbatim} +\latexignore{\rtfignore{\wxheading{Function groups}}} + +\membersection{File name format} + +wxFileName currently supports the file names in the Unix, DOS/Windows, Mac OS +and VMS formats. Although these formats are quite different, wxFileName tries +to treat them all in the same generic way. It supposes that all file names +consist of the following parts: the volume (also known as drive under Windows +or device under VMS), the path which is a sequence of directory names separated +by the \helpref{path separators}{wxfilenamegetpathseparators} and the full +filename itself which, in turn, is composed from the base file name and the +extension. All of the individual components of the file name may be empty and, +for example, the volume name is always empty under Unix, but if they are all +empty simultaneously, the filename object is considered to be in an invalid +state and \helpref{IsOk}{wxfilenameisok} returns {\tt FALSE} for it. + +File names can be case-sensitive or not, the function\rtfsp +\helpref{IsCaseSensitive}{wxfilenameiscasesensitive} allows to determine this. + +The rules for determining if the file name is absolute or relative also depends +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{Normalize}{wxfilenamenormalize}. There +is also an inverse function \helpref{MakeRelativeTo}{wxfilenamemakerelativeto} +which undoes what \helpref{Normalize(wxPATH\_NORM\_DOTS}{wxfilenamenormalize} +does. + +Other functions returning information about the file format provided by this +class are \helpref{GetVolumeSeparator}{wxfilenamegetvolumeseparator},\rtfsp +\helpref{IsPathSeparator}{wxfilenameispathseparator}. + +\helpref{IsRelative}{wxfilenameisrelative} + +\membersection{File name construction} + +TODO. + +\membersection{File tests} + +Before doing the other tests you should use \helpref{IsOk}{wxfilenameisok} to +verify that the filename is well defined. If it is, +\helpref{FileExists}{wxfilenamefileexists} can be used to test if a file with +such name exists and \helpref{DirExists}{wxfilenamedirexists} - if a directory +with this name exists. + +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{AppendDir}{wxfilenameappenddir}\\ +\helpref{InsertDir}{wxfilenameinsertdir}\\ +\helpref{GetDirCount}{wxfilenamegetdircount} +\helpref{PrependDir}{wxfilenameprependdir}\\ +\helpref{RemoveDir}{wxfilenameremovedir} + +To change the components of the file name individually you can use the +following functions: + +\helpref{GetExt}{wxfilenamegetext}\\ +\helpref{GetName}{wxfilenamegetname}\\ +\helpref{GetVolume}{wxfilenamegetvolume}\\ +\helpref{HasExt}{wxfilenamehasext}\\ +\helpref{HasName}{wxfilenamehasname}\\ +\helpref{HasVolume}{wxfilenamehasvolume}\\ +\helpref{SetExt}{wxfilenamesetext}\\ +\helpref{SetName}{wxfilenamesetname}\\ +\helpref{SetVolume}{wxfilenamesetvolume}\\ + +\membersection{Operations} + +These methods allow to work with the file creation, access and modification +times. Note that not all filesystems under all platforms implement these times +in the same way. For example, the access time under Windows has a resolution of +one day (so it is really the access date and not time). The access time may be +updated when the file is executed or not depending on the platform. + +\helpref{GetModificationTime}{wxfilenamegetmodificationtime}\\ +\helpref{GetTimes}{wxfilenamegettimes}\\ +\helpref{SetTimes}{wxfilenamesettimes}\\ +\helpref{Touch}{wxfilenametouch} + +Other file system operations functions are: + +\helpref{Mkdir}{wxfilenamemkdir}\\ +\helpref{Rmdir}{wxfilenamermdir} + \latexignore{\rtfignore{\wxheading{Members}}} -\membersection{wxFileName::wxFileName}\label{wxfilenamewxfilenamedef} +\membersection{wxFileName::wxFileName}\label{wxfilenamewxfilename} \func{}{wxFileName}{\void} Default constructor. -\membersection{wxFileName::wxFileName}\label{wxfilenamewxfilenamecopy} - \func{}{wxFileName}{\param{const wxFileName\& }{filename}} Copy constructor. -\membersection{wxFileName::wxFileName}\label{wxfilenamewxfilename1} - \func{}{wxFileName}{\param{const wxString\& }{fullpath}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} -from a full filename: if it terminates with a '/', a directory path -is contructed (the name will be empty), otherwise a file name and +From a full filename: if it terminates with a '/', a directory path +is constructed (the name will be empty), otherwise a file name and extension are extracted from it - -\membersection{wxFileName::wxFileName}\label{wxfilenamewxfilename2} - \func{}{wxFileName}{\param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} -from a directory name and a file name - - -\membersection{wxFileName::wxFileName}\label{wxfilenamewxfilename3} +Constructor from a directory name and a file name. \func{}{wxFileName}{\param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{const wxString\& }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} -from a directory name, file base name and extension +Constructor from a directory name, base file name and extension +\func{}{wxFileName}{\param{const wxString\& }{volume}, \param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{const wxString\& }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} + +Constructor from a volume name, a directory name, base file name and extension \membersection{wxFileName::AppendDir}\label{wxfilenameappenddir} @@ -111,91 +193,102 @@ from a directory name, file base name and extension \func{void}{Assign}{\param{const wxFileName\& }{filepath}} - -\membersection{wxFileName::Assign}\label{wxfilenameassign} - \func{void}{Assign}{\param{const wxString\& }{fullpath}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} - -\membersection{wxFileName::Assign}\label{wxfilenameassign} - \func{void}{Assign}{\param{const wxString\& }{volume}, \param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{const wxString\& }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} - -\membersection{wxFileName::Assign}\label{wxfilenameassign} - \func{void}{Assign}{\param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} - -\membersection{wxFileName::Assign}\label{wxfilenameassign} - \func{void}{Assign}{\param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{const wxString\& }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} \membersection{wxFileName::AssignCwd}\label{wxfilenameassigncwd} -\func{void}{AssignCwd}{\void} +\func{void}{AssignCwd}{\param{const wxString\& }{volume = ""}} + +Makes this object refer to the current working directory on the specified +volume (or current volume if {\it volume} is empty). -various file/dir operations -retrieve the value of the current working directory +\wxheading{See also} +\helpref{GetCwd}{wxfilenamegetcwd} \membersection{wxFileName::AssignDir}\label{wxfilenameassigndir} \func{void}{AssignDir}{\param{const wxString\& }{dir}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} -empty volume - +Set 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} -get the value of user home (Unix only mainly) - +Set this file name object to the home directory. \membersection{wxFileName::AssignTempFileName}\label{wxfilenameassigntempfilename} -\func{void}{AssignTempFileName}{\param{const wxString\& }{prefix}} - -get a temp file name starting with thespecified prefix +\func{void}{AssignTempFileName}{\param{const wxString\& }{prefix}, \param{wxFile *}{fileTemp = {\tt NULL}}} +The function calls \helpref{CreateTempFileName}{wxfilenamecreatetempfilename} 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 the\rtfsp +\helpref{invalid}{wxfilenameisok} state. \membersection{wxFileName::Clear}\label{wxfilenameclear} \func{void}{Clear}{\void} -reset all components to default, uninitialized state +Reset all components to default, uninitialized state. +\membersection{wxFileName::CreateTempFileName}\label{wxfilenamecreatetempfilename} -\membersection{wxFileName::DirExists}\label{wxfilenamedirexists} +\func{static wxString}{CreateTempFileName}{\param{const wxString\& }{prefix}, \param{wxFile *}{fileTemp = {\tt NULL}}} -\func{bool}{DirExists}{\void} +Returns a temporary file name starting with the given {\it prefix}. If +the {\it prefix} is an absolute path, the temporary file is created in this +directory, otherwise it is created in the default system directory for the +temporary files or in the current directory. + +If the function succeeds, the temporary file is actually created. If\rtfsp +{\it fileTemp} is not {\tt NULL}, this file will be opened using the name of +the temporary file. When possible, this is done in an atomic way ensuring that +no race condition occurs between the temporary file name generation and opening +it which could often lead to security compromise on the multiuser systems. +If {\it fileTemp} is {\tt NULL}, the file is only created, but not opened. + +Under Unix, the temporary file will have read and write permissions for the +owner only to minimize the security problems. + +\wxheading{Parameters} + +\docparam{prefix}{Prefix to use for the temporary file name construction} -does the directory with this name exists? +\docparam{fileTemp}{The file to open or {\tt NULL} to just get the name} +\wxheading{Return value} + +The full temporary file name or an empty string on error. \membersection{wxFileName::DirExists}\label{wxfilenamedirexists} +\func{bool}{DirExists}{\void} + \func{bool}{DirExists}{\param{const wxString\& }{dir}} +Does the directory with this name exists? \membersection{wxFileName::DirName}\label{wxfilenamedirname} \func{wxFileName}{DirName}{\param{const wxString\& }{dir}} - \membersection{wxFileName::FileExists}\label{wxfilenamefileexists} \func{bool}{FileExists}{\void} -does the file with this name exists? - - -\membersection{wxFileName::FileExists}\label{wxfilenamefileexists} - \func{bool}{FileExists}{\param{const wxString\& }{file}} +Does the file with this name exists? \membersection{wxFileName::FileName}\label{wxfilenamefilename} @@ -203,11 +296,22 @@ does the file with this name exists? static pseudo constructors - \membersection{wxFileName::GetCwd}\label{wxfilenamegetcwd} -\func{wxString}{GetCwd}{\void} +\func{wxString}{GetCwd}{\param{const wxString\& }{volume = ""}} + +Retrieve 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 +current volume. + +\wxheading{Return value} + +The string containing the current working directory or an empty string on +error. + +\wxheading{See also} +\helpref{AssignCwd}{wxfilenameassigncwd} \membersection{wxFileName::GetDirCount}\label{wxfilenamegetdircount} @@ -270,17 +374,45 @@ convenience wrapper: get just the last mod time of the file \membersection{wxFileName::GetPath}\label{wxfilenamegetpath} -\constfunc{wxString}{GetPath}{\param{bool }{add\_separator = FALSE}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} +\constfunc{wxString}{GetPath}{\param{int }{flags = $0$}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} -Construct path only - possibly with the trailing separator +Return the path part of the filename (without the name nor 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)} +\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}} + +Return 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 +are two of them and the native one, i.e. the backslash is returned by this +method. + +\wxheading{See also} + +\helpref{GetPathSeparators}{wxfilenamegetpathseparators} \membersection{wxFileName::GetPathSeparators}\label{wxfilenamegetpathseparators} \func{wxString}{GetPathSeparators}{\param{wxPathFormat }{format = wxPATH\_NATIVE}} -get the string of path separators for this format +Get 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 +DOS and Windows both {\tt '/'} and {\tt '\textbackslash'} may be used as +separators. + +\wxheading{See also} +\helpref{GetPathSeparator}{wxfilenamegetpathseparator} \membersection{wxFileName::GetPathWithSep}\label{wxfilenamegetpathwithsep} @@ -298,16 +430,30 @@ 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* }{dtChange}} +\constfunc{bool}{GetTimes}{\param{wxDateTime* }{dtAccess}, \param{wxDateTime* }{dtMod}, \param{wxDateTime* }{dtCreate}} -return the last access, last modification and last change times -(any of the pointers may be NULL) +Return the last access, last modification and creation times. The last access +time is updated whenever the file is read or written (or executed in the case +of Windows), last modification time is only changed when the file is written +to. Finally, the creation time is indeed the time when the file was created +under Windows and the inode change time under Unix (as it is impossible to +retrieve the real file creation time there anyhow) which can also be changed +by many operations after the file creation. + +Aany of the pointers may be {\tt NULL} if the corresponding time is not +needed. + +\wxheading{Return value} +{\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 +doesn't have one or if the file system doesn't support volumes at all (for +example, Unix). \membersection{wxFileName::GetVolumeSeparator}\label{wxfilenamegetvolumeseparator} @@ -355,47 +501,78 @@ are the file names of this type cases sensitive? \constfunc{bool}{IsOk}{\void} -file tests -is the filename valid at all? - +Returns {\tt TRUE} if the filename is valid, {\tt FALSE} if it is not +initialized yet. The assignment functions and +\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}} -is the char a path separator for this format? - +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}} -is this filename relative? +Returns {\tt TRUE} if this filename is not absolute. +\membersection{wxFileName::IsDir}\label{wxfilenameisdir} -\membersection{wxFileName::IsWild}\label{wxfilenameiswild} +\constfunc{bool}{IsDir}{\void} -\func{bool}{IsWild}{\param{wxPathFormat }{format = wxPATH\_NATIVE}} +Returns {\tt TRUE} if this object represents a directory, {\tt FALSE} otherwise +(i.e. if it is a file). Note that this method doesn't test whether the +directory or file really exists, you should use +\helpref{DirExists}{wxfilenamedirexists} or +\helpref{FileExists}{wxfilenamefileexists} for this. -FIXME: what exactly does this do? +\membersection{wxFileName::MakeRelativeTo}\label{wxfilenamemakerelativeto} +\func{bool}{MakeRelativeTo}{\param{const wxString\& }{pathBase = ""}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} -\membersection{wxFileName::Mkdir}\label{wxfilenamemkdir} +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 +file if the current directory were {\it pathBase}. -\func{bool}{Mkdir}{\param{int }{perm = 0777}, \param{bool }{full = FALSE}} +\docparam{pathBase}{the directory to use as root, current directory is used by +default} -directory creation and removal. -if full is TRUE, will try to make each directory in the path. +\docparam{format}{the file name format, native by default} +\wxheading{Return value} + +{\tt TRUE} if the file name has been changed, {\tt FALSE} if we failed to do +anything with it (currently this only happens if the file name is on a volume +different from the volume specified by {\it pathBase}). + +\wxheading{See also} + +\helpref{Normalize}{wxfilenamenormalize} \membersection{wxFileName::Mkdir}\label{wxfilenamemkdir} -\func{bool}{Mkdir}{\param{const wxString\& }{dir}, \param{int }{perm = 0777}, \param{bool }{full = FALSE}} +\func{bool}{Mkdir}{\param{int }{perm = 0777}, \param{int }{flags = $0$}} + +\func{static bool}{Mkdir}{\param{const wxString\& }{dir}, \param{int }{perm = 0777}, \param{int }{flags = $0$}} + +\docparam{dir}{the directory to create} + +\docparam{parm}{the permissions for the newly created directory} + +\docparam{flags}{if the flags contain {\tt wxPATH\_MKDIR\_FULL} flag, +try to create each directory in the path and also don't return an error +if the target directory already exists.} +\wxheading{Return value} + +Returns {\tt TRUE} if the directory was successfully created, {\tt FALSE} +otherwise. \membersection{wxFileName::Normalize}\label{wxfilenamenormalize} -\func{bool}{Normalize}{\param{wxPathNormalize }{flags = wxPATH\_NORM\_ALL}, \param{const wxString\& }{cwd = wxEmptyString}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} +\func{bool}{Normalize}{\param{int }{flags = wxPATH\_NORM\_ALL}, \param{const wxString\& }{cwd = wxEmptyString}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} operations on the path normalize the path: with the default flags value, the path will be @@ -418,30 +595,25 @@ this may be done using another (than current) value of cwd \func{bool}{Rmdir}{\void} +\func{static bool}{Rmdir}{\param{const wxString\& }{dir}} -\membersection{wxFileName::Rmdir}\label{wxfilenamermdir} - -\func{bool}{Rmdir}{\param{const wxString\& }{dir}} +Deletes the specified directory. \membersection{wxFileName::SameAs}\label{wxfilenamesameas} \func{bool}{SameAs}{\param{const wxFileName\& }{filepath}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} -compares with the rules of this platform +Compares the filename using the rules of this platform \membersection{wxFileName::SetCwd}\label{wxfilenamesetcwd} \func{bool}{SetCwd}{\void} -change the current working directory - - -\membersection{wxFileName::SetCwd}\label{wxfilenamesetcwd} - -\func{bool}{SetCwd}{\param{const wxString\& }{cwd}} +\func{static bool}{SetCwd}{\param{const wxString\& }{cwd}} +change the current working directory \membersection{wxFileName::SetExt}\label{wxfilenamesetext} @@ -462,7 +634,7 @@ full name is the file name + extension (but without the path) \membersection{wxFileName::SetTimes}\label{wxfilenamesettimes} -\func{bool}{SetTimes}{\param{const wxDateTime* }{dtCreate}, \param{const wxDateTime* }{dtAccess}, \param{const wxDateTime* }{dtMod}} +\func{bool}{SetTimes}{\param{const wxDateTime* }{dtAccess}, \param{const wxDateTime* }{dtMod}, \param{const wxDateTime* }{dtCreate}} set the file creation and last access/mod times (any of the pointers may be NULL) @@ -475,12 +647,21 @@ set the file creation and last access/mod times \membersection{wxFileName::SplitPath}\label{wxfilenamesplitpath} -\func{void}{SplitPath}{\param{const wxString\& }{fullpath}, \param{wxString* }{volume}, \param{wxString* }{path}, \param{wxString* }{name}, \param{wxString* }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} +\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}} -\func{void}{SplitPath}{\param{const wxString\& }{fullpath}, \param{wxString* }{path}, \param{wxString* }{name}, \param{wxString* }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} +\func{static void}{SplitPath}{\param{const wxString\& }{fullpath}, \param{wxString* }{path}, \param{wxString* }{name}, \param{wxString* }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} -split a fullpath into the volume, path, (base) name and extension -(all of the pointers can be NULL) +This function splits a full file name into components: the volume (with the +first version) path (including the volume in the second version), the base name +and the extension. Any of the output parameters ({\it volume}, {\it path}, +{\it name} or {\it ext}) may be {\tt NULL} if you are not interested in the +value of a particular component. Also, {\it fullpath} may be empty on entry. + +On return, {\it path} contains the file path (without the trailing separator), +{\it name} contains the file name and {\it ext} contains the file extension +without leading dot. All three of them may be empty if the corresponding +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::Touch}\label{wxfilenametouch} @@ -493,20 +674,15 @@ set the access and modification times to the current moment \func{wxFileName\& operator}{operator=}{\param{const wxFileName\& }{filename}} - -\membersection{wxFileName::operator=}\label{wxfilenameoperatorassign} - \func{wxFileName\& operator}{operator=}{\param{const wxString\& }{filename}} +Assigns the new value to this filename object. \membersection{wxFileName::operator==}\label{wxfilenameoperatorequal} \func{bool operator}{operator==}{\param{const wxFileName\& }{filename}} -uses the current platform settings - - -\membersection{wxFileName::operator==}\label{wxfilenameoperatorequal} - \func{bool operator}{operator==}{\param{const wxString\& }{filename}} +Returns {\tt TRUE} if the filenames are equal for the native file format. +