Changeset 1590

Timestamp:

Oct 17, 2008, 8:54:24 PM (15 years ago)

Author:

Peter

Message:

some docs on weighted iterator - closes #395

File:

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

trunk/doc/concepts.doxygen

@@ -28 +28 @@
 - \subpage concept_mutable_container_2d
 - \subpage concept_neighbor_weighting
+- \subpage concept_weighted_iterator
 */
 
@@ -369 +370 @@
 
 */
+
+/**
+\page concept_weighted_iterator Weighted Iterator
+
+\section Description
+
+Most functionality in yat come in two versions: one optimized for
+speed and one weighted version allowing for missing value (see \ref
+weighted_statistics). For example, weighted containers such as
+theplu::yat::utility::MatrixWeighted and
+theplu::yat::classifier::MatrixLookupWeighted allow an easy way to
+handle missing values. Iterators that iterate over such weighted
+containers are by definition \ref concept_weighted_iterator. This
+concept is orthogonal against other iterator concepts such as Random
+Access Iterator.
+
+\section Requirements
+
+When implementing a new iterator that may be a \ref
+concept_weighted_iterator, there are a few things to concider.
+
+\subsection weighted_iterator_traits
+
+To decide whether an iterator is weighted, there exists a
+meta-function
+theplu::yat::utility::weighted_iterator_traits<Iterator>::type that
+will return either theplu::yat::utility::weighted_iterator_tag or
+theplu::yat::utility::unweighted_iterator_tag. The default
+implementation of this meta-function works in most cases, including on
+all std::iterators, but if you implement a new iterator make sure it
+behaves as you desire, or you need to create a specialization.
+
+\subsection iterator_traits
+
+Sometimes it is useful to have unweighted iterators behaving as though
+they were weighted. For instance,
+theplu::yat::statistics::EuclideanDistance calculates the distance
+between two ranges. If both ranges are are unweighted the unweighted
+version is used, and when any of the two ranges is weighted the
+weighted version kicks in. In order to make this work also when
+comparing weighted and unweighted ranges, there must a mechanism to
+let the unweighted iterator behave as though it were weighted.
+
+This can be accomplished through
+theplu::yat::utility::iterator_traits, which enables access to data
+value as well as to weight value. For unweighted iterators the weight
+value is always equal to 1.0 and is not mutable. The default
+implementation works for most iterators including all unweighted, but
+if you implement a new weighted iterator you need to check that the
+default implementation will work for you (see class
+documentation). Otherwise, you will need to implement a
+specialization.
+
+*/