[Boost-commit] svn:boost r49911 - sandbox/itl/libs/itl/doc

Subject: [Boost-commit] svn:boost r49911 - sandbox/itl/libs/itl/doc
From: afojgo_at_[hidden]
Date: 2008-11-24 02:37:06

Author: jofaber
Date: 2008-11-24 02:37:05 EST (Mon, 24 Nov 2008)
New Revision: 49911
URL: http://svn.boost.org/trac/boost/changeset/49911

Log:
Added documentation. Stable {msvc-9.0}
Text files modified: 
   sandbox/itl/libs/itl/doc/examples.qbk |    44 +++++++++++++++++++++++++++++++++++++-- 
   sandbox/itl/libs/itl/doc/itl.qbk      |     6 ++--                                    
   2 files changed, 44 insertions(+), 6 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-11-24 02:37:05 EST (Mon, 24 Nov 2008)
@@ -12,11 +12,11 @@
 
 [table Overview over Itl Examples
         [[level]   [example] [classes] [features]]
-	[[flagship][[link boost_itl.examples.boost_party Boost party]]
+	[[flagship][[link boost_itl.examples.party Party]]
                 [__itv_map__][Generates an attendance history of a party
                           by inserting into an __itv_map__. 
                                           Demonstrating 
-					  ['*aggregate on overlap, split on insertion*]]]
+					  ['*aggregate on overlap*]]]
         [[basic]   [[link boost_itl.examples.interval Interval]]
             [__itv__] [Intervals for integral and continuous instance types. 
                        Closed and open interval borders]]
@@ -43,8 +43,46 @@
 
 [endsect]
 
-[section Boost party]
+[section Party]
 [import ../example/boost_party/boost_party.cpp]
+
+Example *party* demonstrates the possibilities of an interval map 
+(__itv_map__ or __spl_itv_map__). 
+An __itv_map__ maps intervals to a given content. In this case the 
+content is a set of party guests represented by their name strings.
+
+As time goes by, groups of people join the party and leave later in the evening.
+So we add a time interval and a name set to the __itv_map__ for the attendance
+of each group of people, that come together and leave together.
+
+On every overlap of intervals, the corresponding name sets are accumulated. At
+the points of overlap the intervals are split. The accumulation of content
+is done via an operator += that has to be implemented
+for the content parameter of the __itv_map__.
+
+Finally the interval_map contains the history of attendance and all points in
+time, where the group of party guests changed.
+
+Party demonstrates a principle that we call 
+['*aggregate on overlap (aggrovering)*]:
+On insertion a value associated to the interval is aggregated with those
+values in the interval_map that overlap with the inserted value.
+
+There are two behavioral aspects to ['*aggrovering*]: a ['*decompositional
+behavior*] and an ['*accumulative behavior*].
+
+* The ['*decompositional behavior*] splits up intervals on the /time/ /dimension/ of the 
+  interval_map so that the intervals are split whenever associated values
+  change.
+
+* The ['*accumulative behavior*] accumulates associated values on every overlap of
+  an insertion for the associated values.
+	
+The aggregation function is += by default. Different aggregations can
+be used, if desired. In the example the history of the tallest party guest's
+height is calculated using [classref boost::itl::inplace_max inplace_max] 
+as aggregation function. 
+	
 [example_boost_party]
 [endsect]
 

Modified: sandbox/itl/libs/itl/doc/itl.qbk
==============================================================================
--- sandbox/itl/libs/itl/doc/itl.qbk	(original)
+++ sandbox/itl/libs/itl/doc/itl.qbk	2008-11-24 02:37:05 EST (Mon, 24 Nov 2008)
@@ -66,8 +66,8 @@
 The Interval Template Library (ITL) offers *intervals* and two kinds of 
 interval containers: *interval_sets* and *interval_maps*.
 
-An [classref boost::itl::interval_base_set interval_set] implements a set as a set of intervals.[br]
-An [classref boost::itl::interval_base_map interval_map] implements a map as a map of interval value pairs.
+An [classref boost::itl::interval_base_set interval_set] implements a set as a /*set*/ of intervals.[br]
+An [classref boost::itl::interval_base_map interval_map] implements a map as a /*map*/ of interval value pairs.
 
 [classref boost::itl::interval_base_set Interval_sets] and 
 [classref boost::itl::interval_base_map interval_maps] thus expose two different aspects in
@@ -77,7 +77,7 @@
 aspects are useful and are therefore supported. 
 
 Working with interval_sets and interval_maps can be 
-beneficial whenever in a given problem domain the elements of 
+beneficial whenever the elements of 
 sets appear in contiguous chunks: intervals. This is obviously the 
 case in many problem domains, namely in fields that deal with problems 
 related to date and time.