Subject: [Boost-commit] svn:boost r59596 - sandbox/itl/libs/itl/doc
From: afojgo_at_[hidden]
Date: 2010-02-09 11:59:48
Author: jofaber
Date: 2010-02-09 11:59:46 EST (Tue, 09 Feb 2010)
New Revision: 59596
URL: http://svn.boost.org/trac/boost/changeset/59596
Log:
Improvements and additions to the documentation.
Text files modified:
sandbox/itl/libs/itl/doc/acknowledgments.qbk | 2
sandbox/itl/libs/itl/doc/examples.qbk | 180 ++++++++++++++++++++-------------------
sandbox/itl/libs/itl/doc/functions_addition.qbk | 44 +++++++++
sandbox/itl/libs/itl/doc/functions_cons_copy_dest.qbk | 9 ++
sandbox/itl/libs/itl/doc/functions_containedness.qbk | 8 +
sandbox/itl/libs/itl/doc/functions_element_iteration.qbk | 14 +++
sandbox/itl/libs/itl/doc/functions_equivs_orderings.qbk | 13 ++
sandbox/itl/libs/itl/doc/functions_erasure.qbk | 15 +++
sandbox/itl/libs/itl/doc/functions_insertion.qbk | 33 +++++++
sandbox/itl/libs/itl/doc/functions_intersection.qbk | 16 +++
sandbox/itl/libs/itl/doc/functions_iterator_related.qbk | 32 ++++--
sandbox/itl/libs/itl/doc/functions_range.qbk | 6 +
sandbox/itl/libs/itl/doc/functions_selection.qbk | 12 ++
sandbox/itl/libs/itl/doc/functions_size.qbk | 6 +
sandbox/itl/libs/itl/doc/functions_streaming.qbk | 8 +
sandbox/itl/libs/itl/doc/functions_subtraction.qbk | 14 +++
sandbox/itl/libs/itl/doc/functions_symmetric_difference.qbk | 15 +++
sandbox/itl/libs/itl/doc/interface.qbk | 22 ++--
sandbox/itl/libs/itl/doc/introduction.qbk | 15 ++
19 files changed, 353 insertions(+), 111 deletions(-)
Modified: sandbox/itl/libs/itl/doc/acknowledgments.qbk
==============================================================================
--- sandbox/itl/libs/itl/doc/acknowledgments.qbk (original)
+++ sandbox/itl/libs/itl/doc/acknowledgments.qbk 2010-02-09 11:59:46 EST (Tue, 09 Feb 2010)
@@ -26,7 +26,7 @@
at the BoostCon 2009 by Jeff Garland, David Jenkins, Tobias Loew,
Barend Gehrels, Luke Simonson and Hartmut Kaiser.
Special thanks for reading and improving this documentation to
-Neal Becker and Ilya Bobir.
+Neal Becker, Ilya Bobir and Brian Wood.
Jeff Flinn provided valuable feedback and a codepatch to fix
portability problems with CodeWarrior 9.4. Many thanks for that.
Modified: sandbox/itl/libs/itl/doc/examples.qbk
==============================================================================
--- sandbox/itl/libs/itl/doc/examples.qbk (original)
+++ sandbox/itl/libs/itl/doc/examples.qbk 2010-02-09 11:59:46 EST (Tue, 09 Feb 2010)
@@ -16,20 +16,16 @@
[__itv_map__][Generates an attendance history of a party
by inserting into an __itv_map__.
Demonstrating
- ['*aggregate on overlap*]]]
+ ['*aggregate on overlap*].]]
[[basic] [[link boost_itl.examples.interval Interval]]
[__itv__] [Intervals for integral and continuous instance types.
- Closed and open interval borders]]
+ Closed and open interval borders.]]
[[basic] [[link boost_itl.examples.interval_container Interval container]]
[__itv_set__,\n__sep_itv_set__,\n__spl_itv_set__,\n__spl_itv_map__,\n__itv_map__]
- [Basic characteristics of interval containers]]
+ [Basic characteristics of interval containers.]]
[[basic] [[link boost_itl.examples.overlap_counter Overlap counter]]
[__itv_map__][The most simple application of an interval map:
Counting the overlaps of added intervals.]]
- [[basic] [[link boost_itl.examples.std_copy Std copy]]
- [__itv_map__][Fill interval containers using `std::copy`.]]
- [[basic] [[link boost_itl.examples.std_transform Std transform]]
- [__itv_map__,\n__sep_itv_set__][Fill interval containers from user defined objects using `std::transform`.]]
[[advanced][[link boost_itl.examples.partys_height_average Party's height average]]
[__itv_map__][Using /aggregate on overlap/ a history of height averages of party guests is computed.
Associated values are user defined class objects, that implement
@@ -39,7 +35,7 @@
[Using /aggregate on overlap/ the heights of the party's tallest guests are computed.
Associated values are aggregated via a maximum functor, that can
be chosen as template parameter of an interval_map class template.]]
- [[advanced][[link boost_itl.examples.month_and_week_grid Time grids for months and weeks]]
+ [[advanced][[link boost_itl.examples.time_grids_for_months_and_weeks Time grids for months and weeks]]
[__spl_itv_set__]
[Shows how the ['*border preserving*]
__spl_itv_set__ can be used to create time partitions where different
@@ -53,6 +49,12 @@
[[advanced][[link boost_itl.examples.user_groups User groups]][__itv_map__]
[Example [*user_groups] shows how interval_maps can be unified or
intersected to calculate desired information.]]
+
+ [[and std] [[link boost_itl.examples.std_copy Std copy]]
+ [__itv_map__][Fill interval containers using `std::copy`.]]
+ [[and std] [[link boost_itl.examples.std_transform Std transform]]
+ [__itv_map__,\n__sep_itv_set__][Fill interval containers from user defined objects using `std::transform`.]]
+
]
[endsect]
@@ -100,7 +102,7 @@
We are introducing __itv_maps__ using an
['interval map ['*of sets of strings*]],
because of it's didactic advantages. The party example is
-used to give an immediate and depictive access to the basic ideas of
+used to give an immediate access to the basic ideas of
interval maps and /aggregate on overlap/.
For real world applications, an interval_map of sets is
not necessarily recommended.
@@ -108,7 +110,7 @@
a `std::map` of `std::sets`.
There is a big realm though of using
interval_maps with numerical and other
-efficient codomain types.
+efficient data types for the associated values.
]
[endsect] [/ Party]
@@ -158,81 +160,6 @@
[endsect]
-[section Std copy]
-
-The standard algorithm
-[@http://www.cplusplus.com/reference/algorithm/copy/ `std::copy`]
-can be used to fill interval containers
-from standard containers of intervals or
-interval value pairs (segments). Because intervals
-do not represent ['*elements*] but ['*sets*], that
-can be empty or contain more than one element,
-the usage of `std::copy` differs from what we
-are familiar with using ['containers of elements].
-
-* Use `itl::inserter` from `#include <boost/itl/iterator.hpp>`
- instead of `std::inserter` to call insertions on the target
- interval container.
-
-* As shown in the examples above and below this point, most of
- the time we will not be interested to `insert` segments
- into __itv_maps__ but to __biLadd__
- them, in order to generate the desired aggregation results.
- You can use `std::copy` with an `itl::adder` instead of an
- `itl::inserter` to achieve this.
-
-[import ../example/std_copy_/std_copy.cpp]
-[example_std_copy]
-
-[endsect][/ Std copy]
-
-
-[section Std transform]
-
-Instead of writing loops, the standard algorithm
-[@http://www.cplusplus.com/reference/algorithm/transform/ `std::transform`]
-can be used to fill interval containers
-from std containers of user defined objects.
-We need a function, that
-maps the ['user defined object] into the
-['segement type] of an interval map or the
-['interval type] of an interval set.
-Based on that we can use `std::transform`
-with an `itl::inserter` or `itl::adder`
-to transform the user objects into interval
-containers.
-
-[import ../example/std_transform_/std_transform.cpp]
-[example_std_transform]
-
-To get clear about the different behaviors of interval containers
-in the example, you may want to refer to the section about
-[link boost_itl.introduction.interval_combining_styles interval combining styles]
-that uses the same data.
-
-[/
-Instead of `itl::inserter` we could also use an `std::inserter`
-with algorithms `std::copy` and `std::transform`.
-This is ['*depreciated*], because `std::inserter` is designed for
-containers of elements, where ['*exacty one*] element is inserted
-via `std::inserter` if it is not already in the container.
-In contrast to that, an interval or segemnt can represent zero, one,
-or many elements of an interval container.
-
-You can use `std::inserter` *only*, if you actively take care of
-two preconditions:
-
-# None of the intervals or segements of the source containers
- must be empty.
-
-# A segment never carries a neutral value when your target
- interval map absorbs neutrons.
-
-Violating those preconditions leads to ['*undefined behavior*].
-]
-
-[endsect][/ std::transform]
-
[section:partys_height_average Party's height average]
@@ -276,7 +203,7 @@
instantiate an interval_map class template with an
appropriate ['*aggregation functor*]. For the most common
kinds of aggregation the [*itl]
-provides the such functors as shown in the example.
+provides such functors as shown in the example.
Example `partys_tallest_guests.cpp` also demonstrates
the difference between an __itv_map__
@@ -350,5 +277,84 @@
[example_user_groups]
[endsect]
-[endsect]
+
+[section Std copy]
+
+The standard algorithm
+[@http://www.cplusplus.com/reference/algorithm/copy/ `std::copy`]
+can be used to fill interval containers
+from standard containers of intervals or
+interval value pairs (segments). Because intervals
+do not represent ['*elements*] but ['*sets*], that
+can be empty or contain more than one element,
+the usage of `std::copy` differs from what we
+are familiar with using ['containers of elements].
+
+* Use `itl::inserter` from `#include <boost/itl/iterator.hpp>`
+ instead of `std::inserter` to call insertions on the target
+ interval container.
+
+* As shown in the examples above and below this point, most of
+ the time we will not be interested to `insert` segments
+ into __itv_maps__ but to __biLadd__
+ them, in order to generate the desired aggregation results.
+ You can use `std::copy` with an `itl::adder` instead of an
+ `itl::inserter` to achieve this.
+
+[import ../example/std_copy_/std_copy.cpp]
+[example_std_copy]
+
+[endsect][/ Std copy]
+
+
+[section Std transform]
+
+Instead of writing loops, the standard algorithm
+[@http://www.cplusplus.com/reference/algorithm/transform/ `std::transform`]
+can be used to fill interval containers
+from std containers of user defined objects.
+We need a function, that
+maps the ['user defined object] into the
+['segement type] of an interval map or the
+['interval type] of an interval set.
+Based on that we can use `std::transform`
+with an `itl::inserter` or `itl::adder`
+to transform the user objects into interval
+containers.
+
+[import ../example/std_transform_/std_transform.cpp]
+[example_std_transform]
+
+To get clear about the different behaviors of interval containers
+in the example, you may want to refer to the section about
+[link boost_itl.introduction.interval_combining_styles interval combining styles]
+that uses the same data.
+
+[/
+Instead of `itl::inserter` we could also use an `std::inserter`
+with algorithms `std::copy` and `std::transform`.
+This is ['*depreciated*], because `std::inserter` is designed for
+containers of elements, where ['*exacty one*] element is inserted
+via `std::inserter` if it is not already in the container.
+In contrast to that, an interval or segemnt can represent zero, one,
+or many elements of an interval container.
+
+You can use `std::inserter` *only*, if you actively take care of
+two preconditions:
+
+# None of the intervals or segements of the source containers
+ must be empty.
+
+# A segment never carries a neutral value when your target
+ interval map absorbs neutrons.
+
+Violating those preconditions leads to ['*undefined behavior*].
+]
+
+[endsect][/ std::transform]
+
+
+
+
+[endsect][/ examples]
Modified: sandbox/itl/libs/itl/doc/functions_addition.qbk
==============================================================================
--- sandbox/itl/libs/itl/doc/functions_addition.qbk (original)
+++ sandbox/itl/libs/itl/doc/functions_addition.qbk 2010-02-09 11:59:46 EST (Tue, 09 Feb 2010)
@@ -15,6 +15,7 @@
[table
[[Addition] [__ch_itv_sets__][__ch_itv_maps__][itl::set][itl::map] ]
[[`T& T::add(const P&)`] [__ei] [__bp] [__e] [__b] ]
+[[`T& T::add(J prior, const P&)`] [__i] [__p] [__e] [__b] ]
[[`T& operator +=(T&, const P&)`] [__eiS] [__bpM] [__es] [__bm] ]
[[`T operator + (T, const P&)`\n`T operator + (const P&, T)`][__eiS] [__bpM] [__es] [__bm] ]
[[`T& operator |=( T&, const P&)`] [__eiS] [__bpM] [__es] [__bm] ]
@@ -23,7 +24,8 @@
Functions and operators that implement ['*Addition*] on *itl* objects
are given in the table above.
-`operator |=` and `operator |` are identical to `operator +=` and `operator +`.
+`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 `|`.
@@ -49,6 +51,12 @@
]]
]
+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.
+
[endsect][/ Synopsis]
[section Member functions][/ Addition]
@@ -80,6 +88,25 @@
[[__itv_map__\n__spl_itv_map__][] [] [__Olgn__][__On__] ]
]
+[h5 Hinted addition]
+
+Function `T& T::add(T::iterator 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& T::add(T::iterator prior, const P&)
+
+add | e i b p
+----+--------
+s | s
+m | m
+S | S
+M | M
+``
+
[endsect][/ Member function Addition]
[section Inplace operators]
@@ -212,6 +239,21 @@
[endsect][/ Infix operators]
+
+['*See also . . .*]
+[table
+[[]]
+[[[link boost_itl.function_reference.subtraction ['*Subtraction*]] ]]
+[[[link boost_itl.function_reference.insertion ['*Insertion*]] ]]
+]
+
+['*Back to section . . .*]
+[table
+[[]]
+[[[link function_synopsis_table ['*Function Synopsis*]] ]]
+[[[link boost_itl.interface ['*Interface*]] ]]
+]
+
[endsect][/ Addition]
Modified: sandbox/itl/libs/itl/doc/functions_cons_copy_dest.qbk
==============================================================================
--- sandbox/itl/libs/itl/doc/functions_cons_copy_dest.qbk (original)
+++ sandbox/itl/libs/itl/doc/functions_cons_copy_dest.qbk 2010-02-09 11:59:46 EST (Tue, 09 Feb 2010)
@@ -93,6 +93,15 @@
For all type combinations we have ['*linear time complexity*]
in the maximum of the `iterative_size` of `*this` and `src`.
+
+['*Back to section . . .*]
+[table
+[[]]
+[[[link function_synopsis_table ['*Function Synopsis*]]]]
+[[[link boost_itl.interface ['*Interface*]] ]]
+]
+
+
[endsect][/ Construct, copy, destruct]
Modified: sandbox/itl/libs/itl/doc/functions_containedness.qbk
==============================================================================
--- sandbox/itl/libs/itl/doc/functions_containedness.qbk (original)
+++ sandbox/itl/libs/itl/doc/functions_containedness.qbk 2010-02-09 11:59:46 EST (Tue, 09 Feb 2010)
@@ -117,6 +117,14 @@
logarithmic behavior, whereas the linear implementation
stays linear.
+
+['*Back to section . . .*]
+[table
+[[]]
+[[[link function_synopsis_table ['*Function Synopsis*]]]]
+[[[link boost_itl.interface ['*Interface*]] ]]
+]
+
[endsect][/ Containedness]
Modified: sandbox/itl/libs/itl/doc/functions_element_iteration.qbk
==============================================================================
--- sandbox/itl/libs/itl/doc/functions_element_iteration.qbk (original)
+++ sandbox/itl/libs/itl/doc/functions_element_iteration.qbk 2010-02-09 11:59:46 EST (Tue, 09 Feb 2010)
@@ -74,6 +74,20 @@
T::element_const_reverse_iterator T::elements_rend()const``] [Returns a reverse element iterator to a position `elements_rend()` before the first element of the container.]]
]
+
+['*See also . . .*]
+[table
+[[]]
+[[[link boost_itl.function_reference.iterator_related ['*Segment iteration*]] ]]
+]
+
+['*Back to section . . .*]
+[table
+[[]]
+[[[link function_synopsis_table ['*Function Synopsis*]]]]
+[[[link boost_itl.interface ['*Interface*]] ]]
+]
+
[endsect][/ Element iteration]
Modified: sandbox/itl/libs/itl/doc/functions_equivs_orderings.qbk
==============================================================================
--- sandbox/itl/libs/itl/doc/functions_equivs_orderings.qbk (original)
+++ sandbox/itl/libs/itl/doc/functions_equivs_orderings.qbk 2010-02-09 11:59:46 EST (Tue, 09 Feb 2010)
@@ -109,6 +109,19 @@
[endsect]
+
+['*See also . . .*]
+[table
+[[]]
+[[[link boost_itl.semantics.orderings_and_equivalences ['*Semantics*]]]]
+]
+['*Back to section . . .*]
+[table
+[[]]
+[[[link function_synopsis_table ['*Function Synopsis*]]]]
+[[[link boost_itl.interface ['*Interface*]] ]]
+]
+
[endsect][/ Equivalences and Orderings]
Modified: sandbox/itl/libs/itl/doc/functions_erasure.qbk
==============================================================================
--- sandbox/itl/libs/itl/doc/functions_erasure.qbk (original)
+++ sandbox/itl/libs/itl/doc/functions_erasure.qbk 2010-02-09 11:59:46 EST (Tue, 09 Feb 2010)
@@ -154,6 +154,21 @@
[endsect][/ Erasure by Iterators]
+
+['*See also . . .*]
+[table
+[[]]
+[[[link boost_itl.function_reference.insertion ['*Insertion*]] ]]
+[[[link boost_itl.function_reference.subtraction ['*Subtraction*]] ]]
+]
+
+['*Back to section . . .*]
+[table
+[[]]
+[[[link function_synopsis_table ['*Function Synopsis*]] ]]
+[[[link boost_itl.interface ['*Interface*]] ]]
+]
+
[endsect][/ Erasure]
Modified: sandbox/itl/libs/itl/doc/functions_insertion.qbk
==============================================================================
--- sandbox/itl/libs/itl/doc/functions_insertion.qbk (original)
+++ sandbox/itl/libs/itl/doc/functions_insertion.qbk 2010-02-09 11:59:46 EST (Tue, 09 Feb 2010)
@@ -99,6 +99,26 @@
[[interval_maps][] [] [] [__Olgn__][__On__] [] [__Omlgnpm__] ]
]
+
+[h4 Hinted insertion]
+
+Function `T& T::insert(T::iterator prior, const P& addend)` allows
+for an insertion 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 insertion
+above. Hinted insertion is available for these combinations of types:
+``
+// overload table for insertion with hint
+T& T::insert(T::iterator prior, const P&)
+
+insert | e i b p
+-------+--------
+s | s
+m | m
+S | S
+M | M
+``
+
[endsect][/ Insertion]
@@ -123,6 +143,19 @@
[endsect][/ Set]
+['*See also . . .*]
+[table
+[[]]
+[[[link boost_itl.function_reference.addition ['*Erasure*]] ]]
+[[[link boost_itl.function_reference.addition ['*Addition*]] ]]
+]
+
+['*Back to section . . .*]
+[table
+[[]]
+[[[link function_synopsis_table ['*Function Synopsis*]]]]
+[[[link boost_itl.interface ['*Interface*]] ]]
+]
[endsect][/ Insertion]
Modified: sandbox/itl/libs/itl/doc/functions_intersection.qbk
==============================================================================
--- sandbox/itl/libs/itl/doc/functions_intersection.qbk (original)
+++ sandbox/itl/libs/itl/doc/functions_intersection.qbk 2010-02-09 11:59:46 EST (Tue, 09 Feb 2010)
@@ -242,6 +242,22 @@
[endsect][/ Intersection tester]
+
+['*See also . . .*]
+[table
+[[]]
+[[[link boost_itl.function_reference.symmetric_difference ['*Symmetric difference*]] ]]
+[[[link boost_itl.function_reference.subtraction ['*Subtraction*]] ]]
+[[[link boost_itl.function_reference.addition ['*Addition*]] ]]
+]
+['*Back to section . . .*]
+[table
+[[]]
+[[[link function_synopsis_table ['*Function Synopsis*]] ]]
+[[[link boost_itl.interface ['*Interface*]] ]]
+]
+
+
[endsect][/ Intersection]
Modified: sandbox/itl/libs/itl/doc/functions_iterator_related.qbk
==============================================================================
--- sandbox/itl/libs/itl/doc/functions_iterator_related.qbk (original)
+++ sandbox/itl/libs/itl/doc/functions_iterator_related.qbk 2010-02-09 11:59:46 EST (Tue, 09 Feb 2010)
@@ -17,9 +17,9 @@
[[`J T::end()`] [__O1__] [__O1__] [__O1__] [__O1__] ]
[[`J T::rbegin()`] [__O1__] [__O1__] [__O1__] [__O1__] ]
[[`J T::rend()`] [__O1__] [__O1__] [__O1__] [__O1__] ]
-[[`J T::lower_bound(const key_value&)`] [__Olgn__] [__Olgn__] [__Olgn__] [__Olgn__] ]
-[[`J T::upper_bound(const key_value&)`] [__Olgn__] [__Olgn__] [__Olgn__] [__Olgn__] ]
-[[`pair<J,J> T::equal_range(const key_value&)`] [__Olgn__] [__Olgn__] [__Olgn__] [__Olgn__] ]
+[[`J T::lower_bound(const key_type&)`] [__Olgn__] [__Olgn__] [__Olgn__] [__Olgn__] ]
+[[`J T::upper_bound(const key_type&)`] [__Olgn__] [__Olgn__] [__Olgn__] [__Olgn__] ]
+[[`pair<J,J> T::equal_range(const key_type&)`] [__Olgn__] [__Olgn__] [__Olgn__] [__Olgn__] ]
]
[table
@@ -32,18 +32,18 @@
const_reverse_iterator T::rbegin()const``] [Returns a reverse iterator to the last value of the container.] ]
[[`` reverse_iterator T::rend()
const_reverse_iterator T::rend()const``] [Returns a reverse iterator to a position `rend()` before the first value of the container.]]
-[[`` iterator T::lower_bound(const key_value& k)
-const_iterator T::lower_bound(const key_value& key)const``][Returns an iterator that points to the first element `first`, that does not compare less than `key_value key`.
+[[`` iterator T::lower_bound(const key_type& k)
+const_iterator T::lower_bound(const key_type& key)const``][Returns an iterator that points to the first element `first`, that does not compare less than `key_type key`.
`first` can be equal or greater than `key`, or it may overlap `key` for interval containers.]]
-[[`` iterator T::upper_bound(const key_value&)
-const_iterator T::upper_bound(const key_value&)const``] [Returns an iterator that points to the first element `past`, that compares greater than `key_value key`.]]
+[[`` iterator T::upper_bound(const key_type&)
+const_iterator T::upper_bound(const key_type&)const``] [Returns an iterator that points to the first element `past`, that compares greater than `key_type key`.]]
[[``
- pair<iterator,iterator> T::equal_range(const key_value& key)
-pair<const_iterator,const_iterator> T::equal_range(const key_value& key)const
+ pair<iterator,iterator> T::equal_range(const key_type& key)
+pair<const_iterator,const_iterator> T::equal_range(const key_type& key)const
``
]
[Returns a range `[first, past)` of iterators to all elements of the container
- that compare neither less than nor greater than `key_value key`.
+ that compare neither less than nor greater than `key_type key`.
For element containers __itl_set__ and __itl_map__, `equal_range`
contains at most one iterator pointing the element equal to `key`,
if it exists.
@@ -59,6 +59,18 @@
['*logarithmic*] in the `iterative_size` of the container.
]
+['*See also . . .*]
+[table
+[[]]
+[[[link boost_itl.function_reference.element_iteration ['*Element iteration*]] ]]
+]
+['*Back to section . . .*]
+[table
+[[]]
+[[[link function_synopsis_table ['*Function Synopsis*]] ]]
+[[[link boost_itl.interface ['*Interface*]] ]]
+]
+
[endsect][/ Iterator related]
Modified: sandbox/itl/libs/itl/doc/functions_range.qbk
==============================================================================
--- sandbox/itl/libs/itl/doc/functions_range.qbk (original)
+++ sandbox/itl/libs/itl/doc/functions_range.qbk 2010-02-09 11:59:46 EST (Tue, 09 Feb 2010)
@@ -43,6 +43,12 @@
hull(x).last() == x.last()
``
+['*Back to section . . .*]
+[table
+[[]]
+[[[link function_synopsis_table ['*Function Synopsis*]] ]]
+[[[link boost_itl.interface ['*Interface*]] ]]
+]
[endsect][/ Range]
Modified: sandbox/itl/libs/itl/doc/functions_selection.qbk
==============================================================================
--- sandbox/itl/libs/itl/doc/functions_selection.qbk (original)
+++ sandbox/itl/libs/itl/doc/functions_selection.qbk 2010-02-09 11:59:46 EST (Tue, 09 Feb 2010)
@@ -36,6 +36,18 @@
+['*See also . . .*]
+[table
+[[]]
+[[[link boost_itl.function_reference.intersection ['*Intersection*]] ]]
+]
+['*Back to section . . .*]
+[table
+[[]]
+[[[link function_synopsis_table ['*Function Synopsis*]] ]]
+[[[link boost_itl.interface ['*Interface*]] ]]
+]
+
[endsect][/ Selection]
Modified: sandbox/itl/libs/itl/doc/functions_size.qbk
==============================================================================
--- sandbox/itl/libs/itl/doc/functions_size.qbk (original)
+++ sandbox/itl/libs/itl/doc/functions_size.qbk 2010-02-09 11:59:46 EST (Tue, 09 Feb 2010)
@@ -42,6 +42,12 @@
which is also it's `cardinality`.] ]
]
+['*Back to section . . .*]
+[table
+[[]]
+[[[link function_synopsis_table ['*Function Synopsis*]] ] ]
+[[[link boost_itl.interface ['*Interface*]] ] ]
+]
[endsect][/ Size]
Modified: sandbox/itl/libs/itl/doc/functions_streaming.qbk
==============================================================================
--- sandbox/itl/libs/itl/doc/functions_streaming.qbk (original)
+++ sandbox/itl/libs/itl/doc/functions_streaming.qbk 2010-02-09 11:59:46 EST (Tue, 09 Feb 2010)
@@ -23,6 +23,14 @@
[[`std::string T::as_string()`] [Returns a string representation of the object of type `T`]]
]
+
+['*Back to section . . .*]
+[table
+[[]]
+[[[link function_synopsis_table ['*Function Synopsis*]]]]
+[[[link boost_itl.interface ['*Interface*]] ]]
+]
+
[endsect][/ Streaming, conversion]
Modified: sandbox/itl/libs/itl/doc/functions_subtraction.qbk
==============================================================================
--- sandbox/itl/libs/itl/doc/functions_subtraction.qbk (original)
+++ sandbox/itl/libs/itl/doc/functions_subtraction.qbk 2010-02-09 11:59:46 EST (Tue, 09 Feb 2010)
@@ -162,5 +162,19 @@
``
[endsect][/- Infix operator Subtraction]
+
+['*See also . . .*]
+[table
+[[]]
+[[[link boost_itl.function_reference.addition ['*Addition*]] ]]
+[[[link boost_itl.function_reference.erasure ['*Erasure*]] ]]
+]
+['*Back to section . . .*]
+[table
+[[]]
+[[[link function_synopsis_table ['*Function Synopsis*]] ]]
+[[[link boost_itl.interface ['*Interface*]] ]]
+]
+
[endsect][/ Subtraction]
Modified: sandbox/itl/libs/itl/doc/functions_symmetric_difference.qbk
==============================================================================
--- sandbox/itl/libs/itl/doc/functions_symmetric_difference.qbk (original)
+++ sandbox/itl/libs/itl/doc/functions_symmetric_difference.qbk 2010-02-09 11:59:46 EST (Tue, 09 Feb 2010)
@@ -147,6 +147,21 @@
[endsect][/ Infix operators Symmetric Difference]
+
+['*See also . . .*]
+[table
+[[]]
+[[[link boost_itl.function_reference.intersection ['*Intersection*]] ]]
+[[[link boost_itl.function_reference.subtraction ['*Subtraction*]] ]]
+[[[link boost_itl.function_reference.addition ['*Addition*]] ]]
+]
+['*Back to section . . .*]
+[table
+[[]]
+[[[link function_synopsis_table ['*Function Synopsis*]] ]]
+[[[link boost_itl.interface ['*Interface*]] ]]
+]
+
[endsect][/ Symmetric Difference]
Modified: sandbox/itl/libs/itl/doc/interface.qbk
==============================================================================
--- sandbox/itl/libs/itl/doc/interface.qbk (original)
+++ sandbox/itl/libs/itl/doc/interface.qbk 2010-02-09 11:59:46 EST (Tue, 09 Feb 2010)
@@ -429,20 +429,20 @@
[table Itl Interfaces
[[T] [interval][__ch_itv_sets__][__ch_itv_maps__][itl::set][itl::map][std::set][std::map]]
[/ interval itvset itvmap itl:set itl:map std:set std:map]
-[[__biLConsCopyDest__] [ ] [ ] [ ] [ ] [ ] [ ] [ ]]
+[[__biLConsCopyDest__ [#function_synopsis_table]][ ] [ ] [ ] [ ] [ ] [ ] [ ]]
[[`T::T()`] [1] [1] [1] [1] [1] [1] [1]]
[[`T::T(const P&)`] [A] [__eiS] [__bpM] [1] [1] [1] [1]]
[/ FYI [`T::T(...)`] [3] [ ] [ ] [3] [3] [3] [3]]
[[`T& T::operator=(const P&)`] [A] [__S] [__M] [1] [1] [1] [1]]
[[`void T::swap(T&)`] [ ] [1] [1] [1] [1] [1] [1]]
-[[__biLContainedness__] [interval][__ch_itv_sets__][__ch_itv_maps__][itl::set][itl::map][std::set][std::map]]
+[[__biLContainedness__ ][interval][__ch_itv_sets__][__ch_itv_maps__][itl::set][itl::map][std::set][std::map]]
[[`void T::clear()`] [1] [1] [1] [1] [1] [1] [1]]
[[`bool T::empty()const`] [1] [1] [1] [1] [1] [1] [1]]
[[`bool T::contains(const P&)const`] [__ei] [__eiS][__eiS __bpM][__es] [__bm] [ ] [ ]]
[[`bool T::contained_in(const P&)const`] [__i] [__S] [__M] [1] [1] [ ] [ ]]
-[[__biLEquivsOrderings__][interval][__ch_itv_sets__][__ch_itv_maps__][itl::set][itl::map][std::set][std::map]]
+[[__biLEquivsOrderings__ ][interval][__ch_itv_sets__][__ch_itv_maps__][itl::set][itl::map][std::set][std::map]]
[[`bool operator == (const T&, const T&)`] [1] [1] [1] [1] [1] [1] [1]]
[[`bool operator != (const T&, const T&)`] [1] [1] [1] [1] [1] [1] [1]]
[[`bool operator < (const T&, const T&)`] [1] [1] [1] [1] [1] [1] [1]]
@@ -454,27 +454,28 @@
[[`bool is_element_greater(const T&, const P&)`][ ] [__S] [__M] [1] [1] [ ] [ ]]
[[`bool is_protonic_equal(const T&, const P&)`][ ] [ ] [__M] [ ] [1] [ ] [ ]]
-[[__biLSize__] [interval][__ch_itv_sets__][__ch_itv_maps__][itl::set][itl::map][std::set][std::map]]
+[[__biLSize__ ] [interval][__ch_itv_sets__][__ch_itv_maps__][itl::set][itl::map][std::set][std::map]]
[[`size_type T::size()const`] [1] [1] [1] [1] [1] [1] [1]]
[[`size_type T::cardinality()const`] [1] [1] [1] [1] [1] [ ] [ ]]
[[`difference_type T::length()const`] [1] [1] [1] [ ] [ ] [ ] [ ]]
[[`size_t T::iterative_size()const`] [ ] [1] [1] [1] [1] [ ] [ ]]
[[`size_t T::interval_count()const`] [ ] [1] [1] [ ] [ ] [ ] [ ]]
-[[__biLRange__] [ ] [ ] [ ] [ ] [ ] [ ] [ ]]
+[[__biLRange__ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ]]
[[`interval<domain_type> hull(const T&)`] [ ] [1] [1] [ ] [ ] [ ] [ ]]
[[`domain_type T::lower()const`] [1] [1] [1] [ ] [ ] [ ] [ ]]
[[`domain_type T::upper()const`] [1] [1] [1] [ ] [ ] [ ] [ ]]
[[`domain_type T::first()const`] [1] [1] [1] [ ] [ ] [ ] [ ]]
[[`domain_type T::last()const`] [1] [1] [1] [ ] [ ] [ ] [ ]]
-[[__biLSelection__] [ ] [ ] [ ] [ ] [ ] [ ] [ ]]
+[[__biLSelection__ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ]]
[[`J T::find(const domain_type&)`] [ ] [1] [1] [2] [2] [2] [2]]
[[`codomain_type& operator[] (const domain_type&)`][ ] [ ] [] [ ] [1] [ ] [1]]
[[`codomain_type operator() (const domain_type&)const`][ ][ ] [1] [ ] [1] [ ] [ ]]
[[__biLAddition__] [interval][__ch_itv_sets__][__ch_itv_maps__][itl::set][itl::map][std::set][std::map]]
[[`T& T::add(const P&)`] [ ] [__ei] [__bp] [__e] [__b] [ ] [ ]]
+[[`T& T::add(J pos, const P&)`] [ ] [__i] [__p] [__e] [__b] [ ] [ ]]
[[`T& operator +=(T&, const P&)`] [ ] [__eiS] [__bpM] [__es] [__bm] [ ] [ ]]
[[`T operator + (T, const P&)`\n`T operator + (const P&, T)`]
[ ] [__eiS] [__bpM] [__es] [__bm] [ ] [ ]]
@@ -488,6 +489,7 @@
[[__biLInsertion__] [interval][__ch_itv_sets__][__ch_itv_maps__][itl::set][itl::map][std::set][std::map]]
[[`V T::insert(const P&)`] [ ] [__ei] [__bp] [__e] [__b] [__e] [__b]]
+[[`V T::insert(J pos, const P&)`] [ ] [__i] [__p] [__e] [__b] [__e] [__b]]
[[`T& insert(T&, const P&)`] [ ] [__eiS] [__bpM] [__es] [__bm] [ ] [ ] ]
[[`T& T::set(const P&)`] [ ] [ ] [__bp] [ ] [1] [ ] [ ] ]
@@ -514,11 +516,11 @@
[[`J T::end()`] [ ] [2] [2] [2] [2] [2] [2]]
[[`J T::rbegin()`] [ ] [2] [2] [2] [2] [2] [2]]
[[`J T::rend()`] [ ] [2] [2] [2] [2] [2] [2]]
-[[`J T::lower_bound(const key_value&)`] [ ] [2] [2] [2] [2] [2] [2]]
-[[`J T::upper_bound(const key_value&)`] [ ] [2] [2] [2] [2] [2] [2]]
-[[`pair<J,J> T::equal_range(const key_value&)`][ ] [2] [2] [2] [2] [2] [2]]
+[[`J T::lower_bound(const key_type&)`] [ ] [2] [2] [2] [2] [2] [2]]
+[[`J T::upper_bound(const key_type&)`] [ ] [2] [2] [2] [2] [2] [2]]
+[[`pair<J,J> T::equal_range(const key_type&)`] [ ] [2] [2] [2] [2] [2] [2]]
-[[__biLStreaming__] [interval][__ch_itv_sets__][__ch_itv_maps__][itl::set][itl::map][std::set][std::map]]
+[[__biLStreaming__ ] [interval][__ch_itv_sets__][__ch_itv_maps__][itl::set][itl::map][std::set][std::map]]
[[`std::basic_ostream operator << (basic_ostream&, const T&)`]
[1] [1] [1] [1] [1] [1] [1]]
[[`std::string T::as_string()`] [1] [1] [1] [1] [1] [ ] [ ]]
Modified: sandbox/itl/libs/itl/doc/introduction.qbk
==============================================================================
--- sandbox/itl/libs/itl/doc/introduction.qbk (original)
+++ sandbox/itl/libs/itl/doc/introduction.qbk 2010-02-09 11:59:46 EST (Tue, 09 Feb 2010)
@@ -12,6 +12,9 @@
The /Interval Template Library/ is currently submitted
for a formal review on the boost developer's list.
+
+[* The review will start on February 18, 2010 and will end on February 27, 2010.]
+
Depending on the review's result the library might or
might not become a boost library.
@@ -155,6 +158,14 @@
As can be seen from the example an __itv_map__ has both
a ['*decompositional behavior*] (on the time dimension) as well as
an ['*accumulative one*] (on the associated values).
+
+Addability and aggregate on overlap are useful features on
+__itv_maps__ implemented via function `add` and `operator +=`.
+But you can also use them with the ['traditional]
+[link boost_itl.function_reference.insertion insert semantics]
+that behaves like `std::map::insert` generalized for
+interval insertion.
+
[endsect]
[section Itl's class templates]
@@ -165,7 +176,7 @@
* An __itl_set__ is behavioral equal to __itv_bsets__ on the __bi_conceptual__ aspect.
* An __itl_map__ is behavioral equal to __itv_bmaps__ on the __bi_conceptual__ aspect.
- Specifically a __itl_map__
+ Specifically an __itl_map__
implements ['*aggregate on overlap*], which is
named ['*aggregate on collision*] for an element container.
@@ -279,7 +290,7 @@
__Sep_itv_set__ implements the separating style.
This style preserves borders, that are never passed by an overlapping
-interval. So if all intervals that are inserted into an __sep_itv_set__
+interval. So if all intervals that are inserted into a __sep_itv_set__
are generated form a certain grid that never pass say month borders, then
these borders are preserved in the __sep_itv_set__.