Boost logo

Boost-Commit :

Subject: [Boost-commit] svn:boost r50145 - sandbox/itl/libs/itl/doc
From: afojgo_at_[hidden]
Date: 2008-12-05 16:35:36

Author: jofaber
Date: 2008-12-05 16:35:36 EST (Fri, 05 Dec 2008)
New Revision: 50145

Added documentation. Introduction aspects, examples. Stable {msvc-9.0}
Text files modified:
   sandbox/itl/libs/itl/doc/examples.qbk | 32 ++++++++++-
   sandbox/itl/libs/itl/doc/itl.qbk | 106 +++++++++++++++++++++++++++++++++------
   2 files changed, 118 insertions(+), 20 deletions(-)

Modified: sandbox/itl/libs/itl/doc/examples.qbk
--- sandbox/itl/libs/itl/doc/examples.qbk (original)
+++ sandbox/itl/libs/itl/doc/examples.qbk 2008-12-05 16:35:36 EST (Fri, 05 Dec 2008)
@@ -89,21 +89,45 @@
 [section Interval]
 Example *interval* shows some basic functionality of __itvs__.
-Different instances of __itvs__ for integral ([^int, Time]) and
-continuous types ([^double, std::string]) are used and some
-intersing functions calls on open intervals are tested e.g.:
-``interval<double>::rightopen(1/sqrt(2.0), sqrt(2.0)).contains(sqrt(2.0));``
+* Different instances of __itvs__ for integral ([^int, Time]) and
+ continuous types ([^double, std::string]) are used.
+* The examples uses open and closed intervals bounds.
+* Some borderline functions calls on open interval borders are tested e.g.:
+ `interval<double>::rightopen(1/sqrt(2.0), sqrt(2.0)).contains(sqrt(2.0));`
 [import ../example/interval/interval.cpp]
 [section Interval container]
+Example [*interval container] demonstrates the characteristic behaviors
+of different interval containers that are also summarized
+in the introductory [link boost.itl.introduction.interval_combining_styles Interval Combining Styles].
 [import ../example/interval_container/interval_container.cpp]
 [section Time grids for months and weeks]
+A __spl_itv_set__ preserves all interval borders on insertion
+and intersection operations. So given a __spl_itv_set__
+x = {[1, 3)}
+x.add( [2, 4)) then
+x == {[1,2)[2,3)[3,4)}
+Using this property we can intersect __spl_itv_maps__ in
+order to iterate over intervals accounting for all occurring
+changes of interval borders.
+In this example we provide an intersection of two __spl_itv_sets__
+representing a month and week time grid.
 [import ../example/month_and_week_grid/month_and_week_grid.cpp]

Modified: sandbox/itl/libs/itl/doc/itl.qbk
--- sandbox/itl/libs/itl/doc/itl.qbk (original)
+++ sandbox/itl/libs/itl/doc/itl.qbk 2008-12-05 16:35:36 EST (Fri, 05 Dec 2008)
@@ -24,9 +24,17 @@
 [def __Itvs__ [classref boost::itl::interval Intervals]]
 [def __itv_set__ [classref boost::itl::interval_set interval_set]]
 [def __itv_sets__ [classref boost::itl::interval_set interval_sets]]
+[def __itv_bset__ [classref boost::itl::interval_base_set interval_set]]
+[def __Itv_bset__ [classref boost::itl::interval_base_set Interval_set]]
 [def __itv_bsets__ [classref boost::itl::interval_base_set interval_sets]]
 [def __Itv_bsets__ [classref boost::itl::interval_base_set Interval_sets]]
+[def __ele_set__ [classref boost::itl::set set]]
+[def __ele_sets__ [classref boost::itl::set sets]]
+[def __itl_set__ [classref boost::itl::set itl::set]]
+[def __itl_sets__ [classref boost::itl::set itl::sets]]
 [def __Itv_set__ [classref boost::itl::interval_set Interval_set]]
 [def __spl_itv_set__ [classref boost::itl::split_interval_set split_interval_set]]
 [def __spl_itv_sets__ [classref boost::itl::split_interval_set split_interval_sets]]
@@ -35,11 +43,20 @@
 [def __Sep_itv_set__ [classref boost::itl::separate_interval_set Separate_interval_set]]
 [def __itv_map__ [classref boost::itl::interval_map interval_map]]
 [def __itv_maps__ [classref boost::itl::interval_map interval_maps]]
+[def __itv_map_s__ [classref boost::itl::interval_map interval_map's]]
+[def __itv_bmap__ [classref boost::itl::interval_base_map interval_map]]
+[def __Itv_bmap__ [classref boost::itl::interval_base_map Interval_map]]
 [def __itv_bmaps__ [classref boost::itl::interval_base_map interval_maps]]
 [def __Itv_bmaps__ [classref boost::itl::interval_base_map Interval_maps]]
 [def __Itv_map__ [classref boost::itl::interval_map Interval_map]]
 [def __spl_itv_map__ [classref boost::itl::split_interval_map split_interval_map]]
 [def __Spl_itv_map__ [classref boost::itl::split_interval_map Split_interval_map]]
+[def __spl_itv_maps__ [classref boost::itl::split_interval_map split_interval_maps]]
+[def __ele_map__ [classref boost::itl::map map]]
+[def __ele_maps__ [classref boost::itl::map maps]]
+[def __itl_map__ [classref boost::itl::map itl::map]]
+[def __itl_maps__ [classref boost::itl::map itl::maps]]
 [def __itv_bse_set__ [classref boost::itl::interval_base_set interval_base_set]]
 [def __e [link element_type *e*]]
@@ -70,20 +87,22 @@
 [section Definition and Basic Example]
-The Interval Template Library (ITL) offers *intervals* and two kinds of
-interval containers: *interval_sets* and *interval_maps*.
+The ['*Interval Template Library (ITL)*] provides __itvs__ and two kinds of
+interval containers: __itv_sets__ and __itv_maps__.
-An __itv_bsets__ implements a [*set] ['(of elements)] using a ['*set*] of intervals.[br]
-An __itv_bmaps__ implements a [*map] ['(of element value pairs)] using a ['*map*] of interval value pairs.
+* An __itv_bset__ implements a [*set] as a set of intervals.
+* An __itv_bmap__ implements a [*map] as a map of interval value pairs.
-__Itv_bsets__ and __itv_bmaps__ thus expose two different aspects in
+[h4 Two Aspects]
+__Itv_bsets__ and __itv_bmaps__ expose two different aspects in
 their interfaces: (1) The functionality of a set or a map, which is the more
-['abstract aspect]. And (2) the functionality of an interval container which
+['abstract aspect]. And (2) the functionality of a container of intervals which
 is the more specific and ['implementation related aspect]. In practice both
 aspects are useful and are therefore supported.
 The first aspect, that will be called ['*conceptual aspect*], is the more important one.
-It means that we will commonly use any interval_set or interval_map like a normal
+It means that we can use any __itv_set__ or __itv_map__ like a normal
 set or map ['*of elements*].
@@ -93,19 +112,20 @@
 The second aspect, that will be called ['*iterative aspect*], allows to exploit the
-fact, that the elements of __itv_sets__ and __itv_maps__ are commonly clustered in
+fact, that the elements of __itv_sets__ and __itv_maps__ are clustered in
 __itvs__ that we can iterate over.
 // Switch on my favorite telecasts using an interval_set
 interval<seconds> news(make_seconds("20:00:00"), make_seconds("20:15:00"));
 interval<seconds> talk_show(make_seconds("22:45:30"), make_seconds("23:30:50"));
-interval_set<seconds> myTvProgam;
+interval_set<seconds> myTvProgram;
-// Iterating over elements (seconds) would be silly
+// Iterating over elements (seconds) would be silly ...
 for(interval_set<seconds>::iterator telecast = myTvProgam.begin();
     telecast != myTvProgam.end(); ++telecast)
+ // this iterates over intervals
@@ -113,7 +133,24 @@
 beneficial whenever the elements of
 sets appear in contiguous chunks: __itvs__. This is obviously the
 case in many problem domains, namely in fields that deal with problems
-related to date and time.
+related to date and time.
+[h4 Addabitlity and Subtractability]
+Unlike std::sets and maps, __itv_sets__ and __itv_maps__ implement
+concept Addable and Subtractable. So __itv_sets__ define an
+`operator +=` that is naturally implemented as ['*set union*] and an
+`operator -=` that is consequently implemented as ['*set difference*].
+In the *itl* also __itv_maps__ are Addable and Subtractable.
+It turned out to be a very fruitful concept to propagate the
+addition or subtraction to the __itv_map_s__ associated values
+in cases where the insertion of an interval value pair into an
+__itv_map__ resulted in a collision of the inserted interval
+value pare with intervals value pairs, that were already in the
+__itv_map__. This operation propagation is called ['*aggregate on overlap*].
+[h4 Aggregate on Overlap]
 This is a first motivating example of a very small party, demonstrationg the
 ['*aggregate on overlap*] principle ['*(aggrovering)*] on __itv_maps__:
@@ -121,7 +158,7 @@
 In the example Mary enters the party first. She attends during the
 time interval [20:00,22:00). Harry enters later he stays within [21:00,23:00).
-typedef set<string> guests;
+typedef itl::set<string> guests;
 interval_map<time, guests> party;
 party += make_pair(interval<time>::rightopen(20:00, 22:00), guests("Mary"));
 party += make_pair(interval<time>::rightopen(21:00, 23:00), guests("Harry"));
@@ -132,14 +169,51 @@
 On overlap of intervals, the corresponding name sets are accumulated. At
 the points of overlap the intervals are split. The accumulation of content on
-overlap of intervals is done via an operator += that has to be implemented
-for the content parameter of the __itv_map__.
+overlap of intervals is done via an `operator +=` that has to be implemented
+for the associated values of the __itv_map__. In the example
+the associated values are guest sets. This set has thus to implement
+`operator +=` as set union.
 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).
+[section Itl's class templates]
+In completion to interval containers the *itl* provides element containers
+__itl_set__ and __itl_map__.
+* An __itl_set__ is behavioral equal to __itv_bsets__
+ except for iteration. That is to say behavioral equal on
+ the conceptual aspect.
+* An __itl_map__ is behavioral equal to __itv_bmaps__
+ except for iteration, that is on the conceptional
+ aspect. Specifically a __itl_map__
+ implements ['*aggregate on overlap*], which is
+ named ['*aggregate on collision*] for an element container.
+The following tabel gives an overview over the main
+class templates provided by the *itl*.
+[table Synopsis over the itl's class templates
+[[granularity][style] [sets] [maps] ]
+[[interval] [] [__itv__] [] ]
+[[] [joining] [__itv_set__] [__itv_set__] ]
+[[] [separating][__sep_itv_set__][] ]
+[[] [splitting] [__spl_itv_set__][__spl_itv_set__]]
+[[element] [] [__ele_set__] [__ele_map__] ]
+__Itv__ is placed deliberately in column *sets* because an
+interval is a set as well. Column ['*style*] refers to
+the different ways in which interval containers digest added
+intervals. These combining styles are described in the next
 [section Interval Combining Styles]
 When we add intervals or interval value pairs to interval containers,
@@ -212,8 +286,8 @@
 __Itv_set__ and __itv_map__ are always
 in a ['*minimal representation*]. This is useful in many cases, where the
 points of insertion or intersecton of intervals are not relevant. So in most
-instances [classref boost::itl::interval_set interval_set] and
-[classref boost::itl::interval_map Interval_map] will be the first choice
+instances __itv_set__ and
+__itv_map__ will be the first choice
 for an interval container.
 [h4 Splitting interval containers]

Boost-Commit list run by bdawes at, david.abrahams at, gregod at, cpdaniel at, john at