MinMax.H

Go to the documentation of this file.

/*---------------------------------------------------------------------------*\
  =========                 |
  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
   \\    /   O peration     |
    \\  /    A nd           | www.openfoam.com
     \\/     M anipulation  |
-------------------------------------------------------------------------------
    Copyright (C) 2019-2025 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::MinMax

Description
    A min/max value pair with additional methods.
    In addition to conveniently storing values, it can be used for logic
    operations or to modify data. A few global functions and functors are
    also provided.

    Examples of use.

    Determine min/max limits from a List of values:
    \verbatim
    List<scalar> values = ...;

    // on construction
    MinMax<scalar> range(values);

    range.reset();

    range += val;

    // global minMax() function
    Info<< minMax(values) << nl;
    \endverbatim

    General comparison operations
    \verbatim
    scalar val;
    if (val < range) ... value is below range min
    if (range.contains(val)) ... value within range
    if (range.compare(val) > 0) ... value is above range max
    if (range(val)) ... value within range - as predicate
    \endverbatim

    Since the range has a predicate form, it can be used as a filter method.
    For example,
    \verbatim
    Info<< "values in range: " << subsetList(values, range) << nl;

    boolList mask = ListOps::create<bool>(values, range);
    Info<< "values values in range " << mask << nl;
    \endverbatim

    One advantage offered by MinMax is to clamp or limit values
    to a particular range. For example,
    \verbatim
    scalarMinMax range(lower, upper);

    scalar val;
    val = range.clamp(val)    .. return clamped values

    // vs.
    val = min(max(value, lower), upper)
    \endverbatim

\*---------------------------------------------------------------------------*/

#ifndef Foam_MinMax_H
#define Foam_MinMax_H

#include "scalar.H"
#include "zero.H"
#include "Pair.H"
#include "Tuple2.H"
#include "VectorSpace.H"
#include <type_traits>

// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //

namespace Foam
{

// Forward Declarations
template<class T> class MinMax;

// Common min/max types
typedef MinMax<label> labelMinMax;      
typedef MinMax<scalar> scalarMinMax;    


/*---------------------------------------------------------------------------*\
                         Class MinMax Declaration
\*---------------------------------------------------------------------------*/

template<class T>
class MinMax
{
    // Private Data

        //- Min value
        T min_;

        //- Max value
        T max_;

public:

    // Typedefs

        //- The value type the MinMax represents
        typedef T value_type;

        //- Component type
        typedef typename pTraits<T>::cmptType cmptType;


    // Constructors

        //- Default construct: an inverted range
        inline MinMax();

        //- Construct from min/max limits
        inline MinMax(const T& minVal, const T& maxVal);

        //- Implicit construct from min/max limits
        inline MinMax(const std::pair<T,T>& range);

        //- Implicit construct from min/max limits
        inline MinMax(const Pair<T>& range);

        //- Implicit construct from min/max limits
        inline MinMax(const Tuple2<T,T>& range);

        //- Construct with a single zero value
        inline explicit MinMax(Foam::zero);

        //- Implicit construct from zero_one as 0-1 range (pTraits zero, one)
        inline MinMax(Foam::zero_one);

        //- Construct with a single initial value
        inline explicit MinMax(const T& val);

        //- Construct from list of values
        inline explicit MinMax(const UList<T>& vals);


    // Static Member Functions

        //- A semi-infinite range from minVal to the type max
        inline static MinMax<T> ge(const T& minVal);

        //- A semi-infinite range from type min to maxVal
        inline static MinMax<T> le(const T& maxVal);

        //- A 0-1 range corresponding to the pTraits zero, one
        inline static MinMax<T> zero_one();


    // Member Functions

    // Access

        //- The min value
        const T& min() const noexcept { return min_; }

        //- The min value
        T& min() noexcept { return min_; }

        //- The max value
        const T& max() const noexcept { return max_; }

        //- The max value
        T& max() noexcept { return max_; }

        //- The min/max average value
        inline T centre() const;

        //- The min to max span. Zero for invalid range.
        inline T span() const;

        //- The magnitude of the min to max span. Zero for invalid range.
        inline scalar mag() const;

        //- Range is empty if it is inverted
        inline bool empty() const;

        //- Range is non-inverted
        inline bool good() const;

        //- Reset to an inverted (invalid) range
        inline void reset();

        //- Reset min/max to be identical to the specified value
        inline void reset(const T& val);

        //- Reset min/max to specified values
        inline void reset(const T& minVal, const T& maxVal);

        //- Same as reset() - reset to an inverted (invalid) range
        void clear() { reset(); }


    // Testing / Query

        //- Test if the ranges intersect (exclusive check)
        inline bool intersects(const MinMax<T>& b) const;

        //- Test if ranges overlap/touch (inclusive check)
        inline bool overlaps(const MinMax<T>& b) const;

        //- Compares the min/max range with the specified value.
        //  \return
        //  -  0: value is within the range, or range is invalid
        //  - -1: range (max) is less than the value
        //  - +1: range (min) is greater than value
        inline int compare(const T& val) const;

        //- True if the value is within the range (inclusive check)
        inline bool contains(const T& val) const;

        //- Return value clamped component-wise.
        //  If the range is invalid, just returns the value.
        inline T clamp(const T& val) const;


    // Manipulate

        //- Extend the range to include the other min/max range
        inline MinMax<T>& add(const MinMax& other);

        //- Include the value into the range
        inline MinMax<T>& add(const T& val);

        //- Include the values into the range
        inline MinMax<T>& add(const UList<T>& vals);

        //- Include two or more values into the range.
        //  All values must be similar types
        template<class... Args>
        inline MinMax<T>& add(const T& val0, const T& val1, Args&&... values);


    // Member Operators

        //- Identical to contains(), for use as a predicate.
        inline bool operator()(const T& val) const;

        //- Restrict min/max range to union with other range
        inline MinMax<T>& operator&=(const MinMax<T>& b);

        //- Extend min/max range to include other range
        //  Can be used in a reduction operation.
        inline MinMax<T>& operator+=(const MinMax<T>& b);

        //- Extend min/max range to include value
        inline MinMax<T>& operator+=(const T& val);

        //- Extend min/max range to include all values
        inline MinMax<T>& operator+=(const UList<T>& vals);

        //- Multiply range by scalar factor
        inline MinMax<T>& operator*=(scalar s);

        //- Divide range by scalar factor
        inline MinMax<T>& operator/=(scalar s);


    // Housekeeping

        //- Range is non-inverted. Same as good (2022-10)
        bool valid() const { return good(); }

        //- Old method name. Same as clamp (2023-01)
        T clip(const T& val) const { return this->clamp(val); }
};


// * * * * * * * * * * * * * * * * * Traits  * * * * * * * * * * * * * * * * //

//- Declare MinMax as non-contiguous (similar to Tuple2).
//  Output remains separate (even in binary) and, since the defined
//  \c operator+ is somewhat non-standard, also avoid false matching with
//  any MPI intrinsic operation.
template<class T>
struct is_contiguous<MinMax<T>> : std::false_type {};


// * * * * * * * * * * * * * * * Global Functions  * * * * * * * * * * * * * //

//- Min/max range as a string
template<class T>
word name(const MinMax<T>& range)
{
    return '(' + Foam::name(range.min()) + ',' + Foam::name(range.max()) + ')';
}

// * * * * * * * * * * * * * * * IOstream Operators  * * * * * * * * * * * * //

//- Read min/max range as (min max) tuple from Istream
template<class T>
inline Istream& operator>>(Istream& is, MinMax<T>& range)
{
    is.readBegin("min.max");
    is >> range.min() >> range.max();
    is.readEnd("min.max");

    is.check(FUNCTION_NAME);
    return is;
}

//- Write min/max range as (min max) tuple to Ostream
template<class T>
inline Ostream& operator<<(Ostream& os, const MinMax<T>& range)
{
    os  << token::BEGIN_LIST
        << range.min() << token::SPACE << range.max()
        << token::END_LIST;
    return os;
}


// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //

} // End namespace Foam

// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //

#include "MinMaxI.H"

// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //

#endif

// Global Functions and Operators
#include "MinMaxOps.H"


// ************************************************************************* //