ENH: additional IndirectList static methods

- uniq() : creates an IndirectList with duplicated entries
  filtered out

- subset() : creates an IndirectList with positions that satisfy
  a condition predicate.

- subset_if() : creates an IndirectList with values that satisfy a
  given predicate.

  An indirect subset will be cheaper than creating a subset copy
  of the original data, and also allows modification.

STYLE: combine UIndirectList.H into UIndirectList.H (reduce file clutter)

applications/test/ListOps/Test-ListOps.C

@@ -151,6 +151,10 @@ int main(int argc, char *argv[])
         << subsetList(test6, evenNonZero) << nl
         << endl;
 
+    Info<< "Subset of non-zero, even values: "
+        << IndirectList<label>::subset_if(test6, evenNonZero) << nl
+        << endl;
+
     test6.append(identity(13, 12));
 
     Info<< "Randomized: " << flatOutput(test6) << endl;

applications/test/UIndirectList/Test-UIndirectList.C

@@ -27,7 +27,7 @@ Description
 
 \*---------------------------------------------------------------------------*/
 
-#include "UIndirectList.H"
+#include "IndirectList.H"
 #include "DynamicList.H"
 #include "IOstreams.H"
 #include "ListOps.H"

applications/test/minMax1/Test-minMax1.C

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2019 OpenCFD Ltd.
+    Copyright (C) 2019-2022 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -190,6 +190,8 @@ int main(int argc, char *argv[])
             << nl;
 
         Info<< "Subset = " << subsetList(values1, limiter) << nl;
+        Info<< "Subset = "
+            << IndirectList<scalar>::subset_if(values1, limiter) << nl;
 
         Info<< nl << "test clip() with limiter: " << limiter << nl;
         for (const scalar& val : values1)

applications/test/sort/Test-sortList.C

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011 OpenFOAM Foundation
-    Copyright (C) 2017-2019 OpenCFD Ltd.
+    Copyright (C) 2017-2022 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,7 +28,9 @@ Description
 
 \*---------------------------------------------------------------------------*/
 
+#include "SortList.H"
 #include "SortableList.H"
+#include "IndirectList.H"
 #include "ListOps.H"
 #include "HashSet.H"
 #include "stringOps.H"
@@ -49,6 +51,18 @@ void printInfo(const SortableList<T>& list)
 
 int main(int argc, char *argv[])
 {
+    {
+        const labelList orig({7, 9, 7, 12, 9, 1, 12, 2, 4, 7, 4, 0});
+
+        Info<< "original list: " << flatOutput(orig) << endl;
+
+        auto unique = IndirectList<label>::uniq(orig);
+
+        Info<< "unique  list: " << flatOutput(unique) << endl;
+        Info<< "unique  idx : " << flatOutput(unique.addressing()) << endl;
+    }
+
+
     const labelList orig({7, 9, 1, 2, 4, 7, 4, 0});
 
     labelList order;

src/OpenFOAM/containers/IndirectLists/IndirectList/IndirectList.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011-2016 OpenFOAM Foundation
-    Copyright (C) 2017-2019 OpenCFD Ltd.
+    Copyright (C) 2017-2022 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -33,22 +33,82 @@ Description
 See also
     Foam::UIndirectList for a version without addressing allocation.
 
+Class
+    Foam::UIndirectList
+
+Description
+    A List with indirect addressing.
+    Like IndirectList but does not store addressing
+
+    Note the const_cast of the list values. This is so we can use it both
+    on const and non-const lists. Alternative would be to have a const_
+    variant etc.
+
 SourceFiles
     IndirectListI.H
 
 \*---------------------------------------------------------------------------*/
 
-#ifndef IndirectList_H
+#ifndef Foam_IndirectList_H
-#define IndirectList_H
+#define Foam_IndirectList_H
 
+#include "List.H"
+#include "IndirectListBase.H"
 #include "IndirectListAddressing.H"
-#include "UIndirectList.H"
 
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
 namespace Foam
 {
 
+// Forward Declarations
+template<class T> class IndirectList;
+template<class T> class UIndirectList;
+
+// Common list types
+typedef UIndirectList<bool> boolUIndList;       //!< UIndirectList of bools
+typedef UIndirectList<label> labelUIndList;     //!< UIndirectList of labels
+
+
+/*---------------------------------------------------------------------------*\
+                        Class UIndirectList Declaration
+\*---------------------------------------------------------------------------*/
+
+template<class T>
+class UIndirectList
+:
+    public IndirectListBase<T, labelUList>
+{
+public:
+
+    // Constructors
+
+        //- Shallow copy values and addressing
+        UIndirectList(const UList<T>& values, const labelUList& addr)
+        :
+            IndirectListBase<T, labelUList>(values, addr)
+        {}
+
+        //- Copy construct (shallow copy values and addressing)
+        UIndirectList(const UIndirectList<T>& list)
+        :
+            UIndirectList<T>(list.values(), list.addressing())
+        {}
+
+
+    // Member Operators
+
+        //- Use standard assignment operations
+        using IndirectListBase<T, labelUList>::operator=;
+
+        //- Deep copy values, Fatal if list sizes are not identical
+        void operator=(const UIndirectList<T>& rhs)
+        {
+            this->copyList(rhs);
+        }
+};
+
+
 /*---------------------------------------------------------------------------*\
                         Class IndirectList Declaration
 \*---------------------------------------------------------------------------*/
@@ -82,6 +142,53 @@ public:
         inline explicit IndirectList(const UIndirectList<T>& list);
 
 
+    // Static Functions
+
+        //- Return an IndirectList comprising entries with \em positions
+        //- that satisfy the condition predicate.
+        //
+        //  The condition predicate can be considered a type of \em mask
+        //  for any given position.
+        //  A boolList, bitSet, labelRange or labelHashSet all satisfy
+        //  the requirements for use as position condition predicates.
+        //
+        //  \param values  The source list values
+        //  \param select  Accept/reject predicate based on \em position.
+        //  \param invert  Invert (negate) the selection logic
+        template<class UnaryCondition>
+        static IndirectList<T> subset
+        (
+            const UList<T>& values,
+            const UnaryCondition& select,
+            const bool invert = false
+        );
+
+        //- Return an IndirectList comprising entries with \em values
+        //- that satisfy the predicate.
+        //
+        //  \param values  The source list values
+        //  \param pred    Predicate used to test the \em value
+        //  \param invert  Invert (negate) the selection logic
+        template<class UnaryPredicate>
+        static IndirectList<T> subset_if
+        (
+            const UList<T>& values,
+            const UnaryPredicate& pred,
+            const bool invert = false
+        );
+
+        //- Return an IndirectList with duplicate entries filtered out.
+        //  Preserves the original input order, unless sorted = true
+        //
+        //  \param values  The source list values
+        //  \param sorted  Retain sorted order instead of original order
+        static IndirectList<T> uniq
+        (
+            const UList<T>& values,
+            const bool sorted = false
+        );
+
+
     // Member Functions
 
         //- The list addressing

src/OpenFOAM/containers/IndirectLists/IndirectList/IndirectListI.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011-2016 OpenFOAM Foundation
-    Copyright (C) 2019-2020 OpenCFD Ltd.
+    Copyright (C) 2019-2022 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -115,4 +115,111 @@ inline Foam::IndirectList<T>::IndirectList(const UIndirectList<T>& list)
 {}
 
 
+// * * * * * * * * * * * * * Static Member Functions * * * * * * * * * * * * //
+
+template<class T>
+template<class UnaryCondition>
+Foam::IndirectList<T> Foam::IndirectList<T>::subset
+(
+    const UList<T>& values,
+    const UnaryCondition& select,
+    const bool invert
+)
+{
+    const label len = values.size();
+
+    IndirectList<T> result(values, Foam::zero{});
+    labelList& addr = result.addressing();
+
+    addr.resize_nocopy(len);
+
+    label count = 0;
+    for (label i=0; i < len; ++i)
+    {
+        // Test on position
+        if (select(i) ? !invert : invert)
+        {
+            addr[count] = i;
+            ++count;
+        }
+    }
+    addr.resize(count);
+
+    return result;
+}
+
+
+template<class T>
+template<class UnaryPredicate>
+Foam::IndirectList<T> Foam::IndirectList<T>::subset_if
+(
+    const UList<T>& values,
+    const UnaryPredicate& pred,
+    const bool invert
+)
+{
+    const label len = values.size();
+
+    IndirectList<T> result(values, Foam::zero{});
+    labelList& addr = result.addressing();
+
+    addr.resize_nocopy(len);
+
+    label count = 0;
+    for (label i=0; i < len; ++i)
+    {
+        // Test on value
+        if (pred(values[i]) ? !invert : invert)
+        {
+            addr[count] = i;
+            ++count;
+        }
+    }
+    addr.resize(count);
+
+    return result;
+}
+
+
+template<class T>
+Foam::IndirectList<T> Foam::IndirectList<T>::uniq
+(
+    const UList<T>& values,
+    const bool sorted
+)
+{
+    const label len = values.size();
+
+    IndirectList<T> result(values, Foam::zero{});
+    labelList& order = result.addressing();
+
+    // Start from sorted order
+    Foam::sortedOrder(values, order);
+
+    if (len > 1)
+    {
+        label count = 0;
+        for (label i = 1; i < len; ++i)
+        {
+            // Eliminate duplicates
+            if (values[order[count]] != values[order[i]])
+            {
+                ++count;
+                order[count] = order[i];
+            }
+        }
+        ++count;
+        order.resize(count);
+
+        // Recover the original input order
+        if (!sorted)
+        {
+            Foam::sort(order);
+        }
+    }
+
+    return result;
+}
+
+
 // ************************************************************************* //

src/OpenFOAM/containers/IndirectLists/IndirectList/UIndirectList.H

@@ -0,0 +1,16 @@
+/*---------------------------------------------------------------------------*\
+Description
+    Compatibility include
+
+    UIndirectList.H combined into IndirectList.H (MAY-2022)
+
+\*---------------------------------------------------------------------------*/
+
+#ifndef Foam_UIndirectList_H
+#define Foam_UIndirectList_H
+
+#include "IndirectList.H"
+
+#endif
+
+// ************************************************************************* //

src/OpenFOAM/containers/IndirectLists/IndirectListBase/IndirectListAddressing.H

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2017-2021 OpenCFD Ltd.
+    Copyright (C) 2017-2022 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -33,8 +33,10 @@ Description
 
 \*---------------------------------------------------------------------------*/
 
-#ifndef IndirectListAddressing_H
+#ifndef Foam_IndirectListAddressing_H
-#define IndirectListAddressing_H
+#define Foam_IndirectListAddressing_H
+
+#include <utility>   // std::move
 
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 

src/OpenFOAM/containers/IndirectLists/UIndirectList/UIndirectList.H

@@ -1,108 +0,0 @@
-/*---------------------------------------------------------------------------*\
-  =========                 |
-  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
-   \\    /   O peration     |
-    \\  /    A nd           | www.openfoam.com
-     \\/     M anipulation  |
--------------------------------------------------------------------------------
-    Copyright (C) 2011-2016 OpenFOAM Foundation
-    Copyright (C) 2017-2019 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/>.
-
-Class
-    Foam::UIndirectList
-
-Description
-    A List with indirect addressing.
-
-    Like IndirectList but does not store addressing.
-
-    Note the const_cast of the list values. This is so we can use it both
-    on const and non-const lists. Alternative would be to have a const_
-    variant etc.
-
-SourceFiles
-
-\*---------------------------------------------------------------------------*/
-
-#ifndef UIndirectList_H
-#define UIndirectList_H
-
-#include "List.H"
-#include "IndirectListBase.H"
-
-// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
-
-namespace Foam
-{
-
-// Forward Declarations
-template<class T> class UIndirectList;
-
-// Common list types
-typedef UIndirectList<bool> boolUIndList;       //!< UIndirectList of bools
-typedef UIndirectList<label> labelUIndList;     //!< UIndirectList of labels
-
-/*---------------------------------------------------------------------------*\
-                        Class UIndirectList Declaration
-\*---------------------------------------------------------------------------*/
-
-template<class T>
-class UIndirectList
-:
-    public IndirectListBase<T, labelUList>
-{
-public:
-
-    // Constructors
-
-        //- Shallow copy values and addressing
-        UIndirectList(const UList<T>& values, const labelUList& addr)
-        :
-            IndirectListBase<T, labelUList>(values, addr)
-        {}
-
-        //- Copy construct (shallow copy values and addressing)
-        UIndirectList(const UIndirectList<T>& list)
-        :
-            UIndirectList<T>(list.values(), list.addressing())
-        {}
-
-
-    // Member Operators
-
-        //- Use standard assignment operations
-        using IndirectListBase<T, labelUList>::operator=;
-
-        //- Deep copy values, Fatal if list sizes are not identical
-        void operator=(const UIndirectList<T>& rhs)
-        {
-            this->copyList(rhs);
-        }
-};
-
-
-// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
-
-} // End namespace Foam
-
-// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
-
-#endif
-
-// ************************************************************************* //

src/OpenFOAM/containers/Lists/ListOps/ListOps.H

@@ -246,6 +246,7 @@ void inplaceUniqueSort
 //  \endcode
 //
 //  \return The subsetted list
+//  \see IndirectList::subset
 template<class BoolListType, class T>
 List<T> subset
 (
@@ -261,6 +262,7 @@ List<T> subset
 //  \param[in] invert set as true to invert the selection logic
 //
 //  \return The subsetted list
+//  \see IndirectList::subset
 template<class T>
 List<T> subset
 (
@@ -306,6 +308,9 @@ void inplaceSubset
 //  \param[in] input the list input values.
 //  \param[in] pred the selection predicate
 //  \param[in] invert set as true to invert the selection logic
+//
+//  \return The subsetted list
+//  \see IndirectList::subset_if
 template<class T, class UnaryPredicate>
 List<T> subsetList
 (

src/OpenFOAM/meshes/meshShapes/cell/cellIndList.H

@@ -37,13 +37,12 @@ Description
 
 \*---------------------------------------------------------------------------*/
 
-#ifndef cellIndList_H
+#ifndef Foam_cellIndList_H
-#define cellIndList_H
+#define Foam_cellIndList_H
 
 // Include all normal list typedefs as well
 #include "cellList.H"
 #include "IndirectList.H"
-#include "UIndirectList.H"
 
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 

src/OpenFOAM/meshes/meshShapes/cellShape/cellShapeI.H

@@ -29,7 +29,7 @@ License
 #include "Istream.H"
 #include "cell.H"
 #include "cellModel.H"
-#include "UIndirectList.H"
+#include "IndirectList.H"
 
 // * * * * * * * * * * * * * * * * Constructors  * * * * * * * * * * * * * * //
 

src/OpenFOAM/meshes/meshShapes/edge/edgeIndList.H

@@ -37,13 +37,12 @@ Description
 
 \*---------------------------------------------------------------------------*/
 
-#ifndef edgeIndList_H
+#ifndef Foam_edgeIndList_H
-#define edgeIndList_H
+#define Foam_edgeIndList_H
 
 // Include all normal list typedefs as well
 #include "edgeList.H"
 #include "IndirectList.H"
-#include "UIndirectList.H"
 
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 

src/OpenFOAM/meshes/meshShapes/face/faceIndList.H

@@ -37,13 +37,12 @@ Description
 
 \*---------------------------------------------------------------------------*/
 
-#ifndef faceIndList_H
+#ifndef Foam_faceIndList_H
-#define faceIndList_H
+#define Foam_faceIndList_H
 
 // Include all normal list typedefs as well
 #include "faceList.H"
 #include "IndirectList.H"
-#include "UIndirectList.H"
 
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 

src/OpenFOAM/meshes/primitiveShapes/point/pointIndList.H

@@ -37,13 +37,12 @@ Description
 
 \*---------------------------------------------------------------------------*/
 
-#ifndef pointIndList_H
+#ifndef Foam_pointIndList_H
-#define pointIndList_H
+#define Foam_pointIndList_H
 
 // Include all normal list typedefs as well
 #include "pointList.H"
 #include "IndirectList.H"
-#include "UIndirectList.H"
 
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 

src/OpenFOAM/primitives/Scalar/lists/scalarIndList.H

@@ -37,13 +37,12 @@ Description
 
 \*---------------------------------------------------------------------------*/
 
-#ifndef scalarIndList_H
+#ifndef Foam_scalarIndList_H
-#define scalarIndList_H
+#define Foam_scalarIndList_H
 
 // Include all normal list typedefs as well
 #include "scalarList.H"
 #include "IndirectList.H"
-#include "UIndirectList.H"
 
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 

src/OpenFOAM/primitives/Vector/lists/vectorIndList.H

@@ -37,13 +37,12 @@ Description
 
 \*---------------------------------------------------------------------------*/
 
-#ifndef vectorIndList_H
+#ifndef Foam_vectorIndList_H
-#define vectorIndList_H
+#define Foam_vectorIndList_H
 
 // Include all normal list typedefs as well
 #include "vectorList.H"
 #include "IndirectList.H"
-#include "UIndirectList.H"
 
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 

src/OpenFOAM/primitives/ints/lists/labelIndList.H

@@ -43,14 +43,13 @@ Description
 // Include all normal list typedefs as well
 #include "labelList.H"
 #include "IndirectList.H"
-#include "UIndirectList.H"
 
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
 namespace Foam
 {
-    // NB: labelUIndList is defined in UIndirectList itself
     typedef IndirectList<label>  labelIndList;
+    // labelUIndList is defined in UIndirectList itself
 }
 
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //

src/OpenFOAM/primitives/strings/lists/stringListOps.H

@@ -70,6 +70,7 @@ namespace Foam
     //  \endcode
     //
     //  \return List indices for matching strings
+    //  \see IndirectList::subset_if
     template<class UnaryMatchPredicate, class StringType>
     labelList findMatchingStrings
     (
@@ -161,6 +162,7 @@ namespace Foam
     //  \code
     //    subsetMatchingStrings<regExp, stringList>(myRegExp, list);
     //  \endcode
+    //  \see IndirectList::subset_if
     template<class UnaryMatchPredicate, class StringListType>
     StringListType subsetMatchingStrings
     (
@@ -326,8 +328,6 @@ namespace Foam
     }
 
 
-
-
 /*---------------------------------------------------------------------------*\
                       Namespace stringListOps Declaration
 \*---------------------------------------------------------------------------*/

src/finiteArea/faMatrices/faMatrix/faMatrix.C

@@ -30,7 +30,7 @@ License
 #include "edgeFields.H"
 #include "calculatedFaPatchFields.H"
 #include "zeroGradientFaPatchFields.H"
-#include "UIndirectList.H"
+#include "IndirectList.H"
 #include "UniformList.H"
 #include "demandDrivenData.H"
 

src/finiteArea/faMesh/faMeshBoundaryHaloTemplates.C

@@ -26,7 +26,7 @@ License
 \*---------------------------------------------------------------------------*/
 
 #include "faMeshBoundaryHalo.H"
-#include "UIndirectList.H"
+#include "IndirectList.H"
 #include "Pstream.H"
 
 // * * * * * * * * * * * * * * * Member Functions  * * * * * * * * * * * * * //

src/finiteVolume/fields/fvPatchFields/derived/mappedFixedInternalValue/mappedFixedInternalValueFvPatchField.C

@@ -26,7 +26,7 @@ License
 \*---------------------------------------------------------------------------*/
 
 #include "mappedFixedInternalValueFvPatchField.H"
-#include "UIndirectList.H"
+#include "IndirectList.H"
 
 // * * * * * * * * * * * * * * * * Constructors  * * * * * * * * * * * * * * //
 

src/finiteVolume/fields/fvPatchFields/derived/mappedFixedPushedInternalValue/mappedFixedPushedInternalValueFvPatchField.C

@@ -26,7 +26,7 @@ License
 \*---------------------------------------------------------------------------*/
 
 #include "mappedFixedPushedInternalValueFvPatchField.H"
-#include "UIndirectList.H"
+#include "IndirectList.H"
 
 // * * * * * * * * * * * * * * * * Constructors  * * * * * * * * * * * * * * //
 

src/finiteVolume/fvMatrices/fvMatrix/fvMatrix.C

@@ -31,7 +31,7 @@ License
 #include "calculatedFvPatchFields.H"
 #include "extrapolatedCalculatedFvPatchFields.H"
 #include "coupledFvPatchFields.H"
-#include "UIndirectList.H"
+#include "IndirectList.H"
 #include "UniformList.H"
 #include "demandDrivenData.H"
 

src/functionObjects/utilities/areaWrite/areaWrite.C

@@ -34,7 +34,7 @@ License
 #include "HashOps.H"
 #include "ListOps.H"
 #include "Time.H"
-#include "UIndirectList.H"
+#include "IndirectList.H"
 #include "addToRunTimeSelectionTable.H"
 
 // * * * * * * * * * * * * * * Static Data Members * * * * * * * * * * * * * //

src/sampling/sampledSet/sampledSets/sampledSets.C

@@ -34,7 +34,7 @@ License
 #include "mapPolyMesh.H"
 #include "IOmanip.H"
 #include "IOobjectList.H"
-#include "UIndirectList.H"
+#include "IndirectList.H"
 #include "ListOps.H"
 #include "addToRunTimeSelectionTable.H"
 

src/sampling/sampledSurface/sampledSurfaces/sampledSurfaces.C

@@ -35,7 +35,7 @@ License
 #include "HashOps.H"
 #include "ListOps.H"
 #include "Time.H"
-#include "UIndirectList.H"
+#include "IndirectList.H"
 #include "addToRunTimeSelectionTable.H"
 
 // * * * * * * * * * * * * * * Static Data Members * * * * * * * * * * * * * //