| Home | Libraries | People | FAQ | More

### Addition

#### Synopsis

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
`J T::add(J pos, const P&)` | i | p |  | b
`J 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.

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 `J T::add(J 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
    J T::add(J prior, const P&)                     ---+--------
    J add(T&, J 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