Boost logo

Boost-Commit :

Date view Thread view Subject view Author view

Subject: [Boost-commit] svn:boost r51428 - sandbox/itl/libs/itl/doc
From: afojgo_at_[hidden]
Date: 2009-02-24 06:32:47

Author: jofaber
Date: 2009-02-24 06:32:47 EST (Tue, 24 Feb 2009)
New Revision: 51428
URL: http://svn.boost.org/trac/boost/changeset/51428

Log:
Reviewed documentation. Typos and other corrections. Stable {msvc-9.0, partly congcc-4.3-a7}

Text files modified:
   sandbox/itl/libs/itl/doc/concepts.qbk | 37 +++++++-----------
   sandbox/itl/libs/itl/doc/interface.qbk | 31 ++++++++-------
   sandbox/itl/libs/itl/doc/itl.qbk | 1
   sandbox/itl/libs/itl/doc/semantics.qbk | 77 ++++++++++++++++++---------------------
   4 files changed, 68 insertions(+), 78 deletions(-)

Modified: sandbox/itl/libs/itl/doc/concepts.qbk
==============================================================================
--- sandbox/itl/libs/itl/doc/concepts.qbk (original)
+++ sandbox/itl/libs/itl/doc/concepts.qbk 2009-02-24 06:32:47 EST (Tue, 24 Feb 2009)
@@ -86,9 +86,9 @@
 An __itv__ is considered to be a set of elements as well.
 With respect to the `Set` concept
 presented above __itv__ implements the concept only partially. The reason for
-that is that addition `operator +=` and subtraction `operator -=` can not
+that is that addition and subtraction can not
 be defined on __itvs__. Two intervals `[1,2]` and `[4,5]` are not addable to
-a single new __itv__. In other words __itvs__ are incomplete w.r.t. union and
+a ['*single*] new __itv__. In other words __itvs__ are incomplete w.r.t. union and
 difference. __Itv_sets__ can be defined as the ['*completion*] of intervals
 for the union and difference operations.
 
@@ -113,20 +113,12 @@
 ]
 
 As one can see, on the abstract kernel the signatures of the itl's `Set` and `Map`
-concepts are identical, except for the typename. This is not a trivial
-signature since the major
-operations that are used in fundamental axioms that make up the semantics
-of the concepts are given. While signatures are identical
-The sets of valid laws are different, which will be discussed in more detail
-in section JODO.
-
-[/ This is due to the fact, that Map::operator+= is not just adding and
-Map::operator-= is not only removing ... liegt and der implementierung von
-add und subtract.]
-
-[/ Auf dem Kern sind die Signaturen (fast) gleich. Unterschiede Semantik.
-vor allem +=, -= und erst recht *=]
-
+concepts are identical, except for the typename.
+While signatures are identical
+The sets of valid laws are different, which will be described in more detail
+in the sections on the
+[link boost_itl.semantics.sets semantics of itl Sets] and
+[link boost_itl.semantics.maps Maps].
 These semantical differences are mainly based on the implementation
 of the pivotal memberfunctions `add` and `subtract` for elements
 and intervals that again serve for implementing
@@ -135,18 +127,18 @@
 
 [section Addability, Subtractability and Aggregate on Overlap]
 
-While addition and subtraction on `Sets` implement set union and
-set difference, for `Maps` we want to implement ['*aggregation*] on
+While ['*addition*] and ['*subtraction*] on `Sets`
+are implemented as ['*set union*] and ['*set difference],
+for `Maps` we want to implement ['*aggregation*] on
 the associated values for the case of collision (of key elements)
 or overlap (of key intervals), which has been refered to as
 ['*aggregate on overlap*] or ['*aggrovering*] above.
-
 This kind of `Addability` and `Subtractability` allows to compute
 a lot of useful aggregation results on an __itv_map_s__ associated
 values, just by adding and subtracting value pairs.
 Various examples of ['*aggrovering*] are given in
 [link boost_itl.examples section examples].
-In addition this concept of `Addability` and `Subtractability`
+In addition, this concept of `Addability` and `Subtractability`
 contains the classical `Insertability` and `Erasability` of
 key value pairs as a special case so it provides a broader
 new semantics without loss of the /classical/ one.
@@ -164,6 +156,7 @@
 [table
 [[`Combine<T>`] [`inverse<Combine<T> >::type`]]
 [[__ip_plus__`<T>`] [__ip_minus__`<T>`] ]
+[[__ip_et__`<T>`] [__ip_caret__`<T>`] ]
 [[__ip_star__`<T>`] [__ip_slash__`<T>`] ]
 [[__ip_max__`<T>`] [__ip_min__`<T>`] ]
 [[__ip_identity__`<T>`][__ip_erasure__`<T>`]]
@@ -312,7 +305,7 @@
 with an implementaion that resembled the default trait.
 Only the deeper analysis of the itl's ['*aggregating Map's
 concept*] in the course of preparation of the library for boost
-led to the introduction of map Trais.
+led to the introduction of map Traits.
 
 [h5 Add-Subtract Antinomy in Aggregating Maps]
 
@@ -362,7 +355,7 @@
 
 [h5 Partial and Total Maps]
 
-The idea of a neutron absorbing map is
+The idea of a neutron absorbing map is,
 that an ['*associated neutron*] value of a pair `(k,0)`
 ['*codes non-existence*] for it's key `k`.
 So the pair `(k,0)` immediately tunnels from

Modified: sandbox/itl/libs/itl/doc/interface.qbk
==============================================================================
--- sandbox/itl/libs/itl/doc/interface.qbk (original)
+++ sandbox/itl/libs/itl/doc/interface.qbk 2009-02-24 06:32:47 EST (Tue, 24 Feb 2009)
@@ -122,9 +122,10 @@
 interval_set<string, german_compare> sections; // 2nd parameter is a template
 std::set<string, german_compare<string> > words; // 2nd parameter is a type
 ``
-This choice has been made, because template parameters have to be
+
+[/ This choice has been made, because template parameters have to be
 instantiated with different types inside itl class templates. This problem
-is described in detail in section JODO.
+is described in detail in section JODO.]
 
 [endsect][/ Class templates]
 
@@ -142,7 +143,7 @@
 [[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>()`] ]
+[[] [] [`template`] [`Section`] [`Section<CodomainT>`] [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.]]
 ]
 
@@ -292,7 +293,7 @@
 //cat_map: {([1,3)->Hello)([3,5)->Hello world)([5,7)-> world)}
 ``
 
-For ['complete aggregation functionality] and inverse aggregation functor on
+For ['complete aggregation functionality] an inverse aggregation functor on
 a `Map`'s `CodomainT` is needed. The itl provides a
 metafunction [classref boost::itl::inverse inverse]
 for that purpose. Using the default
@@ -305,7 +306,7 @@
 In the itl's design we make the assumption,
 in particular for the default setting of parameters
 `Combine = `[classref boost::itl::inplace_minus inplace_plus],
-type `CodomainT` has a neutral element or `neutron`
+that type `CodomainT` has a neutral element or `neutron`
 with respect to the `Combine` functor.
 
 
@@ -315,7 +316,7 @@
 [section Associated Types]
 
 In order to give an overview over ['*associated types*] the *itl* works
-with we will again work with abbreviations that were introduced in the
+with, we will apply abbreviations again that were introduced in the
 presentaiton of itl class templates,
 
 [pre
@@ -343,12 +344,12 @@
 Av := class Alloc = std::allocator<std::pair<DomainT,CodomainT> >
 a := template<class>class Alloc = std::allocator
 ``
-with some additions,
+With some additions,
 ``
-sz := template<class D>size
-df := template<class D>difference
+sz := template<class D>class size
+df := template<class D>class difference
 Xl := class ExclusiveLess = exclusive_less<Interval<DomainT,Compare> >
-inv:= template<class Combiner>inverse
+inv:= template<class Combiner>class inverse
 (T,U) := std::pair<T,U> for typnames T,U
 ``
 
@@ -394,26 +395,26 @@
 comparison. In order to achieve a concise representation, a series
 of ['*placeholders*] are used throughout the function matrix.
 
-The ['*placeholder's*] purpose is to express the polymorhic
+The ['*placeholder's*] purpose is to express the polymorphic
 usage of the functions. The ['*first column*] of the function matrix
 contains the signatures of the functions. Within these
 signatures `T` denotes a container type and `I,J` and `P`
 polymorphic argument and result types.
 
 Within the body of the matrix, sets of *boldface* placeholders denote
-the sets of possible instantiations for a polymorhic
+the sets of possible instantiations for a polymorphic
 placeholder `P`. For instance __eiS denotes that for the
 argument type `P`, an element __e, an interval __i or an interval_set __S
 can be instantiated.
 
-If the polymorhism can not be described in this way, only the ['*number*] of
+If the polymorphism can not be described in this way, only the ['*number*] of
 overloaded implementations for the function of that row is shown.
 
 [table
 [[Placeholder] [Argument types] [Description]]
 [[`T` ] [] [a container type]]
-[[`P` ] [] [polymorhical container argument type]]
-[[`I,J` ] [] [polymorhical iterator type]]
+[[`P` ] [] [polymorphical container argument type]]
+[[`I,J` ] [] [polymorphical iterator type]]
 [[`V` ] [] [various types `V`, that do dot fall in the categories above]]
 [[1,2,... ] [] [number of implementations for this function]]
 [[A ] [] [implementation generated by compilers]]

Modified: sandbox/itl/libs/itl/doc/itl.qbk
==============================================================================
--- sandbox/itl/libs/itl/doc/itl.qbk (original)
+++ sandbox/itl/libs/itl/doc/itl.qbk 2009-02-24 06:32:47 EST (Tue, 24 Feb 2009)
@@ -68,6 +68,7 @@
 [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_caret__ [classref boost::itl::inplace_caret inplace_caret]]
 [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]]

Modified: sandbox/itl/libs/itl/doc/semantics.qbk
==============================================================================
--- sandbox/itl/libs/itl/doc/semantics.qbk (original)
+++ sandbox/itl/libs/itl/doc/semantics.qbk 2009-02-24 06:32:47 EST (Tue, 24 Feb 2009)
@@ -8,7 +8,7 @@
 
 [section Semantics]
 
-In the *itl* we follow the notion, that the semantics of a ['*concept*] or an
+In the *itl* we follow the notion, that the semantics of a ['*concept*] or
 ['*abstract data type*] can be expressed by ['*laws*]. We formulate
 laws over interval containers that can be evaluated for a given
 instantiation of the variables contained in the law. The following
@@ -25,8 +25,7 @@
 were validated using the Law based Test Automaton ['*LaBatea*],
 a tool that generates instances for the law's variables and then
 tests it's validity.
-
-Since the *itl* deals with sets, maps and orderings, that are
+Since the *itl* deals with sets, maps and relations, that are
 well known objects from mathematics, the laws that we are
 using are mostly /recycled/ ones. Also some of those laws are grouped
 in notions like e.g. /orderings/ or /algebras/.
@@ -37,11 +36,11 @@
 
 On all set and map containers of the itl, there is an `operator <`
 that implements a
-[@http://www.sgi.com/tech/stl/StrictWeakOrdering.html strict weak ordering]
-(see also [@http://en.wikipedia.org/wiki/Strict_weak_ordering here]).
+[@http://www.sgi.com/tech/stl/StrictWeakOrdering.html strict weak ordering].
+[/ (see also [@http://en.wikipedia.org/wiki/Strict_weak_ordering here]).]
 The semantics of `operator <` is the same as for an stl's
 [@http://www.sgi.com/tech/stl/SortedAssociativeContainer.html SortedAssociativeContainer],
-especially
+specifically
 [@http://www.sgi.com/tech/stl/set.html stl::set]
 and
 [@http://www.sgi.com/tech/stl/map.html stl::map]:
@@ -83,7 +82,6 @@
 matters, not their sequence. So there are functions
 `contained_in` and `element_equal` that implement
 the subset relation and the equality on elements.
-
 Yet, `contained_in` and `is_element_equal` functions are not
 really working on the level of elements. They also
 work on the basis of the containers templates
@@ -100,7 +98,7 @@
 ``
 
 For a constant `Compare` order on key elements,
-memberfunktion `contained_in` that is defined for all
+member function `contained_in` that is defined for all
 itl::containers implements a
 [@http://en.wikipedia.org/wiki/Partially_ordered_set partial order]
 on itl::containers.
@@ -132,7 +130,7 @@
 are giving an overview over the checked laws ordered by
 operations. If possible, the laws are formulated with
 the stronger lexicographical equality (`operator ==`)
-which implies the the laws validity for the weaker
+which implies the law's validity for the weaker
 element equality `is_element_equal`. Throughout this
 chapter we will denote element equality as `=e=` instead
 of `is_element_equal` where a short notation is advantageous.
@@ -141,7 +139,7 @@
 
 For the operation ['*set union*] available as
 `operator +, +=, |, |=` and the neutral element
-`neutron<S>::value()` which is the empty set `T()`
+`neutron<S>::value()` which is the empty set `S()`
 these laws hold:
 ``
 Associativity<S,+,== >: S a,b,c; a+(b+c) == (a+b)+c
@@ -159,9 +157,10 @@
 Commutativity<S,&,== >: S a,b; a&b == b&a
 ``
 
+[/ JODO
 Neutrality has *not* been validated to avoid
 additional requirements on the sets template
-parameters.
+parameters.]
 
 [h5 Laws on set difference]
 
@@ -183,7 +182,7 @@
 ``
                  + & -
 Associativity == ==
-Neutrality == == ==
+Neutrality == ==
 Commutativity == ==
 Inversion ==
 ``
@@ -257,7 +256,7 @@
 below is an adaption for the binary set difference `-`, which is
 also called ['*relative complement*].
 ``
-DeMorgan<S,+,&,=v= > : S a,b,c; a - (b + c) =v= (a - b) * (a - c)
+DeMorgan<S,+,&,=v= > : S a,b,c; a - (b + c) =v= (a - b) & (a - c)
 DeMorgan<S,&,+,=v= > : S a,b,c; a - (b & c) =v= (a - b) + (a - c)
 ``
 
@@ -275,10 +274,10 @@
 [h5 Symmetric Difference]
 
 ``
-SymmetricDifference<S,== > : S a,b,c; (a + b) - (a * b) == (a - b) + (b - a)
+SymmetricDifference<S,== > : S a,b,c; (a + b) - (a & b) == (a - b) + (b - a)
 ``
 
-Finally Symmetrical Difference holds for all of itl set types and
+Finally Symmetric Difference holds for all of itl set types and
 lexicographical equality.
 
 [/ pushout laws]
@@ -292,7 +291,6 @@
 the semantics of the *itl's* maps may be a different one, because
 of it's aggregating facilities, where the aggregating combiner
 operations are passed to combine the map's associated values.
-
 It turnes out, that the aggregation on overlap principle
 induces semantical properties to itl maps in such a way,
 that the set of equations that are valid will depend on
@@ -340,18 +338,14 @@
 of numbers as counting or quantifying the key values
 of the map.
 
-
-[h4 Summary of Collector and Quantifier Semantics]
-
-Itl `Maps of Sets` of `Collectors`
-are models of a concept `Set` which implies that all laws that have been
+Itl ['*Maps of Sets*] or ['*Collectors*]
+are models of concept `Set`. This implies that all laws that have been
 stated as a semantics for `itl::Sets` in the previous chapter also hold for
 `Maps of Sets`.
-
-Itl `Maps of Numbers` of `Quantifiers` on the contrary are not models of concept `Set`.
+Itl ['*Maps of Numbers*] or ['*Quantifiers*] on the contrary are not models
+of concept `Set`.
 But there is a substantial intersection of laws that apply both for
-`Collectors` and `Quantifiers`. `Maps of Numbers` appear to be a models
-of a concept `InfiniteVector` instead.
+`Collectors` and `Quantifiers`.
 
 [table
 [[Kind of Map] [Alias] [Behavior] ]
@@ -359,21 +353,23 @@
 [[Maps of Numbers][Quantifier][Counts or quantifies *the* key values]]
 ]
 
-In the next two sections the law based semantics of `Maps of Sets` (Collectors)
-and `Maps of Numbers` (Quantifiers) will be described in more detail.
+In the next two sections the law based semantics of ['*Collectors*]
+and ['*Quantifiers*] will be described in more detail.
 
 [endsect][/ Maps]
 
 [section Collectors: Maps of Sets]
 
-`Itl Maps of Sets` or `Collectors`, behave like `Sets`.
+Itl `Collectors`, behave like `Sets`.
 This can be understood easily, if we consider, that
-ervery map of sets can be transformed to an equivalent
+every map of sets can be transformed to an equivalent
 set of pairs.
-For instance
+For instance in the pseudocode below map `m`
+``
+itl::map<int,set<int> > m = {(1->{1,2}), (2->{1})};
+``
+is equivalent to set `s`
 ``
-//Pseudocode:
-itl::map<int,set<int> > m = {(1->{1,2}), (2->{1})}; //is equivalent to
 itl::set<pair<int,int> > s = {(1,1),(1,2), //representing 1->{1,2}
                               (2,1) }; //representing 2->{1}
 ``
@@ -403,17 +399,17 @@
 # Deleting value pairs form the Collector, if it's associated value
   becomes a neutral value or `neutron`.
 # Using a different equality, called protonic equality in the laws
- to validate. Protonic equality `is_protonic_equal` or `=p=` only
+ to validate. Protonic equality only
   accounts for value pairs that that carry values unequal to the `neutron` value.
 
 Solution (1) led to the introduction of map traits, particularly trait
-partial_absorber trait which is the default setting in all itl's map
+['*partial_absorber*], which is the default setting in all itl's map
 templates.
 
 Solution (2), is applied to check the semantics of itl::Maps for the
 partial_enricher trait that does not delete value pairs that carry
 neutrons. Protonic equality is implemented by a non member function
-called `is_protonic_equal`. Througout this chapter
+called `is_protonic_equal`. Throughout this chapter
 protonic equality in pseudocode and law denotations is denoted
 as `=p=` operator.
 
@@ -524,7 +520,7 @@
 subtraction make sense
 ``
 itl::map<int,some_number> q = {(1->1)};
-q -= (2->1); // key 2 is not not in the map so
+q -= (2->1); // key 2 is not in the map so
 q == {(1->1)}; // q is unchanged by 'aggregate on collision'
 ``
 If `some_number` is a `signed` numerical type
@@ -535,7 +531,7 @@
 q == {(1->1), (2-> -1)}; // adding the inverse element
 ``
 As commented in the example, subtraction of a key value
-pair `(k,v)` can obviously defined as adding the ['*inverse element*]
+pair `(k,v)` can obviously be defined as adding the ['*inverse element*]
 for that key `(k,-v)`, if the key is not yet stored in the map.
 
 [h4 Partial and Total Quantifiers and Infinite Vectors]
@@ -553,7 +549,6 @@
 The __tabsorber__ trait fits specifically well with
 a `Quantifier` if it's `CodomainT` has an inverse
 element, like all signed numerical type have.
-
 As we can see later in this section this kind of
 a total `Quantifier` has the basic properties that
 elements of a
@@ -600,7 +595,7 @@
           ->0 ->1 ->0
 q = {[min 2)[2 4)[4 max]};
             ->0 ->1 ->0
-p*q =={[min 1)[1 2)[2 3)[3 4)[4 max]};
+p&q =={[min 1)[1 2)[2 3)[3 4)[4 max]};
           ->0 ->1 ->2 ->1 ->0
 ``
 
@@ -610,7 +605,7 @@
 for unsigned or signed numbers. So the sets of
 laws that are valid for Quantifiers will be different
 depending on the instantiation of an unsigned or
-a signed number type as CodomainT parameter.
+a signed number type as `CodomainT` parameter.
 
 Again, we are presenting the investigated sets of laws, this time for
 `Quantifier` types `Q` which are
@@ -716,7 +711,7 @@
 commutative monoids
 with respect to the
 `operator +` and the neutral element `Q()`.
-If the Quantifiers `CodomainT` type has an /inverse element/
+If the Quantifier's `CodomainT` type has an /inverse element/
 like e.g. `signed numbers` do,
 the `CodomainT` type is a
 ['*commutative*] or ['*abelian group*].

Date view Thread view Subject view Author view

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