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;
+}
+
+
+// ************************************************************************* //