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

Models an interval whose bounds may be open. More...

#include <general_interval.hpp>

Public Types

using value_t = ValueType
 The numeric type of the bounds.
using closure_t = Interval<value_t>
 The type of the closure, the closed interval with the same bounds.

Public Member Functions

 GeneralInterval ()=default
 Default constructor.
 GeneralInterval (value_t value)
 Construct a degenerate interval from a single value.
 GeneralInterval (const closure_t &closed)
 Construct from a closed interval.
 GeneralInterval (value_t lower, value_t upper, bool left_open=false, bool right_open=false)
 Construct an interval from two bounds and their openness.
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?
bool left_open () const
 Is lower() NOT contained in the interval?
bool left_closed () const
 Is lower() contained in the interval?
bool right_open () const
 Is upper() NOT contained in the interval?
bool right_closed () const
 Is upper() contained in the interval?
value_t lower () const
 Returns the lower bound of the interval.
value_t upper () const
 Returns the upper bound of the interval.
const closure_t & closure () const
 Returns the closure of the interval.
bool contains (value_t value) const
 Whether a scalar lies in this interval.
bool contains (const GeneralInterval &other) const
 Is other fully contained in this interval?
GeneralInterval set_union (const GeneralInterval &other) const
 Returns the union of this interval and another interval.
GeneralInterval set_intersection (const GeneralInterval &other) const
 Returns the intersection of this interval and another interval.
GeneralInterval operator- () const
 Negation of an interval.
GeneralInterval & operator+= (const GeneralInterval &rhs)
 In-place addition of another interval.
GeneralInterval & operator-= (const GeneralInterval &rhs)
 In-place subtraction of another interval.
GeneralInterval & operator*= (const GeneralInterval &rhs)
 In-place multiplication by another interval.
GeneralInterval & operator/= (const GeneralInterval &rhs)
 In-place division by another interval.
std::string print_interval_form () const
 Print the interval in interval form.

Friends

GeneralInterval operator+ (GeneralInterval lhs, const GeneralInterval &rhs)
 Addition of two intervals.
GeneralInterval operator- (GeneralInterval lhs, const GeneralInterval &rhs)
 Subtraction of two intervals.
GeneralInterval operator* (GeneralInterval lhs, const GeneralInterval &rhs)
 Multiplication of two intervals.
GeneralInterval operator/ (GeneralInterval lhs, const GeneralInterval &rhs)
 Division of two intervals.

(Note that these are not member symbols.)

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

Detailed Description

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

Models an interval whose bounds may be open.

Interval represents closed intervals only. GeneralInterval adds the openness of each bound on top of one, so the half-open \( \lbrack a, b) \) and \( (a, b\rbrack \) and the open \( (a, b) \) are representable too. Openness decides which values are members, and nothing else: the width, median, and radius are those of the closure, the closed Interval with the same bounds. An infinite bound is never a member, so it is always open.

An Interval converts implicitly, and losslessly, to a GeneralInterval with both bounds closed (save an infinite one), so arithmetic that mixes the two types promotes to GeneralInterval. The reverse conversion discards information and is spelled out with closure().

Template Parameters
ValueTypeThe floating-point type of the bounds

Constructor & Destructor Documentation

◆ GeneralInterval() [1/4]

template<typename ValueType>
sigma::GeneralInterval< ValueType >::GeneralInterval ( )
default

Default constructor.

Constructs an empty interval (contains no values).

Exceptions
noneNo throw guarantee

◆ GeneralInterval() [2/4]

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

Construct a degenerate interval from a single value.

Parameters
valueThe value to set both bounds to. Both bounds are closed, unless value is infinite, in which case the interval is empty.
Exceptions
noneNo throw guarantee

◆ GeneralInterval() [3/4]

template<typename ValueType>
sigma::GeneralInterval< ValueType >::GeneralInterval ( const closure_t & closed)
inline

Construct from a closed interval.

Every closed interval is a general interval with two closed bounds, so this conversion is implicit and loses nothing. The exception is an infinite bound, which is opened, as for every other constructor.

Parameters
closedThe closed interval to convert
Exceptions
noneNo throw guarantee

◆ GeneralInterval() [4/4]

template<typename ValueType>
sigma::GeneralInterval< ValueType >::GeneralInterval ( value_t lower,
value_t upper,
bool left_open = false,
bool right_open = false )

Construct an interval from two bounds and their openness.

For convenience, the bounds are sorted so that lower() <= upper(). An infinite bound is always open, whatever is requested. A single value with an open bound contains nothing, so it constructs the empty interval; this includes a single infinite value.

Parameters
lowerThe lower bound of the interval
upperThe upper bound of the interval
left_openIs lower just outside the interval?
right_openIs upper just outside the interval?
Exceptions
noneNo throw guarantee

Member Function Documentation

◆ closure()

template<typename ValueType>
const closure_t & sigma::GeneralInterval< ValueType >::closure ( ) const
inline

Returns the closure of the interval.

The closure is the closed interval with the same bounds, which is the smallest Interval containing *this.

Returns
The closure of *this. The closure of the empty interval is the empty Interval.
Exceptions
noneNo throw guarantee

◆ contains() [1/2]

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

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::GeneralInterval< ValueType >::contains ( value_t value) const

Whether a scalar lies in this interval.

Returns true if lower() <= value <= upper(). Equality to lower()/ upper() is only allowed if left_closed()/right_closed() is true, respectively.

Parameters
valueThe scalar to test
Returns
True if value lies in the interval represented by *this and false otherwise.
Exceptions
noneNo throw guarantee

◆ empty()

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

Is *this the empty interval?

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

◆ left_closed()

template<typename ValueType>
bool sigma::GeneralInterval< ValueType >::left_closed ( ) const
inline

Is lower() contained in the interval?

Returns
True if lower() is contained in the interval.
Exceptions
noneNo throw guarantee.

◆ left_open()

template<typename ValueType>
bool sigma::GeneralInterval< ValueType >::left_open ( ) const
inline

Is lower() NOT contained in the interval?

Returns
True if lower() is NOT contained in the interval. False for the empty interval.
Exceptions
noneNo throw guarantee

◆ lower()

template<typename ValueType>
value_t sigma::GeneralInterval< 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::GeneralInterval< ValueType >::median ( ) const
inline

Returns the midpoint of the interval.

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

◆ operator*=()

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

In-place multiplication by another interval.

A bound of the product is closed if any of the products of operand bounds that equals it combines two closed bounds, or if it is zero and either operand contains zero.

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

◆ operator+=()

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

In-place addition of another interval.

A bound of the sum is open if either bound that produced it is.

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

◆ operator-()

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

Negation of an interval.

Given the interval [a, b], the negation is [-b, -a]. The openness of the bounds is reversed, e.g., [a, b) becomes (-b, -a].

Returns
A new interval with negated bounds
Exceptions
noneNo throw guarantee

◆ operator-=()

template<typename ValueType>
GeneralInterval & sigma::GeneralInterval< ValueType >::operator-= ( const GeneralInterval< 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/=()

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

In-place division by another interval.

A divisor merely bounded by an open zero, such as \( (0, 1\rbrack \), does not contain zero and is divided by normally; the quotient is then unbounded on that side. A bound of the quotient is closed under the same rule as for multiplication, except that a zero bound is closed when the dividend contains zero.

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

◆ print_interval_form()

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

Print the interval in interval form.

The interval is printed in the form where closed bounds are represented by square brackets and open bounds are represented by parentheses.

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

◆ radius()

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

Returns the half-width of the interval.

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

◆ right_closed()

template<typename ValueType>
bool sigma::GeneralInterval< ValueType >::right_closed ( ) const
inline

Is upper() contained in the interval?

Returns
True if upper() is contained in the interval.
Exceptions
noneNo throw guarantee

◆ right_open()

template<typename ValueType>
bool sigma::GeneralInterval< ValueType >::right_open ( ) const
inline

Is upper() NOT contained in the interval?

Returns
True if upper() is NOT contained in the interval. False for the empty interval.
Exceptions
noneNo throw guarantee

◆ set_intersection()

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

Returns the intersection of this interval and another interval.

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

◆ set_union()

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

Returns the union of this interval and another interval.

Because the result must be an interval, union is only defined when there is no gap between the intervals: they must overlap, or touch at a point that at least one of them contains, as in \( \lbrack 0, 1) \cup [1, 2] = [0, 2] \).

Parameters
otherThe interval to union with
Returns
The union of this interval and other
Exceptions
std::domain_errorif there is a gap between the intervals. Strong throw guarantee.

◆ upper()

template<typename ValueType>
value_t sigma::GeneralInterval< 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::GeneralInterval< ValueType >::width ( ) const
inline

Returns the distance between the interval's bounds.

The width does NOT depend on the openness of the bounds.

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

◆ operator!=()

template<typename T1, typename T2>
bool operator!= ( const GeneralInterval< T1 > & lhs,
const GeneralInterval< 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 ValueType>
GeneralInterval operator* ( GeneralInterval< ValueType > lhs,
const GeneralInterval< ValueType > & rhs )
friend

Multiplication of two intervals.

Either operand may also be an Interval or a scalar, which is converted.

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 ValueType>
GeneralInterval operator+ ( GeneralInterval< ValueType > lhs,
const GeneralInterval< ValueType > & rhs )
friend

Addition of two intervals.

Either operand may also be an Interval or a scalar, which is converted.

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 ValueType>
GeneralInterval operator- ( GeneralInterval< ValueType > lhs,
const GeneralInterval< ValueType > & rhs )
friend

Subtraction of two intervals.

Either operand may also be an Interval or a scalar, which is converted.

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 ValueType>
GeneralInterval operator/ ( GeneralInterval< ValueType > lhs,
const GeneralInterval< ValueType > & rhs )
friend

Division of two intervals.

Either operand may also be an Interval or a scalar, which is converted.

Parameters
lhsThe left-hand interval
rhsThe right-hand interval
Returns
A new interval that is the quotient of lhs and rhs
Exceptions
std::domain_errorif rhs contains zero. Strong throw guarantee.

◆ operator<()

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

Orders two intervals, primarily by their median.

The same deliberately weak, total ordering as for Interval, meant only for consumers that need some consistent ordering to sort by and not a rigorous enclosure relation: the closures are compared first. Intervals with the same closure are then ordered by the openness of the lower bound and then of the upper bound, with a closed bound before an open one, so that, as for Interval, neither of two intervals precedes the other exactly when they are equal. 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 GeneralInterval< 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 GeneralInterval< T1 > & lhs,
const GeneralInterval< T2 > & rhs )
related

Compare two intervals for equality.

Two intervals are equal if they have the same bounds and the same openness.

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>
GeneralInterval< T > widen ( const GeneralInterval< T > & a,
typename GeneralInterval< T >::value_t point )
related

Widens an interval just enough to contain a point.

As for widen(const Interval<T>&, T), except that point may also lie on an open bound of a. Either way, the bound that point moves or lands on is closed.

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 and closed; the degenerate interval [point, point] if a is empty.
Exceptions
noneNo throw guarantee

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