| Home | Libraries | People | FAQ | More

### Function Synopsis

In this section a single matrix is given, that shows all functions with shared names and identical or analogous semantics and their polymorphical overloads across the class templates of the icl. Associated are the corresponding functions of the stl for easy comparison. In order to achieve a concise representation, a series of placeholders are used throughout the function matrix.

The placeholder's purpose is to express the polymorphic usage of the functions. The first column of the function matrix contains the signatures of the functions. Within these signatures `T` denotes a container type and `J` and `P` polymorphic argument and result types.

Within the body of the matrix, sets of boldface placeholders denote the sets of possible instantiations for a polymorphic placeholder `P`. For instance e i S denotes that for the argument type `P`, an element e, an interval i or an interval_set S can be instantiated.

If the polymorphism can not be described in this way, only the number of overloaded implementations for the function of that row is shown.

Placeholder | Argument types | Description
--- | --- | ---
`T` |  | a container or interval type
`P` |  | polymorphical container argument type
`J` |  | polymorphical iterator type
`K` |  | polymorphical element_iterator type for interval containers
`V` |  | various types `V`, that do dot fall in the categories above
1,2,... |  | number of implementations for this function
A |  | implementation generated by compilers
e | T::element_type | the element type of `interval_sets` or `std::sets`
i | T::segment_type | the segment type of of `interval_sets`
s | element sets | `std::set` or other models of the icl's set concept
S | interval_sets | one of the interval set types
b | T::element_type | type of `interval_map's` or `icl::map's` element value pairs
p | T::segment_type | type of `interval_map's` interval value pairs
m | element maps | `icl::map` icl's map type
M | interval_maps | one of the interval map types
d | discrete types | types with a least steppable discrete unit: Integral types, date/time types etc.
c | continuous types | types with (theoretically) infinitely many elements beween two values.

Table 1.13. Synopsis Functions and Overloads

T | intervals | interval sets | interval maps | element sets | element maps
--- | --- | --- | --- | --- | ---
Construct, copy, destruct |  |  |  |  |
`T::T()` | 1 | 1 | 1 | 1 | 1
`T::T(const P&)` | A | e i S | b p M | 1 | 1
`T& T::operator=(const P&)` | A | S | M | 1 | 1
`void T::swap(T&)` |  | 1 | 1 | 1 | 1
Containedness | intervals | interval sets | interval maps | element sets | element maps
`bool T::empty()const` |  | 1 | 1 | 1 | 1
`bool is_empty(const T&)` | 1 | 1 | 1 | 1 | 1
`bool contains(const T&, const P&)` `bool within(const P&, const T&)` | e i | e i S | e i S b p M | e s | b m
Equivalences and Orderings | intervals | interval sets | interval maps | element sets | element maps
`bool operator == (const T&, const T&)` | 1 | 1 | 1 | 1 | 1
`bool operator != (const T&, const T&)` | 1 | 1 | 1 | 1 | 1
`bool operator < (const T&, const T&)` | 1 | 1 | 1 | 1 | 1
`bool operator > (const T&, const T&)` | 1 | 1 | 1 | 1 | 1
`bool operator <= (const T&, const T&)` | 1 | 1 | 1 | 1 | 1
`bool operator >= (const T&, const T&)` | 1 | 1 | 1 | 1 | 1
`bool is_element_equal(const T&, const P&)` |  | S | M | 1 | 1
`bool is_element_less(const T&, const P&)` |  | S | M | 1 | 1
`bool is_element_greater(const T&, const P&)` |  | S | M | 1 | 1
`bool is_distinct_equal(const T&, const P&)` |  |  | M |  | 1
Size | intervals | interval sets | interval maps | element sets | element maps
`size_type T::size()const` |  | 1 | 1 | 1 | 1
`size_type size(const T&)` | 1 | 1 | 1 | 1 | 1
`size_type cardinality(const T&)` | 1 | 1 | 1 | 1 | 1
`difference_type length(const T&)` | 1 | 1 | 1 |  |
`size_type iterative_size(const T&)` |  | 1 | 1 | 1 | 1
`size_type interval_count(const T&)` |  | 1 | 1 |  |
Selection |  |  |  |  |
`J T::find(const P&)` |  | e i | e i | 2 | 2
`J find(T&, const P&)` |  | e i | e i |  |
`codomain_type& operator[] (const domain_type&)` |  |  |  |  | 1
`codomain_type operator() (const domain_type&)const` |  |  | 1 |  | 1
Range |  |  |  |  |
`interval_type hull(const T&)` |  | 1 | 1 |  |
`T hull(const T&, const T&)` | 1 |  |  |  |
`domain_type lower(const T&)` | 1 | 1 | 1 |  |
`domain_type upper(const T&)` | 1 | 1 | 1 |  |
`domain_type first(const T&)` | 1 | 1 | 1 |  |
`domain_type last(const T&)` | 1 | 1 | 1 |  |
Addition | intervals | interval sets | interval maps | element sets | element maps
`T& T::add(const P&)` |  | e i | b p |  | b
`T& add(T&, const P&)` |  | e i | b p | e | b
`T& T::add(J pos, const P&)` |  | i | p |  | b
`T& add(T&, J pos, const P&)` |  | i | p | e | b
`T& operator +=(T&, const P&)` |  | e i S | b p M | e s | b m
`T operator + (T, const P&)` `T operator + (const P&, T)` |  | e i S | b p M | e s | b m
`T& operator |=( T&, const P&)` |  | e i S | b p M | e s | b m
`T operator | (T, const P&)` `T operator | (const P&, T)` |  | e i S | b p M | e s | b m
Subtraction |  |  |  |  |
`T& T::subtract(const P&)` |  | e i | b p |  | b
`T& subtract(T&, const P&)` |  | e i | b p | e | b
`T& operator -=(T&, const P&)` |  | e i S | e i S b p M | e s | b m
`T operator - (T, const P&)` |  | e i S | e i S b p M | e s | b m
`T left_subtract(T, const T&)` | 1 |  |  |  |
`T right_subtract(T, const T&)` | 1 |  |  |  |
Insertion | intervals | interval sets | interval maps | element sets | element maps
`V T::insert(const P&)` |  | e i | b p | e | b
`V insert(T&, const P&)` |  | e i | b p | e | b
`V T::insert(J pos, const P&)` |  | i | p | e | b
`V insert(T&, J pos, const P&)` |  | i | p | e | b
`T& insert(T&, const P&)` |  | e i S | b p M | e s | b m
`T& T::set(const P&)` |  |  | b p |  | 1
`T& set_at(T&, const P&)` |  |  | b p |  | 1
Erasure |  |  |  |  |
`void T::clear()` |  | 1 | 1 | 1 | 1
`void clear(const T&)` |  | 1 | 1 | 1 | 1
`T& T::erase(const P&)` |  | e i | e i b p | e | b p
`T& erase(T&, const P&)` |  | e i S | e i S b p M | e s | b m
`void T::erase(iterator)` |  | 1 | 1 | 1 | 1
`void T::erase(iterator,iterator)` |  | 1 | 1 | 1 | 1
Intersection | intervals | interval sets | interval maps | element sets | element maps
`void add_intersection(T&, const T&, const P&)` |  | e i S | e i S b p M |  |
`T& operator &=(T&, const P&)` |  | e i S | e i S b p M | e s | b m
`T operator & (T, const P&)` `T operator & (const P&, T)` | i | e i S | e i S b p M | e s | b m
`bool intersects(const T&, const P&)` `bool disjoint(const T&, const P&)` | i | e i S | e i S b p M | e s | b m
Symmetric difference |  |  |  |  |
`T& T::flip(const P&)` |  | e i | b p |  | b
`T& flip(T&, const P&)` |  | e i | b p | e | b
`T& operator ^=(T&, const P&)` |  | e i S | b p M | e s | b m
`T operator ^ (T, const P&)` `T operator ^ (const P&, T)` |  | e i S | b p M | e s | b m
Iteration | intervals | interval sets | interval maps | element sets | element maps
`J T::begin()` |  | 2 | 2 | 2 | 2
`J T::end()` |  | 2 | 2 | 2 | 2
`J T::rbegin()` |  | 2 | 2 | 2 | 2
`J T::rend()` |  | 2 | 2 | 2 | 2
`J T::lower_bound(const key_type&)` |  | 2 | 2 | 2 | 2
`J T::upper_bound(const key_type&)` |  | 2 | 2 | 2 | 2
`pair<J,J> T::equal_range(const key_type&)` |  | 2 | 2 | 2 | 2
Element iteration | intervals | interval sets | interval maps | element sets | element maps
`K elements_begin(T&)` |  | 2 | 2 |  |
`K elements_end(T&)` |  | 2 | 2 |  |
`K elements_rbegin(T&)` |  | 2 | 2 |  |
`K elements_rend(T&)` |  | 2 | 2 |  |
Streaming, conversion | intervals | interval sets | interval maps | element sets | element maps
`std::basic_ostream operator << (basic_ostream&, const T&)` | 1 | 1 | 1 | 1 | 1

Many but not all functions of icl intervals are listed in the table above. Some specific functions are summarized in the next table. For the group of the constructing functions, placeholders d denote discrete domain types and c denote continuous domain types `T::domain_type` for an interval_type `T` and an argument types `P`.

Table 1.14. Additional interval functions

T | discrete _interval | continuous _interval | right_open _interval | left_open _interval | closed _interval | open _interval
--- | --- | --- | --- | --- | --- | ---
Interval bounds | dynamic | dynamic | static | static | static | static
Form |  |  | asymmetric | asymmetric | symmetric | symmetric
Construction |  |  |  |  |  |
`T singleton(const P&)` | d | c | d | d | d | d
`T construct(const P&, const P&)` | d | c | d c | d c | d | d
`T construct(const P&, const P&, interval_bounds)` | d | c |  |  |  |
`T hull(const P&, const P&)` | d | c | d c | d c | d | d
`T span(const P&, const P&)` | d | c | d c | d c | d | d
`static T right_open(const P&, const P&)` | d | c |  |  |  |
`static T left_open(const P&, const P&)` | d | c |  |  |  |
`static T closed(const P&, const P&)` | d | c |  |  |  |
`static T open(const P&, const P&)` | d | c |  |  |  |
Orderings |  |  |  |  |  |
`bool exclusive_less(const T&, const T&)` | 1 | 1 | 1 | 1 | 1 | 1
`bool lower_less(const T&, const T&)` `bool lower_equal(const T&, const T&)` `bool lower_less_equal(const T&, const T&)` | 1 | 1 | 1 | 1 | 1 | 1
`bool upper_less(const T&, const T&)` `bool upper_equal(const T&, const T&)` `bool upper_less_equal(const T&, const T&)` | 1 | 1 | 1 | 1 | 1 | 1
Miscellaneous |  |  |  |  |  |
`bool touches(const T&, const T&)` | 1 | 1 | 1 | 1 | 1 | 1
`T inner_complement(const T&, const T&)` | 1 | 1 | 1 | 1 | 1 | 1
`difference_type distance(const T&, const T&)` | 1 | 1 | 1 | 1 | 1 | 1

##### Element iterators for interval containers

Iterators on interval conainers that are refered to in section Iteration of the function synopsis table are segment iterators. They reveal the more implementation specific aspect, that the fundamental aspect abstracts from. Iteration over segments is fast, compared to an iteration over elements, particularly if intervals are large. But if we want to view our interval containers as containers of elements that are usable with std::algoritms, we need to iterate over elements.

Iteration over elements . . .

- is possible only for integral or discrete `domain_types`
- can be very slow if the intervals are very large.
- and is therefore depreciated

On the other hand, sometimes iteration over interval containers on the element level might be desired, if you have some interface that works for `std::SortedAssociativeContainers` of elements and you need to quickly use it with an interval container. Accepting the poorer performance might be less bothersome at times than adjusting your whole interface for segment iteration.

| Caution
So we advice you to choose element iteration over interval containers judiciously. Do not use element iteration by default or habitual. Always try to achieve results using namespace global functions or operators (preferably inplace versions) or iteration over segments first.