Changeset 3548 for trunk/doc

Timestamp:

Jan 1, 2017, 5:56:44 AM (6 years ago)

Author:

Peter

Message:

The concept 'Distance' now requires that operator() works on iterator
that are readable and forward traversal, i.e., the previously implicit
requirement that iterator's reference type is lvalue is
dropped. closes #873

File:

• trunk/doc/concepts.doxygen (modified) (3 diffs)

trunk/doc/concepts.doxygen

@@ -293 +293 @@
 
 \ref concept_distance is a concept for classes implementing different
-alternatives to calculate the distance between two points.
+alternatives to calculate the distance between two ranges. For details
+on requirements needed for a class modelling the concept \ref
+concept_distance refer to section below, but a convenient way to
+implement a class is to use class theplu::yat::statistics::Distance as
+base class.
 
 \section concept_distance_requirments Requirements
@@ -307 +311 @@
 
 \verbatim
-template<typename Iter1, typename Iter2>
-double  operator() (Iter1 beg1, Iter1 end1, Iter2 beg2) const
+template<typename Iterator1, typename Iterator2>
+double  operator() (Iterator1 beg1, Iterator1 end1, Iterator2 beg2) const
 \endverbatim
 
@@ -314 +318 @@
 elements of two ranges. The first range is given by [\a beg1, \a end1)
 and the second range starts with \a beg2 and has the same length as
-the first range. The function should support iterators of the category
-std::forward_iterator. The function should provide both a fast
-calculation for unweighted iterators and a calculation for weighted
-iterators. The latter correspond to the case where elements in a range
-have both a value and a weight. The selection between unweighted and
-weighted implementations should utilize
+the first range. The function should support iterators that model \ref
+concept_data_iterator and \forward_traversal_iterator, in other words,
+the function should not assume any functionality not guaranteed by
+concepts \forward_traversal_iterator and \readable_iterator.
+
+As \ref concept_data_iterator should be supported implies that class
+should support \ref concept_weighted_iterator. Typically a \ref
+concept_distance class has a fast calculation for the case when
+neither of the two input ranges is weighted, and a separate function
+taking care of weights. A convenient way to select between unweighted and
+weighted implementations is to utilize tag structs
 theplu::yat::utility::unweighted_iterator_tag and
-theplu::yat::utility::weighted_iterator_tag. Moreover
-theplu::yat::utility::weighted_if_any2 should be utilized to provide a
-weighted implementation if any of the two ranges is weighted, and an
-unweighted implementation when both ranges are unweighted.
+theplu::yat::utility::weighted_iterator_tag as returned from meta-function
+theplu::yat::utility::weighted_if_any2.
+
+The class theplu::yat::utility::DistanceConcept an be used to test
+that a class fulfills these requirements.
 
 \section concept_distance_implementations Implementations