Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

PrevUpHomeNext

Addition

Synopsis
Functions
Inplace operators
Infix operators

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.

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

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_icl_sets__

__ch_icl_maps__

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.

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


PrevUpHomeNext