1[/ 2 Copyright (c) 2008-2009 Joachim Faulhaber 3 4 Distributed under the Boost Software License, Version 1.0. 5 (See accompanying file LICENSE_1_0.txt or copy at 6 http://www.boost.org/LICENSE_1_0.txt) 7] 8 9 10[section Function Reference] 11 12Section [link boost_icl.interface.function_synopsis Function Synopsis] 13above gave an overview of the polymorphic functions of the icl. 14This is what you will need to find the desired possibilities to combine icl 15functions and objects most of the time. 16The functions and overloads that you intuitively expect 17should be provided, so you won't need to refer to the documentation very often. 18 19If you are interested 20 21* in the ['*specific design of the function overloads*], 22* in ['*complexity characteristics*] for certain overloads 23* or if the compiler ['*refuses to resolve*] specific function application you want to use, 24 25refer to this section that describes the polymorphic function families of the icl 26in detail. 27 28[h5 Placeholders] 29 30For a concise representation the same __eiS_phs__ will be used that have been 31introduced in section [link boost_icl.interface.function_synopsis Function Synopsis]. 32 33[h5 More specific function documentation] 34 35This section covers the most important polymorphic and namespace global 36functions of the *icl*. More specific functions can be looked up 37in the doxygen generated 38[link interval_container_library_reference reference documentation]. 39 40[section Overload tables] 41 42Many of the *icl's* functions are overloaded for 43elements, segments, element and interval containers. 44But not all type combinations are provided. Also 45the admissible type combinations are different for 46different functions and operations. 47To concisely represent the overloads that can be 48used we use synoptical tables that contain 49possible type combinations for an operation. 50These are called ['*overload tables*]. As an example 51the overload tables for the inplace intersection 52`operator &=` are given: 53 54`` 55// overload tables for 56T& operator &= (T&, const P&) 57 58element containers: interval containers: 59&= | e b s m &= | e i b p S M 60---+-------- ---+------------ 61s | s s S | S S S 62m | m m m m M | M M M M M M 63`` 64 65For the binary `T& operator &= (T&, const P&)` there are two 66different tables for the overloads of element and interval containers. 67The first argument type `T` is displayed as row headers 68of the tables. 69The second argument type `P` is displayed as column headers 70of the tables. 71If a combination of `T` and `P` is admissible the related 72cell of the table is non empty. 73It displays the result type of the operation. In this example 74the result type is always equal to the first argument. 75 76The possible types that can be instantiated for `T` and `P` 77are element, interval and container types abbreviated by 78placeholders that are defined 79[link boost_icl.interface.function_synopsis here] 80and can be summarized as 81 82__s : element set, __S : interval sets, __e : elements, __i : intervals\n 83__m:element map, __M:interval maps, __b:element-value pairs, __p:interval-value pairs 84 85 86[endsect][/ Overload tables] 87 88[section Segmentational Fineness] 89 90For overloading tables on infix operators, we need to 91break down __itv_sets__ and __itv_maps__ to the 92specific class templates 93 94[table 95[[][] [][] [][]] 96[[[#ph_def_S1][*S1]][__itv_set__][[#ph_def_S2][*S2]][__sep_itv_set__][[#ph_def_S3][*S3]][__spl_itv_set__]] 97[[[#ph_def_M1][*M1]][__itv_map__][][] [[#ph_def_M3][*M3]][__spl_itv_map__]] 98] 99 100 101choosing *Si* and *Mi* as placeholders. 102 103The indices *i* of *Si* and *Mi* represent a property 104called ['*segmentational fineness*] or short ['*fineness*], 105which is a ['*type trait*] on interval containers. 106 107[table 108[[]] 109[[`segmentational_fineness<`[*Si]`>::value` == *i*]] 110[[`segmentational_fineness<`[*Mi]`>::value` == *i*]] 111] 112 113 114Segmentational fineness represents the fact, 115that for interval containers holding the same elements, a 116splitting interval container may contain more segments as 117a separating container which in turn may contain more 118segments than a joining one. So for an 119`` 120operator > 121`` 122where 123`` 124x > y // means that 125x is_finer_than y 126 127// we have 128 129finer coarser 130split_interval_set interval_set 131 > separate_interval_set > 132split_interval_map interval_map 133`` 134 135This relation is needed to resolve the instantiation of 136infix operators e.g. `T operator + (P, Q)` for two interval container types 137`P` and `Q`. If both `P` and `Q` are candidates for the result 138type `T`, one of them must be chosen by the compiler. 139We choose the type that is segmentational finer as 140result type `T`. This way we do not loose the ['*segment information*] 141that is stored in the ['*finer*] one of the container types `P` and `Q`. 142 143`` 144// overload tables for 145T operator + (T, const P&) 146T operator + (const P&, T) 147 148element containers: interval containers: 149+ | e b s m + | e i b p S1 S2 S3 M1 M3 150---+-------- ---+--------------------------- 151e | s e | S1 S2 S3 152b | m i | S1 S2 S3 153s | s s b | M1 M3 154m | m m p | M1 M3 155 S1 | S1 S1 S1 S2 S3 156 S2 | S2 S2 S2 S2 S3 157 S3 | S3 S3 S3 S3 S3 158 M1 | M1 M1 M1 M3 159 M3 | M3 M3 M3 M3 160`` 161 162 163So looking up a type combination for e.g. 164`T operator + (interval_map, split_interval_map)` 165which is equivalent to 166`T operator + (M1, M3)` 167we find for row type `M1` and column type `M3` 168that `M3` 169will be assigned as result type, because `M3` 170is finer than `M1`. 171So this type combination will result in 172choosing this 173`` 174split_interval_map operator + (const interval_map&, split_interval_map) 175`` 176implementation by the compiler. 177 178[endsect][/ Segmentational Fineness] 179 180[section Key Types] 181 182In an *stl* map `map<K,D>` the first parameter type of the map 183template `K` is called `key_type`. It allows to select key-value pairs 184pairs via `find(const K&)` 185and to remove key-value pairs using `erase(const K&)`. 186For icl Maps we have generalized key types to a larger 187set of types. Not only the `key_type` (`domain_type`) 188but also an interval type and a set type can be ['*key types*], 189that allow for ['*selection*] and ['*removal*] of map elements 190segments and submaps. 191 192[table Selection of elements, segments and sub maps using key types 193[[ ][ __M: __itv_maps__ ][ __m: icl_map ]] 194[[__e: `domain_type` ][ key value pair ][ key value pair ]] 195[[__i: `interval_type` ][ interval value pair ][ ]] 196[[__S: __itv_sets__ ][ interval map ][ ]] 197[[__s: __icl_set__ ][ ][ interval map ]] 198] 199 200__biLSubtraction__, __biLerasure__, __biLintersection__ 201[/ , which is a generalized find ] 202and __biLcontainedness__ predicates 203can be used with those kinds of key types. 204For instance, the overload table for intersection 205 206`` 207// overload tables for 208T& operator &= (T&, const P&) 209 210element containers: interval containers: 211&= | e b s m &= | e i b p S M 212---+-------- ---+------------ 213s | s s S | S S S 214m | m m m m M | M M M M M M 215`` 216 217has a part that that allows for selection by key objects 218 219`` 220element containers: interval containers: 221&= | e b s m &= | e i b p S M 222---+-------- ---+------------ 223s | s s S | S S S 224m | m m M | M M M 225`` 226 227and another part that provides overloads for 228generalized intersection: 229 230`` 231element containers: interval containers: 232&= | e b s m &= | e i b p S M 233---+-------- ---+------------ 234s | s s S | S S S 235m | m m M | M M M 236`` 237 238For `Sets`, the ['*key types*] defined for maps 239are identical with the set types themselves. 240So the distinction between the function groups 241['*selection by key*] and ['*generalized intersection*] 242fall together in the well known ['*set intersection*]. 243 244[endsect][/ Key Types] 245 246[include functions_cons_copy_dest.qbk] 247[include functions_containedness.qbk] 248[include functions_equivs_orderings.qbk] 249[include functions_size.qbk] 250[include functions_range.qbk] 251[include functions_selection.qbk] 252[include functions_addition.qbk] 253[include functions_subtraction.qbk] 254[include functions_insertion.qbk] 255[include functions_erasure.qbk] 256[include functions_intersection.qbk] 257[include functions_symmetric_difference.qbk] 258[include functions_iterator_related.qbk] 259[include functions_element_iteration.qbk] 260[include functions_streaming.qbk] 261 262[include functions_interval_construct.qbk] 263[include functions_interval_orderings.qbk] 264[include functions_interval_misc.qbk] 265 266 267[endsect][/ Function Reference] 268 269 270