sigma  1.0.0
Loading...
Searching...
No Matches
sigma::Triplex< IntervalType > Class Template Reference

Models an interval together with a best estimate inside it. More...

#include <triplex.hpp>

Public Types

using interval_t = IntervalType
 The type of the bounds.
using value_t = typename interval_t::value_t
 The numeric type of the bounds and the nominal value.

Public Member Functions

 Triplex ()=default
 Default constructor.
 Triplex (value_t value)
 Constructs the degenerate triplex for an exactly known value.
 Triplex (value_t lower, value_t nominal, value_t upper)
 Constructs a triplex from its bounds and its nominal value.
template<typename I = interval_t, std::enable_if_t< is_general_interval_v< I >, int > = 0>
 Triplex (value_t lower, value_t nominal, value_t upper, bool left_open, bool right_open=false)
 Constructs a triplex whose bounds may be open.
 Triplex (interval_t interval, value_t nominal)
 Constructs a triplex from an interval and a nominal value.
bool empty () const
 Is *this the empty triplex?
value_t lower () const
 Returns the lower bound.
value_t nominal () const
 Returns the nominal value.
value_t upper () const
 Returns the upper bound.
value_t width () const
 Returns the distance between the bounds.
value_t median () const
 Returns the midpoint of the bounds.
value_t lower_radius () const
 Returns the distance from the lower bound to the nominal value.
value_t upper_radius () const
 Returns the distance from the nominal value to the upper bound.
const interval_t & interval () const
 Returns the bounds, discarding the nominal value.
template<typename I = interval_t, std::enable_if_t< is_general_interval_v< I >, int > = 0>
bool left_open () const
 Is lower() NOT a member of *this?
template<typename I = interval_t, std::enable_if_t< is_general_interval_v< I >, int > = 0>
bool left_closed () const
 Is lower() a member of *this?
template<typename I = interval_t, std::enable_if_t< is_general_interval_v< I >, int > = 0>
bool right_open () const
 Is upper() NOT a member of *this?
template<typename I = interval_t, std::enable_if_t< is_general_interval_v< I >, int > = 0>
bool right_closed () const
 Is upper() a member of *this?
bool contains (value_t value) const
 Whether a scalar lies within the bounds.
bool contains (const Triplex &other) const
 Whether the bounds of other lie within the bounds of *this.
Triplex operator- () const
 Negation of a triplex.
Triplex & operator+= (const Triplex &rhs)
 In-place addition of another triplex.
Triplex & operator-= (const Triplex &rhs)
 In-place subtraction of another triplex.
Triplex & operator*= (const Triplex &rhs)
 In-place multiplication by another triplex.
Triplex & operator/= (const Triplex &rhs)
 In-place division by another triplex.

Friends

Triplex operator+ (Triplex lhs, const Triplex &rhs)
 Addition of two triplex numbers.
Triplex operator- (Triplex lhs, const Triplex &rhs)
 Subtraction of two triplex numbers.
Triplex operator* (Triplex lhs, const Triplex &rhs)
 Multiplication of two triplex numbers.
Triplex operator/ (Triplex lhs, const Triplex &rhs)
 Division of two triplex numbers.
Triplex detail_::make_triplex_ (interval_t bounds, value_t nominal)
 Lets make_triplex_ use the unchecked constructor.

(Note that these are not member symbols.)

template<typename IntervalType>
std::ostream & operator<< (std::ostream &os, const Triplex< IntervalType > &t)
 Overload stream insertion to print a triplex.
template<typename I1, typename I2>
bool operator== (const Triplex< I1 > &lhs, const Triplex< I2 > &rhs)
 Compare two triplex numbers for equality.
template<typename I1, typename I2>
bool operator!= (const Triplex< I1 > &lhs, const Triplex< I2 > &rhs)
 Compare two triplex numbers for inequality.
template<typename IntervalType>
bool operator< (const Triplex< IntervalType > &lhs, const Triplex< IntervalType > &rhs)
 Orders two triplex numbers, primarily by their nominal values.
template<typename IntervalType>
bool operator> (const Triplex< IntervalType > &lhs, const Triplex< IntervalType > &rhs)
 Same ordering as operator<, with the operands reversed.
template<typename IntervalType>
bool operator<= (const Triplex< IntervalType > &lhs, const Triplex< IntervalType > &rhs)
 Same ordering as operator<, negated.
template<typename IntervalType>
bool operator>= (const Triplex< IntervalType > &lhs, const Triplex< IntervalType > &rhs)
 Same ordering as operator<, negated and reversed.

Detailed Description

template<typename IntervalType>
class sigma::Triplex< IntervalType >

Models an interval together with a best estimate inside it.

A triplex number \( \langle a, m, b \rangle \) is an interval \( [a, b] \) plus a distinguished member \( m \) of it, the nominal value. The interval is a rigorous enclosure, computed exactly as IntervalType would compute it. The nominal value is computed in ordinary, round-to-nearest floating point from the operand nominal values, so the nominal value of any triplex computation is the result of the same computation performed with plain value_t on the input nominal values. Nothing ties the nominal value to the median of the interval; in general they differ.

If the scalar computation overflows, or otherwise produces a non-finite value, the nominal value is kept anyway. Such a nominal value is not a member of the interval, and can be detected with std::isfinite(nominal()).

See the Triplex Arithmetic page of the documentation for the full design.

Template Parameters
IntervalTypeThe type of the bounds: Interval<T> for closed bounds or GeneralInterval<T> for bounds that may be open.

Constructor & Destructor Documentation

◆ Triplex() [1/5]

template<typename IntervalType>
sigma::Triplex< IntervalType >::Triplex ( )
default

Default constructor.

Constructs the empty triplex, which contains no values and has no nominal value.

Exceptions
noneNo throw guarantee

◆ Triplex() [2/5]

template<typename IntervalType>
sigma::Triplex< IntervalType >::Triplex ( value_t value)
inline

Constructs the degenerate triplex for an exactly known value.

Parameters
valueThe value of the lower bound, the nominal value, and the upper bound.
Exceptions
std::domain_errorif value is not finite. Strong throw guarantee.

◆ Triplex() [3/5]

template<typename IntervalType>
sigma::Triplex< IntervalType >::Triplex ( value_t lower,
value_t nominal,
value_t upper )
inline

Constructs a triplex from its bounds and its nominal value.

The arguments are in the order they are ordered by, and unlike for Interval nothing is reordered. Both bounds are closed.

Parameters
lowerThe lower bound
nominalThe nominal value. Must satisfy lower <= nominal <= upper.
upperThe upper bound
Exceptions
std::domain_errorif nominal is not a member of the interval [lower, upper], which includes the case lower > upper. Strong throw guarantee.

◆ Triplex() [4/5]

template<typename IntervalType>
template<typename I = interval_t, std::enable_if_t< is_general_interval_v< I >, int > = 0>
sigma::Triplex< IntervalType >::Triplex ( value_t lower,
value_t nominal,
value_t upper,
bool left_open,
bool right_open = false )
inline

Constructs a triplex whose bounds may be open.

Only available when interval_t is a GeneralInterval.

Template Parameters
IUsed to disable this overload for closed intervals. Do not supply it.
Parameters
lowerThe lower bound
nominalThe nominal value. Must be a member of the interval, so it may not equal an open bound.
upperThe upper bound
left_openIs lower just outside the interval?
right_openIs upper just outside the interval?
Exceptions
std::domain_errorif nominal is not a member of the interval, which includes the case lower > upper. Strong throw guarantee.

◆ Triplex() [5/5]

template<typename IntervalType>
sigma::Triplex< IntervalType >::Triplex ( interval_t interval,
value_t nominal )
inlineexplicit

Constructs a triplex from an interval and a nominal value.

There is deliberately no constructor from an interval alone, since it would have to make up a nominal value.

Parameters
intervalThe bounds of the triplex
nominalThe nominal value. Must be a member of interval.
Exceptions
std::domain_errorif nominal is not a member of interval, which includes every nominal when interval is empty. Strong throw guarantee.

Member Function Documentation

◆ contains() [1/2]

template<typename IntervalType>
bool sigma::Triplex< IntervalType >::contains ( const Triplex< IntervalType > & other) const
inline

Whether the bounds of other lie within the bounds of *this.

The nominal values play no part.

Parameters
otherThe triplex to test. The empty triplex is contained in every triplex.
Returns
True if interval() contains other.interval().
Exceptions
noneNo throw guarantee

◆ contains() [2/2]

template<typename IntervalType>
bool sigma::Triplex< IntervalType >::contains ( value_t value) const
inline

Whether a scalar lies within the bounds.

Parameters
valueThe scalar to test
Returns
True if interval() contains value, false otherwise.
Exceptions
noneNo throw guarantee

◆ empty()

template<typename IntervalType>
bool sigma::Triplex< IntervalType >::empty ( ) const
inline

Is *this the empty triplex?

Returns
True if *this contains no values, false otherwise.
Exceptions
noneNo throw guarantee

◆ interval()

template<typename IntervalType>
const interval_t & sigma::Triplex< IntervalType >::interval ( ) const
inline

Returns the bounds, discarding the nominal value.

Returns
The interval of *this. Empty if *this is.
Exceptions
noneNo throw guarantee

◆ left_closed()

template<typename IntervalType>
template<typename I = interval_t, std::enable_if_t< is_general_interval_v< I >, int > = 0>
bool sigma::Triplex< IntervalType >::left_closed ( ) const
inline

Is lower() a member of *this?

Only available when interval_t is a GeneralInterval.

Template Parameters
IUsed to disable this overload for closed intervals. Do not supply it.
Returns
True if the lower bound is closed.
Exceptions
noneNo throw guarantee

◆ left_open()

template<typename IntervalType>
template<typename I = interval_t, std::enable_if_t< is_general_interval_v< I >, int > = 0>
bool sigma::Triplex< IntervalType >::left_open ( ) const
inline

Is lower() NOT a member of *this?

Only available when interval_t is a GeneralInterval.

Template Parameters
IUsed to disable this overload for closed intervals. Do not supply it.
Returns
True if the lower bound is open. False for the empty triplex.
Exceptions
noneNo throw guarantee

◆ lower()

template<typename IntervalType>
value_t sigma::Triplex< IntervalType >::lower ( ) const
inline

Returns the lower bound.

Returns
The lower bound value
Exceptions
std::domain_errorif *this is empty. Strong throw guarantee.

◆ lower_radius()

template<typename IntervalType>
value_t sigma::Triplex< IntervalType >::lower_radius ( ) const
inline

Returns the distance from the lower bound to the nominal value.

Returns
nominal() - lower()
Exceptions
std::domain_errorif *this is empty. Strong throw guarantee.

◆ median()

template<typename IntervalType>
value_t sigma::Triplex< IntervalType >::median ( ) const
inline

Returns the midpoint of the bounds.

The median is a property of the set and is unrelated to nominal().

Returns
The midpoint of lower() and upper().
Exceptions
std::domain_errorif *this is empty. Strong throw guarantee.

◆ nominal()

template<typename IntervalType>
value_t sigma::Triplex< IntervalType >::nominal ( ) const
inline

Returns the nominal value.

The nominal value is the best estimate of the quantity. It is NOT, in general, the midpoint of the bounds (see median()), nor a statistical expectation.

Returns
The nominal value. May be non-finite if a computation overflowed.
Exceptions
std::domain_errorif *this is empty. Strong throw guarantee.

◆ operator*=()

template<typename IntervalType>
Triplex< IntervalType > & sigma::Triplex< IntervalType >::operator*= ( const Triplex< IntervalType > & rhs)

In-place multiplication by another triplex.

Parameters
rhsThe triplex to multiply by
Returns
Reference to this triplex after multiplication. Empty if either operand is.
Exceptions
noneNo throw guarantee

◆ operator+=()

template<typename IntervalType>
Triplex< IntervalType > & sigma::Triplex< IntervalType >::operator+= ( const Triplex< IntervalType > & rhs)

In-place addition of another triplex.

As for interval_t, the empty triplex is the identity of addition.

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

◆ operator-()

template<typename IntervalType>
Triplex sigma::Triplex< IntervalType >::operator- ( ) const
inline

Negation of a triplex.

Negation is exact, so \( -\langle a, m, b \rangle = \langle -b, -m, -a \rangle \), with the openness of the bounds swapped.

Returns
A new triplex with negated bounds and nominal value
Exceptions
noneNo throw guarantee

◆ operator-=()

template<typename IntervalType>
Triplex< IntervalType > & sigma::Triplex< IntervalType >::operator-= ( const Triplex< IntervalType > & rhs)

In-place subtraction of another triplex.

As for interval_t, subtracting from the empty triplex negates rhs.

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

◆ operator/=()

template<typename IntervalType>
Triplex< IntervalType > & sigma::Triplex< IntervalType >::operator/= ( const Triplex< IntervalType > & rhs)

In-place division by another triplex.

As for interval_t, division by an interval containing zero is an error, even when the nominal value of rhs is not zero.

Parameters
rhsThe triplex to divide by
Returns
Reference to this triplex after division. Empty if either operand is.
Exceptions
std::domain_errorif rhs contains zero. Strong throw guarantee.

◆ right_closed()

template<typename IntervalType>
template<typename I = interval_t, std::enable_if_t< is_general_interval_v< I >, int > = 0>
bool sigma::Triplex< IntervalType >::right_closed ( ) const
inline

Is upper() a member of *this?

Only available when interval_t is a GeneralInterval.

Template Parameters
IUsed to disable this overload for closed intervals. Do not supply it.
Returns
True if the upper bound is closed.
Exceptions
noneNo throw guarantee

◆ right_open()

template<typename IntervalType>
template<typename I = interval_t, std::enable_if_t< is_general_interval_v< I >, int > = 0>
bool sigma::Triplex< IntervalType >::right_open ( ) const
inline

Is upper() NOT a member of *this?

Only available when interval_t is a GeneralInterval.

Template Parameters
IUsed to disable this overload for closed intervals. Do not supply it.
Returns
True if the upper bound is open. False for the empty triplex.
Exceptions
noneNo throw guarantee

◆ upper()

template<typename IntervalType>
value_t sigma::Triplex< IntervalType >::upper ( ) const
inline

Returns the upper bound.

Returns
The upper bound value
Exceptions
std::domain_errorif *this is empty. Strong throw guarantee.

◆ upper_radius()

template<typename IntervalType>
value_t sigma::Triplex< IntervalType >::upper_radius ( ) const
inline

Returns the distance from the nominal value to the upper bound.

Returns
upper() - nominal()
Exceptions
std::domain_errorif *this is empty. Strong throw guarantee.

◆ width()

template<typename IntervalType>
value_t sigma::Triplex< IntervalType >::width ( ) const
inline

Returns the distance between the bounds.

Returns
upper() - lower(), as computed by interval_t.
Exceptions
std::domain_errorif *this is empty. Strong throw guarantee.

◆ operator!=()

template<typename I1, typename I2>
bool operator!= ( const Triplex< I1 > & lhs,
const Triplex< I2 > & rhs )
related

Compare two triplex numbers for inequality.

Template Parameters
I1The interval type of the left-hand triplex
I2The interval type of the right-hand triplex
Parameters
lhsThe first triplex
rhsThe second triplex
Returns
Whether the instances are not equivalent
Exceptions
noneNo throw guarantee

◆ operator*

template<typename IntervalType>
Triplex operator* ( Triplex< IntervalType > lhs,
const Triplex< IntervalType > & rhs )
friend

Multiplication of two triplex numbers.

Either operand may also be a value_t, which is converted.

Parameters
lhsThe left-hand triplex
rhsThe right-hand triplex
Returns
The product of lhs and rhs
Exceptions
noneNo throw guarantee

◆ operator+

template<typename IntervalType>
Triplex operator+ ( Triplex< IntervalType > lhs,
const Triplex< IntervalType > & rhs )
friend

Addition of two triplex numbers.

Either operand may also be a value_t, which is converted.

Parameters
lhsThe left-hand triplex
rhsThe right-hand triplex
Returns
The sum of lhs and rhs
Exceptions
noneNo throw guarantee

◆ operator-

template<typename IntervalType>
Triplex operator- ( Triplex< IntervalType > lhs,
const Triplex< IntervalType > & rhs )
friend

Subtraction of two triplex numbers.

Either operand may also be a value_t, which is converted.

Parameters
lhsThe left-hand triplex
rhsThe right-hand triplex
Returns
The difference of lhs and rhs
Exceptions
noneNo throw guarantee

◆ operator/

template<typename IntervalType>
Triplex operator/ ( Triplex< IntervalType > lhs,
const Triplex< IntervalType > & rhs )
friend

Division of two triplex numbers.

Either operand may also be a value_t, which is converted.

Parameters
lhsThe left-hand triplex
rhsThe right-hand triplex
Returns
The quotient of lhs and rhs
Exceptions
std::domain_errorif rhs contains zero. Strong throw guarantee.

◆ operator<()

template<typename IntervalType>
bool operator< ( const Triplex< IntervalType > & lhs,
const Triplex< IntervalType > & rhs )
related

Orders two triplex numbers, primarily by their nominal values.

As for Interval's ordering by median, this is a total order meant for sorting and not an enclosure relation. Triplex numbers are compared lexicographically by nominal value, then lower bound, then upper bound, and then, for a general triplex, by the openness of the lower and upper bounds, with a closed bound before an open one. The tie-breaks make the order consistent with operator==: neither of two triplex numbers precedes the other exactly when they are equal, so they can be keys of ordered containers. The empty triplex sorts before every non-empty one.

As for plain floating point, a NaN nominal value has no place in the order.

Template Parameters
IntervalTypeThe interval type of the triplex numbers
Parameters
lhsThe first triplex
rhsThe second triplex
Returns
Whether lhs precedes rhs.
Exceptions
noneNo throw guarantee

◆ operator<<()

template<typename IntervalType>
std::ostream & operator<< ( std::ostream & os,
const Triplex< IntervalType > & t )
related

Overload stream insertion to print a triplex.

The triplex is printed as "[lower, nominal, upper]", with a parenthesis in place of the bracket for an open bound. The empty triplex prints as "∅".

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

◆ operator==()

template<typename I1, typename I2>
bool operator== ( const Triplex< I1 > & lhs,
const Triplex< I2 > & rhs )
related

Compare two triplex numbers for equality.

Two triplex numbers are equal if their intervals, including the openness of any bound, and their nominal values are equal.

Template Parameters
I1The interval type of the left-hand triplex
I2The interval type of the right-hand triplex
Parameters
lhsThe first triplex
rhsThe second triplex
Returns
Whether the instances are equivalent
Exceptions
noneNo throw guarantee

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