123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269 |
- [/
- 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<K,D>` 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]
|