Addition

Addition	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

Functions and operators that implement Addition on icl objects are given in the table above. operator |= and operator | are behavioral identical to operator += and operator +. This is a redundancy that has been introduced deliberately, because a set union semantics is often attached operators |= and |.

	Description of Addition
`Sets`	Addition on Sets implements set union
`Maps`	Addition on Maps implements a map union function similar to set union. If, on insertion of an element value pair `(k,v)` it's key `k` is in the map already, the addition function is propagated to the associated value. This functionality has been introduced as aggregate on collision for element maps and aggregate on overlap for interval maps. Find more on addability of maps and related semantic issues following the links. Examples, demonstrating Addition on interval containers are overlap counter, party and party's height average.

Description of Addition

Sets

Addition on Sets implements set union

Maps

Addition on Maps implements a map union function similar to set union. If, on insertion of an element value pair (k,v) it's key k is in the map already, the addition function is propagated to the associated value. This functionality has been introduced as aggregate on collision for element maps and aggregate on overlap for interval maps.

Find more on addability of maps and related semantic issues following the links.

Examples, demonstrating Addition on interval containers are overlap counter, party and party's height average.

For Sets addition and insertion are implemented identically. Functions add and insert collapse to the same function. For Maps addition and insertion work differently. Function add performs aggregations on collision or overlap, while function insert only inserts values that do not yet have key values.

Functions

The admissible combinations of types for member function T& T::add(const P&) can be summarized in the overload table below:

// overload table for    T\P| e i b p  
T& T::add(const P&)      ---+--------
T& add(T&, const P&)      s | s
                          m |     m
                          S | S S      
                          M |     M M

The next table contains complexity characteristics for add.

Table 1.21. Time Complexity for member function add on icl containers

`T& T::add(const P&)` `T& add(T&, const P&)`	domain type	interval type	domain mapping type	interval mapping type
`std::set`	O(log n)
`icl::map`			O(log n)
`interval_set` `separate_interval_set`	O(log n)	amortized O(log n)
`split_interval_set`	O(log n)	O(n)
`interval_map` `split_interval_map`			O(log n)	O(n)

Hinted addition

Function T& T::add(T::iterator prior, const P& addend) allows for an addition in constant time, if addend can be inserted right after iterator prior without collision. If this is not possible the complexity characteristics are as stated for the non hinted addition above. Hinted addition is available for these combinations of types:

// overload table for addition with hint        T\P| e i b p   
T& T::add(T::iterator prior, const P&)          ---+--------
T& add(T&, T::iterator prior, const P&)          s | s
                                                 m |     m
                                                 S |   S      
                                                 M |       M

Inplace operators

The possible overloads of inplace T& operator += (T&, const P&) are given by two tables, that show admissible combinations of types. Row types show instantiations of argument type T. Columns types show show instantiations of argument type P. If a combination of argument types is possible, the related table cell contains the result type of the operation. Placeholders e i b p s S m M will be used to denote elements, intervals, element value pairs, interval value pairs, element sets, interval sets, element maps and interval maps. The first table shows the overloads of += for element containers the second table refers to interval containers.

// overload tables for             element containers:     interval containers:  
T& operator += (T&, const P&)      += | e b s m            += | e i b p S M    
                                   ---+--------            ---+------------    
                                   s  | s   s              S  | S S     S       
                                   m  |   m   m            M  |     M M   M

For the definition of admissible overloads we separate element containers from interval containers. Within each group all combinations of types are supported for an operation, that are in line with the icl's design and the sets of laws, that establish the icl's semantics.

Overloads between element containers and interval containers could also be defined. But this has not been done for pragmatical reasons: Each additional combination of types for an operation enlarges the space of possible overloads. This makes the overload resolution by compilers more complex, error prone and slows down compilation speed. Error messages for unresolvable or ambiguous overloads are difficult to read and understand. Therefore overloading of namespace global functions in the icl are limited to a reasonable field of combinations, that are described here.

Complexity

For different combinations of argument types T and P different implementations of the operator += are selected. These implementations show different complexity characteristics. If T is a container type, the combination of domain elements (e) or element value pairs (b) is faster than a combination of intervals (i) or interval value pairs (p) which in turn is faster than the combination of element or interval containers. The next table shows time complexities of addition for icl's element containers.

Sizes n and m are in the complexity statements are sizes of objects T y and P x:

n = iterative_size(y);
m = iterative_size(x); //if P is a container type

Note, that for an interval container the number of elements T::size is different from the number of intervals that you can iterate over. Therefore a function T::iterative_size() is used that provides the desired kind of size.

Table 1.22. Time Complexity for inplace Addition on element containers

`T& operator += (T& y, const P& x)`	domain type	domain mapping type	__ch_iclsets][_ch_iclmaps_
`std::set`	O(log n)		O(m)
`icl::map`		O(log n)		O(m)

Time complexity characteristics of inplace addition for interval containers is given by this table.

Table 1.23. Time Complexity for inplace Addition on interval containers

`T& operator += (T& y, const P& x)`		domain type	interval type	domain mapping type	interval mapping type	interval sets	interval maps
interval_sets	`interval_set` `separate_interval_set`	O(log n)	amortized O(log n)			O(m log(n+m))
	`split_interval_set`	O(log n)	O(n)			O(m log(n+m))
interval_maps				O(log n)	O(n)		O(m log(n+m))

Since the implementation of element and interval containers is based on the link red-black tree implementation of std::AssociativeContainers, we have a logarithmic complexity for addition of elements. Addition of intervals or interval value pairs is amortized logarithmic for interval_sets and separate_interval_sets and linear for split_interval_sets and interval_maps. Addition is linear for element containers and loglinear for interval containers.

Infix operators

The admissible type combinations for infix operator + are defined by the overload tables below.

// overload tables for          element containers:     interval containers:
T operator + (T, const P&)      +  | e b s m            +  | e  i  b  p  S1 S2 S3 M1 M3  
T operator + (const P&, T)      ---+--------            ---+---------------------------
                                e  |     s              e  |             S1 S2 S3 
                                b  |       m            i  |             S1 S2 S3 
                                s  | s   s              b  |                      M1 M3  
                                m  |   m   m            p  |                      M1 M3
                                                        S1 | S1 S1       S1 S2 S3 
                                                        S2 | S2 S2       S2 S2 S3 
                                                        S3 | S3 S3       S3 S3 S3 
                                                        M1 |       M1 M1          M1 M3
                                                        M3 |       M3 M3          M3 M3

See also . . .

Subtraction
Insertion

Back to section . . .

Function Synopsis
Interface