Struct Ival 

pub struct Ival { /* private fields */ }

A standard Rival interval containing two arbitrary-precision endpoints.

A standard interval includes both endpoints. Neither endpoint is allowed to be NaN. Intervals can be either real (with rug::Float endpoints) or boolean (with endpoints 0 or 1).

Boolean intervals

In a boolean interval, false is considered less than true, yielding three boolean interval values:

• True: [1, 1] — constructed with Ival::bool_interval(true, true)
• False: [0, 0] — constructed with Ival::bool_interval(false, false)
• Uncertain: [0, 1] — constructed with Ival::bool_interval(false, true)

Error intervals

Sometimes an interval will contain invalid inputs to some function. For example, sqrt is undefined for negative inputs! In cases like this, Rival’s output interval will only consider valid inputs. Error flags are “sticky”: further computations on an interval will maintain already-set error flags.

Interval Operations

Rival aims to ensure three properties of all helper functions:

• Soundness means output intervals contain any output on inputs drawn from the input intervals. IEEE-1788 refers to this as the output interval being valid.

• Refinement means, moreover, that narrower input intervals lead to narrower output intervals. Rival’s movability flags make this a somewhat more complicated property than typical.

• Weak completeness means, moreover, that Rival returns the narrowest possible valid interval. IEEE-1788 refers to this as the output interval being tight.

Weak completeness (tightness) is the strongest possible property, while soundness (validity) is the weakest, with refinement somewhere in between.

The typical use case for Rival is to recompute a certain expression at ever higher precision, until the computed interval is narrow enough. However, interval arithmetic is not complete. For example, due to the limitations of the underlying MPFR library, it’s impossible to compute (exp(x) / exp(x)) for large enough values of x.

While it’s impossible to detect this in all cases, Rival provides support for movability flags that can detect many such instances automatically. Movability flags are correctly propagated by all of Rival’s supported operations, and are set by functions such as exp.

Implementations

impl Ival

pub fn add_assign(&mut self, a: &Ival, b: &Ival)

Compute the interval sum a + b.

pub fn sub_assign(&mut self, a: &Ival, b: &Ival)

Compute the interval difference a - b.

pub fn mul_assign(&mut self, a: &Ival, b: &Ival)

Compute the interval product a * b.

pub fn div_assign(&mut self, a: &Ival, b: &Ival)

Compute the interval quotient a / b.

pub fn fma_assign(&mut self, a: &Ival, b: &Ival, c: &Ival)

Compute the interval fused multiply-add a * b + c.

pub fn fdim_assign(&mut self, x: &Ival, y: &Ival)

Compute the interval positive difference fdim(x, y) = max(x - y, 0).

pub fn hypot_assign(&mut self, x: &Ival, y: &Ival)

Compute the interval Euclidean distance hypot(x, y) = sqrt(x² + y²).

impl Ival

pub fn not_assign(&mut self, input: &Ival)

Compute the interval logical NOT of input.

pub fn and_assign(&mut self, lhs: &Ival, rhs: &Ival)

Compute the interval logical AND of lhs and rhs.

pub fn or_assign(&mut self, lhs: &Ival, rhs: &Ival)

Compute the interval logical OR of lhs and rhs.

pub fn eq_assign(&mut self, lhs: &Ival, rhs: &Ival)

Compute the interval equality comparison lhs == rhs.

pub fn ne_assign(&mut self, lhs: &Ival, rhs: &Ival)

Compute the interval inequality comparison lhs != rhs.

pub fn lt_assign(&mut self, lhs: &Ival, rhs: &Ival)

Compute the interval less-than comparison lhs < rhs.

pub fn le_assign(&mut self, lhs: &Ival, rhs: &Ival)

Compute the interval less-than-or-equal comparison lhs <= rhs.

pub fn gt_assign(&mut self, lhs: &Ival, rhs: &Ival)

Compute the interval greater-than comparison lhs > rhs.

pub fn ge_assign(&mut self, lhs: &Ival, rhs: &Ival)

Compute the interval greater-than-or-equal comparison lhs >= rhs.

pub fn if_assign(&mut self, cond: &Ival, when_true: &Ival, when_false: &Ival)

Compute an interval conditional: if cond then when_true else when_false.

Here, cond must be a boolean interval, while when_true and when_false should be intervals of the same type, either both real or both boolean. If cond is uncertain, the union of when_true and when_false is returned.

Note that typically, uses of if_assign are incomplete because they are not flow-sensitive. For example, if (x < 0) then (-x) else x is always non-negative, but both branches evaluate to the same interval because the condition does not refine the value of x in either branch.

pub fn error_assign(&mut self, input: &Ival)

Returns a boolean interval indicating whether any inputs were discarded when computing input.

These flags are “sticky”: further computations on input will maintain the already-set error flags.

pub fn assert_assign(&mut self, cond: &Ival)

Returns an illegal interval if cond is false, a legal interval if cond is true, and a partially-legal one if cond’s truth value is unknown. The value of the output interval is always true.

impl Ival

pub fn set_pi(&mut self)

Set this interval to contain π.

pub fn set_e(&mut self)

Set this interval to contain e.

impl Ival

pub fn monotonic_assign<F>(&mut self, mpfr_func: &F, a: &Ival)

where F: Fn(&Float, &mut Float, Round) -> bool,

Lift a (weakly) monotonic MPFR function to a function on intervals.

A weakly monotonic function is one where larger inputs produce larger (or equal) outputs. Note that if a non-monotonic function is passed, the results will not be sound.

pub fn comonotonic_assign<F>(&mut self, mpfr_func: &F, a: &Ival)

where F: Fn(&Float, &mut Float, Round) -> bool,

Lift a (weakly) co-monotonic MPFR function to a function on intervals.

A weakly co-monotonic function is one where larger inputs produce smaller (or equal) outputs. Note that if a non-co-monotonic function is passed, the results will not be sound.

pub fn neg_assign(&mut self, a: &Ival)

Compute the interval negation of a.

pub fn fabs_assign(&mut self, x: &Ival)

Compute the interval absolute value of x.

pub fn sqrt_assign(&mut self, a: &Ival)

Compute the interval square root of a.

pub fn cbrt_assign(&mut self, a: &Ival)

Compute the interval cube root of a.

pub fn exp_assign(&mut self, a: &Ival)

Compute the interval exponential of a.

pub fn exp2_assign(&mut self, a: &Ival)

Compute the interval base-2 exponential of a.

pub fn expm1_assign(&mut self, a: &Ival)

Compute the interval exp(a) - 1.

pub fn log_assign(&mut self, a: &Ival)

Compute the interval natural logarithm of a.

pub fn log2_assign(&mut self, a: &Ival)

Compute the interval base-2 logarithm of a.

pub fn log10_assign(&mut self, a: &Ival)

Compute the interval base-10 logarithm of a.

pub fn log1p_assign(&mut self, a: &Ival)

Compute the interval log(1 + a).

pub fn logb_assign(&mut self, a: &Ival)

Compute the interval logb (exponent extraction) of a.

pub fn asin_assign(&mut self, a: &Ival)

Compute the interval arcsine of a.

pub fn acos_assign(&mut self, a: &Ival)

Compute the interval arccosine of a.

pub fn atan_assign(&mut self, a: &Ival)

Compute the interval arctangent of a.

pub fn atan2_assign(&mut self, y: &Ival, x: &Ival)

Compute the interval two-argument arctangent atan2(y, x).

pub fn sinh_assign(&mut self, a: &Ival)

Compute the interval hyperbolic sine of a.

pub fn cosh_assign(&mut self, a: &Ival)

Compute the interval hyperbolic cosine of a.

pub fn tanh_assign(&mut self, a: &Ival)

Compute the interval hyperbolic tangent of a.

pub fn asinh_assign(&mut self, a: &Ival)

Compute the interval inverse hyperbolic sine of a.

pub fn acosh_assign(&mut self, a: &Ival)

Compute the interval inverse hyperbolic cosine of a.

pub fn atanh_assign(&mut self, a: &Ival)

Compute the interval inverse hyperbolic tangent of a.

pub fn erf_assign(&mut self, a: &Ival)

Compute the interval error function of a.

pub fn erfc_assign(&mut self, a: &Ival)

Compute the interval complementary error function of a.

pub fn rint_assign(&mut self, a: &Ival)

Compute the interval round-to-integer of a.

pub fn round_assign(&mut self, a: &Ival)

Compute the interval round-to-integer of a.

pub fn ceil_assign(&mut self, a: &Ival)

Compute the interval ceiling of a.

pub fn floor_assign(&mut self, a: &Ival)

Compute the interval floor of a.

pub fn trunc_assign(&mut self, a: &Ival)

Compute the interval truncation of a.

pub fn fmin_assign(&mut self, a: &Ival, b: &Ival)

Compute the interval minimum of a and b.

pub fn fmax_assign(&mut self, a: &Ival, b: &Ival)

Compute the interval maximum of a and b.

pub fn copysign_assign(&mut self, x: &Ival, y: &Ival)

Compute the interval copysign(x, y).

impl Ival

pub fn fmod_assign(&mut self, x: &Ival, y: &Ival)

Compute the interval floating-point remainder fmod(x, y).

pub fn remainder_assign(&mut self, x: &Ival, y: &Ival)

Compute the interval remainder remainder(x, y).

impl Ival

pub fn pow_assign(&mut self, x: &Ival, y: &Ival)

Compute the interval power x^y.

pub fn pow2_assign(&mut self, x: &Ival)

impl Ival

pub fn cos_assign(&mut self, x: &Ival)

Compute the interval cosine of x.

pub fn sin_assign(&mut self, x: &Ival)

Compute the interval sine of x.

pub fn tan_assign(&mut self, x: &Ival)

Compute the interval tangent of x.

impl Ival

pub fn lo(&self) -> &Float

Returns the low endpoint of this interval.

pub fn hi(&self) -> &Float

Returns the high endpoint of this interval.

pub fn lo_mut(&mut self) -> &mut Float

pub fn hi_mut(&mut self) -> &mut Float

pub fn lo_immovable(&self) -> bool

pub fn hi_immovable(&self) -> bool

pub fn set_immovable(&mut self, lo: bool, hi: bool)

pub fn error_flags(&self) -> ErrorFlags

pub fn set_error_flags(&mut self, err: ErrorFlags)

pub fn prec(&self) -> u32

pub fn set_prec(&mut self, prec: u32)

pub fn from_lo_hi(lo: Float, hi: Float) -> Self

Construct an interval from two endpoints.

If either endpoint is NaN, or if lo == hi and both are infinite, an illegal interval is returned (with error flags set). The interval is considered movable.

pub fn bool_interval(lo_true: bool, hi_true: bool) -> Self

Construct a boolean interval.

A boolean interval has 2-bit precision endpoints: false is represented as 0 and true as 1. Boolean intervals are always immovable.

pub fn f64_assign(&mut self, value: f64)

pub fn zero(prec: u32) -> Self

pub fn union_assign(&mut self, other: Ival)

Compute the union of this interval with other.

Maintains error flags, and movability flags when possible. If either interval is totally in error, the other is used with its partial error flag set.

pub fn split_at(&self, val: &Float) -> (Ival, Ival)

Split an interval at a point, returning the two halves of that interval on either side of the split point.

Trait Implementations

impl Clone for Ival

fn clone(&self) -> Ival

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Ival

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Hash for Ival

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Ival

fn eq(&self, other: &Ival) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Ival

impl StructuralPartialEq for Ival