|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r50132 - sandbox/itl/libs/itl/doc
From: afojgo_at_[hidden]
Date: 2008-12-05 08:30:45
Author: jofaber
Date: 2008-12-05 08:30:44 EST (Fri, 05 Dec 2008)
New Revision: 50132
URL: http://svn.boost.org/trac/boost/changeset/50132
Log:
Added documentation. Set types synopsis, examples. Stable {msvc-9.0}
Text files modified:
sandbox/itl/libs/itl/doc/examples.qbk | 7 ++
sandbox/itl/libs/itl/doc/interface.qbk | 68 ++++++++++++++++++++++---
sandbox/itl/libs/itl/doc/itl.qbk | 105 ++++++++++++++++++++++++++-------------
3 files changed, 135 insertions(+), 45 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 08:30:44 EST (Fri, 05 Dec 2008)
@@ -87,6 +87,13 @@
[endsect]
[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));``
+
[import ../example/interval/interval.cpp]
[example_interval]
[endsect]
Modified: sandbox/itl/libs/itl/doc/interface.qbk
==============================================================================
--- sandbox/itl/libs/itl/doc/interface.qbk (original)
+++ sandbox/itl/libs/itl/doc/interface.qbk 2008-12-05 08:30:44 EST (Fri, 05 Dec 2008)
@@ -8,17 +8,66 @@
[section Interface]
-[table Associated types of sets
-[[Aspects] [] [type] [interval_sets] [interval] [itl::set] [std::set]]
-[[abstract] [data] [domain_type] [DomainT] [DomainT] [DomainT] []]
-[[] [ordering][domain_compare] [Compare<DomainT>] [Compare<DomainT>][Compare<DomainT>][]]
-[[iterative][data] [interval_type] [Interval<Compare<DomainT>>][][][]]
-[[] [] [key_type] [Interval<Compare<DomainT>>][][] [_Key]]
-[[] [] [value_type] [Interval<Compare<DomainT>>][][] [_Key]]
-[[] [ordering][interval_compare][exclusive_less<interval_type>][][] []]
-[[] [] [key_compare] [exclusive_less<interval_type>][][] [_Compare]]
+Section Interface gives an overview over the types and functions
+of the ITL. Synoptical tables allow to review the overall structure of
+the libraries design and to recognize structural equalities and differences
+with the corresponding containers of the standard template library.
+
+There are two majaor aspects or views of itl containers. The first and predominant
+aspect is called conceptual. The second and minor aspect is called iterative or
+iteration related.
+
+[table
+[[Aspect] [Abstraction level][] [] [Practical]]
+[[Conceptual][more abstract][concept related] [iterator idependent][interval_sets(maps) can be used as sets(maps)
+ except for element iteration.]]
+[[Iterative] [less abstract][implementation related][iterator dependent] [interval_sets(maps) can be interval iterated]]
]
+On the conceptual aspect
+
+* in interval implements a set of elements partially.
+* an interval_set implements a set of elements.
+* an interval_map implements a map of element value pairs.
+
+On the iteration related or iterative aspect
+
+* an interval_set implements a set of intervals.
+* an interval_map implements a map of interval value pairs.
+
+
+
+In the table of associated types of interval_sets
+there are types like key_type, value_type and key_compare
+for the iterative aspect.
+
+[section Types]
+
+[table Types and parameter types of sets
+[[] [type of elements][order of elements][type of intervals] [memory allocation]]
+[[template parameter] [class] [template<class>class] [template<class,template<class>class>class] [template<class>class]]
+[[interval] [DomainT][Compare = std::less] [] []]
+[[interval_set] [DomainT][Compare = std::less] [Interval = itl::interval] [Alloc = std::alloc]]
+[[itl::set] [DomainT][Compare = std::less] [Interval = itl::interval] [Alloc = std::alloc]]
+[[template parameter] [class] [class] [class] [class]]
+[[std::set] [_Key] [_Compare = std::less<_Key>][] [Alloc = std::alloc<_Key>]]
+]
+
+[table Associated types of sets
+[[Aspects] [] [type] [interval] [interval_sets] [itl::set] [std::set]]
+[[conceptual] [data] [domain_type] [DomainT] [DomainT] [DomainT] []]
+[[] [ordering][domain_compare] [Compare<DomainT>][Compare<DomainT>] [Compare<DomainT>][]]
+[[iterative] [data] [interval_type] [] [Interval<DomainT,Compare>] [] []]
+[[] [] [key_type] [] [Interval<DomainT,Compare>] [] [_Key]]
+[[] [] [value_type] [] [Interval<DomainT,Compare>] [] [_Key]]
+[[] [ordering][interval_compare][] [exclusive_less<interval_type>][] []]
+[[] [] [key_compare] [] [exclusive_less<interval_type>][] [_Compare]]
+]
+
+[endsect]
+
+[section Function Matrix]
+
[table
[[Placeholder] [Argument types] [Description]]
[[[#element_type] [*e]] [T::domain_type] [the element type of the container]]
@@ -76,5 +125,6 @@
[[J upper_bound(const I&)] [ ] [2] [2] [2] [2] [2] [2]]
]
+[endsect]
[endsect]
\ No newline at end of file
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 08:30:44 EST (Fri, 05 Dec 2008)
@@ -20,8 +20,13 @@
[/ Macros will be used for links so we have a central place to change them ]
[def __itv__ [classref boost::itl::interval interval]]
[def __Itv__ [classref boost::itl::interval Interval]]
+[def __itvs__ [classref boost::itl::interval intervals]]
+[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_bsets__ [classref boost::itl::interval_base_set interval_sets]]
+[def __Itv_bsets__ [classref boost::itl::interval_base_set Interval_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]]
@@ -30,6 +35,8 @@
[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_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]]
@@ -66,24 +73,50 @@
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 __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.
-[classref boost::itl::interval_base_set Interval_sets] and
-[classref boost::itl::interval_base_map interval_maps] thus expose two different aspects in
+__Itv_bsets__ and __itv_bmaps__ thus 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
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
+set or map ['*of elements*].
+
+``
+interval_set<int> mySet;
+mySet.insert(42);
+bool has_answer = mySet.contains(42);
+``
+
+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
+__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;
+myTVProgram.add(news).add(talk_show);
+
+// Iterating over elements (seconds) would be silly
+for(interval_set<seconds>::iterator telecast = myTvProgam.begin();
+ telecast != myTvProgam.end(); ++telecast)
+ TV.switch_on(*telecast);
+``
+
Working with interval_sets and interval_maps can be
beneficial whenever the elements of
-sets appear in contiguous chunks: intervals. This is obviously the
+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.
This is a first motivating example of a very small party, demonstrationg the
-['*aggregate on overlap*] principle ['*(aggrovering)*] on interval_maps:
+['*aggregate on overlap*] principle ['*(aggrovering)*] on __itv_maps__:
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).
@@ -100,11 +133,11 @@
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 interval_map.
+for the content parameter of the __itv_map__.
-As can be seen from the example an interval_map has both
-a decompositional behavior (on the time dimension) as well as
-an accumulative one (on the associated values).
+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).
[endsect]
[section Interval Combining Styles]
@@ -134,20 +167,20 @@
[[classref boost::itl::split_interval_set split_interval_set] /C/]]
[[]
[``
- [1 3)
-+ [2 4)
-+ [4 5)
-= [1 5)``]
+ {[1 3) }
++ [2 4)
++ [4 5)
+= {[1 5)}``]
[``
- [1 3)
-+ [2 4)
-+ [4 5)
-= [1 4)[4 5)``]
+ {[1 3)} }
++ [2 4)
++ [4 5)
+= {[1 4)[4 5)}``]
[``
- [1 3)
-+ [2 4)
-+ [4 5)
-= [1 2)[2 3)[3 4)[4 5)``]
+ {[1 3) }
++ [2 4)
++ [4 5)
+= {[1 2)[2 3)[3 4)[4 5)}``]
]
[[map] [[classref boost::itl::interval_map interval_map] /D/]
@@ -156,25 +189,25 @@
[[]
[``
- [1 3)->1
-+ [2 4)->1
-+ [4 5)->1
-= [1 2)[2 3)[3 5)
- ->1 ->2 ->1``]
+ {[1 3)->1 }
++ [2 4)->1
++ [4 5)->1
+= {[1 2)[2 3)[3 5) }
+ | ->1 ->2 ->1 |``]
[]
[``
- [1 3)->1
-+ [2 4)->1
-+ [4 5)->1
-= [1 2)[2 3)[3 4)[4 5)
- ->1 ->2 ->1 ->1``]
+ {[1 3)->1 }
++ [2 4)->1
++ [4 5)->1
+= {[1 2)[2 3)[3 4)[4 5) }
+ | ->1 ->2 ->1 ->1 |``]
]
]
-Note that =interval_sets= /A/, /B/ and /C/ represent the same set of elements
-and =interval_maps= /D/ and /E/ represent the same map of elements.
+Note that =interval_sets= /A/, /B/ and /C/ represent the same set of elements ={1,2,3,4}=
+and =interval_maps= /D/ and /E/ represent the same map of elements [^{1->1, 2->2, 3->1, 4->1}].
-Joining interval containers
+[h4 Joining interval containers]
__Itv_set__ and __itv_map__ are always
in a ['*minimal representation*]. This is useful in many cases, where the
@@ -183,7 +216,7 @@
[classref boost::itl::interval_map Interval_map] will be the first choice
for an interval container.
-Splitting interval containers
+[h4 Splitting interval containers]
__Spl_itv_set__ and __spl_itv_map__ on the contrary
have an ['*insertion memory*]. They do accumulate interval borders both
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk