added wxFileName::MakeRelativeTo() and the tests/docs for it

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

docs/latex/wx/filename.tex

@@ -87,7 +87,10 @@ File names can be case-sensitive or not, the function\rtfsp
 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}.
+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
@@ -451,15 +454,13 @@ invalid state (the former only do it on failure).
 
 \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::IsWild}\label{wxfilenameiswild}
 
@@ -467,6 +468,28 @@ is this filename relative?
 
 FIXME: what exactly does this do?
 
+\membersection{wxFileName::MakeRelativeTo}\label{wxfilenamemakerelativeto}
+
+\func{bool}{MakeRelativeTo}{\param{const wxString\& }{pathBase = ""}, \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
+file if the current directory were {\it pathBase}.
+
+\docparam{pathBase}{the directory to use as root, current directory is used by
+default}
+
+\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}
 

include/wx/filename.h

@@ -231,6 +231,18 @@ public:
                    const wxString& cwd = wxEmptyString,
                    wxPathFormat format = wxPATH_NATIVE);
 
+        // get a path path relative to the given base directory, i.e. opposite
+        // of Normalize
+        //
+        // pass an empty string to get a path relative to the working directory
+        //
+        // returns TRUE if the file name was modified, FALSE if we failed to do
+        // anything with it (happens when the file is on a different volume,
+        // for example)
+    bool MakeRelativeTo(const wxString& pathBase = _T(""),
+                        wxPathFormat format = wxPATH_NATIVE);
+
+
     // Comparison
 
         // compares with the rules of this platform

samples/console/console.cpp

@@ -884,6 +884,48 @@ static void TestFileNameTemp()
     }
 }
 
+static void TestFileNameMakeRelative()
+{
+    puts("*** testing wxFileName::MakeRelativeTo() ***");
+
+    for ( size_t n = 0; n < WXSIZEOF(filenames); n++ )
+    {
+        const FileNameInfo& fni = filenames[n];
+
+        wxFileName fn(fni.fullname, fni.format);
+
+        // choose the base dir of the same format
+        wxString base;
+        switch ( fni.format )
+        {
+            case wxPATH_UNIX:
+                base = "/usr/bin/";
+                break;
+
+            case wxPATH_DOS:
+                base = "c:\\";
+                break;
+
+            case wxPATH_MAC:
+            case wxPATH_VMS:
+                // TODO: I don't know how this is supposed to work there
+                continue;
+        }
+
+        printf("'%s' relative to '%s': ",
+               fn.GetFullPath(fni.format).c_str(), base.c_str());
+
+        if ( !fn.MakeRelativeTo(base, fni.format) )
+        {
+            puts("unchanged");
+        }
+        else
+        {
+            printf("'%s'\n", fn.GetFullPath(fni.format).c_str());
+        }
+    }
+}
+
 static void TestFileNameComparison()
 {
     // TODO!
@@ -5235,6 +5277,7 @@ int main(int argc, char **argv)
         DumpFileName(fn);
     }
 
+    TestFileNameMakeRelative();
     if ( 0 )
     {
     TestFileNameConstruction();

src/common/filename.cpp

@@ -743,11 +743,51 @@ bool wxFileName::Normalize(wxPathNormalize flags,
     return TRUE;
 }
 
+bool wxFileName::MakeRelativeTo(const wxString& pathBase, wxPathFormat format)
+{
+    wxFileName fnBase(pathBase, format);
+
+    // get cwd only once - small time saving
+    wxString cwd = wxGetCwd();
+    Normalize(wxPATH_NORM_ALL, cwd, format);
+    fnBase.Normalize(wxPATH_NORM_ALL, cwd, format);
+
+    bool withCase = IsCaseSensitive(format);
+
+    // we can't do anything if the files live on different volumes
+    if ( !GetVolume().IsSameAs(fnBase.GetVolume(), withCase) )
+    {
+        // nothing done
+        return FALSE;
+    }
+
+    // same drive, so we don't need our volume
+    m_volume.clear();
+
+    // remove common directories starting at the top
+    while ( !m_dirs.IsEmpty() && !fnBase.m_dirs.IsEmpty() &&
+                m_dirs[0u].IsSameAs(fnBase.m_dirs[0u], withCase) )
+    {
+        m_dirs.Remove(0u);
+        fnBase.m_dirs.Remove(0u);
+    }
+
+    // add as many ".." as needed
+    size_t count = fnBase.m_dirs.GetCount();
+    for ( size_t i = 0; i < count; i++ )
+    {
+        m_dirs.Insert(wxT(".."), 0u);
+    }
+
+    // we were modified
+    return TRUE;
+}
+
 // ----------------------------------------------------------------------------
 // filename kind tests
 // ----------------------------------------------------------------------------
 
-bool wxFileName::SameAs( const wxFileName &filepath, wxPathFormat format)
+bool wxFileName::SameAs(const wxFileName &filepath, wxPathFormat format)
 {
     wxFileName fn1 = *this,
                fn2 = filepath;