ENH: support format readOptions for surfaceReader types (#2609)

- similar to surface writing formats, also support optional
  dictionary of reading options. The main beneficiary of this is the
  ensight surface reader:

  readOptions
  {
      ensight
      {
          masterOnly true;
      }
  }

  This will restrict reading to the master rank. Surfaces and values
  read will be broadcast to the other ranks, with the intention of
  reducing load on the filesystem.

ENH: add writing of Dimensioned fields for areaWrite functionObject

- can be useful for examining finite-area source terms

src/fileFormats/Make/files

@@ -1,3 +1,4 @@
+common/fileFormats.C
 common/manifoldCellsMeshObject.C
 
 colours/colourTable.C

src/fileFormats/common/fileFormats.C

@@ -0,0 +1,122 @@
+/*---------------------------------------------------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     |
+    \\  /    A nd           | www.openfoam.com
+     \\/     M anipulation  |
+-------------------------------------------------------------------------------
+    Copyright (C) 2022 OpenCFD Ltd.
+-------------------------------------------------------------------------------
+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 "fileFormats.H"
+#include "dictionary.H"
+
+// * * * * * * * * * * * * * * * Local Functions * * * * * * * * * * * * * * //
+
+namespace Foam
+{
+
+// Extract and merge 'default' + formatName from list of dictionaries
+//
+// \returns dictionary of merged options
+static dictionary combineFormatOptions
+(
+    const word& formatName,
+    std::initializer_list<const dictionary*> dicts
+)
+{
+    dictionary options;
+
+    // Default specification. Merge from all levels
+    // - literal search only
+    for (const dictionary* dict : dicts)
+    {
+        if
+        (
+            dict
+         && (dict = dict->findDict("default", keyType::LITERAL)) != nullptr
+        )
+        {
+            options.merge(*dict);
+        }
+    }
+
+    // Format specification. Merge from all levels
+    // - allow REGEX search
+    if (!formatName.empty())
+    {
+        for (const dictionary* dict : dicts)
+        {
+            if
+            (
+                dict
+             && (dict = dict->findDict(formatName)) != nullptr
+            )
+            {
+                options.merge(*dict);
+            }
+        }
+    }
+
+    return options;
+}
+
+} // End namespace Foam
+
+
+// * * * * * * * * * * * * * * * Global Functions  * * * * * * * * * * * * * //
+
+Foam::dictionary Foam::fileFormats::getFormatOptions
+(
+    const dictionary& dict,
+    const word& formatName,
+    const word& entryName
+)
+{
+    return combineFormatOptions
+    (
+        formatName,
+        {
+            dict.findDict(entryName, keyType::LITERAL)
+        }
+    );
+}
+
+
+Foam::dictionary Foam::fileFormats::getFormatOptions
+(
+    const dictionary& dict,
+    const dictionary& altDict,
+    const word& formatName,
+    const word& entryName
+)
+{
+    return combineFormatOptions
+    (
+        formatName,
+        {
+            dict.findDict(entryName, keyType::LITERAL),
+            altDict.findDict(entryName, keyType::LITERAL)
+        }
+    );
+}
+
+
+// ************************************************************************* //

src/fileFormats/common/fileFormats.H

@@ -0,0 +1,102 @@
+/*---------------------------------------------------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     |
+    \\  /    A nd           | www.openfoam.com
+     \\/     M anipulation  |
+-------------------------------------------------------------------------------
+    Copyright (C) 2022 OpenCFD Ltd.
+-------------------------------------------------------------------------------
+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/>.
+
+Namespace
+    Foam::fileFormats
+
+Description
+    Namespace to isolate specifics for file formats,
+    and some common utilities.
+
+SourceFiles
+    fileFormats.C
+
+\*---------------------------------------------------------------------------*/
+
+#ifndef Foam_fileFormats_H
+#define Foam_fileFormats_H
+
+#include "word.H"
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+namespace Foam
+{
+
+// Forward Declarations
+class dictionary;
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+namespace fileFormats
+{
+
+//- Find "formatOptions" in a top-level dictionary.
+//- Extract and merge 'default' + formatName values.
+//
+//  \returns dictionary of merged formatOptions
+dictionary getFormatOptions
+(
+    //! The top-level dictionary to search
+    const dictionary& dict,
+
+    //! The format name. Eg, \c ensight
+    const word& formatName,
+
+    //! Dictionary sub-entry to search for
+    const word& entryName = "formatOptions"
+);
+
+//- Find "formatOptions" in a top-level dictionary,
+//- and optional override dictionary.
+//- Extract and merge 'default' + formatName values.
+//
+//  \returns dictionary of merged formatOptions
+dictionary getFormatOptions
+(
+    //! The top-level dictionary to search
+    const dictionary& dict,
+
+    //! Additional dictionary to search
+    const dictionary& altDict,
+
+    //! The format name. Eg, \c ensight
+    const word& formatName,
+
+    //! Dictionary sub-entry to search for
+    const word& entryName = "formatOptions"
+);
+
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+} // End namespace fileFormats
+} // End namespace Foam
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+#endif
+
+// ************************************************************************* //

src/fileFormats/ensight/read/ensightReadFile.C

@@ -180,7 +180,27 @@ Foam::Istream& Foam::ensightReadFile::read(label& value)
 }
 
 
-Foam::Istream& Foam::ensightReadFile::read(scalar& value)
+Foam::Istream& Foam::ensightReadFile::read(float& value)
+{
+    if (format() == IOstreamOption::BINARY)
+    {
+        read
+        (
+            reinterpret_cast<char*>(&value),
+            sizeof(value)
+        );
+    }
+    else
+    {
+        stdStream() >> value;
+        syncState();
+    }
+
+    return *this;
+}
+
+
+Foam::Istream& Foam::ensightReadFile::read(double& value)
 {
     float fvalue;
 
@@ -191,15 +211,14 @@ Foam::Istream& Foam::ensightReadFile::read(scalar& value)
             reinterpret_cast<char*>(&fvalue),
             sizeof(fvalue)
         );
-
-        value = fvalue;
     }
     else
     {
-        stdStream() >> value;
+        stdStream() >> fvalue;
         syncState();
     }
 
+    value = fvalue;
     return *this;
 }
 

src/fileFormats/ensight/read/ensightReadFile.H

@@ -27,7 +27,8 @@ Class
     Foam::ensightReadFile
 
 Description
-    Ensight output with specialized read() for strings, integers and floats.
+    A variant of IFstream with specialised read() for
+    strings, integers and floats.
     Correctly handles binary read as well.
 
 \*---------------------------------------------------------------------------*/
@@ -98,13 +99,16 @@ public:
         virtual Istream& read(char* buf, std::streamsize count);
 
         //- Read string as "%80s" or as binary
-        Istream& read(string& value);
+        virtual Istream& read(string& value);
 
         //- Read integer as "%10d" or as binary
-        Istream& read(label& value);
+        virtual Istream& read(label& value);
 
-        //- Read float as "%12.5e" or as binary
-        Istream& read(scalar& value);
+        //- Read floating-point as "%12.5e" or as binary
+        virtual Istream& read(float& value);
+
+        //- Read floating-point as "%12.5e" or as a binary (narrowed) float
+        virtual Istream& read(double& value);
 
         //- Read element keyword
         virtual Istream& readKeyword(string& key);