|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r50347 - in sandbox/itl: boost/itl libs/itl/doc
From: afojgo_at_[hidden]
Date: 2008-12-21 16:43:27
Author: jofaber
Date: 2008-12-21 16:43:26 EST (Sun, 21 Dec 2008)
New Revision: 50347
URL: http://svn.boost.org/trac/boost/changeset/50347
Log:
Added documentation. Required concepts, parameter Section, Interface. Stable {msvc-9.0, partly congcc-4.3-a7}
Text files modified:
sandbox/itl/boost/itl/notate.hpp | 2
sandbox/itl/libs/itl/doc/concepts.qbk | 42 ++++++++++++++--
sandbox/itl/libs/itl/doc/interface.qbk | 99 ++++++++++++++++++++-------------------
sandbox/itl/libs/itl/doc/itl.qbk | 23 ++++++--
4 files changed, 104 insertions(+), 62 deletions(-)
Modified: sandbox/itl/boost/itl/notate.hpp
==============================================================================
--- sandbox/itl/boost/itl/notate.hpp (original)
+++ sandbox/itl/boost/itl/notate.hpp 2008-12-21 16:43:26 EST (Sun, 21 Dec 2008)
@@ -1,4 +1,6 @@
/*----------------------------------------------------------------------------+
+Copyright (c) 2007-2008: Joachim Faulhaber
++-----------------------------------------------------------------------------+
Copyright (c) 1999-2006: Cortex Software GmbH, Kantstrasse 57, Berlin
+-----------------------------------------------------------------------------+
Boost Software License - Version 1.0 - August 17th, 2003
Modified: sandbox/itl/libs/itl/doc/concepts.qbk
==============================================================================
--- sandbox/itl/libs/itl/doc/concepts.qbk (original)
+++ sandbox/itl/libs/itl/doc/concepts.qbk 2008-12-21 16:43:26 EST (Sun, 21 Dec 2008)
@@ -162,9 +162,9 @@
For `Combine` functors, the Itl provides an __inverse__ functor.
[table
-[[Combine<T>] [inverse<Combine<T> >::type]]
+[[`Combine<T>`] [`inverse<Combine<T> >::type`]]
[[__ip_plus__`<T>`] [__ip_minus__`<T>`] ]
-[[__ip_star__`<T>`] [__ip_div__`<T>`] ]
+[[__ip_star__`<T>`] [__ip_slash__`<T>`] ]
[[__ip_max__`<T>`] [__ip_min__`<T>`] ]
[[__ip_identity__`<T>`][__ip_erasure__`<T>`]]
[[`Functor`] [__ip_erasure__`<T>`]]
@@ -205,7 +205,7 @@
But you could instantiate an __itv_map__ to have
`insert/erase` semantics this way:
``
-interval_map<int,int,neutron_absorber,interval,
+interval_map<int,int,neutron_absorber,
std::less,
inplace_identity //Combine parameter specified
> m;
@@ -245,12 +245,40 @@
[[__emitter__] [all value pairs that don't carry protons have neutrons as mapped values.]]
]
+Note, that a neutron is defined in relation to a combiner operation. In many cases
+this relation is straight and often covered by the default parameters of itl `Maps`.
+
+[table
+[[type] [operation] [neutron]]
+[[`int`] [addition] [`0`] ]
+[[`string`] [concatenation] [`""`] ]
+[[`set<T>`] [union] [`{}`] ]
+]
+
+In those cases the `neutron` value is delivered by the default constructor
+of a type. But there are well known exceptions like for numeric multiplication:
+
+[table
+[[type] [operation] [neutron]]
+[[`int`] [multiplication] [`1`] ]
+]
+
+Therefore an itl functor implements a static function `neutron()` to make
+shure that the correct `neutron()` is used, which is used in the implementation
+of ['aggregate on overlap].
+``
+inplace_times<int>::neutron() == 1
+// or more general
+inplace_times<T>::neutron() == unon<T>::value()
+``
+
[h4 Neutron Absorber]
From a pragmatic perspective value pairs that carry `neutrons` as
mapped values can often be deleted. If we count, for instance,
the number of overlaps of inserted intervals in an __itv_map__
-(see example [overlap_counter]), most of the time, we are not
+(see example [link boost_itl.examples.overlap_counter overlap counter]),
+most of the time, we are not
interested in whether an overlap has been counted `0` times or
has not been counted at all.
@@ -286,7 +314,7 @@
Sometimes this subtle distiction is needed. Then a __enricher__
is the right choice. Also, If we want to give two `itl::Maps`
a common set of keys in order to, say, iterate synchronously
-over both maps, we need __enricher__ s.
+over both maps, we need __enrichers__.
[h4 Neutron Emitter]
@@ -300,8 +328,8 @@
is always initialized with neutron values.
Of course those initial neutronic values for all keys of the
-maps domain is *not* stored on the __emitter__ map. So it's
-implementation is as minimal as the implementation of a
+maps domain are *not* stored on the __emitter__ map. So it's
+implementation is as minimal as the implementation of an
__absorber__.
[endsect] [/ kind of nuclear]
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-21 16:43:26 EST (Sun, 21 Dec 2008)
@@ -10,7 +10,7 @@
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
+the libraries design and to focus on structural equalities and differences
with the corresponding containers of the standard template library.
In the table of associated types of interval_sets
@@ -35,9 +35,8 @@
[[__itv_bsets__][__itv_set__] [`<DomainT,Compare,Interval,Alloc>`]]
[[] [__sep_itv_set__][`<DomainT,Compare,Interval,Alloc>`]]
[[] [__spl_itv_set__][`<DomainT,Compare,Interval,Alloc>`]]
-[[__itl_set__] [__itl_set__] [`<DomainT,Compare,Alloc>`]]
-[[=std::set=] [`std::set`] [`<_Key,_Compare,_Alloc>`]]
-[[][]]
+[[__itl_set__] [__itl_set__] [`<DomainT,Compare, Alloc>`]]
+[[=std::set=] [`std::set`] [`<_Key, _Compare, _Alloc>`]]
]
Templates and template parameters, given in the preceeding table are
@@ -65,10 +64,10 @@
[table map class templates
[[group] [template] [instance parameters]]
-[[__itv_bmaps__][__itv_map__] [`<DomainT,CodomainT,Compare,Combine,Traits,Interval,Alloc>`]]
-[[] [__spl_itv_map__][`<DomainT,CodomainT,Compare,Combine,Traits,Interval,Alloc>`]]
-[[__itl_map__] [__itl_map__] [`<DomainT,CodomainT,Compare,Combine,Traits,Alloc>`]]
-[[=std::map=] [`std::map`] [`<_Key,_Data,_Compare,_Alloc>`]]
+[[__itv_bmaps__][__itv_map__] [`<DomainT,CodomainT,Traits,Compare,Combine,Section,Interval,Alloc>`]]
+[[] [__spl_itv_map__][`<DomainT,CodomainT,Traits,Compare,Combine,Section,Interval,Alloc>`]]
+[[__itl_map__] [__itl_map__] [`<DomainT,CodomainT,Traits,Compare,Combine,Section,Alloc>`]]
+[[=std::map=] [`std::map`] [`<_Key, _Data, _Compare, _Alloc>`]]
]
@@ -79,12 +78,12 @@
that all have equal template parameters.
[table Parameters of map class templates
-[[] [elements][mapped values][order of elements] [aggregation] [traits] [type of intervals] [memory allocation]]
-[[template parameter] [`class`] [`class`] [`template <class>class`] [`template <class>class`] [`class`] [`template <class, template<class>class> class`][`template <class>class`]]
-[[__itv_bmaps__] [`DomainT`][`CodomainT`][`Compare = std::less`] [`Combine = inplace_plus`] [`Traits = neutron_absorber`][`Interval = itl::interval`] [`Alloc = std::alloc`]]
-[[__itl_map__] [`DomainT`][`CodomainT`][`Compare = std::less`] [`Combine = inplace_plus`] [`Traits = neutron_absorber`][`Interval = itl::interval`] [`Alloc = std::alloc`]]
-[[template parameter] [`class`] [`class`] [`class`] [] [] [] [`class`]]
-[[=std::map=] [`_Key`] [`_Data`] [`_Compare = std::less<_Key>`][] [] [] [`Alloc = std::alloc<_Key>`]]
+[[] [elements][mapped values][traits] [order of elements] [aggregation propagation] [intersection propagation] [type of intervals] [memory allocation]]
+[[template parameter] [`class`] [`class`] [`class`] [`template <class>class`] [`template <class>class`] [`template <class, template<class>class> class`][`template <class, template<class>class> class`][`template <class>class`]]
+[[__itv_bmaps__] [`DomainT`][`CodomainT`] [`Traits = neutron_absorber`] [`Compare = std::less`] [`Combine = inplace_plus`] [`Section = itl::inplace_star`] [`Interval = itl::interval`] [`Alloc = std::alloc`]]
+[[__itl_map__] [`DomainT`][`CodomainT`] [`Traits = neutron_absorber`] [`Compare = std::less`] [`Combine = inplace_plus`] [`Section = itl::inplace_star`] [`Alloc = std::alloc`]]
+[[template parameter] [`class`] [`class`] [] [`class`] [] [] [] [`class`]]
+[[=std::map=] [`_Key`] [`_Data`] [] [`_Compare = std::less<_Key>`][] [] [] [`Alloc = std::alloc<_Key>`]]
]
Using the following placeholders,
@@ -92,10 +91,11 @@
``
D := class DomainT,
C := class CodomainT,
+T := class Traits,
Cp := class Compare = std::less<DomainT>,
cp := template<class D>class Compare = std::less,
cb := template<class C>class Combine = itl::inplace_plus,
-T := class Traits,
+s := template<class C>class Section = itl::inplace_star,
i := template<class D,template<class>class cp>class Interval = itl::interval
Ad := class Alloc = std::allocator<DomainT>
Av := class Alloc = std::allocator<std::pair<DomainT,CodomainT> >
@@ -105,13 +105,13 @@
we arrive at a final synoptical matrix of class templates and their parameters.
[pre
-interval <D, cp, >
-interval_sets<D, cp, i, a >
-itl::set <D, cp, a >
-std::set <D, Cp, Ad>
-interval_maps<D, C, cp, cb, T, i, a >
-itl::map <D, C, cp, cb, T, a >
-std::map <D, C Cp, Av>
+interval <D, cp, >
+interval_sets<D, cp, i, a >
+itl::set <D, cp, a >
+std::set <D, Cp, Ad>
+interval_maps<D, C, T, cp, cb, s, i, a >
+itl::map <D, C, T, cp, cb, s, a >
+std::map <D, C Cp, Av>
]
The choice of parameters and their positions follow the std::containers
@@ -139,26 +139,28 @@
[table
[[] [used in] [Kind] [Parameter] [Instance] [Description] ]
-[[Domain order] [`interval, Sets, Maps`][`typename`][`DomainT`] [] [For the type `DomainT` of key elements]]
-[[] [] [`template`] [`Compare`] [`Compare<DomainT>`] [there is an order `Compare`] ]
-[[Interval type] [`interval_sets/maps`][`template`] [`Interval`] [`Interval<DomainT,Compare>`] [the `Interval` parameter has to use the same element type and order ] ]
-[[Codomain aggregation][`Maps`] [`typename`] [`CodomainT`][] [For the type `CodomainT` of associated values]]
-[[] [] [`template`] [`Combine`] [`Combine<CodomainT>`] [there is a binary functor `Combine<CodomainT>()` to combine them ] ]
-[[] [] [] [] [`Inverse<Combine<CodomainT>>`][and implicity an `Inverse` functor to inversely combine them. ] ]
+[[Domain order] [`interval, Sets, Maps`][`typename`][`DomainT`] [] [For the type `DomainT` of key elements `...`]]
+[[] [] [`template`] [`Compare`] [`Compare<DomainT>`] [`...` there is an order `Compare`] ]
+[[Interval type] [`interval_sets/maps`][`template`] [`Interval`] [`Interval<DomainT,Compare>`] [`...` the `Interval` parameter has to use the same element type and order. ] ]
+[[Codomain aggregation][`Maps`] [`typename`] [`CodomainT`][] [For the type `CodomainT` of associated values `...`]]
+[[] [] [`template`] [`Combine`] [`Combine<CodomainT>`] [`...` there is a binary functor `Combine<CodomainT>()` to combine them ] ]
+[[] [] [] [] [`Inverse<Combine<CodomainT>>`][`...` and implicity an `Inverse` functor to inversely combine them. ] ]
+[[] [] [`template`] [`Section`] [`Section<CodomainT>`] [For a intersection operation intersection is propagated to CodomainT values via functor `Section<CodomainT>()`] ]
[[Memory allocation] [`Sets, Maps`] [`template`] [`Alloc`] [`Alloc<`/various/`>`] [An allocator can be chosen for memory allocation.]]
]
[/ table
-[[Kind] [Parameter] [Condition] [Requirement] ]
-[[`typename`][`DomainT`] [] [`Regular<DomainT> && LessThanComparable<DomainT,Compare>`
- `&& (IsIncrementable<DomainT>||HasUnon<DomainT>)`] ]
-[[][] [`IsIntegral<DomainT>`] [`IsIncrementable<DomainT> && IsDecrementable<DomainT>`] ]
+[[Kind] [Parameter] [Condition] [Requirement] ]
+[[`typename`][`DomainT`] [] [`Regular<DomainT> && LessThanComparable<DomainT,Compare>`
+ `&& (IsIncrementable<DomainT>||HasUnon<DomainT>)`] ]
+[[][] [`IsIntegral<DomainT>`] [`IsIncrementable<DomainT> && IsDecrementable<DomainT>`] ]
[[`typename`][`CodomainT`][`Combine` and `Inverse<Combine>` unused] []]
-[[][] [only `Combine` used ] [`EqualityComparable<CodomainT> && Addable<CodomainT,Combine>`] ]
-[[][] [also `Inverse<Combine>` used][`&& Subtractable<CodomainT,Inverse<Combine> >`] ]
-[[`template`][`Compare`] [] [`LessThanComparable<DomainT,Compare>`] ]
-[[`template`][`Combine`] [only `Combine` used] [`Addable<CodomainT,Combine>`]]
-[[][] [also `Inverse<Combine>` used][`&& Subtractable<CodomainT,Inverse<Combine> >`] ]
+[[][] [only `Combine` used ] [`EqualityComparable<CodomainT> && Addable<CodomainT,Combine>`] ]
+[[][] [also `Inverse<Combine>` used] [`&& Subtractable<CodomainT,Inverse<Combine> >`] ]
+[[`template`][`Compare`] [] [`LessThanComparable<DomainT,Compare>`] ]
+[[`template`][`Combine`] [only `Combine` used] [`Addable<CodomainT,Combine>`]]
+[[][] [and `Inverse<Combine>` used] [`&& Subtractable<CodomainT,Inverse<Combine> >`] ]
+[[][] [`Section` used and `CodomainT` is a set][`Intersectable<CodomainT,Section>`] ]
]
[h4 Requirements on DomainT]
@@ -235,21 +237,22 @@
using the default combiner `Combine = itl::inplace_plus`.
[table
-[[Parameter] [Condition] [Operators] [Requirement] ]
-[[`CodomainT`][`add` and `subtract` unused][`CodomainT(), ==`][`Regular<CodomainT>` which implies] ]
-[[] [] [] [`DefaultConstructible<CodomainT> && EqualityComparable<CodomainT>`] ]
-[[] [only `add` used ] [`+=`] [`&& Combinable<CodomainT,Combine>`] ]
-[[] [also `subtract` used] [`-=`] [`&& Combinable<CodomainT,Inverse<Combine> >`]]
+[[Parameter] [Condition] [Operators] [Requirement] ]
+[[`CodomainT`][`add`, `subtract`, `intersect` unused] [`CodomainT(), ==`][`Regular<CodomainT>` which implies] ]
+[[] [] [] [`DefaultConstructible<CodomainT> && EqualityComparable<CodomainT>`] ]
+[[] [only `add` used ] [`+=`] [`&& Combinable<CodomainT,Combine>`] ]
+[[] [... and also `subtract` used] [`-=`] [`&& Combinable<CodomainT,Inverse<Combine> >`]]
+[[] [`Section` used and `CodomainT` is a set][`*=`] [`&& Intersectable<CodomainT,Section>`] ]
]
The requirements on the type `CodomainT` of associated values for a __itl_map__ or __itv_map__
depend on the usage of their aggregation functionality. If aggregation on overlap
-is never used, that is to say neither `+, +=, add` nor `-, -=, subtract` are used on the
-__itv_map__, then `CodomainT` only needs to be `Regular`.
-Concept
-[@http://www.generic-programming.org/languages/conceptcpp/issues/concepts-closed.html `Regular` is under construction]
-but it can be said that it expresses the properties of common ['*regular*]
-object semantics that particularly implies `DefaultConstructible` and
+is never used, that is to say that none of the addition, subtraction and intersection
+operations (`+, +=, add`, `-, -=, subtract`, *, *=, add_intersection) are used on the
+__itv_map__, then `CodomainT` only needs to be
+[@http://www.generic-programming.org/languages/conceptcpp/issues/concepts-closed.html Regular].
+['*Regular*]
+object semantics implies `DefaultConstructible` and
`EqualityComparable` which means it has
a default ctor `CodomainT()` and an `operator ==`.
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-21 16:43:26 EST (Sun, 21 Dec 2008)
@@ -57,14 +57,22 @@
[def __spl_itv_maps__ [classref boost::itl::split_interval_map split_interval_maps]]
[def __inverse__ [classref boost::itl::inverse inverse]]
-[def __ip_plus__ [classref boost::itl::inplace_plus inplace_plus]]
-[def __ip_minus__ [classref boost::itl::inplace_minus inplace_minus]]
-[def __ip_star__ [classref boost::itl::inplace_star inplace_star]]
-[def __ip_div__ [classref boost::itl::inplace_div inplace_div]]
-[def __ip_min__ [classref boost::itl::inplace_min inplace_min]]
-[def __ip_max__ [classref boost::itl::inplace_max inplace_max]]
+[def __ip_cross__ [classref boost::itl::inplace_cross inplace_cross]]
+[def __ip_dash__ [classref boost::itl::inplace_dash inplace_dash]]
+[def __ip_plus__ [classref boost::itl::inplace_plus inplace_plus]]
+[def __ip_minus__ [classref boost::itl::inplace_minus inplace_minus]]
+[def __ip_star__ [classref boost::itl::inplace_star inplace_star]]
+[def __ip_slash__ [classref boost::itl::inplace_slash inplace_slash]]
+[def __ip_times__ [classref boost::itl::inplace_times inplace_times]]
+[def __ip_divide__ [classref boost::itl::inplace_divide inplace_divide]]
+[def __ip_pipe__ [classref boost::itl::inplace_pipe inplace_pipe]]
+[def __ip_et__ [classref boost::itl::inplace_et inplace_et]]
+[def __ip_min__ [classref boost::itl::inplace_min inplace_min]]
+[def __ip_max__ [classref boost::itl::inplace_max inplace_max]]
[def __ip_identity__ [classref boost::itl::inplace_identity inplace_identity]]
-[def __ip_erasure__ [classref boost::itl::inplace_erasure inplace_erasure]]
+[def __ip_erasure__ [classref boost::itl::inplace_erasure inplace_erasure]]
+[def __ip_bitset_union__ [classref boost::itl::inplace_bitset_union inplace_bitset_union]]
+[def __ip_bitset_difference__ [classref boost::itl::inplace_bitset_difference inplace_bitset_difference]]
[def __itv_bmap_add__ [memberref boost::itl::interval_base_map::add add]]
@@ -76,6 +84,7 @@
[def __absorber__ [classref boost::itl::neutron_absorber neutron_absorber]]
[def __enricher__ [classref boost::itl::neutron_enricher neutron_enricher]]
+[def __enrichers__ [classref boost::itl::neutron_enricher neutron_enrichers]]
[def __emitter__ [classref boost::itl::neutron_emitter neutron_emitter]]
[def __itv_bse_set__ [classref boost::itl::interval_base_set interval_base_set]]
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