ENH: align Enum methods with HashTable

- deprecate get(key, deflt) in favour of lookup(key, deflt).
  Method name compatibility with HashTable.

- deprecate operator().
  The meaning is too opaque and equally served by other means:

  - use get(key) instead of operator()(key).
    Const access whereas HashTable::operator()(key)
    creates missing entry.

  - lookup(key, deflt) - instead of operator()(key, deflt).
    Const access whereas HashTable::operator()(key, deflt)
    creates a missing entry.

- make Enum iterable to allow participation in range-for etc.

applications/test/Enum/Test-Enum.C

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2018-2019 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -125,6 +125,17 @@ int main(int argc, char *argv[])
         <<"stdout: "<< otherNames2
         << nl << nl;
 
+    Info<< "iterate:" << nl;
+    forAllConstIters(otherNames2, iter)
+    {
+        Info<< "key=" << iter.key() << " val=" << iter.val() << nl;
+    }
+
+    for (const word& k : otherNames2)
+    {
+        Info<< "    " << k << " is " << otherNames2[k] << nl;
+    }
+    Info<< nl;
 
     otherNames2.clear();
     otherNames2.append

src/OpenFOAM/expressions/fields/fieldExprScanner.cc

@@ -204,7 +204,7 @@ bool Foam::expressions::fieldExpr::scanner::dispatch_method
         << "Method:" << ident
         << " at " << driver_.parsePosition() << nl;
 
-    const int methType = fieldMethodEnums.get(ident, -1);
+    const int methType = fieldMethodEnums.lookup(ident, -1);
 
     if (methType > 0)
     {
@@ -243,7 +243,7 @@ bool Foam::expressions::fieldExpr::scanner::dispatch_ident
     else
     {
         // Check for function name
-        tokType = funcTokenEnums.get(ident, -1);
+        tokType = funcTokenEnums.lookup(ident, -1);
 
         if (tokType > 0)
         {
@@ -257,7 +257,7 @@ bool Foam::expressions::fieldExpr::scanner::dispatch_ident
 
         #ifdef HAS_LOOKBEHIND_TOKENS
         // Specials such "cset" also reset the look-behind
-        tokType = lookBehindTokenEnums.get(ident, -1);
+        tokType = lookBehindTokenEnums.lookup(ident, -1);
 
         if (tokType > 0)
         {
@@ -299,7 +299,7 @@ bool Foam::expressions::fieldExpr::scanner::dispatch_ident
     (
         quoted || dot == std::string::npos
       ? -1
-      : fieldMethodEnums.get(ident.substr(dot+1), -1)
+      : fieldMethodEnums.lookup(ident.substr(dot+1), -1)
     );
 
     if

src/OpenFOAM/expressions/fields/fieldExprScanner.rl

@@ -333,7 +333,7 @@ bool Foam::expressions::fieldExpr::scanner::dispatch_method
         << "Method:" << ident
         << " at " << driver_.parsePosition() << nl;
 
-    const int methType = fieldMethodEnums.get(ident, -1);
+    const int methType = fieldMethodEnums.lookup(ident, -1);
 
     if (methType > 0)
     {
@@ -372,7 +372,7 @@ bool Foam::expressions::fieldExpr::scanner::dispatch_ident
     else
     {
         // Check for function name
-        tokType = funcTokenEnums.get(ident, -1);
+        tokType = funcTokenEnums.lookup(ident, -1);
 
         if (tokType > 0)
         {
@@ -386,7 +386,7 @@ bool Foam::expressions::fieldExpr::scanner::dispatch_ident
 
         #ifdef HAS_LOOKBEHIND_TOKENS
         // Specials such "cset" also reset the look-behind
-        tokType = lookBehindTokenEnums.get(ident, -1);
+        tokType = lookBehindTokenEnums.lookup(ident, -1);
 
         if (tokType > 0)
         {
@@ -428,7 +428,7 @@ bool Foam::expressions::fieldExpr::scanner::dispatch_ident
     (
         quoted || dot == std::string::npos
       ? -1
-      : fieldMethodEnums.get(ident.substr(dot+1), -1)
+      : fieldMethodEnums.lookup(ident.substr(dot+1), -1)
     );
 
     if

src/OpenFOAM/primitives/enums/Enum.C

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2017-2019 OpenCFD Ltd.
+    Copyright (C) 2017-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -51,17 +51,6 @@ Foam::Enum<EnumType>::Enum
 
 // * * * * * * * * * * * * * * * Member Functions  * * * * * * * * * * * * * //
 
-template<class EnumType>
-Foam::List<Foam::word> Foam::Enum<EnumType>::sortedToc() const
-{
-    List<word> list(keys_);
-
-    Foam::sort(list);
-
-    return list;
-}
-
-
 template<class EnumType>
 void Foam::Enum<EnumType>::append
 (
@@ -99,7 +88,7 @@ EnumType Foam::Enum<EnumType>::get(const word& enumName) const
 
 
 template<class EnumType>
-EnumType Foam::Enum<EnumType>::get
+EnumType Foam::Enum<EnumType>::lookup
 (
     const word& enumName,
     const EnumType deflt

src/OpenFOAM/primitives/enums/Enum.H

@@ -66,15 +66,10 @@ class Enum
         //- The names for the enum
         List<word> keys_;
 
-        //- The values for the enum
+        //- The values for the enum, stored as int
         List<int> vals_;
 
 
-public:
-
-    //- The type of enumeration represented by the Enum
-    typedef EnumType value_type;
-
     // Allow enums and integrals (should fit within an int)
     static_assert
     (
@@ -82,6 +77,16 @@ public:
         "Enum must be enum or an integral type"
     );
 
+public:
+
+    // Typedefs
+
+        //- The type of keys used
+        typedef word key_type;
+
+        //- The type of enumeration represented by the Enum
+        typedef EnumType value_type;
+
 
     // Constructors
 
@@ -108,16 +113,16 @@ public:
         inline label size() const noexcept;
 
         //- The list of enum names, in construction order. Same as toc()
-        inline const List<word>& names() const;
+        inline const List<word>& names() const noexcept;
-
-        //- The list of enum names, in construction order. Same as names()
-        inline const List<word>& toc() const;
-
-        //- The sorted list of enum names.
-        List<word> sortedToc() const;
 
         //- The list of enum values, in construction order.
-        inline const List<int>& values() const;
+        inline const List<int>& values() const noexcept;
+
+        //- The list of enum names, in construction order. Same as names()
+        inline const List<word>& toc() const noexcept;
+
+        //- The sorted list of enum names.
+        inline List<word> sortedToc() const;
 
 
     // Modify
@@ -143,23 +148,24 @@ public:
         //  \return position in list or -1 if not found.
         inline label find(const EnumType e) const;
 
-        //- Test if there is an enumeration corresponding to the given name.
+        //- True if there is an enumeration corresponding to the given name.
         inline bool found(const word& enumName) const;
 
-        //- Test if there is a name corresponding to the given enumeration.
+        //- True if there is a name corresponding to the given enumeration.
         inline bool found(const EnumType e) const;
 
         //- The enumeration corresponding to the given name.
         //  FatalError if not found.
         EnumType get(const word& enumName) const;
 
+        //- The name corresponding to the given enumeration.
+        //  Return an empty word if there is no corresponding name for it.
+        inline const word& get(const EnumType e) const;
+
         //- The enumeration corresponding to the given name.
         //  \return The enumeration or default if not found.
-        EnumType get(const word& enumName, const EnumType deflt) const;
+        //  \note Method name compatibility with HashTable
-
+        EnumType lookup(const word& enumName, const EnumType deflt) const;
-        //- The name corresponding to the given enumeration.
-        //  Return an empty word if not found.
-        inline const word& get(const EnumType e) const;
 
 
     // Read
@@ -241,26 +247,59 @@ public:
 
         //- Return the enumeration corresponding to the given name
         //  FatalError if the name is not found.
-        //  Identical to single parameter get()
+        //  Identical to get()
         inline EnumType operator[](const word& enumName) const;
 
         //- Return the first name corresponding to the given enumeration,
         //- or an empty word on failure.
-        //  Identical to single parameter get()
+        //  Identical to get()
         inline const word& operator[](const EnumType e) const;
 
-        //- Return the first name corresponding to the given enumeration,
-        //- or an empty word on failure.
-        //  Identical to single parameter get()
-        inline const word& operator()(const EnumType e) const;
 
-        //- Return the enumeration corresponding to the given name,
+    // Iteration
-        //- or deflt if the name is not found.
+
-        inline EnumType operator()
+        //- A const_iterator for iterating an Enum list
+        //  \note The iterator dereference returns the \b key
+        class const_iterator
+        {
+            //- The list being iterated
+            const Enum* ptr_;
+
+            //- Index in the list
+            label idx_;
+
+        public:
+
+            //- Default construct, construct at given position
+            inline explicit const_iterator
             (
-            const word& enumName,
+                const Enum* eptr = nullptr,
-            const EnumType deflt
+                const label idx = 0
-        ) const;
+            ) noexcept;
+
+            //- The name at the current index
+            inline const word& key() const;
+
+            //- Enumeration value at the current index
+            inline EnumType val() const;
+
+            //- De-referencing returns the name (key)
+            //  This is similar to HashSet (not HashTable!) and allows
+            //  convenient output and traversing of the names
+            const word& operator*() const { return key(); }
+
+            //- Move to the next index
+            inline const_iterator& operator++() noexcept;
+
+            inline bool operator==(const const_iterator& iter) const noexcept;
+            inline bool operator!=(const const_iterator& iter) const noexcept;
+        };
+
+        inline const_iterator cbegin() const;
+        inline const_iterator cend() const;
+
+        const_iterator begin() const { return cbegin(); }
+        const_iterator end() const { return cend(); }
 
 
     // Housekeeping
@@ -281,7 +320,32 @@ public:
             return getOrDefault(key, dict, deflt, failsafe);
         }
 
-        //- Deprecated(2018-10) same as two-parameter get()
+
+        //- Deprecated(2020-11) use get() method
+        //  \deprecated(2020-11) - use get() method
+        FOAM_DEPRECATED_FOR(2020-11, "get() method")
+        const word& operator()(const EnumType e) const
+        {
+            return get(e);
+        }
+
+        //- Deprecated(2020-11) use two-parameter lookup() method
+        //  \deprecated(2020-11) - use two-parameter lookup() method
+        FOAM_DEPRECATED_FOR(2020-11, "lookup() method")
+        EnumType operator()(const word& key, const EnumType deflt) const
+        {
+            return lookup(key, deflt);
+        }
+
+        //- Deprecated(2020-11) use two-parameter lookup() method
+        //  \deprecated(2020-11) - use two-parameter lookup() method
+        FOAM_DEPRECATED_FOR(2020-11, "lookup() method")
+        EnumType get(const word& key, const EnumType deflt) const
+        {
+            return lookup(key, deflt);
+        }
+
+        //- Deprecated(2018-10) same as two-parameter get() method
         //  \deprecated(2018-10) - use two-parameter get() method
         FOAM_DEPRECATED_FOR(2018-10, "get() method")
         EnumType lookup(const word& key, const dictionary& dict) const

src/OpenFOAM/primitives/enums/EnumI.H

@@ -42,26 +42,41 @@ inline Foam::label Foam::Enum<EnumType>::size() const noexcept
 
 
 template<class EnumType>
-inline const Foam::wordList& Foam::Enum<EnumType>::names() const
+inline const Foam::List<Foam::word>&
+Foam::Enum<EnumType>::names() const noexcept
 {
     return keys_;
 }
 
 
 template<class EnumType>
-inline const Foam::wordList& Foam::Enum<EnumType>::toc() const
+inline const Foam::List<int>&
-{
+Foam::Enum<EnumType>::values() const noexcept
-    return keys_;
-}
-
-
-template<class EnumType>
-inline const Foam::List<int>& Foam::Enum<EnumType>::values() const
 {
     return vals_;
 }
 
 
+template<class EnumType>
+inline const Foam::List<Foam::word>&
+Foam::Enum<EnumType>::toc() const noexcept
+{
+    return keys_;
+}
+
+
+template<class EnumType>
+inline Foam::List<Foam::word>
+Foam::Enum<EnumType>::sortedToc() const
+{
+    List<word> list(keys_);
+
+    Foam::sort(list);
+
+    return list;
+}
+
+
 template<class EnumType>
 inline void Foam::Enum<EnumType>::clear()
 {
@@ -155,6 +170,80 @@ inline OS& Foam::Enum<EnumType>::writeList(OS& os, const label) const
 }
 
 
+// * * * * * * * * * * * * * * * * Iterators * * * * * * * * * * * * * * * * //
+
+template<class EnumType>
+inline Foam::Enum<EnumType>::const_iterator::const_iterator
+(
+    const Enum* eptr,
+    const label idx
+) noexcept
+:
+    ptr_(eptr),
+    idx_(idx)
+{}
+
+
+template<class EnumType>
+inline const Foam::word&
+Foam::Enum<EnumType>::const_iterator::key() const
+{
+    return ptr_->names()[idx_];
+}
+
+
+template<class EnumType>
+inline EnumType Foam::Enum<EnumType>::const_iterator::val() const
+{
+    return EnumType(ptr_->values()[idx_]);
+}
+
+
+template<class EnumType>
+inline typename Foam::Enum<EnumType>::const_iterator&
+Foam::Enum<EnumType>::const_iterator::operator++() noexcept
+{
+    ++idx_;
+    return *this;
+}
+
+
+template<class EnumType>
+inline bool Foam::Enum<EnumType>::const_iterator::operator==
+(
+    const const_iterator& iter
+) const noexcept
+{
+    return idx_ == iter.idx_;
+}
+
+
+template<class EnumType>
+inline bool Foam::Enum<EnumType>::const_iterator::operator!=
+(
+    const const_iterator& iter
+) const noexcept
+{
+    return idx_ != iter.idx_;
+}
+
+
+template<class EnumType>
+inline typename Foam::Enum<EnumType>::const_iterator
+Foam::Enum<EnumType>::cbegin() const
+{
+    return typename Enum<EnumType>::const_iterator(this);
+}
+
+
+template<class EnumType>
+inline typename Foam::Enum<EnumType>::const_iterator
+Foam::Enum<EnumType>::cend() const
+{
+    return typename Enum<EnumType>::const_iterator(this, this->size());
+}
+
+
 // * * * * * * * * * * * * * * * Member Operators  * * * * * * * * * * * * * //
 
 template<class EnumType>
@@ -177,34 +266,6 @@ inline const Foam::word& Foam::Enum<EnumType>::operator[]
 }
 
 
-template<class EnumType>
-inline const Foam::word& Foam::Enum<EnumType>::operator()
-(
-    const EnumType e
-) const
-{
-    return get(e);
-}
-
-
-template<class EnumType>
-inline EnumType Foam::Enum<EnumType>::operator()
-(
-    const word& enumName,
-    const EnumType deflt
-) const
-{
-    const label idx = find(enumName);
-
-    if (idx >= 0)
-    {
-        return EnumType(vals_[idx]);
-    }
-
-    return deflt;
-}
-
-
 // * * * * * * * * * * * * * * * IOstream Operators  * * * * * * * * * * * * //
 
 template<class EnumType>

src/finiteVolume/expressions/patch/patchExprScanner.cc

@@ -258,7 +258,7 @@ static int driverTokenType
     {
         const word fieldType(driver_.getFieldClassName(ident));
 
-        int tokType = fieldTokenEnums().get(fieldType, -1);
+        int tokType = fieldTokenEnums().lookup(fieldType, -1);
 
         if (tokType > 0)
         {
@@ -328,7 +328,7 @@ bool Foam::expressions::patchExpr::scanner::dispatch_method
         << "Method:" << ident
         << " at " << driver_.parsePosition() << nl;
 
-    const int methType = fieldMethodEnums.get(ident, -1);
+    const int methType = fieldMethodEnums.lookup(ident, -1);
 
     if (methType > 0)
     {
@@ -367,7 +367,7 @@ bool Foam::expressions::patchExpr::scanner::dispatch_ident
     else
     {
         // Check for function name
-        tokType = funcTokenEnums.get(ident, -1);
+        tokType = funcTokenEnums.lookup(ident, -1);
 
         if (tokType > 0)
         {
@@ -381,7 +381,7 @@ bool Foam::expressions::patchExpr::scanner::dispatch_ident
 
         #ifdef HAS_LOOKBEHIND_TOKENS
         // Specials such "cset" also reset the look-behind
-        tokType = lookBehindTokenEnums.get(ident, -1);
+        tokType = lookBehindTokenEnums.lookup(ident, -1);
 
         if (tokType > 0)
         {
@@ -423,7 +423,7 @@ bool Foam::expressions::patchExpr::scanner::dispatch_ident
     (
         quoted || dot == std::string::npos
       ? -1
-      : fieldMethodEnums.get(ident.substr(dot+1), -1)
+      : fieldMethodEnums.lookup(ident.substr(dot+1), -1)
     );
 
     if

src/finiteVolume/expressions/patch/patchExprScanner.rl

@@ -256,7 +256,7 @@ static int driverTokenType
     {
         const word fieldType(driver_.getFieldClassName(ident));
 
-        int tokType = fieldTokenEnums().get(fieldType, -1);
+        int tokType = fieldTokenEnums().lookup(fieldType, -1);
 
         if (tokType > 0)
         {
@@ -459,7 +459,7 @@ bool Foam::expressions::patchExpr::scanner::dispatch_method
         << "Method:" << ident
         << " at " << driver_.parsePosition() << nl;
 
-    const int methType = fieldMethodEnums.get(ident, -1);
+    const int methType = fieldMethodEnums.lookup(ident, -1);
 
     if (methType > 0)
     {
@@ -498,7 +498,7 @@ bool Foam::expressions::patchExpr::scanner::dispatch_ident
     else
     {
         // Check for function name
-        tokType = funcTokenEnums.get(ident, -1);
+        tokType = funcTokenEnums.lookup(ident, -1);
 
         if (tokType > 0)
         {
@@ -512,7 +512,7 @@ bool Foam::expressions::patchExpr::scanner::dispatch_ident
 
         #ifdef HAS_LOOKBEHIND_TOKENS
         // Specials such "cset" also reset the look-behind
-        tokType = lookBehindTokenEnums.get(ident, -1);
+        tokType = lookBehindTokenEnums.lookup(ident, -1);
 
         if (tokType > 0)
         {
@@ -554,7 +554,7 @@ bool Foam::expressions::patchExpr::scanner::dispatch_ident
     (
         quoted || dot == std::string::npos
       ? -1
-      : fieldMethodEnums.get(ident.substr(dot+1), -1)
+      : fieldMethodEnums.lookup(ident.substr(dot+1), -1)
     );
 
     if

src/finiteVolume/expressions/volume/volumeExprScanner.cc

@@ -287,7 +287,7 @@ static int driverTokenType
     {
         const word fieldType(driver_.getFieldClassName(ident));
 
-        int tokType = fieldTokenEnums().get(fieldType, -1);
+        int tokType = fieldTokenEnums().lookup(fieldType, -1);
 
         if (tokType > 0)
         {
@@ -357,7 +357,7 @@ bool Foam::expressions::volumeExpr::scanner::dispatch_method
         << "Method:" << ident
         << " at " << driver_.parsePosition() << nl;
 
-    const int methType = fieldMethodEnums.get(ident, -1);
+    const int methType = fieldMethodEnums.lookup(ident, -1);
 
     if (methType > 0)
     {
@@ -396,7 +396,7 @@ bool Foam::expressions::volumeExpr::scanner::dispatch_ident
     else
     {
         // Check for function name
-        tokType = funcTokenEnums.get(ident, -1);
+        tokType = funcTokenEnums.lookup(ident, -1);
 
         if (tokType > 0)
         {
@@ -410,7 +410,7 @@ bool Foam::expressions::volumeExpr::scanner::dispatch_ident
 
         #ifdef HAS_LOOKBEHIND_TOKENS
         // Specials such "cset" also reset the look-behind
-        tokType = lookBehindTokenEnums.get(ident, -1);
+        tokType = lookBehindTokenEnums.lookup(ident, -1);
 
         if (tokType > 0)
         {
@@ -452,7 +452,7 @@ bool Foam::expressions::volumeExpr::scanner::dispatch_ident
     (
         quoted || dot == std::string::npos
       ? -1
-      : fieldMethodEnums.get(ident.substr(dot+1), -1)
+      : fieldMethodEnums.lookup(ident.substr(dot+1), -1)
     );
 
     if

src/finiteVolume/expressions/volume/volumeExprScanner.rl

@@ -285,7 +285,7 @@ static int driverTokenType
     {
         const word fieldType(driver_.getFieldClassName(ident));
 
-        int tokType = fieldTokenEnums().get(fieldType, -1);
+        int tokType = fieldTokenEnums().lookup(fieldType, -1);
 
         if (tokType > 0)
         {
@@ -488,7 +488,7 @@ bool Foam::expressions::volumeExpr::scanner::dispatch_method
         << "Method:" << ident
         << " at " << driver_.parsePosition() << nl;
 
-    const int methType = fieldMethodEnums.get(ident, -1);
+    const int methType = fieldMethodEnums.lookup(ident, -1);
 
     if (methType > 0)
     {
@@ -527,7 +527,7 @@ bool Foam::expressions::volumeExpr::scanner::dispatch_ident
     else
     {
         // Check for function name
-        tokType = funcTokenEnums.get(ident, -1);
+        tokType = funcTokenEnums.lookup(ident, -1);
 
         if (tokType > 0)
         {
@@ -541,7 +541,7 @@ bool Foam::expressions::volumeExpr::scanner::dispatch_ident
 
         #ifdef HAS_LOOKBEHIND_TOKENS
         // Specials such "cset" also reset the look-behind
-        tokType = lookBehindTokenEnums.get(ident, -1);
+        tokType = lookBehindTokenEnums.lookup(ident, -1);
 
         if (tokType > 0)
         {
@@ -583,7 +583,7 @@ bool Foam::expressions::volumeExpr::scanner::dispatch_ident
     (
         quoted || dot == std::string::npos
       ? -1
-      : fieldMethodEnums.get(ident.substr(dot+1), -1)
+      : fieldMethodEnums.lookup(ident.substr(dot+1), -1)
     );
 
     if

src/functionObjects/field/derivedFields/derivedFields.C

@@ -202,7 +202,7 @@ bool Foam::functionObjects::derivedFields::read(const dictionary& dict)
 
     for (const word& key : derivedNames)
     {
-        derivedTypes_[ngood] = knownNames.get(key, derivedType::UNKNOWN);
+        derivedTypes_[ngood] = knownNames.lookup(key, derivedType::UNKNOWN);
 
         switch (derivedTypes_[ngood])
         {

src/functionObjects/utilities/abort/abort.C

@@ -80,7 +80,7 @@ static enum Time::stopAtControls getStopAction(const std::string& filename)
         const word actionName(word::validate(fileContent.substr(equals+1)));
 
         return
-            Time::stopAtControlNames
+            Time::stopAtControlNames.lookup
             (
                 actionName,
                 Time::stopAtControls::saUnknown

src/meshTools/coupling/externalFileCoupler.C

@@ -77,7 +77,7 @@ static enum Time::stopAtControls getStopAction(const std::string& filename)
         const word actionName(word::validate(fileContent.substr(equals+1)));
 
         return
-            Time::stopAtControlNames
+            Time::stopAtControlNames.lookup
             (
                 actionName,
                 Time::stopAtControls::saUnknown