\latexignore{\rtfignore{\wxheading{Function groups}}}
+
\membersection{File name format}
wxFileName currently supports the file names in the Unix, DOS/Windows, Mac OS
\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{static void}{AssignCwd}{\param{const wxString\& }{volume = wxEmptyString}}
\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}
Returns {\tt true} if the directory with this name exists.
+
\membersection{wxFileName::DirName}\label{wxfilenamedirname}
\func{static wxFileName}{DirName}{\param{const wxString\& }{dir}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
The {\it dir} parameter may have trailing path separator or not.
+
\membersection{wxFileName::FileExists}\label{wxfilenamefileexists}
\constfunc{bool}{FileExists}{\void}
\helpref{DirExists}{wxfilenamedirexists}
+
\membersection{wxFileName::FileName}\label{wxfilenamefilename}
\func{static wxFileName}{FileName}{\param{const wxString\& }{file}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
function exists mainly for symmetry with \helpref{DirName}{wxfilenamedirname}.
+
\membersection{wxFileName::GetCwd}\label{wxfilenamegetcwd}
\func{static wxString}{GetCwd}{\param{const wxString\& }{volume = ""}}
\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{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{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 = {\tt wxPATH\_GET\_VOLUME}}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
the path.}
\end{twocollist}
+
\membersection{wxFileName::GetPathSeparator}\label{wxfilenamegetpathseparator}
\func{static wxChar}{GetPathSeparator}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
\helpref{GetPathSeparators}{wxfilenamegetpathseparators}
+
\membersection{wxFileName::GetPathSeparators}\label{wxfilenamegetpathseparators}
\func{static wxString}{GetPathSeparators}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
\helpref{GetPathSeparator}{wxfilenamegetpathseparator}
+
\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}
doesn't have one or if the file system doesn't support volumes at all (for
example, Unix).
+
\membersection{wxFileName::GetVolumeSeparator}\label{wxfilenamegetvolumeseparator}
\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 {\tt true} if an extension is present.
+
\membersection{wxFileName::HasName}\label{wxfilenamehasname}
\constfunc{bool}{HasName}{\void}
Returns {\tt true} if a name is present.
+
\membersection{wxFileName::HasVolume}\label{wxfilenamehasvolume}
\constfunc{bool}{HasVolume}{\void}
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}
Returns {\tt true} if this filename is absolute.
+
\membersection{wxFileName::IsCaseSensitive}\label{wxfilenameiscasesensitive}
\func{static bool}{IsCaseSensitive}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
Returns {\tt true} if the file names of this type are case-sensitive.
+
\membersection{wxFileName::IsOk}\label{wxfilenameisok}
\constfunc{bool}{IsOk}{\void}
\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{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 = wxEmptyString}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
\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{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::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}}
// path components manipulation
// ----------------------------------------------------------------------------
+/* static */ bool wxFileName::IsValidDirComponent(const wxString& dir)
+{
+ if ( dir.empty() )
+ {
+ wxFAIL_MSG( _T("empty directory passed to wxFileName::InsertDir()") );
+
+ return false;
+ }
+
+ const size_t len = dir.length();
+ for ( size_t n = 0; n < len; n++ )
+ {
+ if ( dir[n] == GetVolumeSeparator() || IsPathSeparator(dir[n]) )
+ {
+ wxFAIL_MSG( _T("invalid directory component in wxFileName") );
+
+ return false;
+ }
+ }
+
+ return true;
+}
+
void wxFileName::AppendDir( const wxString &dir )
{
- m_dirs.Add( dir );
+ if ( IsValidDirComponent(dir) )
+ m_dirs.Add( dir );
}
void wxFileName::PrependDir( const wxString &dir )
{
- m_dirs.Insert( dir, 0 );
+ InsertDir(0, dir);
}
void wxFileName::InsertDir( int before, const wxString &dir )
{
- m_dirs.Insert( dir, before );
+ if ( IsValidDirComponent(dir) )
+ m_dirs.Insert( dir, before );
}
void wxFileName::RemoveDir( int pos )
fullpath += wxGetVolumeString(GetVolume(), format);
}
- // the leading character
- switch ( format )
+ const size_t dirCount = m_dirs.GetCount();
+ if ( dirCount )
{
- case wxPATH_MAC:
- if ( m_relative )
- fullpath += wxFILE_SEP_PATH_MAC;
- break;
+ // the leading character
+ switch ( format )
+ {
+ case wxPATH_MAC:
+ if ( m_relative )
+ fullpath += wxFILE_SEP_PATH_MAC;
+ break;
- case wxPATH_DOS:
- if (!m_relative)
- fullpath += wxFILE_SEP_PATH_DOS;
- break;
+ case wxPATH_DOS:
+ if ( !m_relative )
+ fullpath += wxFILE_SEP_PATH_DOS;
+ break;
- default:
- wxFAIL_MSG( wxT("Unknown path format") );
- // fall through
+ default:
+ wxFAIL_MSG( wxT("Unknown path format") );
+ // fall through
- case wxPATH_UNIX:
- if ( !m_relative )
- {
- // normally the absolute file names starts with a slash with
- // one exception: file names like "~/foo.bar" don't have it
- if ( m_dirs.IsEmpty() || m_dirs[0u] != _T('~') )
+ case wxPATH_UNIX:
+ if ( !m_relative )
{
- fullpath += wxFILE_SEP_PATH_UNIX;
+ // normally the absolute file names start with a slash
+ // with one exception: the ones like "~/foo.bar" don't
+ // have it
+ if ( m_dirs[0u] != _T('~') )
+ {
+ fullpath += wxFILE_SEP_PATH_UNIX;
+ }
}
- }
- break;
+ break;
- case wxPATH_VMS:
- // no leading character here but use this place to unset
- // wxPATH_GET_SEPARATOR flag: under VMS it doesn't make sense as,
- // if I understand correctly, there should never be a dot before
- // the closing bracket
- flags &= ~wxPATH_GET_SEPARATOR;
- }
+ case wxPATH_VMS:
+ // no leading character here but use this place to unset
+ // wxPATH_GET_SEPARATOR flag: under VMS it doesn't make sense
+ // as, if I understand correctly, there should never be a dot
+ // before the closing bracket
+ flags &= ~wxPATH_GET_SEPARATOR;
+ }
- // then concatenate all the path components using the path separator
- size_t dirCount = m_dirs.GetCount();
- if ( dirCount )
- {
+ // then concatenate all the path components using the path separator
if ( format == wxPATH_VMS )
{
fullpath += wxT('[');
fullpath += wxT(']');
}
}
+ else // no directories
+ {
+ // still append path separator if requested
+ if ( flags & wxPATH_GET_SEPARATOR )
+ fullpath += GetPathSeparator(format);
+ }
return fullpath;
}