multiprecision/doc/tutorial_interval_mpfi.qbk

[/
  Copyright 2011 - 2020 John Maddock.
  Copyright 2013 - 2019 Paul A. Bristow.
  Copyright 2013 Christopher Kormanyos.

  Distributed under the Boost Software License, Version 1.0.
  (See accompanying file LICENSE_1_0.txt or copy at
  http://www.boost.org/LICENSE_1_0.txt).
]

[section:interval Interval Number Types]

There is one currently only one interval number type supported - [mpfi].

[section:mpfi mpfi_float]

`#include <boost/multiprecision/mpfi.hpp>`

   namespace boost{ namespace multiprecision{

   template <unsigned Digits10>
   class mpfi_float_backend;

   typedef number<mpfi_float_backend<50> >    mpfi_float_50;
   typedef number<mpfi_float_backend<100> >   mpfifloat_100;
   typedef number<mpfi_float_backend<500> >   mpfifloat_500;
   typedef number<mpfi_float_backend<1000> >  mpfi_float_1000;
   typedef number<mpfi_float_backend<0> >     mpfi_float;

   }} // namespaces

The `mpfi_float_backend` type is used in conjunction with `number`: It acts as a thin wrapper around the [mpfi] `mpfi_t`
to provide an real-number type that is a drop-in replacement for the native C++ floating-point types, but with
much greater precision and implementing interval arithmetic.

Type `mpfi_float_backend` can be used at fixed precision by specifying a non-zero `Digits10` template parameter, or
at variable precision by setting the template argument to zero.  The `typedef`s `mpfi_float_50`, `mpfi_float_100`,
`mpfi_float_500`, `mpfi_float_1000` provide arithmetic types at 50, 100, 500 and 1000 decimal digits precision
respectively.  The `typedef mpfi_float` provides a variable precision type whose precision can be controlled via theF
`number`s member functions.

[note This type only provides `numeric_limits` support when the precision is fixed at compile time.]

As well as the usual conversions from arithmetic and string types, instances of `number<mpfi_float_backend<N> >` are
copy constructible and assignable from:

* The [mpfi] native type `mpfi_t`.
* The `number` wrappers around [mpfi] or [mpfr]: `number<mpfi_float_backend<M> >` and `number<mpfr_float<M> >`.
* There is a two argument constructor taking two `number<mpfr_float<M> >` arguments specifying the interval.

It's also possible to access the underlying `mpfi_t` via the `data()` member function of `mpfi_float_backend`.

Things you should know when using this type:

* A default constructed `mpfi_float_backend` is set to zero (['Note that this is [*not] the default [mpfi] behavior]).
* No changes are made to [gmp] or [mpfr] global settings, so this type can coexist with existing
[mpfr] or [gmp] code.
* The code can equally use [mpir] in place of [gmp] - indeed that is the preferred option on Win32.
* This backend supports rvalue-references and is move-aware, making instantiations of `number` on this backend move aware.
* Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted
as a valid floating-point number.
* Division by zero results in an infinity.

There are some additional non member functions for working on intervals:

  template <unsigned Digits10, expression_template_option ExpressionTemplates>
  number<mpfr_float_backend<Digits10>, ExpressionTemplates> lower(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& val);

Returns the lower end of the interval.

  template <unsigned Digits10, expression_template_option ExpressionTemplates>
  number<mpfr_float_backend<Digits10>, ExpressionTemplates> upper(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& val);

Returns the upper end of the interval.

  template <unsigned Digits10, expression_template_option ExpressionTemplates>
  number<mpfr_float_backend<Digits10>, ExpressionTemplates> median(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& val);

Returns the mid point of the interval.

  template <unsigned Digits10, expression_template_option ExpressionTemplates>
  number<mpfr_float_backend<Digits10>, ExpressionTemplates> width(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& val);

Returns the absolute width of the interval.

  template <unsigned Digits10, expression_template_option ExpressionTemplates>
  number<mpfi_float_backend<Digits10>, ExpressionTemplates> intersect(
    const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a,
    const number<mpfi_float_backend<Digits10>, ExpressionTemplates>&  b);

Returns the interval which is the intersection of the ['a] and ['b].  Returns an
unspecified empty interval if there is no such intersection.

  template <unsigned Digits10, expression_template_option ExpressionTemplates>
  number<mpfi_float_backend<Digits10>, ExpressionTemplates> hull(
    const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a,
    const number<mpfi_float_backend<Digits10>, ExpressionTemplates>&  b);

Returns the interval which is the union of ['a] and ['b].

  template <unsigned Digits10, expression_template_option ExpressionTemplates>
  bool overlap(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a,
               const number<mpfi_float_backend<Digits10>, ExpressionTemplates>&  b);

Returns `true` only if the intervals ['a] and ['b] overlap.

  template <unsigned Digits10, expression_template_option ExpressionTemplates1, expression_template_option ExpressionTemplates2>
  bool in(const number<mpfr_float_backend<Digits10>, ExpressionTemplates1>& a,
          const number<mpfi_float_backend<Digits10>, ExpressionTemplates2>&  b);

Returns `true` only if point ['a] is contained within the interval ['b].

  template <unsigned Digits10, expression_template_option ExpressionTemplates>
  bool zero_in(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a);

Returns `true` only if the interval ['a] contains the value zero.

  template <unsigned Digits10, expression_template_option ExpressionTemplates>
  bool subset(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a,
              const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& b);

Returns `true` only if ['a] is a subset of ['b].

  template <unsigned Digits10, expression_template_option ExpressionTemplates>
  bool proper_subset(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a,
                     const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& b);

Returns `true` only if ['a] is a proper subset of ['b].

  template <unsigned Digits10, expression_template_option ExpressionTemplates>
  bool empty(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a);

Returns `true` only if ['a] is an empty interval, equivalent to `upper(a) < lower(a)`.

  template <unsigned Digits10, expression_template_option ExpressionTemplates>
  bool singleton(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a);

Returns `true` if `lower(a) == upper(a)`.

[h5 [mpfi] example:]

[mpfi_eg]

[endsect] [ section:mpfi mpfi_float]

[endsect] [/section:interval Interval Number Types]