Circulator.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) 2012-2015 OpenFOAM Foundation
    Copyright (C) 2022-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::Circulator
 
Description
    Walks over a container as if it were circular. The container must have the
    following members defined:
        - size_type
        - difference_type
        - iterator / const_iterator
        - reference / const_reference
 
    Examples
 
    \code
        face f(identity(5));
 
        // Construct Circulator from the face
        Circulator<face> circ(f);
 
        // If it has a size to iterate over,
        // circulate around the list starting and finishing at the fulcrum.
        if (!circ.empty())
        {
            do
            {
                *circ += 1;
 
                Info<< "Iterate forwards over face : " << *circ << endl;
 
            } while (circ.circulate(CirculatorBase::FORWARD));
        }
    \endcode
 
SourceFiles
    CirculatorI.H
 
\*---------------------------------------------------------------------------*/
 
#ifndef Foam_Circulator_H
#define Foam_Circulator_H
 
#include <type_traits>  // std::conditional
 
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
namespace Foam
{
 
/*---------------------------------------------------------------------------*\
                       Class CirculatorBase Declaration
\*---------------------------------------------------------------------------*/
 
//- Template-invariant parts for circulators
class CirculatorBase
{
public:
 
    // Public Data
 
        //- Direction type enumeration
        enum direction
        {
            NONE,
            CLOCKWISE,
            ANTICLOCKWISE
        };
 
 
    // Constructors
 
        //- Default construct
        CirculatorBase() = default;
};
 
 
/*---------------------------------------------------------------------------*\
                       Class CirculatorIters Declaration
\*---------------------------------------------------------------------------*/
 
//- A pair of begin/end iterators used for implementing circular iteration
template<class Container, bool Const>
class CirculatorIters
:
    public CirculatorBase
{
public:
 
    // STL type definitions
 
        //- The type that can represent the size of Container
        using size_type = typename Container::size_type;
 
        //- The type that represents difference between iterator objects
        using difference_type = typename Container::difference_type;
 
        //- The container iterator type (const/non-const)
        using iterator = std::conditional_t
        <
            Const,
            typename Container::const_iterator,
            typename Container::iterator
        >;
 
        //- The reference type (const/non-const)
        using reference = std::conditional_t
        <
            Const,
            typename Container::const_reference,
            typename Container::reference
        >;
 
 
private:
 
    // Private Data
 
        //- The container beginning
        iterator begin_;
 
        //- The container end
        iterator end_;
 
        //- Random access iterator for traversing Container.
        iterator iter_;
 
        //- Iterator holding location of the fulcrum (start and end) of
        //- the container.
        //- Used to decide when iterator should stop circulating the container
        iterator fulcrum_;
 
 
protected:
 
    // Protected Member Functions
 
        //- Compare for equality
        inline bool equal(const CirculatorIters<Container, Const>& rhs);
 
        //- Move iterator forward
        inline void increment();
 
        //- Move iterator backward
        inline void decrement();
 
 
public:
 
    // Constructors
 
        //- Default construct
        inline CirculatorIters();
 
        //- Construct from begin/end iterators
        inline CirculatorIters(const iterator& begin, const iterator& end);
 
        //- Copy construct
        CirculatorIters(const CirculatorIters<Container, Const>& rhs);
 
 
    // Member Functions
 
        //- True if begin/end iterators are identical
        inline bool empty() const;
 
        //- Return the range of the iterator pair
        inline size_type size() const;
 
        //- The distance between the iterator and the fulcrum.
        //  This is equivalent to the number of rotations of the circulator
        inline difference_type nRotations() const;
 
        //- Circulate around the list in the given direction
        //- \return True if iterator has not yet reached the fulcrum
        inline bool circulate
        (
            const CirculatorBase::direction dir = CirculatorBase::NONE
        );
 
        //- Set the fulcrum to the current position of the iterator
        inline void setFulcrumToIterator();
 
        //- Set the iterator to the current position of the fulcrum
        inline void setIteratorToFulcrum();
 
        //- Dereference the current iterator
        inline reference curr() const;
 
        //- Dereference the next iterator
        inline reference next() const;
 
        //- Dereference the previous iterator
        inline reference prev() const;
 
 
    // Member Operators
 
        //- Assignment operator for circulators operating
        //- on the same container type
        inline void operator=(const CirculatorIters<Container, Const>& rhs);
 
        //- Prefix increment the iterator.
        //  Wraps iterator to the begin if it reaches the end
        inline CirculatorIters<Container, Const>& operator++();
 
        //- Postfix increment the iterator.
        //  Wraps iterator to the begin if it reaches the end
        inline CirculatorIters<Container, Const> operator++(int);
 
        //- Prefix decrement the iterator.
        //  Wraps iterator to the end if it reaches the beginning
        inline CirculatorIters<Container, Const>& operator--();
 
        //- Postfix decrement the iterator.
        //  Wraps iterator to the end if it reaches the beginning
        inline CirculatorIters<Container, Const> operator--(int);
 
        //- Check for equality of this iterator with another iterator that
        //- operate on the same container type
        inline bool operator==
        (
            const CirculatorIters<Container, Const>&
        ) const;
 
        //- Check for inequality of this iterator with another iterator that
        //- operate on the same container type
        inline bool operator!=
        (
            const CirculatorIters<Container, Const>&
        ) const;
 
        //- Dereference the iterator. Same as curr()
        inline reference operator*() const;
 
        //- Dereference the iterator. Same as curr()
        inline reference operator()() const;
 
        //- Return the difference between this iterator and another iterator
        //- that operate on the same container type
        inline difference_type operator-
        (
            const CirculatorIters<Container, Const>&
        ) const;
};
 
 
/*---------------------------------------------------------------------------*\
                         Class Circulator Declaration
\*---------------------------------------------------------------------------*/
 
template<class Container>
class Circulator
:
    public CirculatorIters<Container, false>
{
public:
 
    // Constructors
 
        //- Default construct
        Circulator() = default;
 
        //- Construct from begin/end of a container
        explicit Circulator(Container& obj)
        :
            CirculatorIters<Container, false>(obj.begin(), obj.end())
        {}
 
        //- Construct from two iterators
        Circulator
        (
            const typename Container::iterator& begin,
            const typename Container::iterator& end
        )
        :
            CirculatorIters<Container, false>(begin, end)
        {}
 
        //- Copy construct
        Circulator(const Circulator<Container>& rhs) = default;
 
 
    // Member Operators
 
        //- Copy assignment
        Circulator<Container>& operator=
        (
            const Circulator<Container>& rhs
        ) = default;
};
 
 
/*---------------------------------------------------------------------------*\
                      Class ConstCirculator Declaration
\*---------------------------------------------------------------------------*/
 
//- Like Foam::Circulator, but with const-access iterators
template<class Container>
class ConstCirculator
:
    public CirculatorIters<Container, true>
{
public:
 
    // Constructors
 
        //- Default construct
        ConstCirculator() = default;
 
        //- Construct from begin/end of a container
        explicit ConstCirculator(const Container& obj)
        :
            CirculatorIters<Container, true>(obj.begin(), obj.end())
        {}
 
        //- Construct from two iterators
        inline ConstCirculator
        (
            const typename Container::const_iterator& begin,
            const typename Container::const_iterator& end
        )
        :
            CirculatorIters<Container, true>(begin, end)
        {}
 
        //- Copy construct
        ConstCirculator(const ConstCirculator<Container>& rhs) = default;
 
 
    // Member Operators
 
        //- Copy assignment
        ConstCirculator<Container>& operator=
        (
            const ConstCirculator<Container>& rhs
        ) = default;
};
 
 
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
} // End namespace Foam
 
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
#include "CirculatorI.H"
 
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
#endif
 
// ************************************************************************* //