// @HEADER // ***************************************************************************** // Teuchos: Common Tools Package // // Copyright 2004 NTESS and the Teuchos contributors. // SPDX-License-Identifier: BSD-3-Clause // ***************************************************************************** // @HEADER // Range1D class used for representing a range of positive integers. // Its primary usage is in accessing vectors and matrices by subregions // of rows and columns // #ifndef TEUCHOS_RANGE1D_HPP #define TEUCHOS_RANGE1D_HPP /*! \file Teuchos_Range1D.hpp \brief . */ #include "Teuchos_ScalarTraits.hpp" #include "Teuchos_Assert.hpp" namespace Teuchos { /** \brief Subregion Index Range Class. * * The class %Range1D encapsulates a 1-D, zero-based, range of * non-negative indexes. It is used to index into vectors and matrices and * return subregions of them respectively. * * Constructing using Range1D() yields a range that represents the * entire dimension of an object [0, max_ubound] (an entire * std::vector, all the rows in a matrix, or all the columns in a matrix * etc.). * * Constructing using \ref Range1D::Range1D "Range1D(INVALID)" yields * an invalid range [0,-2] with size() == -1. Once * constructed with Range1D(INVALID), a %Range1D object can * pass through many other operations that may change %lbound() and * %ubound() but will never change size()==-1. * * Constructing using \ref Range1D::Range1D "Range1D(lbound,ubound)" * yields a finite-dimensional zero-based range. The validity of constructed * range will only be checked if TEUCHOS_DEBUG is defined. * * There are many \ref Range1D_funcs_grp "non-member functions" that can be * used with %Range1D objects. * * The default copy constructor and assignment operator functions are allowed * since they have the correct semantics. */ class Range1D { public: /** \brief Deprecated. */ typedef Teuchos_Ordinal Index; /** \brief Deprecated. */ typedef Teuchos_Ordinal Ordinal; /** \brief . */ enum EInvalidRange { INVALID }; /** \brief Used for Range1D(INVALID) */ static const Range1D Invalid; /** \brief Construct a full range. * * Postconditions: */ inline Range1D(); /** \brief Constructs an invalid range. * * Postconditions: */ inline Range1D(EInvalidRange); /** \brief Construct a finite range [lbound, ubound]. * * Preconditions: * * Postconditions: * * \note It is allowed for ubound == lbound-1 which yields a * zero-sized range. There are use cases where this is useful so it is * allowed. */ inline Range1D(Ordinal lbound, Ordinal ubound); /** \brief Returns \c true if the range represents the entire region. */ inline bool full_range() const; /** \brief Return lower bound of the range */ inline Ordinal lbound() const; /** \brief Return upper bound of the range */ inline Ordinal ubound() const; /** \brief Return the size of the range (ubound() - lbound() + 1) */ inline Ordinal size() const; /** \brief Return true if the index is in range */ inline bool in_range(Ordinal i) const; /** \brief Increment the range by a constant * * \precondition this->lbound() + incr >= 0 (throws \c out_of_range) */ inline Range1D& operator+=( Ordinal incr ); /** \brief Deincrement the range by a constant. * * \precondition this->lbound() - incr >= 0 (throws \c out_of_range) */ inline Range1D& operator-=( Ordinal incr ); private: Ordinal lbound_; Ordinal ubound_; inline void assert_valid_range(Ordinal lbound, Ordinal ubound) const; }; // end class Range1D /** \brief rng1 == rng2. * * @return Returns rng1.lbound() == rng2.ubound() && rng1.ubound() == rng2.ubound(). * * \relates Range1D */ inline bool operator==(const Range1D& rng1, const Range1D& rng2 ) { return rng1.lbound() == rng2.lbound() && rng1.ubound() == rng2.ubound(); } /** \brief rng1 == rng2. * * @return Returns rng1.lbound() == rng2.ubound() && rng1.ubound() == rng2.ubound(). * * \relates Range1D */ inline bool operator!=(const Range1D& rng1, const Range1D& rng2 ) { return !(rng1 == rng2); } /** \brief rng_lhs = rng_rhs + i. * * Increments the upper and lower bounds by a constant. * * Postcondition: * * \relates Range1D */ inline Range1D operator+(const Range1D &rng_rhs, Range1D::Ordinal i) { return Range1D(i+rng_rhs.lbound(), i+rng_rhs.ubound()); } /** \brief rng_lhs = i + rng_rhs. * * Increments the upper and lower bounds by a constant. * * Postcondition: * * \relates Range1D */ inline Range1D operator+(Range1D::Ordinal i, const Range1D &rng_rhs) { return Range1D(i+rng_rhs.lbound(), i+rng_rhs.ubound()); } /** \brief rng_lhs = rng_rhs - i. * * Deincrements the upper and lower bounds by a constant. * * Postcondition: * * \relates Range1D */ inline Range1D operator-(const Range1D &rng_rhs, Range1D::Ordinal i) { return Range1D(rng_rhs.lbound()-i, rng_rhs.ubound()-i); } /** \brief Return a bounded index range from a potentially unbounded index * range. * * Return a index range of lbound to ubound if rng.full_range() == true * , otherwise just return a copy of rng. * * Postconditions: * * \relates Range1D */ inline Range1D full_range(const Range1D &rng, Range1D::Ordinal lbound, Range1D::Ordinal ubound) { return rng.full_range() ? Range1D(lbound,ubound) : rng; } /** \brief Print out to ostream. * * \relates Range1D */ TEUCHOSCORE_LIB_DLL_EXPORT std::ostream& operator<<(std::ostream &out, const Range1D& rng); // ////////////////////////////////////////////////////////// // Inline members inline Range1D::Range1D() : lbound_(0), ubound_(std::numeric_limits::max()-1) {} inline Range1D::Range1D( EInvalidRange ) : lbound_(0), ubound_(-2) {} inline Range1D::Range1D(Ordinal lbound_in, Ordinal ubound_in) : lbound_(lbound_in), ubound_(ubound_in) { assert_valid_range(lbound_in,ubound_in); } inline bool Range1D::full_range() const { return (lbound_ == 0 && ubound_ == std::numeric_limits::max()-1); } inline Range1D::Ordinal Range1D::lbound() const { return lbound_; } inline Range1D::Ordinal Range1D::ubound() const { return ubound_; } inline Range1D::Ordinal Range1D::size() const { return ubound_ - lbound_ + 1; } inline bool Range1D::in_range(Ordinal i) const { return lbound_ <= i && i <= ubound_; } inline Range1D& Range1D::operator+=( Ordinal incr ) { assert_valid_range( lbound_ + incr, ubound_ + incr ); lbound_ += incr; ubound_ += incr; return *this; } inline Range1D& Range1D::operator-=( Ordinal incr ) { assert_valid_range( lbound_ - incr, ubound_ - incr ); lbound_ -= incr; ubound_ -= incr; return *this; } // See Range1D.cpp inline void Range1D::assert_valid_range(Ordinal lbound_in, Ordinal ubound_in) const { (void)lbound_in; (void)ubound_in; #ifdef TEUCHOS_DEBUG TEUCHOS_ASSERT_INEQUALITY(lbound_in, >=, 0); TEUCHOS_ASSERT_INEQUALITY(ubound_in, >=, lbound_in - 1); #endif } } // end namespace Teuchos #endif // end TEUCHOS_RANGE1D_HPP