ENH: dictionary add/set methods now return a pointer to the entry

- If the entry could be directly inserted: a pointer to the inserted entry.
- If a dictionary merge was required: a pointer to the dictionary that
  received the entry.
- Return nullptr on any type of insertion failure.

This change is code compatible with existing code since it only alters
a bool return value to be a pointer return value.

applications/test/dictionary2/Make/files

@@ -0,0 +1,3 @@
+Test-dictionary2.C
+
+EXE = $(FOAM_USER_APPBIN)/Test-dictionary2

applications/test/dictionary2/Make/options

@@ -0,0 +1 @@
+EXE_INC =

applications/test/dictionary2/Test-dictionary2.C

@@ -0,0 +1,140 @@
+/*---------------------------------------------------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     |
+    \\  /    A nd           | Copyright (C) 2017 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/>.
+
+Application
+    Test-dictionary2
+
+Description
+
+    Test dictionary insertion
+
+\*---------------------------------------------------------------------------*/
+
+#include "argList.H"
+#include "IOstreams.H"
+#include "IOobject.H"
+#include "IFstream.H"
+#include "dictionary.H"
+#include "stringOps.H"
+
+using namespace Foam;
+
+void entryInfo(entry* e)
+{
+    if (e)
+    {
+        Info<<"added "
+            << e->keyword() << ": " << typeid(e).name() << nl;
+    }
+}
+
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+//  Main program:
+
+int main(int argc, char *argv[])
+{
+    argList::noBanner();
+    argList::noParallel();
+
+    argList args(argc, argv);
+
+    dictionary dict1;
+    for (label i=0; i<5; ++i)
+    {
+        dictionary tmpdict;
+
+        {
+            entry* e = dict1.add
+            (
+                Foam::name("entry%d", i),
+                string("entry" + Foam::name(i))
+            );
+            entryInfo(e);
+        }
+
+        {
+            entry* e = tmpdict.add
+            (
+                Foam::name("subentry%d", i),
+                string("subentry" + Foam::name(i))
+            );
+            entryInfo(e);
+        }
+
+        {
+            entry* e = dict1.add
+            (
+                Foam::name("dict%d", i),
+                tmpdict
+            );
+            entryInfo(e);
+        }
+    }
+
+    // Insert new dictionary or merge into existing one
+    for (auto k : { "dict1", "dict10" })
+    {
+        const word key(k);
+        entry* e = dict1.add(key, dictionary(), true);
+
+        if (e && e->isDict())
+        {
+            e->dict().add(word("sub1" + key), 10);
+            e->dict().add(word("sub2" + key), 20);
+            e->dict().add(word("sub3" + key), 30);
+            e->dict().add(word("sub4" + key), 40);
+            e->dict().add(word("sub5" + key), 50);
+            e->dict().add(word("sub6" + key), 60);
+        }
+    }
+
+
+    // overwrite existing
+    {
+        entry* e = dict1.set(word("dict2"), 1000); // overwrite
+        entryInfo(e);
+    }
+
+    // merge into existing dictionary: returns pointer to existing dict
+    {
+        dictionary tmpdict;
+        tmpdict.add(word("something"), 3.14159);
+
+        entry* e = dict1.add(word("dict4"), tmpdict, true);  // merge
+        entryInfo(e);
+
+        if (e)
+            Info<< nl << "=> " << *e << nl;
+    }
+
+    Info<< nl << "dictionary" << nl << nl;
+    dict1.write(Info, false);
+
+    Info<< "\nDone\n" << endl;
+
+    return 0;
+}
+
+
+// ************************************************************************* //

src/OpenFOAM/db/dictionary/dictionary.C

@@ -532,11 +532,11 @@ Foam::List<Foam::keyType> Foam::dictionary::keys(bool patterns) const
 }
 
 
-bool Foam::dictionary::add(entry* entryPtr, bool mergeEntry)
+Foam::entry* Foam::dictionary::add(entry* entryPtr, bool mergeEntry)
 {
     if (!entryPtr)
     {
-        return false;
+        return nullptr;
     }
 
     auto iter = hashedEntries_.find(entryPtr->keyword());
@@ -549,7 +549,7 @@ bool Foam::dictionary::add(entry* entryPtr, bool mergeEntry)
             iter()->dict().merge(entryPtr->dict());
 
             delete entryPtr;
-            return true;
+            return iter();   // pointer to existing dictionary
         }
 
 
@@ -571,7 +571,7 @@ bool Foam::dictionary::add(entry* entryPtr, bool mergeEntry)
                 );
             }
 
-            return true;
+            return entryPtr;  // now an entry in the dictionary
         }
 
 
@@ -582,7 +582,7 @@ bool Foam::dictionary::add(entry* entryPtr, bool mergeEntry)
         parent_type::remove(entryPtr);
 
         delete entryPtr;
-        return false;
+        return nullptr;
     }
 
 
@@ -600,71 +600,86 @@ bool Foam::dictionary::add(entry* entryPtr, bool mergeEntry)
             );
         }
 
-        return true;
+        return entryPtr;  // now an entry in the dictionary
     }
 
 
     IOWarningInFunction((*this))
-        << "attempt to add entry "<< entryPtr->keyword()
+        << "attempt to add entry " << entryPtr->keyword()
         << " which already exists in dictionary " << name()
         << endl;
 
     delete entryPtr;
-    return false;
+    return nullptr;
 }
 
 
-void Foam::dictionary::add(const entry& e, bool mergeEntry)
+Foam::entry* Foam::dictionary::add(const entry& e, bool mergeEntry)
 {
-    add(e.clone(*this).ptr(), mergeEntry);
+    return add(e.clone(*this).ptr(), mergeEntry);
 }
 
 
-void Foam::dictionary::add(const keyType& k, const word& v, bool overwrite)
+Foam::entry* Foam::dictionary::add
+(
+    const keyType& k,
+    const word& v,
+    bool overwrite
+)
 {
-    add(new primitiveEntry(k, token(v)), overwrite);
+    return add(new primitiveEntry(k, token(v)), overwrite);
 }
 
 
-void Foam::dictionary::add
+Foam::entry* Foam::dictionary::add
 (
     const keyType& k,
     const Foam::string& v,
     bool overwrite
 )
 {
-    add(new primitiveEntry(k, token(v)), overwrite);
+    return add(new primitiveEntry(k, token(v)), overwrite);
 }
 
 
-void Foam::dictionary::add(const keyType& k, const label v, bool overwrite)
+Foam::entry* Foam::dictionary::add
+(
+    const keyType& k,
+    const label v,
+    bool overwrite
+)
 {
-    add(new primitiveEntry(k, token(v)), overwrite);
+    return add(new primitiveEntry(k, token(v)), overwrite);
 }
 
 
-void Foam::dictionary::add(const keyType& k, const scalar v, bool overwrite)
+Foam::entry* Foam::dictionary::add
+(
+    const keyType& k,
+    const scalar v,
+    bool overwrite
+)
 {
-    add(new primitiveEntry(k, token(v)), overwrite);
+    return add(new primitiveEntry(k, token(v)), overwrite);
 }
 
 
-void Foam::dictionary::add
+Foam::entry* Foam::dictionary::add
 (
     const keyType& k,
     const dictionary& v,
     bool mergeEntry
 )
 {
-    add(new dictionaryEntry(k, *this, v), mergeEntry);
+    return add(new dictionaryEntry(k, *this, v), mergeEntry);
 }
 
 
-void Foam::dictionary::set(entry* entryPtr)
+Foam::entry* Foam::dictionary::set(entry* entryPtr)
 {
     if (!entryPtr)
     {
-        return;
+        return nullptr;
     }
 
     // Find non-recursive with patterns
@@ -675,19 +690,20 @@ void Foam::dictionary::set(entry* entryPtr)
     {
         finder.dict().clear();
     }
-    add(entryPtr, true);
+
+    return add(entryPtr, true);
 }
 
 
-void Foam::dictionary::set(const entry& e)
+Foam::entry* Foam::dictionary::set(const entry& e)
 {
-    set(e.clone(*this).ptr());
+    return set(e.clone(*this).ptr());
 }
 
 
-void Foam::dictionary::set(const keyType& k, const dictionary& v)
+Foam::entry* Foam::dictionary::set(const keyType& k, const dictionary& v)
 {
-    set(new dictionaryEntry(k, *this, v));
+    return set(new dictionaryEntry(k, *this, v));
 }
 
 

src/OpenFOAM/db/dictionary/dictionary.H

@@ -684,32 +684,42 @@ public:
         //- Add a new entry.
         //  \param mergeEntry dictionaries are interwoven and primitive
         //         entries are overwritten
-        bool add(entry* entryPtr, bool mergeEntry=false);
+        //  \return pointer to inserted entry, or place of merging
+        //   or nullptr on failure
+        entry* add(entry* entryPtr, bool mergeEntry=false);
 
         //- Add an entry.
         //  \param mergeEntry dictionaries are interwoven and primitive
         //         entries are overwritten
-        void add(const entry& e, bool mergeEntry=false);
+        //  \return pointer to inserted entry, or place of merging
+        //   or nullptr on failure
+        entry* add(const entry& e, bool mergeEntry=false);
 
         //- Add a word entry.
         //  \param overwrite force overwrite of an existing entry.
-        void add(const keyType& k, const word& v, bool overwrite=false);
+        //  \return pointer to inserted entry or nullptr on failure
+        entry* add(const keyType& k, const word& v, bool overwrite=false);
 
         //- Add a string entry.
         //  \param overwrite force overwrite of an existing entry.
-        void add(const keyType& k, const string& v, bool overwrite=false);
+        //  \return pointer to inserted entry or nullptr on failure
+        entry* add(const keyType& k, const string& v, bool overwrite=false);
 
         //- Add a label entry.
         //  \param overwrite force overwrite of an existing entry.
-        void add(const keyType& k, const label v, bool overwrite=false);
+        //  \return pointer to inserted entry or nullptr on failure
+        entry* add(const keyType& k, const label v, bool overwrite=false);
 
         //- Add a scalar entry.
         //  \param overwrite force overwrite of an existing entry.
-        void add(const keyType& k, const scalar v, bool overwrite=false);
+        //  \return pointer to inserted entry or nullptr on failure
+        entry* add(const keyType& k, const scalar v, bool overwrite=false);
 
         //- Add a dictionary entry.
         //  \param mergeEntry merge into an existing sub-dictionary
-        void add
+        //  \return pointer to inserted entry, or place of merging
+        //   or nullptr on failure
+        entry* add
         (
             const keyType& k,
             const dictionary& d,
@@ -718,21 +728,29 @@ public:
 
         //- Add a T entry
         //  \param overwrite force overwrite of existing entry
+        //  \return pointer to inserted entry or nullptr on failure
         template<class T>
-        void add(const keyType& k, const T& v, bool overwrite=false);
+        entry* add(const keyType& k, const T& v, bool overwrite=false);
 
         //- Assign a new entry, overwriting any existing entry.
-        void set(entry* entryPtr);
+        //
+        //  \return pointer to inserted entry or nullptr on failure
+        entry* set(entry* entryPtr);
 
         //- Assign a new entry, overwriting any existing entry.
-        void set(const entry& e);
+        //
+        //  \return pointer to inserted entry or nullptr on failure
+        entry* set(const entry& e);
 
         //- Assign a dictionary entry, overwriting any existing entry.
-        void set(const keyType& k, const dictionary& v);
+        //
+        //  \return pointer to inserted entry or nullptr on failure
+        entry* set(const keyType& k, const dictionary& v);
 
         //- Assign a T entry, overwriting any existing entry.
+        //  \return pointer to inserted entry or nullptr on failure
         template<class T>
-        void set(const keyType& k, const T& v);
+        entry* set(const keyType& k, const T& v);
 
         //- Remove an entry specified by keyword
         bool remove(const word& keyword);

src/OpenFOAM/db/dictionary/dictionaryTemplates.C

@@ -146,16 +146,16 @@ bool Foam::dictionary::readIfPresent
 
 
 template<class T>
-void Foam::dictionary::add(const keyType& k, const T& v, bool overwrite)
+Foam::entry* Foam::dictionary::add(const keyType& k, const T& v, bool overwrite)
 {
-    add(new primitiveEntry(k, v), overwrite);
+    return add(new primitiveEntry(k, v), overwrite);
 }
 
 
 template<class T>
-void Foam::dictionary::set(const keyType& k, const T& v)
+Foam::entry* Foam::dictionary::set(const keyType& k, const T& v)
 {
-    set(new primitiveEntry(k, v));
+    return set(new primitiveEntry(k, v));
 }
 
 

src/OpenFOAM/db/dictionary/functionEntries/README

@@ -14,7 +14,7 @@
   #includeIfPresent | dict/primitive    | string
   #includeFunc      | dict              | word
                     |                   |
-  #calcEntry        | dict/primitive    | string
+  #calc             | dict/primitive    | string
   #codeStream       | dict/primitive    | dictionary