ENH: extend fileName::relative() method

- optionally replace stripped parent directory with the \<case\> shortcut

    "/this/path/and/subdirs/name"

    relative("/this/path")        -> "and/subdirs/name"
    relative("/this/path", true)  -> "\<case\>/and/subdirs/name"

applications/test/fileName/Test-fileName.C

@@ -204,11 +204,10 @@ unsigned testRelative(std::initializer_list<Pair<std::string>> tests)
         const std::string& dir    = test.first();
         const std::string& parent = test.second();
 
-        fileName relative = fileName(dir).relative(parent);
-
         Info<< "directory: " << dir << nl
             << "parent   : " << parent << nl
-            << "relative = " << relative << nl
+            << "relative = " << fileName(dir).relative(parent) << nl
+            << "case-rel = " << fileName(dir).relative(parent, true) << nl
             << endl;
     }
 
@@ -537,12 +536,17 @@ int main(int argc, char *argv[])
         nFail += testRelative
         (
             {
+                { "",  "" },
+                { "",  "/" },
+                { "",  "/some" },
+
                 { "/some/dir/subdir/name",  "" },
                 { "/some/dir/subdir/name",  "/" },
                 { "/some/dir/subdir/name",  "/some" },
                 { "/some/dir/subdir/name",  "/some/" },
                 { "/some/dir/subdir/name",  "/some/dir" },
                 { "/some/dir/subdir/name",  "/some/dir/" },
+                { "/some/dir/subdir/name",  "/some/dir/subdir" },
                 { "/some/dir/subdir/name",  "/some/dir/subdir/name" },
                 { "/some/dir/subdir/name",  "/some/dir/subdir/name/" },
                 { "/some/dir/subdir/name",  "/some/other" },
@@ -554,6 +558,7 @@ int main(int argc, char *argv[])
                 { "/some/dir/subdir/a",  "/some/" },
                 { "/some/dir/subdir/a",  "/some/dir" },
                 { "/some/dir/subdir/a",  "/some/dir/" },
+                { "/some/dir/subdir/a",  "/some/dir/subdir" },
                 { "/some/dir/subdir/a",  "/some/dir/subdir/a" },
                 { "/some/dir/subdir/a",  "/some/dir/subdir/a/" },
                 { "/some/dir/subdir/a",  "/some/other" },
@@ -565,6 +570,7 @@ int main(int argc, char *argv[])
                 { "/some/dir/subdir/a/",  "/some/" },
                 { "/some/dir/subdir/a/",  "/some/dir" },
                 { "/some/dir/subdir/a/",  "/some/dir/" },
+                { "/some/dir/subdir/a/",  "/some/dir/subdir/" },
                 { "/some/dir/subdir/a/",  "/some/dir/subdir/a" },
                 { "/some/dir/subdir/a/",  "/some/dir/subdir/a/" },
                 { "/some/dir/subdir/a/",  "/some/other" },

src/OpenFOAM/primitives/strings/fileName/fileName.C

@@ -364,19 +364,37 @@ std::string Foam::fileName::nameLessExt(const std::string& str)
 }
 
 
-Foam::fileName Foam::fileName::relative(const fileName& parent) const
+Foam::fileName Foam::fileName::relative
+(
+    const fileName& parent,
+    const bool caseRelative
+) const
 {
     const auto top = parent.size();
     const fileName& f = *this;
 
-    // Everything after "parent/xxx" -> "xxx"
+    // Everything after "parent/xxx/yyy" -> "xxx/yyy"
+    //
+    // case-relative:
+    //     "parent/xxx/yyy" -> "<case>/xxx/yyy"
     if
     (
-        top && (f.size() > (top+1)) && (*this)[top] == '/'
+        top && (f.size() > (top+1)) && f[top] == '/'
      && f.startsWith(parent)
     )
     {
-        return f.substr(top+1);
+        if (caseRelative)
+        {
+            return "<case>"/f.substr(top+1);
+        }
+        else
+        {
+            return f.substr(top+1);
+        }
+    }
+    else if (caseRelative && f.size() && !f.isAbsolute())
+    {
+        return "<case>"/f;
     }
 
     return f;

src/OpenFOAM/primitives/strings/fileName/fileName.H

@@ -290,8 +290,18 @@ public:
         //- Remove leading path, returning true if string changed.
         inline bool removePath();
 
-        //- Return name after stripping off the parent directory
-        fileName relative(const fileName& parent) const;
+        //- Return a relative name by stripping off the parent directory
+        //- where possible.
+        //
+        //  \param parent the parent directory
+        //  \param caseRelative replace the parent with \<case\> for later
+        //      use with expand(), or prefix \<case\> if the file name was
+        //      not an absolute location
+        fileName relative
+        (
+            const fileName& parent,
+            const bool caseRelative = false
+        ) const;
 
         //- Return file name without extension (part before last .)
         inline fileName lessExt() const;