1. GetCwd() now has the volume argument, Normalize() works correctly for the

paths without full path but with the volume
2. fixed old SplitPath() version without volume to behave in a backwards
   compatible way
3. added more docs


git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@12784 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/filename.tex

@@ -65,42 +65,115 @@ 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 sam 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}.
+
+Other functions returning information about the file format provided by this
+class are \helpref{GetVolumeSeparator}{wxfilenamegetvolumeseparator},\rtfsp
+\helpref{IsPathSeparator}{wxfilenameispathseparator} and\rtfsp
+\helpref{IsWild}{wxfilenameiswild}.
+
+\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:
+
+\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
+From a full filename: if it terminates with a '/', a directory path
 is contructed (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
+Constructor from a directory name and a file name.
-
-
-\membersection{wxFileName::wxFileName}\label{wxfilenamewxfilename3}
 
 \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, file base name and extension
-
 
 \membersection{wxFileName::AppendDir}\label{wxfilenameappenddir}
 
@@ -134,11 +207,14 @@ from a directory name, file base name and extension
 
 \membersection{wxFileName::AssignCwd}\label{wxfilenameassigncwd}
 
-\func{void}{AssignCwd}{\void}
+\func{void}{AssignCwd}{\param{const wxString\& }{volume = ""}}
 
-various file/dir operations
+Makes this object refer to the current working directory on the specified
-retrieve the value of the current working directory
+volume (or current volume if {\it volume} is empty).
 
+\wxheading{See also}
+
+\helpref{GetCwd}{wxfilenamegetcwd}
 
 \membersection{wxFileName::AssignDir}\label{wxfilenameassigndir}
 
@@ -206,8 +282,20 @@ 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}
 
@@ -384,14 +472,18 @@ FIXME: what exactly does this do?
 
 \func{bool}{Mkdir}{\param{int }{perm = 0777}, \param{bool }{full = FALSE}}
 
-directory creation and removal.
+\func{static bool}{Mkdir}{\param{const wxString\& }{dir}, \param{int }{perm = 0777}, \param{bool }{full = FALSE}}
-if full is TRUE, will try to make each directory in the path.
 
+\docparam{dir}{the directory to create}
 
-\membersection{wxFileName::Mkdir}\label{wxfilenamemkdir}
+\docparam{parm}{the permissions for the newly created directory}
 
-\func{bool}{Mkdir}{\param{const wxString\& }{dir}, \param{int }{perm = 0777}, \param{bool }{full = FALSE}}
+\docparam{full}{if {\tt TRUE}, will try to make each directory in the path}
 
+\wxheading{Return value}
+
+Returns {\tt TRUE} if the directory was successfully created, {\tt FALSE}
+otherwise.
 
 \membersection{wxFileName::Normalize}\label{wxfilenamenormalize}
 
@@ -418,31 +510,26 @@ 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}
+Deletes the specified directory.
-
-\func{bool}{Rmdir}{\param{const wxString\& }{dir}}
 
 
 \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}
 
+\func{static bool}{SetCwd}{\param{const wxString\& }{cwd}}
+
 change the current working directory
 
-
-\membersection{wxFileName::SetCwd}\label{wxfilenamesetcwd}
-
-\func{bool}{SetCwd}{\param{const wxString\& }{cwd}}
-
-
 \membersection{wxFileName::SetExt}\label{wxfilenamesetext}
 
 \func{void}{SetExt}{\param{const wxString\& }{ext}}
@@ -493,20 +580,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.
+

include/wx/filename.h

@@ -189,8 +189,8 @@ public:
     // various file/dir operations
 
         // retrieve the value of the current working directory
-    void AssignCwd();
+    void AssignCwd(const wxString& volume = wxEmptyString);
-    static wxString GetCwd();
+    static wxString GetCwd(const wxString& volume = wxEmptyString);
 
         // change the current working directory
     bool SetCwd();
@@ -321,10 +321,7 @@ public:
                           wxString *path,
                           wxString *name,
                           wxString *ext,
-                          wxPathFormat format = wxPATH_NATIVE)
+                          wxPathFormat format = wxPATH_NATIVE);
-    {
-        SplitPath(fullpath, NULL, path, name, ext, format);
-    }
 
 private:
     // the drive/volume/device specification (always empty for Unix)

src/common/filename.cpp

@@ -311,15 +311,33 @@ bool wxFileName::DirExists( const wxString &dir )
 // CWD and HOME stuff
 // ----------------------------------------------------------------------------
 
-void wxFileName::AssignCwd()
+void wxFileName::AssignCwd(const wxString& volume)
 {
-    AssignDir(wxFileName::GetCwd());
+    AssignDir(wxFileName::GetCwd(volume));
 }
 
 /* static */
-wxString wxFileName::GetCwd()
+wxString wxFileName::GetCwd(const wxString& volume)
 {
-    return ::wxGetCwd();
+    // if we have the volume, we must get the current directory on this drive
+    // and to do this we have to chdir to this volume - at least under Windows,
+    // I don't know how to get the current drive on another volume elsewhere
+    // (TODO)
+    wxString cwdOld;
+    if ( !volume.empty() )
+    {
+        cwdOld = wxGetCwd();
+        SetCwd(volume + GetVolumeSeparator());
+    }
+
+    wxString cwd = ::wxGetCwd();
+
+    if ( !volume.empty() )
+    {
+        SetCwd(cwdOld);
+    }
+
+    return cwd;
 }
 
 bool wxFileName::SetCwd()
@@ -432,9 +450,13 @@ bool wxFileName::Normalize(wxPathNormalize flags,
     if ( (flags & wxPATH_NORM_ABSOLUTE) && !IsAbsolute() )
     {
         if ( cwd.empty() )
-            curDir.AssignCwd();
+        {
-        else
+            curDir.AssignCwd(GetVolume());
+        }
+        else // cwd provided
+        {
             curDir.AssignDir(cwd);
+        }
 
         // the path may be not absolute because it doesn't have the volume name
         // but in this case we shouldn't modify the directory components of it
@@ -976,6 +998,7 @@ wxPathFormat wxFileName::GetFormat( wxPathFormat format )
 // path splitting function
 // ----------------------------------------------------------------------------
 
+/* static */
 void wxFileName::SplitPath(const wxString& fullpathWithVolume,
                            wxString *pstrVolume,
                            wxString *pstrPath,
@@ -1121,6 +1144,22 @@ void wxFileName::SplitPath(const wxString& fullpathWithVolume,
     }
 }
 
+/* static */
+void wxFileName::SplitPath(const wxString& fullpath,
+                           wxString *path,
+                           wxString *name,
+                           wxString *ext,
+                           wxPathFormat format)
+{
+    wxString volume;
+    SplitPath(fullpath, &volume, path, name, ext, format);
+
+    if ( path && !volume.empty() )
+    {
+        path->Prepend(volume + GetVolumeSeparator(format));
+    }
+}
+
 // ----------------------------------------------------------------------------
 // time functions
 // ----------------------------------------------------------------------------