lemon: comparison lemon/maps.h

equal deleted inserted replaced

-:a78a92aed4d0
+:6d86b5fda027
 /// \brief Map for storing values for the range \c [0..size-1] range keys
 ///
 /// The current map has the \c [0..size-1] 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.
+///
+/// \todo Revise its name
 template <typename T>
 class IntegerMap {
 template <typename T1>
 friend class IntegerMap;
 inline IdentityMap<T> identityMap() {
 return IdentityMap<T>();
 }
-///Convert the \c Value of a map to another type.
+///\brief Convert the \c Value of a map to another type using
+///the default conversion.
+///
 ///This \c concepts::ReadMap "read only map"
 ///converts the \c Value of a maps 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> {
 ConvertMap(const M &_m) : m(_m) {};
 /// \brief The subscript operator.
 ///
 /// The subscript operator.
-/// \param k The key
-/// \return The target of the arc
 Value operator[](const Key& k) const {return m[k];}
 };
 ///Returns an \c ConvertMap class
 ///This \c 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.
+///
+/// \todo Revise the misleading name
 template<typename M>
 class SimpleMap : public MapBase<typename M::Key, typename M::Value> {
 const M& m;
 public:
 Value operator[](Key k) const {return m[k];}
 };
 ///Simple writeable wrapping of the map
-///This \c concepts::ReadMap "read only map" returns the simple
+///This \c concepts::WriteMap "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.
+///
+/// \todo Revise the misleading name
 template<typename M>
 class SimpleWriteMap : public MapBase<typename M::Key, typename M::Value> {
 M& m;
 public:
 ShiftMap(const M &_m, const C &_v ) : m(_m), v(_v) {};
 ///\e
 Value operator[](Key k) const {return m[k] + v;}
 };
-///Shift a map with a constant.
+///Shift a map with a constant. This map is also writable.
 ///This \c 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.
 ///
 ///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.
 ///The \c Key and \c Value of \c M2 must be convertible to those of \c M1.
+///
+/// \todo Revise the misleading name
 template<typename M1, typename M2>
 class SubMap : public MapBase<typename M1::Key, typename M1::Value> {
 const M1& m1;
 const M2& m2;
 public:
 ScaleMap(const M &_m, const C &_v ) : m(_m), v(_v) {};
 /// \e
 Value operator[](Key k) const {return v * m[k];}
 };
-///Scales a maps with a constant.
+///Scales a maps with a constant (ReadWrite version).
 ///This \c 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.
 NegMap(const M &_m) : m(_m) {};
 /// \e
 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.
 ///The unary \c - operator must be defined for \c Value, of course.
 ///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>
 ///operator must be defined for it, of course.
 ///
-///\bug We need a unified way to handle the situation below:
-///\code
-///  struct _UnConvertible {};
-///  template<class A> inline A t_abs(A a) {return _UnConvertible();}
-///  template<> inline int t_abs<>(int n) {return abs(n);}
-///  template<> inline long int t_abs<>(long int n) {return labs(n);}
-///  template<> inline long long int t_abs<>(long long int n) {return ::llabs(n);}
-///  template<> inline float t_abs<>(float n) {return fabsf(n);}
-///  template<> inline double t_abs<>(double n) {return fabs(n);}
-///  template<> inline long double t_abs<>(long double n) {return fabsl(n);}
-///\endcode
 template<typename M>
 class AbsMap : public MapBase<typename M::Key, typename M::Value> {
 const M& m;
 public:
 ///parameters and each read request will be passed just to the
 ///first map. This class is the just readable map type of the 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.
+///
+/// \todo Why is it needed?
 template<typename  M1, typename M2>
 class ForkMap : public MapBase<typename M1::Key, typename M1::Value> {
 const M1& m1;
 const M2& m2;
 public:
 NotMap(const M &_m) : m(_m) {};
 ///\e
 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,
 ///the opposite value is set to the original map.
 ///Its \c Key and will be inherited from \c M,
 };
 }
-/// \brief Writable bool map for store each true assigned elements.
+/// \brief Writable bool map for logging each true assigned elements
 ///
-/// Writable bool map to store each true assigned elements. It will
+/// Writable bool map for logging each true assigned elements, i.e it
 /// copies all the keys set to 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
+/// The following example shows how you can write the edges found by the Prim
+/// algorithm directly
 /// to the standard output.
 ///\code
 /// typedef IdMap<Graph, Edge> EdgeIdMap;
 /// EdgeIdMap edgeId(graph);
 ///
 /// StoreBoolMap<ostream_iterator<int>, EdgeIdFunctor>
 ///   writerMap(ostream_iterator<int>(cout, " "), edgeIdFunctor);
 ///
 /// prim(graph, cost, writerMap);
 ///\endcode
+///
+///\todo Revise the name of this class and the relates ones.
 template <typename _Iterator,
 typename _Functor =
 _maps_bits::Identity<typename _maps_bits::
 IteratorTraits<_Iterator>::Value> >
 class StoreBoolMap {
 /// Constructor
 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
 Iterator _begin;
 mutable Iterator _end;
 Functor _functor;
 };
-/// \brief Writable bool map for store each true assigned elements in
+/// \brief Writable bool map for logging each true assigned elements in
-/// a back insertable container.
+/// a back insertable container
 ///
-/// Writable bool map for store each true assigned elements in a back
+/// Writable bool map for logging each true assigned elements by pushing
-/// insertable container. It will push back all the keys set to true into
+/// back them into a back insertable container.
-/// the container. It can be used to retrieve the items into a standard
+/// It can be used to retrieve the items into a standard
-/// container. The next example shows how can you store the undirected
+/// container. The next example shows how you can store the
-/// arcs in a vector with prim algorithm.
+/// edges found by the Prim algorithm in a vector.
 ///
 ///\code
 /// vector<Edge> span_tree_edges;
 /// BackInserterBoolMap<vector<Edge> > inserter_map(span_tree_edges);
 /// prim(graph, cost, inserter_map);
 private:
 Container& container;
 Functor functor;
 };
-/// \brief Writable bool map for store each true assigned elements in
+/// \brief Writable bool map for storing each true assignments in
 /// a front insertable container.
 ///
-/// Writable bool map for store each true assigned elements in a front
+/// Writable bool map for storing each true assignment in a front
 /// insertable container. It will push front all the keys set to \c true into
 /// the container. For example see the BackInserterBoolMap.
 template <typename Container,
 typename Functor =
 _maps_bits::Identity<typename Container::value_type> >
 private:
 Container& container;
 Functor functor;
 };
-/// \brief Writable bool map for store each true assigned elements in
+/// \brief Writable bool map for storing each true assigned elements in
 /// an insertable container.
 ///
-/// Writable bool map for store each true assigned elements in an
+/// Writable bool map for storing each true assigned elements in an
 /// insertable container. It will insert all the keys set to \c true into
-/// the container. If you want to store the cut arcs 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
 /// set<Arc> cut_arcs;
 /// InserterBoolMap<set<Arc> > inserter_map(cut_arcs);
 ///
 /// Writable bool map to fill the elements set to \c true with a given value.
 /// The value can set
 /// the container.
 ///
-/// The next code finds the connected components of the undirected digraph
+/// The following code finds the connected components of a graph
 /// and stores it in the \c comp map:
 ///\code
 /// typedef Graph::NodeMap<int> ComponentMap;
 /// ComponentMap comp(graph);
 /// typedef FillBoolMap<Graph::NodeMap<int> > ComponentFillerMap;
 /// Sets the current fill value
 void fillValue(const typename Map::Value& _fill) {
 fill = _fill;
 }
-/// Setter function of the map
+/// Set function of the map
 void set(const Key& key, Value value) {
 if (value) {
 	map.set(key, fill);
 }
 }
 Map& map;
 typename Map::Value fill;
 };
-/// \brief Writable bool map which stores for each true assigned elements
+/// \brief Writable bool map which stores the sequence number of
-/// the setting order number.
+/// true assignments.
 ///
 /// Writable bool map which stores for each true assigned elements
-/// the setting order number. It make easy to calculate the leaving
+/// the sequence number of this setting.
+/// It makes it easy to calculate the leaving
 /// order of the nodes in the \c Dfs algorithm.
 ///
 ///\code
 /// typedef Digraph::NodeMap<int> OrderMap;
 /// OrderMap order(digraph);
 ///     dfs.start();
 ///   }
 /// }
 ///\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 Digraph::NodeMap<int> OrderMap;
 /// OrderMap order(digraph);
 /// typedef SettingOrderBoolMap<OrderMap> OrderSetterMap;

changeset 27	6724953f2f44
parent 25	751cd8f9bb1c
child 29	0cb4ba427bfd