[Lemon-commits] kpeter: r3446 - in lemon/trunk/lemon: . concepts
Lemon SVN
svn at lemon.cs.elte.hu
Tue Feb 5 13:41:05 CET 2008
Author: kpeter
Date: Tue Feb 5 13:41:05 2008
New Revision: 3446
Modified:
lemon/trunk/lemon/concepts/maps.h
lemon/trunk/lemon/maps.h
Log:
Several doc improvements and fixes in maps.h and concepts/maps.h.
Modified: lemon/trunk/lemon/concepts/maps.h
==============================================================================
--- lemon/trunk/lemon/concepts/maps.h (original)
+++ lemon/trunk/lemon/concepts/maps.h Tue Feb 5 13:41:05 2008
@@ -34,17 +34,23 @@
/// @{
/// Readable map concept
+
+ /// Readable map concept.
+ ///
template<typename K, typename T>
class ReadMap
{
public:
- /// Map's key type.
+ /// The key type of the map.
typedef K Key;
- /// Map's value type. (The type of objects associated with the keys).
+ /// The value type of the map. (The type of objects associated with the keys).
typedef T Value;
- // \bug Value don't need to be default constructible.
/// Returns the value associated with a key.
+
+ /// Returns the value associated with a key.
+ /// \bug Value shouldn't need to be default constructible.
+ ///
Value operator[](const Key &) const {return Value();}
template<typename _ReadMap>
@@ -69,13 +75,16 @@
/// Writable map concept
+
+ /// Writable map concept.
+ ///
template<typename K, typename T>
class WriteMap
{
public:
- /// Map's key type.
+ /// The key type of the map.
typedef K Key;
- /// Map's value type. (The type of objects associated with the keys).
+ /// The value type of the map. (The type of objects associated with the keys).
typedef T Value;
/// Sets the value associated with a key.
@@ -105,15 +114,18 @@
};
};
- ///Read/Writable map concept
+ /// Read/writable map concept
+
+ /// Read/writable map concept.
+ ///
template<typename K, typename T>
class ReadWriteMap : public ReadMap<K,T>,
- public WriteMap<K,T>
+ public WriteMap<K,T>
{
public:
- /// Map's key type.
+ /// The key type of the map.
typedef K Key;
- /// Map's value type. (The type of objects associated with the keys).
+ /// The value type of the map. (The type of objects associated with the keys).
typedef T Value;
/// Returns the value associated with a key.
@@ -132,39 +144,41 @@
///Dereferable map concept
+
+ /// Dereferable map concept.
+ ///
+ /// \todo Rethink this concept.
template<typename K, typename T, typename R, typename CR>
class ReferenceMap : public ReadWriteMap<K,T>
{
public:
/// Tag for reference maps.
typedef True ReferenceMapTag;
- /// Map's key type.
+ /// The key type of the map.
typedef K Key;
- /// Map's value type. (The type of objects associated with the keys).
+ /// The value type of the map. (The type of objects associated with the keys).
typedef T Value;
- /// Map's reference type.
+ /// The reference type of the map.
typedef R Reference;
- /// Map's const reference type.
+ /// The const reference type of the map.
typedef CR ConstReference;
protected:
Value tmp;
public:
- ///Returns a reference to the value associated to a key.
+ ///Returns a reference to the value associated with a key.
Reference operator[](const Key &) { return tmp; }
- ///Returns a const reference to the value associated to a key.
- ConstReference operator[](const Key &) const
- { return tmp; }
+ ///Returns a const reference to the value associated with a key.
+ ConstReference operator[](const Key &) const { return tmp; }
/// Sets the value associated with a key.
void set(const Key &k,const Value &t) { operator[](k)=t; }
- // \todo rethink this concept
template<typename _ReferenceMap>
- struct ReferenceMapConcept {
+ struct Constraints {
void constraints() {
- checkConcept<ReadWriteMap, _ReferenceMap >();
+ checkConcept<ReadWriteMap<K, T>, _ReferenceMap >();
m[key] = val;
val = m[key];
m[key] = ref;
@@ -177,10 +191,10 @@
typename _ReferenceMap::Key& own_key;
typename _ReferenceMap::Value& own_val;
- typename _ReferenceMap::Reference& own_ref;
+ typename _ReferenceMap::Reference own_ref;
Key& key;
Value& val;
- Reference& ref;
+ Reference ref;
_ReferenceMap& m;
};
};
@@ -188,5 +202,7 @@
// @}
} //namespace concepts
+
} //namespace lemon
+
#endif // LEMON_CONCEPT_MAPS_H
Modified: lemon/trunk/lemon/maps.h
==============================================================================
--- lemon/trunk/lemon/maps.h (original)
+++ lemon/trunk/lemon/maps.h Tue Feb 5 13:41:05 2008
@@ -44,17 +44,18 @@
template<typename K, typename T>
class MapBase {
public:
- ///\e
+ /// The key type of the map.
typedef K Key;
- ///\e
+ /// The value type of the map. (The type of objects associated with the keys).
typedef T Value;
};
/// Null map. (a.k.a. DoNothingMap)
- /// If you have to provide a map only for its type definitions,
- /// or if you have to provide a writable map, but
- /// data written to it will sent to <tt>/dev/null</tt>...
+ /// This map can be used if you have to provide a map only for
+ /// its type definitions, or if you have to provide a writable map,
+ /// but data written to it is not required (i.e. it will be sent to
+ /// <tt>/dev/null</tt>).
template<typename K, typename T>
class NullMap : public MapBase<K, T> {
public:
@@ -68,6 +69,10 @@
void set(const K&, const T&) {}
};
+ ///Returns a \c NullMap class
+
+ ///This function just returns a \c NullMap class.
+ ///\relates NullMap
template <typename K, typename V>
NullMap<K, V> nullMap() {
return NullMap<K, V>();
@@ -76,8 +81,9 @@
/// Constant map.
- /// This is a readable map which assigns a specified value to each key.
- /// In other aspects it is equivalent to the \c NullMap.
+ /// This is a \ref concepts::ReadMap "readable" map which assigns a
+ /// specified value to each key.
+ /// In other aspects it is equivalent to \c NullMap.
template<typename K, typename T>
class ConstMap : public MapBase<K, T> {
private:
@@ -90,13 +96,15 @@
/// Default constructor
+ /// Default constructor.
/// The value of the map will be uninitialized.
/// (More exactly it will be default constructed.)
ConstMap() {}
- ///\e
+
+ /// Constructor with specified initial value
- /// \param _v The initial value of the map.
- ///
+ /// Constructor with specified initial value.
+ /// \param _v is the initial value of the map.
ConstMap(const T &_v) : v(_v) {}
///\e
@@ -131,8 +139,9 @@
/// Constant map with inlined constant value.
- /// This is a readable map which assigns a specified value to each key.
- /// In other aspects it is equivalent to the \c NullMap.
+ /// This is a \ref concepts::ReadMap "readable" map which assigns a
+ /// specified value to each key.
+ /// In other aspects it is equivalent to \c NullMap.
template<typename K, typename V, V v>
class ConstMap<K, Const<V, v> > : public MapBase<K, V> {
public:
@@ -147,7 +156,7 @@
void set(const K&, const V&) { }
};
- ///Returns a \c ConstMap class
+ ///Returns a \c ConstMap class with inlined value
///This function just returns a \c ConstMap class with inlined value.
///\relates ConstMap
@@ -156,26 +165,29 @@
return ConstMap<K, Const<V, v> >();
}
- ///Map based on std::map
+ ///Map based on \c std::map
- ///This is essentially a wrapper for \c std::map. With addition that
+ ///This is essentially a wrapper for \c std::map with addition that
///you can specify a default value different from \c Value() .
+ ///It meets the \ref concepts::ReferenceMap "ReferenceMap" concept.
template <typename K, typename T, typename Compare = std::less<K> >
- class StdMap {
+ class StdMap : public MapBase<K, T> {
template <typename K1, typename T1, typename C1>
friend class StdMap;
public:
- typedef True ReferenceMapTag;
- ///\e
- typedef K Key;
- ///\e
- typedef T Value;
- ///\e
+ typedef MapBase<K, T> Parent;
+ ///Key type
+ typedef typename Parent::Key Key;
+ ///Value type
+ typedef typename Parent::Value Value;
+ ///Reference Type
typedef T& Reference;
- ///\e
+ ///Const reference type
typedef const T& ConstReference;
+ typedef True ReferenceMapTag;
+
private:
typedef std::map<K, T, Compare> Map;
@@ -186,13 +198,13 @@
/// Constructor with specified default value
StdMap(const T& value = T()) : _value(value) {}
- /// \brief Constructs the map from an appropriate std::map, and explicitly
- /// specifies a default value.
+ /// \brief Constructs the map from an appropriate \c std::map, and
+ /// explicitly specifies a default value.
template <typename T1, typename Comp1>
StdMap(const std::map<Key, T1, Comp1> &map, const T& value = T())
: _map(map.begin(), map.end()), _value(value) {}
- /// \brief Constructs a map from an other StdMap.
+ /// \brief Constructs a map from an other \ref StdMap.
template<typename T1, typename Comp1>
StdMap(const StdMap<Key, T1, Comp1> &c)
: _map(c._map.begin(), c._map.end()), _value(c._value) {}
@@ -242,30 +254,58 @@
};
};
- /// \brief Map for storing values for the range \c [0..size-1] range keys
+ ///Returns a \c StdMap class
+
+ ///This function just returns a \c StdMap class with specified
+ ///default value.
+ ///\relates StdMap
+ template<typename K, typename V, typename Compare>
+ inline StdMap<K, V, Compare> stdMap(const V& value = V()) {
+ return StdMap<K, V, Compare>(value);
+ }
+
+ template<typename K, typename V>
+ inline StdMap<K, V, std::less<K> > stdMap(const V& value = V()) {
+ return StdMap<K, V, std::less<K> >(value);
+ }
+
+ ///Returns a \c StdMap class created from an appropriate \c std::map
+
+ ///This function just returns a \c StdMap class created from an
+ ///appropriate \c std::map.
+ ///\relates StdMap
+ template<typename K, typename V, typename Compare>
+ inline StdMap<K, V, Compare> stdMap( const std::map<K, V, Compare> &map,
+ const V& value = V() ) {
+ return StdMap<K, V, Compare>(map, value);
+ }
+
+ /// \brief Map for storing values for keys from the range <tt>[0..size-1]</tt>
///
- /// The current map has the \c [0..size-1] keyset and the values
+ /// This map has the <tt>[0..size-1]</tt> keyset and the values
/// are stored in a \c std::vector<T> container. It can be used with
/// some data structures, for example \c UnionFind, \c BinHeap, when
/// the used items are small integer numbers.
template <typename T>
- class IntegerMap {
+ class IntegerMap : public MapBase<int, T> {
template <typename T1>
friend class IntegerMap;
public:
- typedef True ReferenceMapTag;
+ typedef MapBase<int, T> Parent;
///\e
- typedef int Key;
+ typedef typename Parent::Key Key;
///\e
- typedef T Value;
+ typedef typename Parent::Value Value;
///\e
typedef T& Reference;
///\e
typedef const T& ConstReference;
+ typedef True ReferenceMapTag;
+
private:
typedef std::vector<T> Vector;
@@ -276,12 +316,12 @@
/// Constructor with specified default value
IntegerMap(int size = 0, const T& value = T()) : _vector(size, value) {}
- /// \brief Constructs the map from an appropriate std::vector.
+ /// \brief Constructs the map from an appropriate \c std::vector.
template <typename T1>
IntegerMap(const std::vector<T1>& vector)
: _vector(vector.begin(), vector.end()) {}
- /// \brief Constructs a map from an other IntegerMap.
+ /// \brief Constructs a map from an other \ref IntegerMap.
template <typename T1>
IntegerMap(const IntegerMap<T1> &c)
: _vector(c._vector.begin(), c._vector.end()) {}
@@ -314,14 +354,23 @@
};
+ ///Returns an \c IntegerMap class
+
+ ///This function just returns an \c IntegerMap class.
+ ///\relates IntegerMap
+ template<typename T>
+ inline IntegerMap<T> integerMap(int size = 0, const T& value = T()) {
+ return IntegerMap<T>(size, value);
+ }
+
/// @}
/// \addtogroup map_adaptors
/// @{
- /// \brief Identity mapping.
+ /// \brief Identity map.
///
- /// This mapping gives back the given key as value without any
+ /// This map gives back the given key as value without any
/// modification.
template <typename T>
class IdentityMap : public MapBase<T, T> {
@@ -346,10 +395,11 @@
}
- ///Convert the \c Value of a map to another type.
-
- ///This \c concepts::ReadMap "read only map"
- ///converts the \c Value of a maps to type \c T.
+ ///\brief Convert the \c Value of a map to another type using
+ ///the default conversion.
+ ///
+ ///This \ref concepts::ReadMap "read only map"
+ ///converts the \c Value of a map to type \c T.
///Its \c Key is inherited from \c M.
template <typename M, typename T>
class ConvertMap : public MapBase<typename M::Key, T> {
@@ -365,29 +415,29 @@
///\param _m is the underlying map
ConvertMap(const M &_m) : m(_m) {};
- /// \brief The subscript operator.
- ///
- /// The subscript operator.
- /// \param k The key
- /// \return The target of the edge
+ ///\e
Value operator[](const Key& k) const {return m[k];}
};
- ///Returns an \c ConvertMap class
+ ///Returns a \c ConvertMap class
- ///This function just returns an \c ConvertMap class.
+ ///This function just returns a \c ConvertMap class.
///\relates ConvertMap
template<typename T, typename M>
inline ConvertMap<M, T> convertMap(const M &m) {
return ConvertMap<M, T>(m);
}
- ///Simple wrapping of the map
+ ///Simple wrapping of a map
- ///This \c concepts::ReadMap "read only map" returns the simple
+ ///This \ref concepts::ReadMap "read only map" returns the simple
///wrapping of the given map. Sometimes the reference maps cannot be
///combined with simple read maps. This map adaptor wraps the given
///map to simple read map.
+ ///
+ ///\sa SimpleWriteMap
+ ///
+ /// \todo Revise the misleading name
template<typename M>
class SimpleMap : public MapBase<typename M::Key, typename M::Value> {
const M& m;
@@ -403,12 +453,25 @@
Value operator[](Key k) const {return m[k];}
};
- ///Simple writeable wrapping of the map
+ ///Returns a \c SimpleMap class
+
+ ///This function just returns a \c SimpleMap class.
+ ///\relates SimpleMap
+ template<typename M>
+ inline SimpleMap<M> simpleMap(const M &m) {
+ return SimpleMap<M>(m);
+ }
+
+ ///Simple writable wrapping of a map
- ///This \c concepts::ReadMap "read only map" returns the simple
+ ///This \ref concepts::ReadWriteMap "read-write map" returns the simple
///wrapping of the given map. Sometimes the reference maps cannot be
///combined with simple read-write maps. This map adaptor wraps the
///given map to simple read-write map.
+ ///
+ ///\sa SimpleMap
+ ///
+ /// \todo Revise the misleading name
template<typename M>
class SimpleWriteMap : public MapBase<typename M::Key, typename M::Value> {
M& m;
@@ -426,12 +489,21 @@
void set(Key k, const Value& c) { m.set(k, c); }
};
- ///Sum of two maps
+ ///Returns a \c SimpleWriteMap class
- ///This \c concepts::ReadMap "read only map" returns the sum of the two
- ///given maps. Its \c Key and \c Value will be inherited from \c M1.
- ///The \c Key and \c Value of M2 must be convertible to those of \c M1.
+ ///This function just returns a \c SimpleWriteMap class.
+ ///\relates SimpleWriteMap
+ template<typename M>
+ inline SimpleWriteMap<M> simpleWriteMap(M &m) {
+ return SimpleWriteMap<M>(m);
+ }
+
+ ///Sum of two maps
+ ///This \ref concepts::ReadMap "read only map" returns the sum of the two
+ ///given maps.
+ ///Its \c Key and \c Value are inherited from \c M1.
+ ///The \c Key and \c Value of \c M2 must be convertible to those of \c M1.
template<typename M1, typename M2>
class AddMap : public MapBase<typename M1::Key, typename M1::Value> {
const M1& m1;
@@ -461,7 +533,7 @@
///Shift a map with a constant.
- ///This \c concepts::ReadMap "read only map" returns the sum of the
+ ///This \ref concepts::ReadMap "read only map" returns the sum of the
///given map and a constant value.
///Its \c Key and \c Value is inherited from \c M.
///
@@ -469,11 +541,13 @@
///\code
/// ShiftMap<X> sh(x,v);
///\endcode
- ///is equivalent with
+ ///is equivalent to
///\code
/// ConstMap<X::Key, X::Value> c_tmp(v);
/// AddMap<X, ConstMap<X::Key, X::Value> > sh(x,v);
///\endcode
+ ///
+ ///\sa ShiftWriteMap
template<typename M, typename C = typename M::Value>
class ShiftMap : public MapBase<typename M::Key, typename M::Value> {
const M& m;
@@ -493,21 +567,13 @@
Value operator[](Key k) const {return m[k] + v;}
};
- ///Shift a map with a constant.
+ ///Shift a map with a constant (ReadWrite version).
- ///This \c concepts::ReadWriteMap "read-write map" returns the sum of the
+ ///This \ref concepts::ReadWriteMap "read-write map" returns the sum of the
///given map and a constant value. It makes also possible to write the map.
- ///Its \c Key and \c Value is inherited from \c M.
+ ///Its \c Key and \c Value are inherited from \c M.
///
- ///Actually,
- ///\code
- /// ShiftMap<X> sh(x,v);
- ///\endcode
- ///is equivalent with
- ///\code
- /// ConstMap<X::Key, X::Value> c_tmp(v);
- /// AddMap<X, ConstMap<X::Key, X::Value> > sh(x,v);
- ///\endcode
+ ///\sa ShiftMap
template<typename M, typename C = typename M::Value>
class ShiftWriteMap : public MapBase<typename M::Key, typename M::Value> {
M& m;
@@ -529,7 +595,7 @@
void set(Key k, const Value& c) { m.set(k, c - v); }
};
- ///Returns an \c ShiftMap class
+ ///Returns a \c ShiftMap class
///This function just returns an \c ShiftMap class.
///\relates ShiftMap
@@ -538,6 +604,10 @@
return ShiftMap<M, C>(m,v);
}
+ ///Returns a \c ShiftWriteMap class
+
+ ///This function just returns a \c ShiftWriteMap class.
+ ///\relates ShiftWriteMap
template<typename M, typename C>
inline ShiftWriteMap<M, C> shiftMap(M &m,const C &v) {
return ShiftWriteMap<M, C>(m,v);
@@ -545,9 +615,9 @@
///Difference of two maps
- ///This \c concepts::ReadMap "read only map" returns the difference
- ///of the values of the two
- ///given maps. Its \c Key and \c Value will be inherited from \c M1.
+ ///This \ref concepts::ReadMap "read only map" returns the difference
+ ///of the values of the two given maps.
+ ///Its \c Key and \c Value are inherited from \c M1.
///The \c Key and \c Value of \c M2 must be convertible to those of \c M1.
template<typename M1, typename M2>
@@ -577,12 +647,10 @@
///Product of two maps
- ///This \c concepts::ReadMap "read only map" returns the product of the
- ///values of the two
- ///given
- ///maps. Its \c Key and \c Value will be inherited from \c M1.
+ ///This \ref concepts::ReadMap "read only map" returns the product of the
+ ///values of the two given maps.
+ ///Its \c Key and \c Value are inherited from \c M1.
///The \c Key and \c Value of \c M2 must be convertible to those of \c M1.
-
template<typename M1, typename M2>
class MulMap : public MapBase<typename M1::Key, typename M1::Value> {
const M1& m1;
@@ -607,21 +675,23 @@
return MulMap<M1, M2>(m1,m2);
}
- ///Scales a maps with a constant.
+ ///Scales a map with a constant.
- ///This \c concepts::ReadMap "read only map" returns the value of the
+ ///This \ref concepts::ReadMap "read only map" returns the value of the
///given map multiplied from the left side with a constant value.
- ///Its \c Key and \c Value is inherited from \c M.
+ ///Its \c Key and \c Value are inherited from \c M.
///
///Actually,
///\code
/// ScaleMap<X> sc(x,v);
///\endcode
- ///is equivalent with
+ ///is equivalent to
///\code
/// ConstMap<X::Key, X::Value> c_tmp(v);
/// MulMap<X, ConstMap<X::Key, X::Value> > sc(x,v);
///\endcode
+ ///
+ ///\sa ScaleWriteMap
template<typename M, typename C = typename M::Value>
class ScaleMap : public MapBase<typename M::Key, typename M::Value> {
const M& m;
@@ -641,12 +711,15 @@
Value operator[](Key k) const {return v * m[k];}
};
- ///Scales a maps with a constant.
+ ///Scales a map with a constant (ReadWrite version).
- ///This \c concepts::ReadWriteMap "read-write map" returns the value of the
+ ///This \ref concepts::ReadWriteMap "read-write map" returns the value of the
///given map multiplied from the left side with a constant value. It can
- ///be used as write map also if the given multiplier is not zero.
- ///Its \c Key and \c Value is inherited from \c M.
+ ///also be used as write map if the \c / operator is defined between
+ ///\c Value and \c C and the given multiplier is not zero.
+ ///Its \c Key and \c Value are inherited from \c M.
+ ///
+ ///\sa ScaleMap
template<typename M, typename C = typename M::Value>
class ScaleWriteMap : public MapBase<typename M::Key, typename M::Value> {
M& m;
@@ -668,15 +741,19 @@
void set(Key k, const Value& c) { m.set(k, c / v);}
};
- ///Returns an \c ScaleMap class
+ ///Returns a \c ScaleMap class
- ///This function just returns an \c ScaleMap class.
+ ///This function just returns a \c ScaleMap class.
///\relates ScaleMap
template<typename M, typename C>
inline ScaleMap<M, C> scaleMap(const M &m,const C &v) {
return ScaleMap<M, C>(m,v);
}
+ ///Returns a \c ScaleWriteMap class
+
+ ///This function just returns a \c ScaleWriteMap class.
+ ///\relates ScaleWriteMap
template<typename M, typename C>
inline ScaleWriteMap<M, C> scaleMap(M &m,const C &v) {
return ScaleWriteMap<M, C>(m,v);
@@ -684,11 +761,10 @@
///Quotient of two maps
- ///This \c concepts::ReadMap "read only map" returns the quotient of the
- ///values of the two
- ///given maps. Its \c Key and \c Value will be inherited from \c M1.
+ ///This \ref concepts::ReadMap "read only map" returns the quotient of the
+ ///values of the two given maps.
+ ///Its \c Key and \c Value are inherited from \c M1.
///The \c Key and \c Value of \c M2 must be convertible to those of \c M1.
-
template<typename M1, typename M2>
class DivMap : public MapBase<typename M1::Key, typename M1::Value> {
const M1& m1;
@@ -715,19 +791,20 @@
///Composition of two maps
- ///This \c concepts::ReadMap "read only map" returns the composition of
- ///two
- ///given maps. That is to say, if \c m1 is of type \c M1 and \c m2 is
- ///of \c M2,
+ ///This \ref concepts::ReadMap "read only map" returns the composition of
+ ///two given maps.
+ ///That is to say, if \c m1 is of type \c M1 and \c m2 is of \c M2,
///then for
///\code
/// ComposeMap<M1, M2> cm(m1,m2);
///\endcode
- /// <tt>cm[x]</tt> will be equal to <tt>m1[m2[x]]</tt>
+ /// <tt>cm[x]</tt> will be equal to <tt>m1[m2[x]]</tt>.
+ ///
+ ///Its \c Key is inherited from \c M2 and its \c Value is from \c M1.
+ ///\c M2::Value must be convertible to \c M1::Key.
+ ///
+ ///\sa CombineMap
///
- ///Its \c Key is inherited from \c M2 and its \c Value is from
- ///\c M1.
- ///The \c M2::Value must be convertible to \c M1::Key.
///\todo Check the requirements.
template <typename M1, typename M2>
class ComposeMap : public MapBase<typename M2::Key, typename M1::Value> {
@@ -755,27 +832,27 @@
return ComposeMap<M1, M2>(m1,m2);
}
- ///Combines of two maps using an STL (binary) functor.
+ ///Combine of two maps using an STL (binary) functor.
- ///Combines of two maps using an STL (binary) functor.
- ///
+ ///Combine of two maps using an STL (binary) functor.
///
- ///This \c concepts::ReadMap "read only map" takes two maps and a
- ///binary functor and returns the composition of
- ///the two
+ ///This \ref concepts::ReadMap "read only map" takes two maps and a
+ ///binary functor and returns the composition of the two
///given maps unsing the functor.
///That is to say, if \c m1 and \c m2 is of type \c M1 and \c M2
- ///and \c f is of \c F,
- ///then for
+ ///and \c f is of \c F, then for
///\code
/// CombineMap<M1, M2,F,V> cm(m1,m2,f);
///\endcode
/// <tt>cm[x]</tt> will be equal to <tt>f(m1[x],m2[x])</tt>
///
///Its \c Key is inherited from \c M1 and its \c Value is \c V.
- ///The \c M2::Value and \c M1::Value must be convertible to the corresponding
+ ///\c M2::Value and \c M1::Value must be convertible to the corresponding
///input parameter of \c F and the return type of \c F must be convertible
///to \c V.
+ ///
+ ///\sa ComposeMap
+ ///
///\todo Check the requirements.
template<typename M1, typename M2, typename F,
typename V = typename F::result_type>
@@ -801,15 +878,15 @@
///
///For example if \c m1 and \c m2 are both \c double valued maps, then
///\code
- ///combineMap<double>(m1,m2,std::plus<double>())
+ ///combineMap(m1,m2,std::plus<double>())
///\endcode
- ///is equivalent with
+ ///is equivalent to
///\code
///addMap(m1,m2)
///\endcode
///
///This function is specialized for adaptable binary function
- ///classes and c++ functions.
+ ///classes and C++ functions.
///
///\relates CombineMap
template<typename M1, typename M2, typename F, typename V>
@@ -832,12 +909,12 @@
///Negative value of a map
- ///This \c concepts::ReadMap "read only map" returns the negative
- ///value of the
- ///value returned by the
- ///given map. Its \c Key and \c Value will be inherited from \c M.
+ ///This \ref concepts::ReadMap "read only map" returns the negative
+ ///value of the value returned by the given map.
+ ///Its \c Key and \c Value are inherited from \c M.
///The unary \c - operator must be defined for \c Value, of course.
-
+ ///
+ ///\sa NegWriteMap
template<typename M>
class NegMap : public MapBase<typename M::Key, typename M::Value> {
const M& m;
@@ -852,13 +929,14 @@
Value operator[](Key k) const {return -m[k];}
};
- ///Negative value of a map
+ ///Negative value of a map (ReadWrite version)
- ///This \c concepts::ReadWriteMap "read-write map" returns the negative
- ///value of the value returned by the
- ///given map. Its \c Key and \c Value will be inherited from \c M.
+ ///This \ref concepts::ReadWriteMap "read-write map" returns the negative
+ ///value of the value returned by the given map.
+ ///Its \c Key and \c Value are inherited from \c M.
///The unary \c - operator must be defined for \c Value, of course.
-
+ ///
+ /// \sa NegMap
template<typename M>
class NegWriteMap : public MapBase<typename M::Key, typename M::Value> {
M& m;
@@ -884,6 +962,10 @@
return NegMap<M>(m);
}
+ ///Returns a \c NegWriteMap class
+
+ ///This function just returns a \c NegWriteMap class.
+ ///\relates NegWriteMap
template <typename M>
inline NegWriteMap<M> negMap(M &m) {
return NegWriteMap<M>(m);
@@ -891,12 +973,10 @@
///Absolute value of a map
- ///This \c concepts::ReadMap "read only map" returns the absolute value
- ///of the
- ///value returned by the
- ///given map. Its \c Key and \c Value will be inherited
- ///from <tt>M</tt>. <tt>Value</tt>
- ///must be comparable to <tt>0</tt> and the unary <tt>-</tt>
+ ///This \ref concepts::ReadMap "read only map" returns the absolute value
+ ///of the value returned by the given map.
+ ///Its \c Key and \c Value are inherited from \c M.
+ ///\c Value must be comparable to \c 0 and the unary \c -
///operator must be defined for it, of course.
///
///\bug We need a unified way to handle the situation below:
@@ -930,9 +1010,9 @@
};
- ///Returns a \c AbsMap class
+ ///Returns an \c AbsMap class
- ///This function just returns a \c AbsMap class.
+ ///This function just returns an \c AbsMap class.
///\relates AbsMap
template<typename M>
inline AbsMap<M> absMap(const M &m) {
@@ -941,15 +1021,18 @@
///Converts an STL style functor to a map
- ///This \c concepts::ReadMap "read only map" returns the value
- ///of a
- ///given map.
+ ///This \ref concepts::ReadMap "read only map" returns the value
+ ///of a given functor.
///
///Template parameters \c K and \c V will become its
- ///\c Key and \c Value. They must be given explicitely
- ///because a functor does not provide such typedefs.
+ ///\c Key and \c Value.
+ ///In most cases they have to be given explicitly because a
+ ///functor typically does not provide \c argument_type and
+ ///\c result_type typedefs.
///
///Parameter \c F is the type of the used functor.
+ ///
+ ///\sa MapFunctor
template<typename F,
typename K = typename F::argument_type,
typename V = typename F::result_type>
@@ -970,8 +1053,9 @@
///This function just returns a \c FunctorMap class.
///
- ///It is specialized for adaptable function classes and
- ///c++ functions.
+ ///This function is specialized for adaptable binary function
+ ///classes and C++ functions.
+ ///
///\relates FunctorMap
template<typename K, typename V, typename F> inline
FunctorMap<F, K, V> functorMap(const F &f) {
@@ -994,11 +1078,13 @@
///Converts a map to an STL style (unary) functor
///This class Converts a map to an STL style (unary) functor.
- ///that is it provides an <tt>operator()</tt> to read its values.
+ ///That is it provides an <tt>operator()</tt> to read its values.
///
///For the sake of convenience it also works as
- ///a ususal \c concepts::ReadMap "readable map",
+ ///a ususal \ref concepts::ReadMap "readable map",
///i.e. <tt>operator[]</tt> and the \c Key and \c Value typedefs also exist.
+ ///
+ ///\sa FunctorMap
template <typename M>
class MapFunctor : public MapBase<typename M::Key, typename M::Value> {
const M& m;
@@ -1027,14 +1113,17 @@
return MapFunctor<M>(m);
}
- ///Applies all map setting operations to two maps
+ ///Just readable version of \ref ForkWriteMap
- ///This map has two \c concepts::ReadMap "readable map"
+ ///This map has two \ref concepts::ReadMap "readable map"
///parameters and each read request will be passed just to the
- ///first map. This class is the just readable map type of the ForkWriteMap.
+ ///first map. This class is the just readable map type of \c ForkWriteMap.
///
- ///The \c Key and \c Value will be inherited from \c M1.
- ///The \c Key and \c Value of M2 must be convertible from those of \c M1.
+ ///The \c Key and \c Value are inherited from \c M1.
+ ///The \c Key and \c Value of \c M2 must be convertible from those of \c M1.
+ ///
+ ///\sa ForkWriteMap
+
template<typename M1, typename M2>
class ForkMap : public MapBase<typename M1::Key, typename M1::Value> {
const M1& m1;
@@ -1053,14 +1142,16 @@
///Applies all map setting operations to two maps
- ///This map has two \c concepts::WriteMap "writable map"
+ ///This map has two \ref concepts::WriteMap "writable map"
///parameters and each write request will be passed to both of them.
- ///If \c M1 is also \c concepts::ReadMap "readable",
+ ///If \c M1 is also \ref concepts::ReadMap "readable",
///then the read operations will return the
///corresponding values of \c M1.
///
- ///The \c Key and \c Value will be inherited from \c M1.
- ///The \c Key and \c Value of M2 must be convertible from those of \c M1.
+ ///The \c Key and \c Value are inherited from \c M1.
+ ///The \c Key and \c Value of \c M2 must be convertible from those of \c M1.
+ ///
+ ///\sa ForkMap
template<typename M1, typename M2>
class ForkWriteMap : public MapBase<typename M1::Key, typename M1::Value> {
M1& m1;
@@ -1078,16 +1169,19 @@
void set(Key k, const Value &v) {m1.set(k,v); m2.set(k,v);}
};
- ///Returns an \c ForkMap class
+ ///Returns a \c ForkMap class
- ///This function just returns an \c ForkMap class.
- ///
+ ///This function just returns a \c ForkMap class.
///\relates ForkMap
template <typename M1, typename M2>
inline ForkMap<M1, M2> forkMap(const M1 &m1, const M2 &m2) {
return ForkMap<M1, M2>(m1,m2);
}
+ ///Returns a \c ForkWriteMap class
+
+ ///This function just returns a \c ForkWriteMap class.
+ ///\relates ForkWriteMap
template <typename M1, typename M2>
inline ForkWriteMap<M1, M2> forkMap(M1 &m1, M2 &m2) {
return ForkWriteMap<M1, M2>(m1,m2);
@@ -1099,11 +1193,11 @@
///Logical 'not' of a map
- ///This bool \c concepts::ReadMap "read only map" returns the
- ///logical negation of
- ///value returned by the
- ///given map. Its \c Key and will be inherited from \c M,
- ///its Value is <tt>bool</tt>.
+ ///This bool \ref concepts::ReadMap "read only map" returns the
+ ///logical negation of the value returned by the given map.
+ ///Its \c Key is inherited from \c M, its \c Value is \c bool.
+ ///
+ ///\sa NotWriteMap
template <typename M>
class NotMap : public MapBase<typename M::Key, bool> {
const M& m;
@@ -1118,13 +1212,14 @@
Value operator[](Key k) const {return !m[k];}
};
- ///Logical 'not' of a map with writing possibility
+ ///Logical 'not' of a map (ReadWrie version)
- ///This bool \c concepts::ReadWriteMap "read-write map" returns the
- ///logical negation of value returned by the given map. When it is set,
+ ///This bool \ref concepts::ReadWriteMap "read-write map" returns the
+ ///logical negation of the value returned by the given map. When it is set,
///the opposite value is set to the original map.
- ///Its \c Key and will be inherited from \c M,
- ///its Value is <tt>bool</tt>.
+ ///Its \c Key is inherited from \c M, its \c Value is \c bool.
+ ///
+ ///\sa NotMap
template <typename M>
class NotWriteMap : public MapBase<typename M::Key, bool> {
M& m;
@@ -1150,6 +1245,10 @@
return NotMap<M>(m);
}
+ ///Returns a \c NotWriteMap class
+
+ ///This function just returns a \c NotWriteMap class.
+ ///\relates NotWriteMap
template <typename M>
inline NotWriteMap<M> notMap(M &m) {
return NotWriteMap<M>(m);
@@ -1181,16 +1280,17 @@
}
- /// \brief Writable bool map for store each true assigned elements.
+ /// \brief Writable bool map for logging each \c true assigned element
///
- /// Writable bool map to store each true assigned elements. It will
- /// copies all the keys set to true to the given iterator.
+ /// A \ref concepts::ReadWriteMap "read-write" bool map for logging
+ /// each \c true assigned element, i.e it copies all the keys set
+ /// to \c true to the given iterator.
///
/// \note The container of the iterator should contain space
/// for each element.
///
- /// The next example shows how can you write the nodes directly
- /// to the standard output.
+ /// The following example shows how you can write the edges found by
+ /// the \ref Prim algorithm directly to the standard output.
///\code
/// typedef IdMap<UGraph, UEdge> UEdgeIdMap;
/// UEdgeIdMap uedgeId(ugraph);
@@ -1203,6 +1303,10 @@
///
/// prim(ugraph, cost, writerMap);
///\endcode
+ ///
+ ///\sa BackInserterBoolMap
+ ///\sa FrontInserterBoolMap
+ ///\sa InserterBoolMap
template <typename _Iterator,
typename _Functor =
_maps_bits::Identity<typename _maps_bits::
@@ -1220,17 +1324,17 @@
StoreBoolMap(Iterator it, const Functor& functor = Functor())
: _begin(it), _end(it), _functor(functor) {}
- /// Gives back the given iterator set for the first time.
+ /// Gives back the given iterator set for the first key
Iterator begin() const {
return _begin;
}
- /// Gives back the iterator after the last set operation.
+ /// Gives back the the 'after the last' iterator
Iterator end() const {
return _end;
}
- /// Setter function of the map
+ /// The \c set function of the map
void set(const Key& key, Value value) const {
if (value) {
*_end++ = _functor(key);
@@ -1243,26 +1347,30 @@
Functor _functor;
};
- /// \brief Writable bool map for store each true assigned elements in
+ /// \brief Writable bool map for logging each \c true assigned element in
/// a back insertable container.
///
- /// Writable bool map for store each true assigned elements in a back
- /// insertable container. It will push back all the keys set to true into
- /// the container. It can be used to retrieve the items into a standard
- /// container. The next example shows how can you store the undirected
- /// edges in a vector with prim algorithm.
+ /// Writable bool map for logging each \c true assigned element by pushing
+ /// them into a back insertable container.
+ /// It can be used to retrieve the items into a standard
+ /// container. The next example shows how you can store the
+ /// edges found by the Prim algorithm in a vector.
///
///\code
/// vector<UEdge> span_tree_uedges;
/// BackInserterBoolMap<vector<UEdge> > inserter_map(span_tree_uedges);
/// prim(ugraph, cost, inserter_map);
///\endcode
+ ///
+ ///\sa StoreBoolMap
+ ///\sa FrontInserterBoolMap
+ ///\sa InserterBoolMap
template <typename Container,
typename Functor =
_maps_bits::Identity<typename Container::value_type> >
class BackInserterBoolMap {
public:
- typedef typename Container::value_type Key;
+ typedef typename Functor::argument_type Key;
typedef bool Value;
/// Constructor
@@ -1270,7 +1378,7 @@
const Functor& _functor = Functor())
: container(_container), functor(_functor) {}
- /// Setter function of the map
+ /// The \c set function of the map
void set(const Key& key, Value value) {
if (value) {
container.push_back(functor(key));
@@ -1282,18 +1390,22 @@
Functor functor;
};
- /// \brief Writable bool map for store each true assigned elements in
+ /// \brief Writable bool map for logging each \c true assigned element in
/// a front insertable container.
///
- /// Writable bool map for store each true assigned elements in a front
- /// insertable container. It will push front all the keys set to \c true into
- /// the container. For example see the BackInserterBoolMap.
+ /// Writable bool map for logging each \c true assigned element by pushing
+ /// them into a front insertable container.
+ /// It can be used to retrieve the items into a standard
+ /// container. For example see \ref BackInserterBoolMap.
+ ///
+ ///\sa BackInserterBoolMap
+ ///\sa InserterBoolMap
template <typename Container,
typename Functor =
_maps_bits::Identity<typename Container::value_type> >
class FrontInserterBoolMap {
public:
- typedef typename Container::value_type Key;
+ typedef typename Functor::argument_type Key;
typedef bool Value;
/// Constructor
@@ -1301,10 +1413,10 @@
const Functor& _functor = Functor())
: container(_container), functor(_functor) {}
- /// Setter function of the map
+ /// The \c set function of the map
void set(const Key& key, Value value) {
if (value) {
- container.push_front(key);
+ container.push_front(functor(key));
}
}
@@ -1313,12 +1425,14 @@
Functor functor;
};
- /// \brief Writable bool map for store each true assigned elements in
+ /// \brief Writable bool map for storing each \c true assigned element in
/// an insertable container.
///
- /// Writable bool map for store each true assigned elements in an
+ /// Writable bool map for storing each \c true assigned element in an
/// insertable container. It will insert all the keys set to \c true into
- /// the container. If you want to store the cut edges of the strongly
+ /// the container.
+ ///
+ /// For example, if you want to store the cut arcs of the strongly
/// connected components in a set you can use the next code:
///
///\code
@@ -1326,6 +1440,9 @@
/// InserterBoolMap<set<Edge> > inserter_map(cut_edges);
/// stronglyConnectedCutEdges(graph, cost, inserter_map);
///\endcode
+ ///
+ ///\sa BackInserterBoolMap
+ ///\sa FrontInserterBoolMap
template <typename Container,
typename Functor =
_maps_bits::Identity<typename Container::value_type> >
@@ -1334,19 +1451,29 @@
typedef typename Container::value_type Key;
typedef bool Value;
- /// Constructor
+ /// Constructor with specified iterator
+
+ /// Constructor with specified iterator.
+ /// \param _container The container for storing the elements.
+ /// \param _it The elements will be inserted before this iterator.
+ /// \param _functor The functor that is used when an element is stored.
InserterBoolMap(Container& _container, typename Container::iterator _it,
const Functor& _functor = Functor())
: container(_container), it(_it), functor(_functor) {}
/// Constructor
+
+ /// Constructor without specified iterator.
+ /// The elements will be inserted before <tt>_container.end()</tt>.
+ /// \param _container The container for storing the elements.
+ /// \param _functor The functor that is used when an element is stored.
InserterBoolMap(Container& _container, const Functor& _functor = Functor())
: container(_container), it(_container.end()), functor(_functor) {}
- /// Setter function of the map
+ /// The \c set function of the map
void set(const Key& key, Value value) {
if (value) {
- it = container.insert(it, key);
+ it = container.insert(it, functor(key));
++it;
}
}
@@ -1357,13 +1484,13 @@
Functor functor;
};
- /// \brief Fill the true set elements with a given value.
+ /// \brief Writable bool map for filling each \c true assigned element with a
+ /// given value.
///
- /// Writable bool map to fill the elements set to \c true with a given value.
- /// The value can set
- /// the container.
+ /// Writable bool map for filling each \c true assigned element with a
+ /// given value. The value can set the container.
///
- /// The next code finds the connected components of the undirected graph
+ /// The following code finds the connected components of a graph
/// and stores it in the \c comp map:
///\code
/// typedef UGraph::NodeMap<int> ComponentMap;
@@ -1411,7 +1538,7 @@
fill = _fill;
}
- /// Setter function of the map
+ /// The \c set function of the map
void set(const Key& key, Value value) {
if (value) {
map.set(key, fill);
@@ -1424,11 +1551,12 @@
};
- /// \brief Writable bool map which stores for each true assigned elements
- /// the setting order number.
+ /// \brief Writable bool map for storing the sequence number of
+ /// \c true assignments.
///
- /// Writable bool map which stores for each true assigned elements
- /// the setting order number. It make easy to calculate the leaving
+ /// Writable bool map that stores for each \c true assigned elements
+ /// the sequence number of this setting.
+ /// It makes it easy to calculate the leaving
/// order of the nodes in the \c Dfs algorithm.
///
///\code
@@ -1447,9 +1575,9 @@
/// }
///\endcode
///
- /// The discovering order can be stored a little harder because the
+ /// The storing of the discovering order is more difficult because the
/// ReachedMap should be readable in the dfs algorithm but the setting
- /// order map is not readable. Now we should use the fork map:
+ /// order map is not readable. Thus we must use the fork map:
///
///\code
/// typedef Graph::NodeMap<int> OrderMap;
@@ -1487,7 +1615,7 @@
return counter;
}
- /// Setter function of the map
+ /// The \c set function of the map
void set(const Key& key, Value value) {
if (value) {
map.set(key, counter++);
More information about the Lemon-commits
mailing list