gravatar
alpar (Alpar Juttner)
alpar@cs.elte.hu
Several doc improvements in maps.h
0 2 0
default
2 files changed with 53 insertions and 51 deletions:
↑ Collapse diff ↑
Ignore white space 6 line context
... ...
@@ -16,10 +16,10 @@
16 16
 *
17 17
 */
18 18

	
19
// Modified for use in LEMON.
20
// We should really consider using Boost...
19
// This file contains a modified version of the concept checking
20
// utility from BOOST.
21
// See the appropriate copyright notice below.
21 22

	
22
//
23 23
// (C) Copyright Jeremy Siek 2000.
24 24
// Distributed under the Boost Software License, Version 1.0. (See
25 25
// accompanying file LICENSE_1_0.txt or copy at
Ignore white space 6 line context
... ...
@@ -247,7 +247,9 @@
247 247
  /// The current map has the \c [0..size-1] keyset and the values
248 248
  /// are stored in a \c std::vector<T>  container. It can be used with
249 249
  /// some data structures, for example \c UnionFind, \c BinHeap, when 
250
  /// the used items are small integer numbers.
250
  /// the used items are small integer numbers. 
251
  ///
252
  /// \todo Revise its name
251 253
  template <typename T>
252 254
  class IntegerMap {
253 255

	
... ...
@@ -346,8 +348,9 @@
346 348
  }
347 349
  
348 350

	
349
  ///Convert the \c Value of a map to another type.
350

	
351
  ///\brief Convert the \c Value of a map to another type using
352
  ///the default conversion.
353
  ///
351 354
  ///This \c concepts::ReadMap "read only map"
352 355
  ///converts the \c Value of a maps to type \c T.
353 356
  ///Its \c Key is inherited from \c M.
... ...
@@ -368,8 +371,6 @@
368 371
    /// \brief The subscript operator.
369 372
    ///
370 373
    /// The subscript operator.
371
    /// \param k The key
372
    /// \return The target of the arc 
373 374
    Value operator[](const Key& k) const {return m[k];}
374 375
  };
375 376
  
... ...
@@ -388,6 +389,8 @@
388 389
  ///wrapping of the given map. Sometimes the reference maps cannot be
389 390
  ///combined with simple read maps. This map adaptor wraps the given
390 391
  ///map to simple read map.
392
  ///
393
  /// \todo Revise the misleading name
391 394
  template<typename M> 
392 395
  class SimpleMap : public MapBase<typename M::Key, typename M::Value> {
393 396
    const M& m;
... ...
@@ -405,10 +408,12 @@
405 408

	
406 409
  ///Simple writeable wrapping of the map
407 410

	
408
  ///This \c concepts::ReadMap "read only map" returns the simple
411
  ///This \c concepts::WriteMap "write map" returns the simple
409 412
  ///wrapping of the given map. Sometimes the reference maps cannot be
410 413
  ///combined with simple read-write maps. This map adaptor wraps the
411 414
  ///given map to simple read-write map.
415
  ///
416
  /// \todo Revise the misleading name
412 417
  template<typename M> 
413 418
  class SimpleWriteMap : public MapBase<typename M::Key, typename M::Value> {
414 419
    M& m;
... ...
@@ -493,7 +498,7 @@
493 498
    Value operator[](Key k) const {return m[k] + v;}
494 499
  };
495 500

	
496
  ///Shift a map with a constant.
501
  ///Shift a map with a constant. This map is also writable.
497 502

	
498 503
  ///This \c concepts::ReadWriteMap "read-write map" returns the sum of the
499 504
  ///given map and a constant value. It makes also possible to write the map.
... ...
@@ -549,7 +554,8 @@
549 554
  ///of the values of the two
550 555
  ///given maps. Its \c Key and \c Value will be inherited from \c M1.
551 556
  ///The \c Key and \c Value of \c M2 must be convertible to those of \c M1.
552

	
557
  ///
558
  /// \todo Revise the misleading name
553 559
  template<typename M1, typename M2> 
554 560
  class SubMap : public MapBase<typename M1::Key, typename M1::Value> {
555 561
    const M1& m1;
... ...
@@ -641,7 +647,7 @@
641 647
    Value operator[](Key k) const {return v * m[k];}
642 648
  };
643 649

	
644
  ///Scales a maps with a constant.
650
  ///Scales a maps with a constant (ReadWrite version).
645 651

	
646 652
  ///This \c concepts::ReadWriteMap "read-write map" returns the value of the
647 653
  ///given map multiplied from the left side with a constant value. It can
... ...
@@ -858,7 +864,7 @@
858 864
    Value operator[](Key k) const {return -m[k];}
859 865
  };
860 866
  
861
  ///Negative value of a map
867
  ///Negative value of a map (ReadWrite version)
862 868

	
863 869
  ///This \c concepts::ReadWriteMap "read-write map" returns the negative
864 870
  ///value of the value returned by the
... ...
@@ -905,18 +911,6 @@
905 911
  ///must be comparable to <tt>0</tt> and the unary <tt>-</tt>
906 912
  ///operator must be defined for it, of course.
907 913
  ///
908
  ///\bug We need a unified way to handle the situation below:
909
  ///\code
910
  ///  struct _UnConvertible {};
911
  ///  template<class A> inline A t_abs(A a) {return _UnConvertible();}
912
  ///  template<> inline int t_abs<>(int n) {return abs(n);}
913
  ///  template<> inline long int t_abs<>(long int n) {return labs(n);}
914
  ///  template<> inline long long int t_abs<>(long long int n) {return ::llabs(n);}
915
  ///  template<> inline float t_abs<>(float n) {return fabsf(n);}
916
  ///  template<> inline double t_abs<>(double n) {return fabs(n);}
917
  ///  template<> inline long double t_abs<>(long double n) {return fabsl(n);}
918
  ///\endcode
919
  
920 914

	
921 915
  template<typename M> 
922 916
  class AbsMap : public MapBase<typename M::Key, typename M::Value> {
... ...
@@ -1041,6 +1035,8 @@
1041 1035
  ///
1042 1036
  ///The \c Key and \c Value will be inherited from \c M1.
1043 1037
  ///The \c Key and \c Value of M2 must be convertible from those of \c M1.
1038
  ///
1039
  /// \todo Why is it needed?
1044 1040
  template<typename  M1, typename M2> 
1045 1041
  class ForkMap : public MapBase<typename M1::Key, typename M1::Value> {
1046 1042
    const M1& m1;
... ...
@@ -1124,7 +1120,7 @@
1124 1120
    Value operator[](Key k) const {return !m[k];}
1125 1121
  };
1126 1122

	
1127
  ///Logical 'not' of a map with writing possibility
1123
  ///Logical 'not' of a map (ReadWrie version)
1128 1124
  
1129 1125
  ///This bool \c concepts::ReadWriteMap "read-write map" returns the 
1130 1126
  ///logical negation of value returned by the given map. When it is set,
... ...
@@ -1187,15 +1183,16 @@
1187 1183
  }
1188 1184
  
1189 1185

	
1190
  /// \brief Writable bool map for store each true assigned elements.
1186
  /// \brief Writable bool map for logging each true assigned elements
1191 1187
  ///
1192
  /// Writable bool map to store each true assigned elements. It will
1188
  /// Writable bool map for logging each true assigned elements, i.e it
1193 1189
  /// copies all the keys set to true to the given iterator.
1194 1190
  ///
1195 1191
  /// \note The container of the iterator should contain space 
1196 1192
  /// for each element.
1197 1193
  ///
1198
  /// The next example shows how can you write the nodes directly
1194
  /// The following example shows how you can write the edges found by the Prim
1195
  /// algorithm directly
1199 1196
  /// to the standard output.
1200 1197
  ///\code
1201 1198
  /// typedef IdMap<Graph, Edge> EdgeIdMap;
... ...
@@ -1209,6 +1206,8 @@
1209 1206
  ///
1210 1207
  /// prim(graph, cost, writerMap);
1211 1208
  ///\endcode
1209
  ///
1210
  ///\todo Revise the name of this class and the relates ones.
1212 1211
  template <typename _Iterator, 
1213 1212
            typename _Functor =
1214 1213
            _maps_bits::Identity<typename _maps_bits::
... ...
@@ -1226,12 +1225,12 @@
1226 1225
    StoreBoolMap(Iterator it, const Functor& functor = Functor()) 
1227 1226
      : _begin(it), _end(it), _functor(functor) {}
1228 1227

	
1229
    /// Gives back the given iterator set for the first time.
1228
    /// Gives back the given iterator set for the first key
1230 1229
    Iterator begin() const {
1231 1230
      return _begin;
1232 1231
    }
1233 1232
 
1234
    /// Gives back the iterator after the last set operation.
1233
    /// Gives back the the 'after the last' iterator
1235 1234
    Iterator end() const {
1236 1235
      return _end;
1237 1236
    }
... ...
@@ -1249,14 +1248,14 @@
1249 1248
    Functor _functor;
1250 1249
  };
1251 1250

	
1252
  /// \brief Writable bool map for store each true assigned elements in 
1253
  /// a back insertable container.
1251
  /// \brief Writable bool map for logging each true assigned elements in 
1252
  /// a back insertable container
1254 1253
  ///
1255
  /// Writable bool map for store each true assigned elements in a back 
1256
  /// insertable container. It will push back all the keys set to true into
1257
  /// the container. It can be used to retrieve the items into a standard
1258
  /// container. The next example shows how can you store the undirected
1259
  /// arcs in a vector with prim algorithm.
1254
  /// Writable bool map for logging each true assigned elements by pushing
1255
  /// back them into a back insertable container.
1256
  /// It can be used to retrieve the items into a standard
1257
  /// container. The next example shows how you can store the
1258
  /// edges found by the Prim algorithm in a vector.
1260 1259
  ///
1261 1260
  ///\code
1262 1261
  /// vector<Edge> span_tree_edges;
... ...
@@ -1288,10 +1287,10 @@
1288 1287
    Functor functor;
1289 1288
  };
1290 1289

	
1291
  /// \brief Writable bool map for store each true assigned elements in 
1290
  /// \brief Writable bool map for storing each true assignments in 
1292 1291
  /// a front insertable container.
1293 1292
  ///
1294
  /// Writable bool map for store each true assigned elements in a front 
1293
  /// Writable bool map for storing each true assignment in a front 
1295 1294
  /// insertable container. It will push front all the keys set to \c true into
1296 1295
  /// the container. For example see the BackInserterBoolMap.
1297 1296
  template <typename Container,
... ...
@@ -1319,12 +1318,14 @@
1319 1318
    Functor functor;
1320 1319
  };
1321 1320

	
1322
  /// \brief Writable bool map for store each true assigned elements in 
1321
  /// \brief Writable bool map for storing each true assigned elements in 
1323 1322
  /// an insertable container.
1324 1323
  ///
1325
  /// Writable bool map for store each true assigned elements in an 
1324
  /// Writable bool map for storing each true assigned elements in an 
1326 1325
  /// insertable container. It will insert all the keys set to \c true into
1327
  /// the container. If you want to store the cut arcs of the strongly
1326
  /// the container.
1327
  ///
1328
  /// For example, if you want to store the cut arcs of the strongly
1328 1329
  /// connected components in a set you can use the next code:
1329 1330
  ///
1330 1331
  ///\code
... ...
@@ -1369,7 +1370,7 @@
1369 1370
  /// The value can set 
1370 1371
  /// the container.
1371 1372
  ///
1372
  /// The next code finds the connected components of the undirected digraph
1373
  /// The following code finds the connected components of a graph
1373 1374
  /// and stores it in the \c comp map:
1374 1375
  ///\code
1375 1376
  /// typedef Graph::NodeMap<int> ComponentMap;
... ...
@@ -1417,7 +1418,7 @@
1417 1418
      fill = _fill;
1418 1419
    } 
1419 1420

	
1420
    /// Setter function of the map
1421
    /// Set function of the map
1421 1422
    void set(const Key& key, Value value) {
1422 1423
      if (value) {
1423 1424
	map.set(key, fill);
... ...
@@ -1430,11 +1431,12 @@
1430 1431
  };
1431 1432

	
1432 1433

	
1433
  /// \brief Writable bool map which stores for each true assigned elements  
1434
  /// the setting order number.
1435
  ///
1434
  /// \brief Writable bool map which stores the sequence number of 
1435
  /// true assignments.  
1436
  /// 
1436 1437
  /// Writable bool map which stores for each true assigned elements  
1437
  /// the setting order number. It make easy to calculate the leaving
1438
  /// the sequence number of this setting.
1439
  /// It makes it easy to calculate the leaving
1438 1440
  /// order of the nodes in the \c Dfs algorithm.
1439 1441
  ///
1440 1442
  ///\code
... ...
@@ -1453,9 +1455,9 @@
1453 1455
  /// }
1454 1456
  ///\endcode
1455 1457
  ///
1456
  /// The discovering order can be stored a little harder because the
1458
  /// The storing of the discovering order is more difficult because the
1457 1459
  /// ReachedMap should be readable in the dfs algorithm but the setting
1458
  /// order map is not readable. Now we should use the fork map:
1460
  /// order map is not readable. Thus we must use the fork map:
1459 1461
  ///
1460 1462
  ///\code
1461 1463
  /// typedef Digraph::NodeMap<int> OrderMap;
0 comments (0 inline)