template class Interval < typename BoundType,  typename Rounding>

C++ source of an example

This file provides tutorial on how to use inteval arithmetics included in CAPD package. For exact information on interface of class Interval see the header file "include/capd/interval/Interval.h"

Content of this file:


Template parameters

Template class Interval has two parameters
template class Interval <typename BoundType, typename Rounding = BoundType>
The following lines defines new names for intervals with endpoints type: double, int, MpfrClass correspondigly
typedef capd::intervals::Interval< double, capd::rounding::DoubleRounding> DInterval;
typedef capd::intervals::Interval< int, capd::rounding::IntRounding> IntInterval;
typedef capd::intervals::Interval< capd::multiPrec::MpfrClass> MpfrInterval;

Because most of the functions are common for intervals with arbitrary endpoints we use general type interval in the following sections. 
For an example it can be defined as follows

typedef DInterval interval;

Remark: if you include file "capd/interval/DoubleInterval.h" then interval is already defined as Interval< double, DoubleRounding>.

How to create an interval?

We can construct interval by :
interval a;
interval b(1.0);
interval c(2.0, 3.0);
interval d(c);
// a is in general not initialized
// b = [1.0, 1.0]
// c = [2.0, 3.0]
// d = [2.0, 3.0]

The state of interval a depends on flag __INTERVAL_INIT_0__.
If this flag is set in file include/capd/interval/intervalSettings.h than a = [0.0, 0.0],
otherwise a is not initialized (this is the default behaviour).

How to access interval end points?

To obtain left or right end point of the interval we can use leftBound or rightBound functions. They are implemented  both as member and global functions.

Example:
interval c(2.0, 3.0);

// member functions
c.leftBound();
c.rightBound();

// or global functions
leftBound(c);
rightBound(c);



// the result is 2.0
// the result is 3.0


// the result is 2.0
// the result is 3.0

To get point interval that contains left or right end point we use function left or right correspondigly

c.left(); 
left(c);

c.right();
right(c);
// or
// in both cases the result is an interval [2.0, 2.0]

// or
// in both cases the result is an interval [3.0, 3.0]

Remark: there is no function to change only one of the endpoints. For example to change only left end point you can use the following code
c = interval(1.0, c.rightBound());
In this way e.g. you can force constructor to check if interval endpoints are in good order (see Interval Options).

Writting and reading intervals

Intervals can be written to any stream in C++ way using operator <<.  The output depends on parameters of a stream e.g precision.
interval a(1.0, 2.0);
std::cout << a;
std::cout << fixed << setprecision(6) << a;

// output: [1,2]
// output: [1.000000,2.000000]

To read intervals from given stream (e.g. keyboard, file or memory) use operator >>.  Input should be of the form :
[leftEnd,rightEnd]
where leftEnd and rightEnd should be of the form that can be read with operator >> and converted to BoundType object.
interval a;
std::istringstream myStr("[3.21312312, 4.324324324]");
myStr >> a;

Logical operators and inclusions

Operator True if
b==c;
both end points are the same
b!=c;
at least one end point differs
b>c;
b>=c;
b<c;
b<=c;
it is true for any two points from intervals b and c.
For example:  b>c if  leftBound(b) > rightBound(c)

The same operators can be applied if one of the intervals is repleaced by a number (in fact it is treated as point interval) e.g.    b == 1.0;    b < 2.0;

For two intervals one can check inclusions.

True if
c.contains(b);
c.contains(2.5);
c contains b
c contains number 2.5
c.containsInInterior(b);
c contains b in the interior
c.subset(b);
c is subset of b
c.subsetInterior(b);
c is subset of the interior of b

Note: on standard output true is converted into integer value 1 and false into 0.

Arithmetic operators

Arithmetic operations for intervals are implemented in this way that their result always contains all possible results.

For example if  
interval a(-1,0, 2.0), b(1.0, 2.0);
then

Operation Code Result
Sum
a + b;
[0.0, 4.0]
Substraction
a - b;
[-3.0, 1.0]
Product
a * b;
[-2.0, 4.0]
Division
a / b;
[-1.0, 2.0]

If in division b contains 0 then an exception is thrown.

Every arithmetic operation of form  
a = a + b; 
a = a - b;
a = a * b;
a = a / b;
can be also shorten to
a += b;
a -= b;
a *= b;
a /= b;

Elementary functions

Most of the basic functions has his interval version. To be rigorous returned value is always an interval which is upper estimate of the true result. Functions are called exactly in the same way like standard functions operating on doubles.
List of all implemented functions:

Function For an interval x it returns:
power(x, n) xn, where n is an integer
power(x, a) xa, where a is an interval
sqrt(x) square root of x
sin(x), cos(x), tan(x), cot(x) sinus of x, etc.
sinh(x), cosh(x), tanh(x), coth(x) hyperbolic sinus of x, etc.
exp(x) exponens of x
log(x)  natural logarithm of x

Interval specific functions

In this section we collect several usefull functions.

Constants

Two constants : pi and euler are provided by static member fuctions pi and euler

Example:
// returns interval that contains pi constant
interval::pi();

// returns interval that contains euler constant
interval::euler(); 
Note that an output is an interval that containts true value of the constant,
so it strongly depends on type of interval endpoints used.

Remark: When using MpfrClass as an endpoint, the returned value depends also on the precision currently used.

Interval Settings

In file "include/capd/interval/IntervalSetting.h" there are several flags which can be switched on/off  by (un)commenting appropriate line of code:

Flag If switched on Default
__DEBUGGING__  it turns on debugging mode. We check intervals  during each operation and throw exception if interval is not valid. off
__INTERVAL_INIT_0__
default constructor initializes intervals to be [0.0, 0.0].
By default this option is switched off and an interval is not initialized.
off
__INTERVAL_SPEED_OPTIMIZED__ it speeds up computations but enlarges programm size.
It couses many functions to be defined as inline
on
__INTERVAL_DEPRECATED__
it allows use of deprecated functions for backward compatibility. off