ENH: provide formatting version of Foam::name() (issue #253)

- there are some cases in which the C-style sprintf is much more
  convenient, albeit problematic for buffer overwrites.

  Provide a formatting version of Foam::name() for language
  primitives that is buffer-safe.

  Returns a Foam::word, so that further output will be unquoted, but
  without any checking that the characters are indeed entirely valid
  word characters.

  Example use,
      i = 1234;
      s = Foam::name("%08d", i);
      produces '00001234'

  Alternative using string streams:

      std::ostringstream buf;
      buf.fill('0');
      buf << setw(8) << i;
      s = buf.str();

  Note that the format specification can also be slightly more complex:

     Foam::name("output%08d.vtk", i);
     Foam::name("timing=%.2fs", time);

It remains the caller's responsibility to ensure that the format mask
is valid.

applications/test/string/Test-string.C

@@ -3,7 +3,7 @@
   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
    \\    /   O peration     |
     \\  /    A nd           | Copyright (C) 2011-2013 OpenFOAM Foundation
-     \\/     M anipulation  |
+     \\/     M anipulation  | Copyright (C) 2016 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -31,6 +31,10 @@ Description
 #include "dictionary.H"
 #include "IOstreams.H"
 
+#include "int.H"
+#include "uint.H"
+#include "scalar.H"
+
 using namespace Foam;
 
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
@@ -118,6 +122,8 @@ int main(int argc, char *argv[])
         Info<< "after replace: " << test2 << endl;
     }
 
+    cout<< "\nEnter some string to test:\n";
+
     string s;
     Sin.getLine(s);
 
@@ -126,7 +132,39 @@ int main(int argc, char *argv[])
     cout<< "output string with " << s2.length() << " characters\n";
     cout<< "ostream<<  >" << s2 << "<\n";
     Info<< "Ostream<<  >" << s2 << "<\n";
-    Info<< "hash:" << hex << string::hash()(s2) << endl;
+    Info<< "hash:" << hex << string::hash()(s2) << dec << endl;
+
+    cout<< "\ntest Foam::name()\n";
+
+    Info<< "hash: = " << Foam::name("0x%012X", string::hash()(s2)) << endl;
+
+    // test formatting on int
+    {
+        label val = 25;
+        Info<<"val: " << val << "\n";
+
+        Info<< "int " << val << " as word >"
+            << Foam::name(val) << "< or "
+            << Foam::name("formatted >%08d<", val) << "\n";
+    }
+
+    // test formatting on scalar
+    {
+        scalar val = 3.1415926535897931;
+        Info<< "scalar " << val << " as word >"
+            << Foam::name(val) << "< or "
+            << Foam::name("formatted >%.9f<", val) << "\n";
+    }
+
+    // test formatting on uint
+    {
+        uint64_t val = 25000000ul;
+        Info<<"val: " << val << "\n";
+
+        Info<< "uint64 " << val << " as word >"
+            << Foam::name(val) << "< or "
+            << Foam::name("formatted >%08d<", val) << "\n";
+    }
 
     Info<< "\nEnd\n" << endl;
     return 0;

src/OpenFOAM/primitives/Scalar/Scalar.C

@@ -3,7 +3,7 @@
   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
    \\    /   O peration     |
     \\  /    A nd           | Copyright (C) 2011-2016 OpenFOAM Foundation
-     \\/     M anipulation  |
+     \\/     M anipulation  | Copyright (C) 2016 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -23,6 +23,8 @@ License
 
 \*---------------------------------------------------------------------------*/
 
+#include "stringOps.H"
+
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
 namespace Foam
@@ -62,6 +64,18 @@ word name(const Scalar val)
 }
 
 
+word name(const char* fmt, const Scalar val)
+{
+    return stringOps::name(fmt, val);
+}
+
+
+word name(const std::string& fmt, const Scalar val)
+{
+    return stringOps::name(fmt, val);
+}
+
+
 // * * * * * * * * * * * * * * * IOstream Operators  * * * * * * * * * * * * //
 
 Scalar readScalar(Istream& is)

src/OpenFOAM/primitives/Scalar/Scalar.H

@@ -3,7 +3,7 @@
   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
    \\    /   O peration     |
     \\  /    A nd           | Copyright (C) 2011-2016 OpenFOAM Foundation
-     \\/     M anipulation  |
+     \\/     M anipulation  | Copyright (C) 2016 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -109,6 +109,16 @@ public:
 word name(const Scalar);
 
 
+//- Return a word representation of a Scalar, using printf-style formatter.
+//  The representation is not checked for valid word characters.
+word name(const char* fmt, const Scalar);
+
+
+//- Return a word representation of a Scalar, using printf-style formatter.
+//  The representation is not checked for valid word characters.
+word name(const std::string& fmt, const Scalar);
+
+
 // Standard C++ transcendental functions
 transFunc(sqrt)
 

src/OpenFOAM/primitives/ints/int32/int32.H

@@ -3,7 +3,7 @@
   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
    \\    /   O peration     |
     \\  /    A nd           | Copyright (C) 2014-2016 OpenFOAM Foundation
-     \\/     M anipulation  |
+     \\/     M anipulation  | Copyright (C) 2016 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -56,7 +56,22 @@ class Ostream;
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
 //- Return a word representation of an int32
-word name(const int32_t);
+inline word name(const int32_t val)
+{
+    // no stripping required
+    return word(std::to_string(val), false);
+}
+
+
+//- Return a word representation of an int32, using printf-style formatter.
+//  The representation is not checked for valid word characters.
+word name(const char* fmt, const int32_t);
+
+
+//- Return a word representation of an int32, using printf-style formatter.
+//  The representation is not checked for valid word characters.
+word name(const std::string&, const int32_t);
+
 
 // * * * * * * * * * * * * * * * IOstream Operators  * * * * * * * * * * * * //
 

src/OpenFOAM/primitives/ints/int32/int32IO.C

@@ -3,7 +3,7 @@
   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
    \\    /   O peration     |
     \\  /    A nd           | Copyright (C) 2014-2016 OpenFOAM Foundation
-     \\/     M anipulation  |
+     \\/     M anipulation  | Copyright (C) 2016 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -24,6 +24,7 @@ License
 \*---------------------------------------------------------------------------*/
 
 #include "int32.H"
+#include "stringOps.H"
 #include "IOstreams.H"
 
 #include <inttypes.h>
@@ -32,11 +33,15 @@ License
 
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
-Foam::word Foam::name(const int32_t val)
+Foam::word Foam::name(const char* fmt, const int32_t val)
 {
-    std::ostringstream buf;
-    buf << val;
-    return buf.str();
+    return stringOps::name(fmt, val);
+}
+
+
+Foam::word Foam::name(const std::string& fmt, const int32_t val)
+{
+    return stringOps::name(fmt, val);
 }
 
 

src/OpenFOAM/primitives/ints/int64/int64.H

@@ -3,7 +3,7 @@
   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
    \\    /   O peration     |
     \\  /    A nd           | Copyright (C) 2014-2016 OpenFOAM Foundation
-     \\/     M anipulation  |
+     \\/     M anipulation  | Copyright (C) 2016 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -60,7 +60,22 @@ class Ostream;
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
 //- Return a word representation of an int64
-word name(const int64_t);
+inline word name(const int64_t val)
+{
+    // no stripping required
+    return word(std::to_string(val), false);
+}
+
+
+//- Return a word representation of an int64, using printf-style formatter.
+//  The representation is not checked for valid word characters.
+word name(const char* fmt, const int64_t);
+
+
+//- Return a word representation of an int64, using printf-style formatter.
+//  The representation is not checked for valid word characters.
+word name(const std::string& fmt, const int64_t);
+
 
 // * * * * * * * * * * * * * * * IOstream Operators  * * * * * * * * * * * * //
 

src/OpenFOAM/primitives/ints/int64/int64IO.C

@@ -24,6 +24,7 @@ License
 \*---------------------------------------------------------------------------*/
 
 #include "int64.H"
+#include "stringOps.H"
 #include "IOstreams.H"
 
 #include <inttypes.h>
@@ -32,11 +33,15 @@ License
 
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
-Foam::word Foam::name(const int64_t val)
+Foam::word Foam::name(const char* fmt, const int64_t val)
 {
-    std::ostringstream buf;
-    buf << val;
-    return buf.str();
+    return stringOps::name(fmt, val);
+}
+
+
+Foam::word Foam::name(const std::string& fmt, const int64_t val)
+{
+    return stringOps::name(fmt, val);
 }
 
 

src/OpenFOAM/primitives/ints/uint32/uint32.H

@@ -3,7 +3,7 @@
   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
    \\    /   O peration     |
     \\  /    A nd           | Copyright (C) 2014-2016 OpenFOAM Foundation
-     \\/     M anipulation  |
+     \\/     M anipulation  | Copyright (C) 2016 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -55,8 +55,23 @@ class Ostream;
 
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
-//- Return a word representation of an uint32
-word name(const uint32_t);
+//- Return a word representation of a uint32
+inline word name(const uint32_t val)
+{
+    // no stripping required
+    return word(std::to_string(val), false);
+}
+
+
+//- Return a word representation of a uint32, using printf-style formatter.
+//  The representation is not checked for valid word characters.
+word name(const char* fmt, const uint32_t);
+
+
+//- Return a word representation of a uint32, using printf-style formatter.
+//  The representation is not checked for valid word characters.
+word name(const std::string& fmt, const uint32_t);
+
 
 // * * * * * * * * * * * * * * * IOstream Operators  * * * * * * * * * * * * //
 

src/OpenFOAM/primitives/ints/uint32/uint32IO.C

@@ -24,17 +24,22 @@ License
 \*---------------------------------------------------------------------------*/
 
 #include "uint32.H"
+#include "stringOps.H"
 #include "IOstreams.H"
 
 #include <sstream>
 
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
-Foam::word Foam::name(const uint32_t val)
+Foam::word Foam::name(const char* fmt, const uint32_t val)
 {
-    std::ostringstream buf;
-    buf << val;
-    return buf.str();
+    return stringOps::name(fmt, val);
+}
+
+
+Foam::word Foam::name(const std::string& fmt, const uint32_t val)
+{
+    return stringOps::name(fmt, val);
 }
 
 

src/OpenFOAM/primitives/ints/uint64/uint64.H

@@ -3,7 +3,7 @@
   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
    \\    /   O peration     |
     \\  /    A nd           | Copyright (C) 2014-2016 OpenFOAM Foundation
-     \\/     M anipulation  |
+     \\/     M anipulation  | Copyright (C) 2016 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -59,8 +59,23 @@ class Ostream;
 
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
-//- Return a word representation of an uint64
-word name(const uint64_t);
+//- Return a word representation of a uint64
+inline word name(const uint64_t val)
+{
+    // no stripping required
+    return word(std::to_string(val), false);
+}
+
+
+//- Return a word representation of a uint64_t, using printf-style formatter.
+//  The representation is not checked for valid word characters.
+word name(const char* fmt, const uint64_t);
+
+
+//- Return a word representation of a uint64_t, using printf-style formatter.
+//  The representation is not checked for valid word characters.
+word name(const std::string& fmt, const uint64_t);
+
 
 // * * * * * * * * * * * * * * * IOstream Operators  * * * * * * * * * * * * //
 

src/OpenFOAM/primitives/ints/uint64/uint64IO.C

@@ -24,17 +24,22 @@ License
 \*---------------------------------------------------------------------------*/
 
 #include "uint64.H"
+#include "stringOps.H"
 #include "IOstreams.H"
 
 #include <sstream>
 
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
-Foam::word Foam::name(const uint64_t val)
+Foam::word Foam::name(const char* fmt, const uint64_t val)
 {
-    std::ostringstream buf;
-    buf << val;
-    return buf.str();
+    return stringOps::name(fmt, val);
+}
+
+
+Foam::word Foam::name(const std::string& fmt, const uint64_t val)
+{
+    return stringOps::name(fmt, val);
 }
 
 

src/OpenFOAM/primitives/strings/stringOps/stringOps.H

@@ -3,7 +3,7 @@
   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
    \\    /   O peration     |
     \\  /    A nd           | Copyright (C) 2011-2012 OpenFOAM Foundation
-     \\/     M anipulation  |
+     \\/     M anipulation  | Copyright (C) 2016 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -36,6 +36,7 @@ SourceFiles
 #define stringOps_H
 
 #include "string.H"
+#include "word.H"
 #include "dictionary.H"
 #include "HashTable.H"
 
@@ -292,6 +293,21 @@ namespace stringOps
     string& inplaceTrim(string&);
 
 
+    //- Return a word representation of the primitive,
+    //  using printf-style formatter.
+    //  The representation is not checked for valid word characters -
+    //  it is assumed that the caller knows what they are doing
+    template<class PrimitiveType>
+    Foam::word name(const char* fmt, const PrimitiveType& val);
+
+    //- Return a word representation of the primitive,
+    //  using printf-style formatter.
+    //  The representation is not checked for valid word characters -
+    //  it is assumed that the caller knows what they are doing
+    template<class PrimitiveType>
+    Foam::word name(const std::string& fmt, const PrimitiveType& val);
+
+
 } // End namespace stringOps
 
 
@@ -299,6 +315,13 @@ namespace stringOps
 
 } // End namespace Foam
 
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+#ifdef NoRepository
+    #include "stringOpsTemplates.C"
+#endif
+
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
 #endif

src/OpenFOAM/primitives/strings/stringOps/stringOpsTemplates.C

@@ -0,0 +1,69 @@
+/*---------------------------------------------------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     |
+    \\  /    A nd           | Copyright (C) 2016 OpenCFD Ltd.
+     \\/     M anipulation  |
+-------------------------------------------------------------------------------
+License
+    This file is part of OpenFOAM.
+
+    OpenFOAM is free software: you can redistribute it and/or modify it
+    under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
+    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+    for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
+
+\*---------------------------------------------------------------------------*/
+
+#include <cstdio>
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+// NOTE: with C++11 could consider variadic templates for a more general
+// sprintf implementation
+
+template<class PrimitiveType>
+Foam::word Foam::stringOps::name
+(
+    const char* fmt,
+    const PrimitiveType& val
+)
+{
+    // same concept as GNU/BSD asprintf()
+    // use snprintf with zero to determine the number of characters required
+
+    int n = ::snprintf(0, 0, fmt, val);
+    if (n > 0)
+    {
+        char buf[n+1];
+        ::snprintf(buf, n+1, fmt, val);
+        buf[n] = 0;
+
+        // no stripping desired
+        return word(buf, false);
+    }
+
+    return word::null;
+}
+
+
+template<class PrimitiveType>
+Foam::word Foam::stringOps::name
+(
+    const std::string& fmt,
+    const PrimitiveType& val
+)
+{
+    return stringOps::name(fmt.c_str(), val);
+}
+
+
+// ************************************************************************* //