1.1 --- a/lemon/maps.h Sat Dec 22 12:35:00 2007 +0000
1.2 +++ b/lemon/maps.h Sat Dec 22 14:04:22 2007 +0000
1.3 @@ -247,7 +247,9 @@
1.4 /// The current map has the \c [0..size-1] keyset and the values
1.5 /// are stored in a \c std::vector<T> container. It can be used with
1.6 /// some data structures, for example \c UnionFind, \c BinHeap, when
1.7 - /// the used items are small integer numbers.
1.8 + /// the used items are small integer numbers.
1.9 + ///
1.10 + /// \todo Revise its name
1.11 template <typename T>
1.12 class IntegerMap {
1.13
1.14 @@ -346,8 +348,9 @@
1.15 }
1.16
1.17
1.18 - ///Convert the \c Value of a map to another type.
1.19 -
1.20 + ///\brief Convert the \c Value of a map to another type using
1.21 + ///the default conversion.
1.22 + ///
1.23 ///This \c concepts::ReadMap "read only map"
1.24 ///converts the \c Value of a maps to type \c T.
1.25 ///Its \c Key is inherited from \c M.
1.26 @@ -368,8 +371,6 @@
1.27 /// \brief The subscript operator.
1.28 ///
1.29 /// The subscript operator.
1.30 - /// \param k The key
1.31 - /// \return The target of the arc
1.32 Value operator[](const Key& k) const {return m[k];}
1.33 };
1.34
1.35 @@ -388,6 +389,8 @@
1.36 ///wrapping of the given map. Sometimes the reference maps cannot be
1.37 ///combined with simple read maps. This map adaptor wraps the given
1.38 ///map to simple read map.
1.39 + ///
1.40 + /// \todo Revise the misleading name
1.41 template<typename M>
1.42 class SimpleMap : public MapBase<typename M::Key, typename M::Value> {
1.43 const M& m;
1.44 @@ -405,10 +408,12 @@
1.45
1.46 ///Simple writeable wrapping of the map
1.47
1.48 - ///This \c concepts::ReadMap "read only map" returns the simple
1.49 + ///This \c concepts::WriteMap "write map" returns the simple
1.50 ///wrapping of the given map. Sometimes the reference maps cannot be
1.51 ///combined with simple read-write maps. This map adaptor wraps the
1.52 ///given map to simple read-write map.
1.53 + ///
1.54 + /// \todo Revise the misleading name
1.55 template<typename M>
1.56 class SimpleWriteMap : public MapBase<typename M::Key, typename M::Value> {
1.57 M& m;
1.58 @@ -493,7 +498,7 @@
1.59 Value operator[](Key k) const {return m[k] + v;}
1.60 };
1.61
1.62 - ///Shift a map with a constant.
1.63 + ///Shift a map with a constant. This map is also writable.
1.64
1.65 ///This \c concepts::ReadWriteMap "read-write map" returns the sum of the
1.66 ///given map and a constant value. It makes also possible to write the map.
1.67 @@ -549,7 +554,8 @@
1.68 ///of the values of the two
1.69 ///given maps. Its \c Key and \c Value will be inherited from \c M1.
1.70 ///The \c Key and \c Value of \c M2 must be convertible to those of \c M1.
1.71 -
1.72 + ///
1.73 + /// \todo Revise the misleading name
1.74 template<typename M1, typename M2>
1.75 class SubMap : public MapBase<typename M1::Key, typename M1::Value> {
1.76 const M1& m1;
1.77 @@ -641,7 +647,7 @@
1.78 Value operator[](Key k) const {return v * m[k];}
1.79 };
1.80
1.81 - ///Scales a maps with a constant.
1.82 + ///Scales a maps with a constant (ReadWrite version).
1.83
1.84 ///This \c concepts::ReadWriteMap "read-write map" returns the value of the
1.85 ///given map multiplied from the left side with a constant value. It can
1.86 @@ -858,7 +864,7 @@
1.87 Value operator[](Key k) const {return -m[k];}
1.88 };
1.89
1.90 - ///Negative value of a map
1.91 + ///Negative value of a map (ReadWrite version)
1.92
1.93 ///This \c concepts::ReadWriteMap "read-write map" returns the negative
1.94 ///value of the value returned by the
1.95 @@ -905,18 +911,6 @@
1.96 ///must be comparable to <tt>0</tt> and the unary <tt>-</tt>
1.97 ///operator must be defined for it, of course.
1.98 ///
1.99 - ///\bug We need a unified way to handle the situation below:
1.100 - ///\code
1.101 - /// struct _UnConvertible {};
1.102 - /// template<class A> inline A t_abs(A a) {return _UnConvertible();}
1.103 - /// template<> inline int t_abs<>(int n) {return abs(n);}
1.104 - /// template<> inline long int t_abs<>(long int n) {return labs(n);}
1.105 - /// template<> inline long long int t_abs<>(long long int n) {return ::llabs(n);}
1.106 - /// template<> inline float t_abs<>(float n) {return fabsf(n);}
1.107 - /// template<> inline double t_abs<>(double n) {return fabs(n);}
1.108 - /// template<> inline long double t_abs<>(long double n) {return fabsl(n);}
1.109 - ///\endcode
1.110 -
1.111
1.112 template<typename M>
1.113 class AbsMap : public MapBase<typename M::Key, typename M::Value> {
1.114 @@ -1041,6 +1035,8 @@
1.115 ///
1.116 ///The \c Key and \c Value will be inherited from \c M1.
1.117 ///The \c Key and \c Value of M2 must be convertible from those of \c M1.
1.118 + ///
1.119 + /// \todo Why is it needed?
1.120 template<typename M1, typename M2>
1.121 class ForkMap : public MapBase<typename M1::Key, typename M1::Value> {
1.122 const M1& m1;
1.123 @@ -1124,7 +1120,7 @@
1.124 Value operator[](Key k) const {return !m[k];}
1.125 };
1.126
1.127 - ///Logical 'not' of a map with writing possibility
1.128 + ///Logical 'not' of a map (ReadWrie version)
1.129
1.130 ///This bool \c concepts::ReadWriteMap "read-write map" returns the
1.131 ///logical negation of value returned by the given map. When it is set,
1.132 @@ -1187,15 +1183,16 @@
1.133 }
1.134
1.135
1.136 - /// \brief Writable bool map for store each true assigned elements.
1.137 + /// \brief Writable bool map for logging each true assigned elements
1.138 ///
1.139 - /// Writable bool map to store each true assigned elements. It will
1.140 + /// Writable bool map for logging each true assigned elements, i.e it
1.141 /// copies all the keys set to true to the given iterator.
1.142 ///
1.143 /// \note The container of the iterator should contain space
1.144 /// for each element.
1.145 ///
1.146 - /// The next example shows how can you write the nodes directly
1.147 + /// The following example shows how you can write the edges found by the Prim
1.148 + /// algorithm directly
1.149 /// to the standard output.
1.150 ///\code
1.151 /// typedef IdMap<Graph, Edge> EdgeIdMap;
1.152 @@ -1209,6 +1206,8 @@
1.153 ///
1.154 /// prim(graph, cost, writerMap);
1.155 ///\endcode
1.156 + ///
1.157 + ///\todo Revise the name of this class and the relates ones.
1.158 template <typename _Iterator,
1.159 typename _Functor =
1.160 _maps_bits::Identity<typename _maps_bits::
1.161 @@ -1226,12 +1225,12 @@
1.162 StoreBoolMap(Iterator it, const Functor& functor = Functor())
1.163 : _begin(it), _end(it), _functor(functor) {}
1.164
1.165 - /// Gives back the given iterator set for the first time.
1.166 + /// Gives back the given iterator set for the first key
1.167 Iterator begin() const {
1.168 return _begin;
1.169 }
1.170
1.171 - /// Gives back the iterator after the last set operation.
1.172 + /// Gives back the the 'after the last' iterator
1.173 Iterator end() const {
1.174 return _end;
1.175 }
1.176 @@ -1249,14 +1248,14 @@
1.177 Functor _functor;
1.178 };
1.179
1.180 - /// \brief Writable bool map for store each true assigned elements in
1.181 - /// a back insertable container.
1.182 + /// \brief Writable bool map for logging each true assigned elements in
1.183 + /// a back insertable container
1.184 ///
1.185 - /// Writable bool map for store each true assigned elements in a back
1.186 - /// insertable container. It will push back all the keys set to true into
1.187 - /// the container. It can be used to retrieve the items into a standard
1.188 - /// container. The next example shows how can you store the undirected
1.189 - /// arcs in a vector with prim algorithm.
1.190 + /// Writable bool map for logging each true assigned elements by pushing
1.191 + /// back them into a back insertable container.
1.192 + /// It can be used to retrieve the items into a standard
1.193 + /// container. The next example shows how you can store the
1.194 + /// edges found by the Prim algorithm in a vector.
1.195 ///
1.196 ///\code
1.197 /// vector<Edge> span_tree_edges;
1.198 @@ -1288,10 +1287,10 @@
1.199 Functor functor;
1.200 };
1.201
1.202 - /// \brief Writable bool map for store each true assigned elements in
1.203 + /// \brief Writable bool map for storing each true assignments in
1.204 /// a front insertable container.
1.205 ///
1.206 - /// Writable bool map for store each true assigned elements in a front
1.207 + /// Writable bool map for storing each true assignment in a front
1.208 /// insertable container. It will push front all the keys set to \c true into
1.209 /// the container. For example see the BackInserterBoolMap.
1.210 template <typename Container,
1.211 @@ -1319,12 +1318,14 @@
1.212 Functor functor;
1.213 };
1.214
1.215 - /// \brief Writable bool map for store each true assigned elements in
1.216 + /// \brief Writable bool map for storing each true assigned elements in
1.217 /// an insertable container.
1.218 ///
1.219 - /// Writable bool map for store each true assigned elements in an
1.220 + /// Writable bool map for storing each true assigned elements in an
1.221 /// insertable container. It will insert all the keys set to \c true into
1.222 - /// the container. If you want to store the cut arcs of the strongly
1.223 + /// the container.
1.224 + ///
1.225 + /// For example, if you want to store the cut arcs of the strongly
1.226 /// connected components in a set you can use the next code:
1.227 ///
1.228 ///\code
1.229 @@ -1369,7 +1370,7 @@
1.230 /// The value can set
1.231 /// the container.
1.232 ///
1.233 - /// The next code finds the connected components of the undirected digraph
1.234 + /// The following code finds the connected components of a graph
1.235 /// and stores it in the \c comp map:
1.236 ///\code
1.237 /// typedef Graph::NodeMap<int> ComponentMap;
1.238 @@ -1417,7 +1418,7 @@
1.239 fill = _fill;
1.240 }
1.241
1.242 - /// Setter function of the map
1.243 + /// Set function of the map
1.244 void set(const Key& key, Value value) {
1.245 if (value) {
1.246 map.set(key, fill);
1.247 @@ -1430,11 +1431,12 @@
1.248 };
1.249
1.250
1.251 - /// \brief Writable bool map which stores for each true assigned elements
1.252 - /// the setting order number.
1.253 - ///
1.254 + /// \brief Writable bool map which stores the sequence number of
1.255 + /// true assignments.
1.256 + ///
1.257 /// Writable bool map which stores for each true assigned elements
1.258 - /// the setting order number. It make easy to calculate the leaving
1.259 + /// the sequence number of this setting.
1.260 + /// It makes it easy to calculate the leaving
1.261 /// order of the nodes in the \c Dfs algorithm.
1.262 ///
1.263 ///\code
1.264 @@ -1453,9 +1455,9 @@
1.265 /// }
1.266 ///\endcode
1.267 ///
1.268 - /// The discovering order can be stored a little harder because the
1.269 + /// The storing of the discovering order is more difficult because the
1.270 /// ReachedMap should be readable in the dfs algorithm but the setting
1.271 - /// order map is not readable. Now we should use the fork map:
1.272 + /// order map is not readable. Thus we must use the fork map:
1.273 ///
1.274 ///\code
1.275 /// typedef Digraph::NodeMap<int> OrderMap;