// @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:
* - this->full_range()==true
*
- this->size() is a very large number
*
- this->lbound()==0
*
- this->ubound() is a very large number
*
*/
inline Range1D();
/** \brief Constructs an invalid range.
*
* Postconditions:
* - this->full_range() == false
*
- this->size() == -1
*
- this->lbound()==0
*
- this->ubound()==-2
*
*/
inline Range1D(EInvalidRange);
/** \brief Construct a finite range [lbound, ubound].
*
* Preconditions:
* - lbound >= 0 (throw \c out_of_range)
*
- ubound >= lbound-1 (throw \c out_of_range)
*
*
* Postconditions:
* - this->full_range() == false
*
- this->size() == ubound - lbound + 1
*
- this->lbound() == lbound
*
- this->ubound() == ubound
*
*
* \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:
* - rng_lhs.lbound() == rng_rhs.lbound() + i
*
- rng_lhs.ubound() == rng_rhs.ubound() + i
*
*
* \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:
* - rng_lhs.lbound() == i + rng_rhs.lbound()
*
- rng_lhs.ubound() == i + rng_rhs.ubound()
*
*
* \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:
* - rng_lhs.lbound() == rng_rhs.lbound() - i
*
- rng_lhs.ubound() == rng_rhs.ubound() - i
*
*
* \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:
* - [rng.full_range() == true] return.lbound() == lbound
*
- [rng.full_range() == true] return.ubound() == ubound
*
- [rng.full_range() == false] return.lbound() == rng.lbound()
*
- [rng.full_range() == false] return.ubound() == rng.ubound()
*
*
* \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