sigma  1.0.0
Loading...
Searching...
No Matches
sigma::Interval< ValueType > Class Template Reference

Models a closed numeric interval. More...

#include <interval.hpp>

Public Types

using value_t = ValueType
 The numeric type of the bounds.

Public Member Functions

 Interval ()
 Default constructor.
 Interval (value_t value)
 Construct an interval from a single value.
 Interval (value_t lower, value_t upper)
 Construct an interval from two bounds.
value_t width () const
 Returns the distance between the interval's bounds.
value_t median () const
 Returns the midpoint of the interval.
value_t radius () const
 Returns the half-width of the interval.
bool empty () const
 Is *this the empty interval?
value_t lower () const
 Returns the lower bound of the interval.
value_t upper () const
 Returns the upper bound of the interval.
bool contains (value_t value) const
 Whether a scalar lies in this interval.
bool contains (const Interval &other) const
 Is other fully contained in this interval?
Interval set_union (const Interval &other) const
 Returns the union of this interval and another interval.
Interval set_intersection (const Interval &other) const
 Returns the intersection of this interval and another interval.
Interval operator- () const
 Negation of an interval.
Interval & operator+= (const Interval &rhs)
 In-place addition of another interval.
Interval & operator+= (value_t rhs)
 In-place addition of a scalar.
Interval & operator-= (const Interval &rhs)
 In-place subtraction of another interval.
Interval & operator-= (value_t rhs)
 In-place subtraction of a scalar.
Interval & operator*= (const Interval &rhs)
 In-place multiplication by another interval.
Interval & operator*= (value_t rhs)
 In-place multiplication by a scalar.
Interval & operator/= (const Interval &rhs)
 In-place division by another interval.
Interval & operator/= (value_t rhs)
 In-place division by a scalar.
std::string print_interval_form () const
 Print the interval in interval form.

(Note that these are not member symbols.)

template<typename ValueType>
std::ostream & operator<< (std::ostream &os, const Interval< ValueType > &i)
 Overload stream insertion to print an interval.
template<typename T1, typename T2>
bool operator== (const Interval< T1 > &lhs, const Interval< T2 > &rhs)
 Compare two intervals for equality.
template<typename T1, typename T2>
bool operator!= (const Interval< T1 > &lhs, const Interval< T2 > &rhs)
 Compare two intervals for inequality.
template<typename T>
bool operator< (const Interval< T > &lhs, const Interval< T > &rhs)
 Orders two intervals, primarily by their median.
template<typename T>
bool operator> (const Interval< T > &lhs, const Interval< T > &rhs)
 Same ordering as operator<, with the operands reversed.
template<typename T>
bool operator<= (const Interval< T > &lhs, const Interval< T > &rhs)
 Same ordering as operator<, negated.
template<typename T>
bool operator>= (const Interval< T > &lhs, const Interval< T > &rhs)
 Same ordering as operator<, negated and reversed.
template<typename T>
Interval< T > widen (const Interval< T > &a, typename Interval< T >::value_t point)
 Widens an interval just enough to contain a point.
template<typename T>
Interval< T > operator+ (Interval< T > lhs, const Interval< T > &rhs)
 Addition of two intervals.
template<typename T>
Interval< T > operator- (Interval< T > lhs, const Interval< T > &rhs)
 Subtraction of two intervals.
template<typename T>
Interval< T > operator* (Interval< T > lhs, const Interval< T > &rhs)
 Multiplication of two intervals.
template<typename T>
Interval< T > operator/ (Interval< T > lhs, const Interval< T > &rhs)
 Division of two intervals.

Detailed Description

template<typename ValueType>
class sigma::Interval< ValueType >

Models a closed numeric interval.

An interval is defined by a lower and upper bound, both of which are members of the set. This class wraps boost::numeric::interval and provides a median (midpoint) and radius (half-width) interface consistent with the rest of the sigma library. An infinite bound means the interval is unbounded in that direction. Intervals whose bounds may be open are represented by GeneralInterval.

Template Parameters
ValueTypeThe floating-point type of the bounds

Constructor & Destructor Documentation

◆ Interval() [1/3]

template<typename ValueType>
sigma::Interval< ValueType >::Interval ( )
inline

Default constructor.

Constructs an empty interval (contains no values).

Exceptions
noneNo throw guarantee

◆ Interval() [2/3]

template<typename ValueType>
sigma::Interval< ValueType >::Interval ( value_t value)
inline

Construct an interval from a single value.

Constructs an interval with both bounds set to the given value.

Parameters
valueThe value to set both bounds to
Exceptions
noneNo throw guarantee

◆ Interval() [3/3]

template<typename ValueType>
sigma::Interval< ValueType >::Interval ( value_t lower,
value_t upper )
inline

Construct an interval from two bounds.

For convenience, the bounds are sorted so that lower() <= upper().

Parameters
lowerThe lower bound of the interval
upperThe upper bound of the interval
Exceptions
noneNo throw guarantee

Member Function Documentation

◆ contains() [1/2]

template<typename ValueType>
bool sigma::Interval< ValueType >::contains ( const Interval< ValueType > & other) const
inline

Is other fully contained in this interval?

Parameters
otherThe interval to test. The empty interval is contained in every interval.
Returns
True if every value in other is in *this.
Exceptions
noneNo throw guarantee

◆ contains() [2/2]

template<typename ValueType>
bool sigma::Interval< ValueType >::contains ( value_t value) const
inline

Whether a scalar lies in this interval.

An infinite bound marks an unbounded direction, not a member, so no interval contains an infinite (or NaN) value.

Parameters
valueThe scalar to test
Returns
True if value is finite and lower() <= value <= upper(), and false otherwise or if *this is empty.
Exceptions
noneNo throw guarantee

◆ empty()

template<typename ValueType>
bool sigma::Interval< ValueType >::empty ( ) const
inline

Is *this the empty interval?

The empty interval contains no values.

Returns
True if *this is the empty interval, false otherwise.
Exceptions
noneNo throw guarantee

◆ lower()

template<typename ValueType>
value_t sigma::Interval< ValueType >::lower ( ) const
inline

Returns the lower bound of the interval.

Returns
The lower bound value
Exceptions
std::domain_errorif the interval is empty

◆ median()

template<typename ValueType>
value_t sigma::Interval< ValueType >::median ( ) const
inline

Returns the midpoint of the interval.

Returns
The midpoint value
Exceptions
std::domain_errorif the interval is empty

◆ operator*=() [1/2]

template<typename ValueType>
Interval< ValueType > & sigma::Interval< ValueType >::operator*= ( const Interval< ValueType > & rhs)

In-place multiplication by another interval.

Parameters
rhsThe interval to multiply by
Returns
Reference to this interval after multiplication
Exceptions
noneNo throw guarantee

◆ operator*=() [2/2]

template<typename ValueType>
Interval & sigma::Interval< ValueType >::operator*= ( value_t rhs)
inline

In-place multiplication by a scalar.

Parameters
rhsThe scalar to multiply by
Returns
Reference to this interval after multiplication
Exceptions
noneNo throw guarantee

◆ operator+=() [1/2]

template<typename ValueType>
Interval< ValueType > & sigma::Interval< ValueType >::operator+= ( const Interval< ValueType > & rhs)

In-place addition of another interval.

Parameters
rhsThe interval to add
Returns
Reference to this interval after addition
Exceptions
noneNo throw guarantee

◆ operator+=() [2/2]

template<typename ValueType>
Interval & sigma::Interval< ValueType >::operator+= ( value_t rhs)
inline

In-place addition of a scalar.

Parameters
rhsThe scalar to add
Returns
Reference to this interval after addition
Exceptions
noneNo throw guarantee

◆ operator-()

template<typename ValueType>
Interval sigma::Interval< ValueType >::operator- ( ) const
inline

Negation of an interval.

Given the interval [a, b], the negation is [-b, -a].

Returns
A new interval with negated bounds
Exceptions
noneNo throw guarantee

◆ operator-=() [1/2]

template<typename ValueType>
Interval & sigma::Interval< ValueType >::operator-= ( const Interval< ValueType > & rhs)
inline

In-place subtraction of another interval.

Parameters
rhsThe interval to subtract
Returns
Reference to this interval after subtraction
Exceptions
noneNo throw guarantee

◆ operator-=() [2/2]

template<typename ValueType>
Interval & sigma::Interval< ValueType >::operator-= ( value_t rhs)
inline

In-place subtraction of a scalar.

Parameters
rhsThe scalar to subtract
Returns
Reference to this interval after subtraction
Exceptions
noneNo throw guarantee

◆ operator/=() [1/2]

template<typename ValueType>
Interval< ValueType > & sigma::Interval< ValueType >::operator/= ( const Interval< ValueType > & rhs)

In-place division by another interval.

Parameters
rhsThe interval to divide by
Returns
Reference to this interval after division
Exceptions
std::domain_errorif rhs contains zero, including as a bound. Strong throw guarantee.

◆ operator/=() [2/2]

template<typename ValueType>
Interval & sigma::Interval< ValueType >::operator/= ( value_t rhs)
inline

In-place division by a scalar.

Parameters
rhsThe scalar to divide by
Returns
Reference to this interval after division
Exceptions
noneNo throw guarantee

◆ print_interval_form()

template<typename ValueType>
std::string sigma::Interval< ValueType >::print_interval_form ( ) const

Print the interval in interval form.

The interval is printed as "[lower, upper]".

Returns
A string representation of the interval.
Exceptions
noneNo throw guarantee

◆ radius()

template<typename ValueType>
value_t sigma::Interval< ValueType >::radius ( ) const
inline

Returns the half-width of the interval.

This is the distance from the median to either endpoint. This is a convenience method for width() / value_t{2}

Returns
The half-width value
Exceptions
std::domain_errorif the interval is empty

◆ set_intersection()

template<typename ValueType>
Interval< ValueType > sigma::Interval< ValueType >::set_intersection ( const Interval< ValueType > & other) const

Returns the intersection of this interval and another interval.

The intersection of two intervals is the largest interval that is contained in both intervals.

Parameters
otherThe interval to intersect with
Returns
The intersection of this interval and other
Exceptions
NoneNo throw guarantee.

◆ set_union()

template<typename ValueType>
Interval< ValueType > sigma::Interval< ValueType >::set_union ( const Interval< ValueType > & other) const

Returns the union of this interval and another interval.

The union of two intervals is the smallest interval that contains both intervals. Because the result must be an interval, union is only defined when the intervals overlap at least at one point.

Parameters
otherThe interval to union with
Returns
The union of this interval and other
Exceptions
std::domain_errorif the intervals do not overlap. Strong throw guarantee.

◆ upper()

template<typename ValueType>
value_t sigma::Interval< ValueType >::upper ( ) const
inline

Returns the upper bound of the interval.

Returns
The upper bound value
Exceptions
std::domain_errorif the interval is empty

◆ width()

template<typename ValueType>
value_t sigma::Interval< ValueType >::width ( ) const
inline

Returns the distance between the interval's bounds.

The width of an interval is defined by |upper() - lower()|. The width of an empty interval is undefined (and calling this member on an empty interval will cause a domain_error to be thrown)

Returns
The width of the interval
Exceptions
std::domain_errorif the interval is empty

◆ operator!=()

template<typename T1, typename T2>
bool operator!= ( const Interval< T1 > & lhs,
const Interval< T2 > & rhs )
related

Compare two intervals for inequality.

Template Parameters
T1The numerical type of the left-hand interval
T2The numerical type of the right-hand interval
Parameters
lhsThe first interval
rhsThe second interval
Returns
Whether the instances are not equivalent

◆ operator*()

template<typename T>
Interval< T > operator* ( Interval< T > lhs,
const Interval< T > & rhs )
related

Multiplication of two intervals.

Template Parameters
TThe numerical type of the intervals
Parameters
lhsThe left-hand interval
rhsThe right-hand interval
Returns
A new interval that is the product of lhs and rhs
Exceptions
noneNo throw guarantee

◆ operator+()

template<typename T>
Interval< T > operator+ ( Interval< T > lhs,
const Interval< T > & rhs )
related

Addition of two intervals.

Template Parameters
TThe numerical type of the intervals
Parameters
lhsThe left-hand interval
rhsThe right-hand interval
Returns
A new interval that is the sum of lhs and rhs
Exceptions
noneNo throw guarantee

◆ operator-()

template<typename T>
Interval< T > operator- ( Interval< T > lhs,
const Interval< T > & rhs )
related

Subtraction of two intervals.

Template Parameters
TThe numerical type of the intervals
Parameters
lhsThe left-hand interval
rhsThe right-hand interval
Returns
A new interval that is the difference of lhs and rhs
Exceptions
noneNo throw guarantee

◆ operator/()

template<typename T>
Interval< T > operator/ ( Interval< T > lhs,
const Interval< T > & rhs )
related

Division of two intervals.

If the interval contains zero the resulting interval will loose most of its information.

Template Parameters
TThe numerical type of the intervals
Parameters
lhsThe left-hand interval
rhsThe right-hand interval
Returns
A new interval that is the quotient of lhs and rhs
Exceptions
noneNo throw guarantee

◆ operator<()

template<typename T>
bool operator< ( const Interval< T > & lhs,
const Interval< T > & rhs )
related

Orders two intervals, primarily by their median.

Interval containment does not give a total order (overlapping intervals are neither less than, greater than, nor equal to one another under it), so this comparison is a deliberately weaker, total one, meant only for consumers that need some consistent ordering to sort by and not a rigorous enclosure relation. Intervals are compared lexicographically by median, then lower bound, then upper bound. The tie-breaks make the order consistent with operator==: neither of two intervals precedes the other exactly when they are equal, so, e.g., [0, 2] and [-1, 3] are ordered even though they share a median, and intervals can be keys of ordered containers. The empty interval sorts before every non-empty one.

Template Parameters
TThe numerical type of the bounds
Parameters
lhsThe first interval
rhsThe second interval
Returns
Whether lhs precedes rhs.
Exceptions
noneNo throw guarantee

◆ operator<<()

template<typename ValueType>
std::ostream & operator<< ( std::ostream & os,
const Interval< ValueType > & i )
related

Overload stream insertion to print an interval.

Template Parameters
ValueTypeThe numerical type of the bounds
Parameters
osThe ostream to write to
iThe interval to write
Returns
The modified ostream instance
Exceptions
std::ios_base::failureif anything goes wrong while writing. Weak throw guarantee.

◆ operator==()

template<typename T1, typename T2>
bool operator== ( const Interval< T1 > & lhs,
const Interval< T2 > & rhs )
related

Compare two intervals for equality.

Template Parameters
T1The numerical type of the left-hand interval
T2The numerical type of the right-hand interval
Parameters
lhsThe first interval
rhsThe second interval
Returns
Whether the instances are equivalent

◆ widen()

template<typename T>
Interval< T > widen ( const Interval< T > & a,
typename Interval< T >::value_t point )
related

Widens an interval just enough to contain a point.

Template Parameters
TThe numerical type of the bounds
Parameters
aThe interval to widen
pointThe value the result must contain. An infinite or NaN value is never a member of an interval, so for one of those the result cannot contain point.
Returns
a if it already contains point. Otherwise a with the bound on the side of point moved to point; the degenerate interval [point, point] if a is empty.
Exceptions
noneNo throw guarantee

The documentation for this class was generated from the following files: