Module inari::_docs::conformance

Expand description

Conformance to the standard

inari implements a subset of IEEE Std 1788-2015. This page describes the current status of conformance to the standard.

This section lists the interval operations defined in the standard along with their implementations. Most of the operations are implemented in the same manner for Interval (bare intervals) and DecInterval (decorated intervals). Any differences in the API for these types is noted explicitly.

Some operations are only available when the crate is built with the conditional feature gmp, which is enabled by default.

Required operations

Interval constants

Operation	Implementation	Requires `gmp`
empty()	`Interval::EMPTY`	-
entire()	`Interval::ENTIRE`	-

Forward-mode elementary functions

Operation	Implementation	Requires `gmp`
neg(x)	`-x`	-
add(x, y)	`x + y`	-
sub(x, y)	`x - y`	-
mul(x, y)	`x * y`	-
div(x, y)	`x / y`	-
recip(x)	`x.recip()`	-
sqr(x)	`x.sqr()`	-
sqrt(x)	`x.sqrt()`	-
fma(x, y, z)	`x.mul_add(y, z)`	-
pown(x, n)	`x.powi(n)`	Yes
pow(x, y)	`x.pow(y)`	Yes
exp(x)	`x.exp()`	Yes
exp2(x)	`x.exp2()`	Yes
exp10(x)	`x.exp10()`	Yes
log(x)	`x.ln()`	Yes
log2(x)	`x.log2()`	Yes
log10(x)	`x.log10()`	Yes
sin(x)	`x.sin()`	Yes
cos(x)	`x.cos()`	Yes
tan(x)	`x.tan()`	Yes
asin(x)	`x.asin()`	Yes
acos(x)	`x.acos()`	Yes
atan(x)	`x.atan()`	Yes
atan2(y, x)	`y.atan2(x)`	Yes
sinh(x)	`x.sinh()`	Yes
cosh(x)	`x.cosh()`	Yes
tanh(x)	`x.tanh()`	Yes
asinh(x)	`x.asinh()`	Yes
acosh(x)	`x.acosh()`	Yes
atanh(x)	`x.atanh()`	Yes
sign(x)	`x.sign()`	-
ceil(x)	`x.ceil()`	-
floor(x)	`x.floor()`	-
trunc(x)	`x.trunc()`	-
roundTiesToEven(x)	`x.round_ties_to_even()`	-
roundTiesToAway(x)	`x.round()`	-
abs(x)	`x.abs()`	-
min(x, y)	`x.min(y)`	-
max(x, y)	`x.max(y)`	-

Reverse-mode elementary functions

Not implemented.

Two-output division

Operation	Implementation	Requires `gmp`
mulRevToPair(x, y)	`Interval::mul_rev_to_pair`	-

Cancellative addition and subtraction

Operation	Implementation	Requires `gmp`
cancelMinus(x, y)	`Interval::cancel_minus`	-
cancelPlus(x, y)	`Interval::cancel_plus`	-

Set operations

Operation	Implementation	Requires `gmp`
intersection(x, y)	`x.intersection(y)`	-
convexHull(x, y)	`x.convex_hull(y)`	-

Constructors

Operation	Implementation	Requires `gmp`
numsToInterval(a, b)	`interval!(a, b)` `const_interval!(a, b)` `dec_interval!(a, b)` `const_dec_interval!(a, b)`	-
textToInterval(s)	`interval!(s)` `dec_interval!(s)`	Yes

Numeric functions of intervals

Operation	Implementation	Requires `gmp`
inf(x)	`x.inf()`	-
sup(x)	`x.sup()`	-
mid(x)	`x.mid()`	-
wid(x)	`x.wid()`	-
rad(x)	`x.rad()`	-
mag(x)	`x.mag()`	-
mig(x)	`x.mig()`	-

Boolean functions of intervals

Operation	Implementation	Requires `gmp`
isEmpty(x)	`x.is_empty()`	-
isEntire(x)	`x.is_entire()`	-
isNaI(x)	`x.is_nai()` for `DecInterval`	-
equal(x, y)	`x == y`	-
subset(x, y)	`x.subset(y)`	-
less(x, y)	`x.less(y)`	-
precedes(x, y)	`x.precedes(y)`	-
interior(x, y)	`x.interior(y)`	-
strictLess(x, y)	`x.strict_less(y)`	-
strictPrecedes(x, y)	`x.strict_precedes(y)`	-
disjoint(x, y)	`x.disjoint(y)`	-

Recommended operations

Forward-mode elementary functions

Not implemented.

Slope functions

Not implemented.

Boolean functions of intervals

Operation	Implementation	Requires `gmp`
isCommonInterval(x)	`x.is_common_interval()`	-
isSingleton(x)	`x.is_singleton()`	-
isMember(x, y)	`y.contains(x)`	-

Extended interval comparison

Operation	Implementation	Requires `gmp`
overlap(x, y)	`x.overlap(y)` `x.overlap(y)` for `DecInterval`	-

Exact reduction operations

Not implemented.

Operations on/with decorations

Operation	Implementation	Requires `gmp`
newDec(x)	`DecInterval::new(x)`	-
intervalPart(x)	`x.interval()`	-
decorationPart(x)	`x.decoration()`	-
setDec(x, dx)	`DecInterval::set_dec(x, dx)`	-

Comparison of decorations is implemented as defined in the standard.

Input and output (I/O) of intervals

Input

See Constructors.

Output

Operation	Implementation	Requires `gmp`
intervalToText(x)	`format!("{}", x)` (fixed-point, lowercase) `format!("{:e}", x)` (scientific, lowercase) `format!("{:x}", x)` (hexadecimal, lowercase)	Yes

Exact text representation

Operation	Implementation	Requires `gmp`
intervalToExact(x)	`format!("{:x}", x)`	Yes
exactToInterval(s)	`interval_exact!(s)`	Yes

Interchange representations and encodings

Implemented as x.to_be_bytes(), x.to_le_bytes(), x.to_ne_bytes(), x.try_from_be_bytes(), x.try_from_le_bytes() and x.try_from_ne_bytes(). These operations do not require gmp.

Implementation conformance questionnaire

a. Implementation-defined behavior

What status flags or other means to signal the occurrence of certain decoration values in computations does the implementation provide if any?

inari does not signal occurrence of decoration values.

Does the implementation provide the set-based flavor? If so answer the following set of questions.

b. Documentation of behavior

If the implementation supports implicit interval types, how is the interval hull operation realized?

inari does not have implicit interval types.
What accuracy is achieved (i.e., tightest, accurate, or valid) for each of the implementation’s interval operations?

Unless otherwise noted, all operations return the tightest results.
Under what conditions is a constructor unable to determine whether a Level 1 value exists that corresponds to the supplied inputs?

interval!(s) and dec_interval!(s) return an Err with IntervalErrorKind::PossiblyUndefinedOperation when the exponent does not fit within the range of i32, or the mantissa has impractically many digits after the decimal point.
How are cases for rounding a Level 1 value to an F-number handled that are not covered by the rules given in 12.12.8?

See the documentation of Interval::mid and Interval::rad.
How are interval datums converted to their exact text representations?

The user can use format!("{:x}", x) to convert an interval to its exact representation. The result is a hexadecimal interval literal, the detail of which may depend on implementation of MPFR.

c. Implementation-defined behavior

Does the implementation include the interval overlapping function? If so, how is it made available to the user?

Yes, it is provided by Interval::overlap and DecInterval::overlap. Note that the former returns Overlap, while the latter returns Option<Overlap>.
Does the implementation store additional information in a NaI? What functions are provided for the user to set and read this information?

No, no additional information is stored in NaIs.
What means if any does the implementation provide for an exception to be signaled when a NaI is produced?

inari does not signal production of NaIs.
What interval types are supported besides the required ones?

inari does not have additional interval types.
What mechanisms of exception handling are used in exception handlers provided by the implementation? What additional exception handling is provided by the implementation?

Some operations that may fail return Option<T> or Result<T>, which can be handled with the Rust’s standard error handling mechanism.
What is the tie-breaking method used in rounding of supported number formats F that are not IEEE 754 conforming?

inari does not support non IEEE 754 number formats.
Does the implementation include different versions of the same operation for a given type and how are these provided to the user?

There are no such operations at the moment.
What combinations of formats are supported in interval constructors?

interval!(a, b), dec_interval!(a, b) and their const_* versions take two f64 values. interval!(s) and dec_interval!(s) take a string slice.
What is the tightness of the result of constructor calls in cases where the standard does not specify it?

There are no such cases for the supported interval types.
What methods are used to read or write strings from or to character streams? Does the implementation employ variations in locales (such as specific character case matching)? This includes the syntax used in the strings for reading and writing.

Rust’s UTF-8-encoded string types are used. Only the syntax specified in the standard are supported as an input/output. For output, there are a few options for controlling the format.
What is the tightness of the string to interval conversion for non IEEE 754 conforming interval types and the tightness for the interval to string conversion for all interval types?

inari does not support non IEEE 754 interval types. The tightness of output is valid.
What is the result of Level 3 operations for invalid inputs?

inari prevents creation of invalid interval datums. For invalid inputs, bare interval constructors return an Err with either IntervalErrorKind::UndefinedOperation or IntervalErrorKind::PossiblyUndefinedOperation. See also the answers to b.3 and c.5.
What are the interchange representations of the fields of the standard Level 3 representation listed in 14.4?

The user can choose from the big-endian, the little-endian and the target platform’s native byte orders as the interchange representation of the fields.
What decorations does the implementation provide and what is their mathematical definition? How are these decorations mapped when converting an interval to the interchange format?

The decorations com, dac, def, trv and ill are provided. See intro for their definitions. Each decoration is mapped to 16, 12, 8, 4 and 0, respectively, in the interchange representations.
What interchange formats if any are provided for non IEEE 754 interval formats and on non IEEE 754 systems? How are these provided to the user?

No such interval formats/number systems are supported.

Does the implementation support the compressed arithmetic sub-profile of the set-based profile? If so answer the following set of questions.

No, compressed interval formats are not supported.

Does the implementation provide non-standard flavors not defined in this standard? If so answer the following questions for each additional flavor.

No, non-standard flavors are not supported.