# IntervalArithmetic.jl API

## External

### Types

`DecoratedInterval`

A `DecoratedInterval`

is an interval, together with a *decoration*, i.e. a flag that records the status of the interval when thought of as the result of a previously executed sequence of functions acting on an initial interval.

An `IntervalBox`

is an `N`

-dimensional rectangular box, given by a Cartesian product of a vector of `N`

`Interval`

s.

`Region{T} = Union{Interval{T}, IntervalBox{T}}`

### Macros

The `@biginterval`

macro constructs an interval with `BigFloat`

entries.

The `@floatinterval`

macro constructs an interval with `Float64`

entries.

`@format [style::Symbol] [decorations::Bool] [sigfigs::Integer]`

The `@format`

macro provides a simple interface to control the output format for intervals. These options are passed to the `setformat`

function. It returns the new `DisplayParameters`

object.

The arguments may be in any order and of type:

`Symbol`

: the output format (`:full`

,`:standard`

or`:midpoint`

)`Bool`

: whether to display decorations`Integer`

: the number of significant figures

E.g.

```
julia> x = 0.1..0.3
@[0.0999999, 0.300001]
julia> @format full
Display parameters:
- format: full
- decorations: false
- significant figures: 6
julia> x
Interval(0.09999999999999999, 0.30000000000000004)
julia> @format standard 3
Display parameters:
- format: standard
- decorations: false
- significant figures: 3
julia> x
[0.0999, 0.301]
```

The `@interval`

macro is the main method to create an interval. It converts each expression into a narrow interval that is guaranteed to contain the true value passed by the user in the one or two expressions passed to it. When passed two expressions, it takes the hull of the resulting intervals to give a guaranteed containing interval.

Examples:

```
@interval(0.1)
@interval(0.1, 0.2)
@interval(1/3, 1/6)
@interval(1/3^2)
```

### Methods

`bisect(X::Interval, α=0.49609375)`

Split the interval `X`

at position α; α=0.5 corresponds to the midpoint. Returns a tuple of the new intervals.

`bisect(X::IntervalBox, α=0.49609375)`

Bisect the `IntervalBox`

`X`

at position α ∈ [0,1] along its longest side.

`bisect(X::IntervalBox, i::Integer, α=0.49609375)`

Bisect the `IntervalBox`

in side number `i`

.

`cancelminus(a, b)`

Return the unique interval `c`

such that `b+c=a`

.

See Section 12.12.5 of the IEEE-1788 Standard for Interval Arithmetic.

`cancelminus(xx, yy)`

Decorated interval extension; the result is decorated as `trv`

, following the IEEE-1788 Standard (see Sect. 11.7.1, pp 47).

`cancelplus(a, b)`

Returns the unique interval `c`

such that `b-c=a`

; it is equivalent to `cancelminus(a, −b)`

.

`cancelplus(xx, yy)`

Decorated interval extension; the result is decorated as `trv`

, following the IEEE-1788 Standard (see Sect. 11.7.1, pp 47).

`emptyinterval`

s are represented as the interval [∞, -∞]; note that this interval is an exception to the fact that the lower bound is larger than the upper one.

`entireinterval`

s represent the whole Real line: [-∞, ∞].

`hull(a, b)`

Returns the "interval hull" of the intervals `a`

and `b`

, considered as (extended) sets of real numbers, i.e. the smallest interval that contains all of `a`

and `b`

.

`hull(xx, yy)`

Decorated interval extension; the result is decorated as `trv`

, following the IEEE-1788 Standard (see Sect. 11.7.1, pp 47).

`interval(a, b)`

`interval(a, b)`

checks whether [a, b] is a valid `Interval`

, which is the case if `-∞ <= a <= b <= ∞`

, using the (non-exported) `is_valid_interval`

function. If so, then an `Interval(a, b)`

object is returned; if not, then an error is thrown.

`isatomic(x::Interval)`

Check whether an interval `x`

is *atomic*, i.e. is unable to be split. This occurs when the interval is empty, or when the upper bound equals the lower bound or the `nextfloat`

of the lower bound.

`iscommon(x)`

Checks if `x`

is a **common interval**, i.e. a non-empty, bounded, real interval.

`isthin(x)`

Checks if `x`

is the set consisting of a single exactly representable float. Any float which is not exactly representable does *not* yield a thin interval. Corresponds to `isSingleton`

of the standard.

`mince(x::Interval, n)`

Splits `x`

in `n`

intervals of the same diameter, which are returned as a vector.

`mince(x::IntervalBox, n)`

Splits `x`

in `n`

intervals in each dimension of the same diameter. These intervals are combined in all possible `IntervalBox`

-es, which are returned as a vector.

`pow(x::Interval, n::Integer)`

A faster implementation of `x^n`

, currently using `power_by_squaring`

. `pow(x, n)`

will usually return an interval that is slightly larger than that calculated by `x^n`

, but is guaranteed to be a correct enclosure when using multiplication with correct rounding.

`radius(a::Interval)`

Return the radius of the `Interval`

`a`

, such that `a ⊆ m ± radius`

, where `m = mid(a)`

is the midpoint.

`setformat(format=none; decorations=none, sigfigs=none)`

`setformat`

changes how intervals are displayed. It returns the new `DisplayParameters`

object.

Note that The `@format`

macro is more user-friendly.

The following options are available:

`format`

: interval output format`:standard`

:`[1, 2]`

`:full`

:`Interval(1, 2)`

`:midpoint`

: 1.5 ± 0.5

`sigfigs`

: number of significant figures to show in`standard`

mode; the default is 6`decorations`

(boolean): show decorations or not

Example:

```
julia> setformat(:full, decorations=true)
Display parameters:
- format: full
- decorations: true
- significant figures: 6
```

`setrounding(T, mode)`

Set the rounding mode of floating point type `T`

, controlling the rounding of basic arithmetic functions (`+`

, `-`

, `*`

, `/`

and `sqrt`

) and type conversion. Other numerical functions may give incorrect or invalid values when using rounding modes other than the default `RoundNearest`

.

Note that this is currently only supported for `T == BigFloat`

.

Warning

This function is not thread-safe. It will affect code running on all threads, but its behavior is undefined if called concurrently with computations that use the setting.

`setrounding(f::Function, T, mode)`

Change the rounding mode of floating point type `T`

for the duration of `f`

. It is logically equivalent to:

```
old = rounding(T)
setrounding(T, mode)
f()
setrounding(T, old)
```

See `RoundingMode`

for available rounding modes.

`setrounding(Interval, rounding_type::Symbol)`

Set the rounding type used for all interval calculations on Julia v0.6 and above. Valid `rounding_type`

s are (:fast, :tight, :accurate, :slow, :none).