[/ Copyright (c) 2008-2009 Joachim Faulhaber Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] [section Function Reference] Section [link boost_icl.interface.function_synopsis Function Synopsis] above gave an overview of the polymorphic functions of the icl. This is what you will need to find the desired possibilities to combine icl functions and objects most of the time. The functions and overloads that you intuitively expect should be provided, so you won't need to refer to the documentation very often. If you are interested * in the ['*specific design of the function overloads*], * in ['*complexity characteristics*] for certain overloads * or if the compiler ['*refuses to resolve*] specific function application you want to use, refer to this section that describes the polymorphic function families of the icl in detail. [h5 Placeholders] For a concise representation the same __eiS_phs__ will be used that have been introduced in section [link boost_icl.interface.function_synopsis Function Synopsis]. [h5 More specific function documentation] This section covers the most important polymorphic and namespace global functions of the *icl*. More specific functions can be looked up in the doxygen generated [link interval_container_library_reference reference documentation]. [section Overload tables] Many of the *icl's* functions are overloaded for elements, segments, element and interval containers. But not all type combinations are provided. Also the admissible type combinations are different for different functions and operations. To concisely represent the overloads that can be used we use synoptical tables that contain possible type combinations for an operation. These are called ['*overload tables*]. As an example the overload tables for the inplace intersection `operator &=` are given: `` // overload tables for T& operator &= (T&, const P&) element containers: interval containers: &= | e b s m &= | e i b p S M ---+-------- ---+------------ s | s s S | S S S m | m m m m M | M M M M M M `` For the binary `T& operator &= (T&, const P&)` there are two different tables for the overloads of element and interval containers. The first argument type `T` is displayed as row headers of the tables. The second argument type `P` is displayed as column headers of the tables. If a combination of `T` and `P` is admissible the related cell of the table is non empty. It displays the result type of the operation. In this example the result type is always equal to the first argument. The possible types that can be instantiated for `T` and `P` are element, interval and container types abbreviated by placeholders that are defined [link boost_icl.interface.function_synopsis here] and can be summarized as __s : element set, __S : interval sets, __e : elements, __i : intervals\n __m:element map, __M:interval maps, __b:element-value pairs, __p:interval-value pairs [endsect][/ Overload tables] [section Segmentational Fineness] For overloading tables on infix operators, we need to break down __itv_sets__ and __itv_maps__ to the specific class templates [table [[][] [][] [][]] [[[#ph_def_S1][*S1]][__itv_set__][[#ph_def_S2][*S2]][__sep_itv_set__][[#ph_def_S3][*S3]][__spl_itv_set__]] [[[#ph_def_M1][*M1]][__itv_map__][][] [[#ph_def_M3][*M3]][__spl_itv_map__]] ] choosing *Si* and *Mi* as placeholders. The indices *i* of *Si* and *Mi* represent a property called ['*segmentational fineness*] or short ['*fineness*], which is a ['*type trait*] on interval containers. [table [[]] [[`segmentational_fineness<`[*Si]`>::value` == *i*]] [[`segmentational_fineness<`[*Mi]`>::value` == *i*]] ] Segmentational fineness represents the fact, that for interval containers holding the same elements, a splitting interval container may contain more segments as a separating container which in turn may contain more segments than a joining one. So for an `` operator > `` where `` x > y // means that x is_finer_than y // we have finer coarser split_interval_set interval_set > separate_interval_set > split_interval_map interval_map `` This relation is needed to resolve the instantiation of infix operators e.g. `T operator + (P, Q)` for two interval container types `P` and `Q`. If both `P` and `Q` are candidates for the result type `T`, one of them must be chosen by the compiler. We choose the type that is segmentational finer as result type `T`. This way we do not loose the ['*segment information*] that is stored in the ['*finer*] one of the container types `P` and `Q`. `` // overload tables for T operator + (T, const P&) T operator + (const P&, T) element containers: interval containers: + | e b s m + | e i b p S1 S2 S3 M1 M3 ---+-------- ---+--------------------------- 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 `` So looking up a type combination for e.g. `T operator + (interval_map, split_interval_map)` which is equivalent to `T operator + (M1, M3)` we find for row type `M1` and column type `M3` that `M3` will be assigned as result type, because `M3` is finer than `M1`. So this type combination will result in choosing this `` split_interval_map operator + (const interval_map&, split_interval_map) `` implementation by the compiler. [endsect][/ Segmentational Fineness] [section Key Types] In an *stl* map `map` the first parameter type of the map template `K` is called `key_type`. It allows to select key-value pairs pairs via `find(const K&)` and to remove key-value pairs using `erase(const K&)`. For icl Maps we have generalized key types to a larger set of types. Not only the `key_type` (`domain_type`) but also an interval type and a set type can be ['*key types*], that allow for ['*selection*] and ['*removal*] of map elements segments and submaps. [table Selection of elements, segments and sub maps using key types [[ ][ __M: __itv_maps__ ][ __m: icl_map ]] [[__e: `domain_type` ][ key value pair ][ key value pair ]] [[__i: `interval_type` ][ interval value pair ][ ]] [[__S: __itv_sets__ ][ interval map ][ ]] [[__s: __icl_set__ ][ ][ interval map ]] ] __biLSubtraction__, __biLerasure__, __biLintersection__ [/ , which is a generalized find ] and __biLcontainedness__ predicates can be used with those kinds of key types. For instance, the overload table for intersection `` // overload tables for T& operator &= (T&, const P&) element containers: interval containers: &= | e b s m &= | e i b p S M ---+-------- ---+------------ s | s s S | S S S m | m m m m M | M M M M M M `` has a part that that allows for selection by key objects `` element containers: interval containers: &= | e b s m &= | e i b p S M ---+-------- ---+------------ s | s s S | S S S m | m m M | M M M `` and another part that provides overloads for generalized intersection: `` element containers: interval containers: &= | 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 `Sets`, the ['*key types*] defined for maps are identical with the set types themselves. So the distinction between the function groups ['*selection by key*] and ['*generalized intersection*] fall together in the well known ['*set intersection*]. [endsect][/ Key Types] [include functions_cons_copy_dest.qbk] [include functions_containedness.qbk] [include functions_equivs_orderings.qbk] [include functions_size.qbk] [include functions_range.qbk] [include functions_selection.qbk] [include functions_addition.qbk] [include functions_subtraction.qbk] [include functions_insertion.qbk] [include functions_erasure.qbk] [include functions_intersection.qbk] [include functions_symmetric_difference.qbk] [include functions_iterator_related.qbk] [include functions_element_iteration.qbk] [include functions_streaming.qbk] [include functions_interval_construct.qbk] [include functions_interval_orderings.qbk] [include functions_interval_misc.qbk] [endsect][/ Function Reference]