[Boost-commit] svn:boost r50311 - in sandbox/itl: boost/itl/type_traits libs/itl/doc

Subject: [Boost-commit] svn:boost r50311 - in sandbox/itl: boost/itl/type_traits libs/itl/doc
From: afojgo_at_[hidden]
Date: 2008-12-17 17:58:30

Author: jofaber
Date: 2008-12-17 17:58:30 EST (Wed, 17 Dec 2008)
New Revision: 50311
URL: http://svn.boost.org/trac/boost/changeset/50311

Log:
Added documentation. Interface, requirements on template parameters. Stable {msvc-9.0, partly congcc-4.3-a7}
Text files modified: 
   sandbox/itl/boost/itl/type_traits/unon.hpp |     2                                         
   sandbox/itl/libs/itl/doc/interface.qbk     |    84 +++++++++++++++++++++++++++++++++++++++ 
   2 files changed, 83 insertions(+), 3 deletions(-)

Modified: sandbox/itl/boost/itl/type_traits/unon.hpp
==============================================================================
--- sandbox/itl/boost/itl/type_traits/unon.hpp	(original)
+++ sandbox/itl/boost/itl/type_traits/unon.hpp	2008-12-17 17:58:30 EST (Wed, 17 Dec 2008)
@@ -19,7 +19,7 @@
     template<> inline float  unon<float>::value()  { return 1.0; }
     template<> inline double unon<double>::value() { return 1.0; }
     
-    // Smallest 'visible' string that is greater than than the empty string.
+    // Smallest 'visible' string that is greater than the empty string.
     template <>    
     inline std::string unon<std::string>::value(){ return std::string(" "); };
 

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-17 17:58:30 EST (Wed, 17 Dec 2008)
@@ -129,10 +129,90 @@
 instantiated with different types inside itl class templates. This problem
 is described in detail in section JODO.
 
-Required Concepts
+[endsect][/ Class templates]
 
+[section Required Concepts]
+
+There are uniform requirements for the template parameters 
+across *itl's* class templates that are summarized in the
+table below.
+
+[table 
+[[Kind]      [Parameter]  [requires]                                                  ]
+[[`typename`][`DomainT`]  [`Regular<DomainT> && LessThanComparable<DomainT,Compare>` 
+                           `&& (IsIncrementable<DomainT>||HasUnon<DomainT>)`] ]
+[[][]                     [`if(IsIntegral<DomainT>) IsIncrementable<DomainT> && IsDecrementable<DomainT>`] ] 
+[[`typename`][`CodomainT`][`EqualityComparable<CodomainT>` 
+                           `&& Addable<CodomainT,Combine>` 
+                           `&& Subtractable<CodomainT,Inverse<Combine> >`]            ]
+[[`template`][`Compare`]  [`LessThanComparable<DomainT,Compare>`]                     ]
+[[`template`][`Combine`]  [`Addable<CodomainT,Combine>` 
+                           `&& Subtractable<CodomainT,Inverse<Combine> >`]]
+]
+
+[h5 Requirements on DomainT]
+
+A domain type `DomainT` for intervals and interval conainer
+has to satisfy the requirements of concept `Regular` which
+implies among other properties the existence of a copy and
+a default constructor. In addition `IsIncrementable`
+*or* `HasUnon` is required for `DomainT`.
+
+In the *itl* we represent an empty interval by a closed
+interval `[b,a]` where `a < b` (here `<` is represents `Compare<DomainT>()`). 
+To construct one of these empty intervals as default constructor
+for any type `DomainT` we choose `[1,0]`, where `0` is a null-value or `neutron`
+and `1` is a one-value or `unon`:
+`` 
+interval() := [unon<DomainT>::value(), neutron<DomainT>::value()]
+``
+`Neutrons` are implemented via call of the default constructor of
+`DomainT`. An `unon<T>::value()` is implemented by default as a `neutron`, 
+that is incremented once. 
+``
+template <class Type> 
+inline Type unon<Type>::value(){ return succ(neutron<Type>::value()); };
+``
+So a type `DomainT` that is `incrementable` will
+also have an `unon`. If it does not, an `unon` can be provided.
+An `unon` can be any value, that is greater as the neutron value
+in the Compare order given.
+
+An example of a type, that has a neutron but no increment is
+string. So for std::string an unon is implemented like this:
+``
+// Smallest 'visible' string that is greater than the empty string.
+template <>    
+inline std::string unon<std::string>::value(){ return std::string(" "); };
+``
+
+Just as the `_Key` type of std::sets and maps 
+`DomainT` is required to be 
+`LessThanComparable<DomainT,Compare>` wich means, that
+`Compare` has to be a
+[@http://en.wikipedia.org/wiki/Strict_weak_ordering strict weak ordering] on `DomainT`.
+
+Finally, if `DomainT` is an integral type, `DomainT` needs to
+be `incrementable` and `decrementable`. This in(de)crementability
+needs to be implemented on the smallest possible unit of the
+integral type. This seems like being trivial but there are types like e.g.
+`boost::date_time::ptime`, that are integral in nature but do
+not provide the required in(de)cementation.
+
+For __itl_itvs__ incementation and decementation is used
+for moving open to closed interval borders like e.g.
+`[2,43) == [2,42]`. Such operations always need only
+one in(de)crementation, if `DomainT` is an integral type. 
+
+[h5 Requirements on CodomainT]
 
 
+
+[endsect][/ Required Concepts]
+
+
+[section Associated Types]
+
 [table Associated types of sets
 [[Aspects]        []        [type]            [interval]                  [interval_sets]                 [itl::set]        [std::set]]
 [[__conceptual__] [data]    [domain_type]     [DomainT]                   [DomainT]                       [DomainT]         []]
@@ -146,7 +226,7 @@
 [[]               []        [difference_type] [difference <DomainT>::type][interval_type:: difference_type][std::size_t]     []]
 ]                                     
 
-[endsect]
+[endsect][/ Associated Types]
 
 [section Function Matrix]