Interface

Intervals

In the icl we have two groups of interval types. There are statically bounded intervals, right_open_interval, left_open_interval, closed_interval, open_interval, that always have the the same kind of interval borders and dynamically bounded intervals, discrete_interval, continuous_interval which can have one of the four possible bound types at runtime.

Table 1.6. Interval class templates

group	form	template	instance parameters
statically bounded	asymmetric	`right_open_interval`	`<class DomainT, template<class>class Compare>`
		`left_open_interval`	`<...same for all interval class templates...>`
	symmetric	`closed_interval`
		`open_interval`
dynamically bounded		`discrete_interval`
		`continuous_interval`

Not every class template works with all domain types. Use interval class templates according the next table.

Table 1.7. Usability of interval class templates for discrete or continuous domain types

group	form	template	discrete	continuous
statically bounded	asymmetric	`right_open_interval`	yes	yes
		`left_open_interval`	yes	yes
	symmetric	`closed_interval`	yes
		`open_interval`	yes
dynamically bounded		`discrete_interval`	yes
		`continuous_interval`		yes

From a pragmatical point of view, the most important interval class template of the statically bounded group is right_open_interval. For discrete domain types also closed intervals might be convenient. Asymmetric intervals can be used with continuous domain types but continuous_interval is the only class template that allows to represent a singleton interval that contains only one element.

Use continuous_interval, if you work with interval containers of countinuous domain types and you want to be able to handle single values:

typedef interval_set<std::string, std::less, continuous_interval<std::string> > IdentifiersT;
IdentifiersT identifiers, excluded;
identifiers += continuous_interval<std::string>::right_open("a", "c");

// special identifiers shall be excluded
identifiers -= std::string("boost");
cout << "identifiers: " << identifiers << endl;

excluded = IdentifiersT(icl::hull(identifiers)) - identifiers;
cout << "excluded   : " << excluded << endl;

//------ Program output: --------
identifiers: {[a,boost)(boost,c)}
excluded   : {[boost,boost]}

Library defaults and class template `interval`

As shown in the example above, you can choose an interval type by instantiating the interval container template with the desired type.

typedef interval_set<std::string, std::less, continuous_interval<std::string> > IdentifiersT;

But you can work with the library default for interval template parameters as well, which is interval<DomainT,Compare>::type.

	interval bounds	domain_type	interval_default
`#ifdef` BOOST_ICL_USE_STATIC_BOUNDED_INTERVALS	static		`right_open_interval`
`#else`	dynamic	discrete	`discrete_interval`
		continuous	`continuous_interval`

So, if you are always happy with the library default for the interval type, just use

icl::interval<MyDomainT>::type myInterval;

as you standard way of declaring intervals and default parameters for interval containers:

typedef interval_set<std::string> IdentifiersT;
IdentifiersT identifiers, excluded;
identifiers += interval<std::string>::right_open("a", "c");
. . .

So class template interval provides a standard way to work with the library default for intervals. Via interval<D,C>::type you can declare a default interval. In addition four static functions

T interval<D,C>::right_open(const D&, const D&);
T interval<D,C>::left_open(const D&, const D&);
T interval<D,C>::closed(const D&, const D&);
T interval<D,C>::open(const D&, const D&);

allow to construct intervals of the library default T = interval<D,C>::type.

If you

#define BOOST_ICL_USE_STATIC_BOUNDED_INTERVALS

the library uses only statically bounded right_open_interval as default interval type. In this case, the four static functions above are also available, but they only move interval borders consistently, if their domain type is discrete, and create an appropriate right_open_interval finally:

interval<D,C>::right_open(a,b) == [a, b)  ->  [a  , b  )
interval<D,C>:: left_open(a,b) == (a, b]  ->  [a++, b++)
interval<D,C>::    closed(a,b) == [a, b]  ->  [a  , b++)
interval<D,C>::      open(a,b) == (a, b)  ->  [a++, b  )

For continuous domain types only the first of the four functions is applicable that matches the library default for statically bounded intervals: right_open_interval. The other three functions can not perform an appropriate tranformation and will not compile.

Sets

The next two tables give an overview over set class templates of the icl.

Table 1.8. Set class templates

group	template	instance parameters
`interval_sets`	`interval_set`	`<DomainT,Compare,IntervalT,Alloc>`
	`separate_interval_set`	`<DomainT,Compare,IntervalT,Alloc>`
	`split_interval_set`	`<DomainT,Compare,IntervalT,Alloc>`

Templates and template parameters, given in the preceding table are described in detail below. Interval_sets represent three class templates interval_set, separate_interval_set and split_interval_set that all have equal template parameters.

Table 1.9. Parameters of set class templates

	type of elements	order of elements	type of intervals	memory allocation
template parameter	`class`	`template <class>class`	`class`	`template <class>class`
`interval`	`DomainT`	`Compare = std::less`
`interval_sets`	`DomainT`	`Compare = std::less`	`IntervalT = interval<DomainT,Compare>::type`	`Alloc = std::alloc`

Maps

The next two tables give an overview over map class templates of the icl.

Table 1.10. map class templates

group	template	instance parameters
`interval_maps`	`interval_map`	`<DomainT,CodomainT,Traits,Compare,Combine,Section,IntervalT,Alloc>`
	`split_interval_map`	`<DomainT,CodomainT,Traits,Compare,Combine,Section,IntervalT,Alloc>`
`icl::map`	`icl::map`	`<DomainT,CodomainT,Traits,Compare,Combine,Section,Alloc>`

Templates and template parameters, given in the preceding table are described in detail below. Interval_maps represent two class templates interval_map and split_interval_map that all have equal template parameters.

Table 1.11. Parameters of map class templates

	elements	mapped values	traits	order of elements	aggregation propagation	intersection propagation	type of intervals	memory allocation
template parameter	`class`	`class`	`class`	`template <class>class`	`template <class>class`	`template <class>class`	`class`	`template <class>class`
`interval_maps`	`DomainT`	`CodomainT`	`Traits = identity_absorber`	`Compare = std::less`	`Combine = inplace_plus`	`Section = icl::inplace_et`	`IntervalT = interval<DomainT,Compare>::type`	`Alloc = std::alloc`
`icl::map`	`DomainT`	`CodomainT`	`Traits = identity_absorber`	`Compare = std::less`	`Combine = inplace_plus`	`Section = icl::inplace_et`	`Alloc = std::alloc`

Using the following placeholders,

D  := class DomainT,
C  := class CodomainT,
T  := class Traits,
cp := template<class D>class Compare = std::less,
cb := template<class C>class Combine = icl::inplace_plus,
s  := template<class C>class Section = icl::inplace_et,
I  := class IntervalT = icl::interval<D,cp>::type
a  := template<class>class Alloc = std::allocator

we arrive at a final synoptical matrix of class templates and their parameters.

interval     <D,       cp,             >
interval_sets<D,       cp,        I, a >
interval_maps<D, C, T, cp, cb, s, I, a >
icl::map     <D, C, T, cp, cb, s,    a >

The choice of parameters and their positions follow the std::containers as close a possible, so that usage of interval sets and maps does only require minimal additional knowledge.

Additional knowledge is required when instantiating a comparison parameter Compare or an allocation parameter Alloc. In contrast to std::containers these have to be instantiated as templates, like e.g.

interval_set<string, german_compare>      sections; // 2nd parameter is a template
std::set<string, german_compare<string> > words;    // 2nd parameter is a type

Interface

Class templates

Intervals

Library defaults and class template interval

Sets

Maps

Library defaults and class template `interval`