gravatar
kpeter (Peter Kovacs)
kpeter@inf.elte.hu
Doc improvements for several graph maps (#302)
0 1 0
default
1 file changed with 76 insertions and 40 deletions:
↑ Collapse diff ↑
Ignore white space 6 line context
... ...
@@ -56,7 +56,7 @@
56 56
  /// its type definitions, or if you have to provide a writable map,
57 57
  /// but data written to it is not required (i.e. it will be sent to
58 58
  /// <tt>/dev/null</tt>).
59
  /// It conforms the \ref concepts::ReadWriteMap "ReadWriteMap" concept.
59
  /// It conforms to the \ref concepts::ReadWriteMap "ReadWriteMap" concept.
60 60
  ///
61 61
  /// \sa ConstMap
62 62
  template<typename K, typename V>
... ...
@@ -89,7 +89,7 @@
89 89
  /// value to each key.
90 90
  ///
91 91
  /// In other aspects it is equivalent to \c NullMap.
92
  /// So it conforms the \ref concepts::ReadWriteMap "ReadWriteMap"
92
  /// So it conforms to the \ref concepts::ReadWriteMap "ReadWriteMap"
93 93
  /// concept, but it absorbs the data written to it.
94 94
  ///
95 95
  /// The simplest way of using this map is through the constMap()
... ...
@@ -158,7 +158,7 @@
158 158
  /// value to each key.
159 159
  ///
160 160
  /// In other aspects it is equivalent to \c NullMap.
161
  /// So it conforms the \ref concepts::ReadWriteMap "ReadWriteMap"
161
  /// So it conforms to the \ref concepts::ReadWriteMap "ReadWriteMap"
162 162
  /// concept, but it absorbs the data written to it.
163 163
  ///
164 164
  /// The simplest way of using this map is through the constMap()
... ...
@@ -232,7 +232,7 @@
232 232
  /// values to integer keys from the range <tt>[0..size-1]</tt>.
233 233
  /// It can be used with some data structures, for example
234 234
  /// \c UnionFind, \c BinHeap, when the used items are small
235
  /// integers. This map conforms the \ref concepts::ReferenceMap
235
  /// integers. This map conforms to the \ref concepts::ReferenceMap
236 236
  /// "ReferenceMap" concept.
237 237
  ///
238 238
  /// The simplest way of using this map is through the rangeMap()
... ...
@@ -340,7 +340,7 @@
340 340
  /// that you can specify a default value for the keys that are not
341 341
  /// stored actually. This value can be different from the default
342 342
  /// contructed value (i.e. \c %Value()).
343
  /// This type conforms the \ref concepts::ReferenceMap "ReferenceMap"
343
  /// This type conforms to the \ref concepts::ReferenceMap "ReferenceMap"
344 344
  /// concept.
345 345
  ///
346 346
  /// This map is useful if a default value should be assigned to most of
... ...
@@ -706,7 +706,7 @@
706 706
  /// "readable map" to another type using the default conversion.
707 707
  /// The \c Key type of it is inherited from \c M and the \c Value
708 708
  /// type is \c V.
709
  /// This type conforms the \ref concepts::ReadMap "ReadMap" concept.
709
  /// This type conforms to the \ref concepts::ReadMap "ReadMap" concept.
710 710
  ///
711 711
  /// The simplest way of using this map is through the convertMap()
712 712
  /// function.
... ...
@@ -1865,9 +1865,11 @@
1865 1865

	
1866 1866
  public:
1867 1867

	
1868
    /// \brief This class represents the inverse of its owner (IdMap).
1868
    /// \brief The inverse map type of IdMap.
1869 1869
    ///
1870
    /// This class represents the inverse of its owner (IdMap).
1870
    /// The inverse map type of IdMap. The subscript operator gives back
1871
    /// an item by its id.
1872
    /// This type conforms to the \ref concepts::ReadMap "ReadMap" concept.
1871 1873
    /// \see inverse()
1872 1874
    class InverseMap {
1873 1875
    public:
... ...
@@ -1882,9 +1884,9 @@
1882 1884
      /// Constructor for creating an id-to-item map.
1883 1885
      explicit InverseMap(const IdMap& map) : _graph(map._graph) {}
1884 1886

	
1885
      /// \brief Gives back the given item from its id.
1887
      /// \brief Gives back an item by its id.
1886 1888
      ///
1887
      /// Gives back the given item from its id.
1889
      /// Gives back an item by its id.
1888 1890
      Item operator[](int id) const { return _graph->fromId(id, Item());}
1889 1891

	
1890 1892
    private:
... ...
@@ -1903,8 +1905,17 @@
1903 1905
  /// This class provides simple invertable graph maps.
1904 1906
  /// It wraps a standard graph map (\c NodeMap, \c ArcMap or \c EdgeMap)
1905 1907
  /// and if a key is set to a new value, then stores it in the inverse map.
1906
  /// The values of the map can be accessed
1907
  /// with stl compatible forward iterator.
1908
  /// The graph items can be accessed by their values either using
1909
  /// \c InverseMap or \c operator()(), and the values of the map can be
1910
  /// accessed with an STL compatible forward iterator (\c ValueIterator).
1911
  /// 
1912
  /// This map is intended to be used when all associated values are
1913
  /// different (the map is actually invertable) or there are only a few
1914
  /// items with the same value.
1915
  /// Otherwise consider to use \c IterableValueMap, which is more 
1916
  /// suitable and more efficient for such cases. It provides iterators
1917
  /// to traverse the items with the same associated value, however
1918
  /// it does not have \c InverseMap.
1908 1919
  ///
1909 1920
  /// This type is not reference map, so it cannot be modified with
1910 1921
  /// the subscript operator.
... ...
@@ -1945,7 +1956,7 @@
1945 1956

	
1946 1957
    /// \brief Forward iterator for values.
1947 1958
    ///
1948
    /// This iterator is an stl compatible forward
1959
    /// This iterator is an STL compatible forward
1949 1960
    /// iterator on the values of the map. The values can
1950 1961
    /// be accessed in the <tt>[beginValue, endValue)</tt> range.
1951 1962
    /// They are considered with multiplicity, so each value is
... ...
@@ -1958,19 +1969,26 @@
1958 1969
        : it(_it) {}
1959 1970
    public:
1960 1971

	
1972
      /// Constructor
1961 1973
      ValueIterator() {}
1962 1974

	
1975
      /// \e
1963 1976
      ValueIterator& operator++() { ++it; return *this; }
1977
      /// \e
1964 1978
      ValueIterator operator++(int) {
1965 1979
        ValueIterator tmp(*this);
1966 1980
        operator++();
1967 1981
        return tmp;
1968 1982
      }
1969 1983

	
1984
      /// \e
1970 1985
      const Value& operator*() const { return it->first; }
1986
      /// \e
1971 1987
      const Value* operator->() const { return &(it->first); }
1972 1988

	
1989
      /// \e
1973 1990
      bool operator==(ValueIterator jt) const { return it == jt.it; }
1991
      /// \e
1974 1992
      bool operator!=(ValueIterator jt) const { return it != jt.it; }
1975 1993

	
1976 1994
    private:
... ...
@@ -1979,7 +1997,7 @@
1979 1997

	
1980 1998
    /// \brief Returns an iterator to the first value.
1981 1999
    ///
1982
    /// Returns an stl compatible iterator to the
2000
    /// Returns an STL compatible iterator to the
1983 2001
    /// first value of the map. The values of the
1984 2002
    /// map can be accessed in the <tt>[beginValue, endValue)</tt>
1985 2003
    /// range.
... ...
@@ -1989,7 +2007,7 @@
1989 2007

	
1990 2008
    /// \brief Returns an iterator after the last value.
1991 2009
    ///
1992
    /// Returns an stl compatible iterator after the
2010
    /// Returns an STL compatible iterator after the
1993 2011
    /// last value of the map. The values of the
1994 2012
    /// map can be accessed in the <tt>[beginValue, endValue)</tt>
1995 2013
    /// range.
... ...
@@ -2090,10 +2108,12 @@
2090 2108

	
2091 2109
  public:
2092 2110

	
2093
    /// \brief The inverse map type.
2111
    /// \brief The inverse map type of CrossRefMap.
2094 2112
    ///
2095
    /// The inverse of this map. The subscript operator of the map
2096
    /// gives back the item that was last assigned to the value.
2113
    /// The inverse map type of CrossRefMap. The subscript operator gives
2114
    /// back an item by its value.
2115
    /// This type conforms to the \ref concepts::ReadMap "ReadMap" concept.
2116
    /// \see inverse()
2097 2117
    class InverseMap {
2098 2118
    public:
2099 2119
      /// \brief Constructor
... ...
@@ -2120,9 +2140,9 @@
2120 2140
      const CrossRefMap& _inverted;
2121 2141
    };
2122 2142

	
2123
    /// \brief It gives back the read-only inverse map.
2143
    /// \brief Gives back the inverse of the map.
2124 2144
    ///
2125
    /// It gives back the read-only inverse map.
2145
    /// Gives back the inverse of the CrossRefMap.
2126 2146
    InverseMap inverse() const {
2127 2147
      return InverseMap(*this);
2128 2148
    }
... ...
@@ -2272,16 +2292,16 @@
2272 2292
      _inv_map[pi] = q;
2273 2293
    }
2274 2294

	
2275
    /// \brief Gives back the \e RangeId of the item
2295
    /// \brief Gives back the \e range \e id of the item
2276 2296
    ///
2277
    /// Gives back the \e RangeId of the item.
2297
    /// Gives back the \e range \e id of the item.
2278 2298
    int operator[](const Item& item) const {
2279 2299
      return Map::operator[](item);
2280 2300
    }
2281 2301

	
2282
    /// \brief Gives back the item belonging to a \e RangeId
2302
    /// \brief Gives back the item belonging to a \e range \e id
2283 2303
    ///
2284
    /// Gives back the item belonging to a \e RangeId.
2304
    /// Gives back the item belonging to the given \e range \e id.
2285 2305
    Item operator()(int id) const {
2286 2306
      return _inv_map[id];
2287 2307
    }
... ...
@@ -2295,7 +2315,9 @@
2295 2315

	
2296 2316
    /// \brief The inverse map type of RangeIdMap.
2297 2317
    ///
2298
    /// The inverse map type of RangeIdMap.
2318
    /// The inverse map type of RangeIdMap. The subscript operator gives
2319
    /// back an item by its \e range \e id.
2320
    /// This type conforms to the \ref concepts::ReadMap "ReadMap" concept.
2299 2321
    class InverseMap {
2300 2322
    public:
2301 2323
      /// \brief Constructor
... ...
@@ -2313,7 +2335,7 @@
2313 2335
      /// \brief Subscript operator.
2314 2336
      ///
2315 2337
      /// Subscript operator. It gives back the item
2316
      /// that the descriptor currently belongs to.
2338
      /// that the given \e range \e id currently belongs to.
2317 2339
      Value operator[](const Key& key) const {
2318 2340
        return _inverted(key);
2319 2341
      }
... ...
@@ -2331,7 +2353,7 @@
2331 2353

	
2332 2354
    /// \brief Gives back the inverse of the map.
2333 2355
    ///
2334
    /// Gives back the inverse of the map.
2356
    /// Gives back the inverse of the RangeIdMap.
2335 2357
    const InverseMap inverse() const {
2336 2358
      return InverseMap(*this);
2337 2359
    }
... ...
@@ -2342,10 +2364,10 @@
2342 2364
  /// This class provides a special graph map type which can store a
2343 2365
  /// \c bool value for graph items (\c Node, \c Arc or \c Edge).
2344 2366
  /// For both \c true and \c false values it is possible to iterate on
2345
  /// the keys.
2367
  /// the keys mapped to the value.
2346 2368
  ///
2347 2369
  /// This type is a reference map, so it can be modified with the
2348
  /// subscription operator.
2370
  /// subscript operator.
2349 2371
  ///
2350 2372
  /// \tparam GR The graph type.
2351 2373
  /// \tparam K The key type of the map (\c GR::Node, \c GR::Arc or
... ...
@@ -2711,8 +2733,13 @@
2711 2733
  /// For each non-negative value it is possible to iterate on the keys
2712 2734
  /// mapped to the value.
2713 2735
  ///
2736
  /// This map is intended to be used with small integer values, for which
2737
  /// it is efficient, and supports iteration only for non-negative values.
2738
  /// If you need large values and/or iteration for negative integers,
2739
  /// consider to use \ref IterableValueMap instead.
2740
  ///
2714 2741
  /// This type is a reference map, so it can be modified with the
2715
  /// subscription operator.
2742
  /// subscript operator.
2716 2743
  ///
2717 2744
  /// \note The size of the data structure depends on the largest
2718 2745
  /// value in the map.
... ...
@@ -2992,18 +3019,20 @@
2992 3019

	
2993 3020
  /// \brief Dynamic iterable map for comparable values.
2994 3021
  ///
2995
  /// This class provides a special graph map type which can store an
3022
  /// This class provides a special graph map type which can store a
2996 3023
  /// comparable value for graph items (\c Node, \c Arc or \c Edge).
2997 3024
  /// For each value it is possible to iterate on the keys mapped to
2998
  /// the value.
3025
  /// the value (\c ItemIt), and the values of the map can be accessed
3026
  /// with an STL compatible forward iterator (\c ValueIterator).
3027
  /// The map stores a linked list for each value, which contains
3028
  /// the items mapped to the value, and the used values are stored
3029
  /// in balanced binary tree (\c std::map).
2999 3030
  ///
3000
  /// The map stores for each value a linked list with
3001
  /// the items which mapped to the value, and the values are stored
3002
  /// in balanced binary tree. The values of the map can be accessed
3003
  /// with stl compatible forward iterator.
3031
  /// \ref IterableBoolMap and \ref IterableIntMap are similar classes
3032
  /// specialized for \c bool and \c int values, respectively.
3004 3033
  ///
3005 3034
  /// This type is not reference map, so it cannot be modified with
3006
  /// the subscription operator.
3035
  /// the subscript operator.
3007 3036
  ///
3008 3037
  /// \tparam GR The graph type.
3009 3038
  /// \tparam K The key type of the map (\c GR::Node, \c GR::Arc or
... ...
@@ -3079,7 +3108,7 @@
3079 3108

	
3080 3109
    /// \brief Forward iterator for values.
3081 3110
    ///
3082
    /// This iterator is an stl compatible forward
3111
    /// This iterator is an STL compatible forward
3083 3112
    /// iterator on the values of the map. The values can
3084 3113
    /// be accessed in the <tt>[beginValue, endValue)</tt> range.
3085 3114
    class ValueIterator
... ...
@@ -3090,19 +3119,26 @@
3090 3119
        : it(_it) {}
3091 3120
    public:
3092 3121

	
3122
      /// Constructor
3093 3123
      ValueIterator() {}
3094 3124

	
3125
      /// \e
3095 3126
      ValueIterator& operator++() { ++it; return *this; }
3127
      /// \e
3096 3128
      ValueIterator operator++(int) {
3097 3129
        ValueIterator tmp(*this);
3098 3130
        operator++();
3099 3131
        return tmp;
3100 3132
      }
3101 3133

	
3134
      /// \e
3102 3135
      const Value& operator*() const { return it->first; }
3136
      /// \e
3103 3137
      const Value* operator->() const { return &(it->first); }
3104 3138

	
3139
      /// \e
3105 3140
      bool operator==(ValueIterator jt) const { return it == jt.it; }
3141
      /// \e
3106 3142
      bool operator!=(ValueIterator jt) const { return it != jt.it; }
3107 3143

	
3108 3144
    private:
... ...
@@ -3111,7 +3147,7 @@
3111 3147

	
3112 3148
    /// \brief Returns an iterator to the first value.
3113 3149
    ///
3114
    /// Returns an stl compatible iterator to the
3150
    /// Returns an STL compatible iterator to the
3115 3151
    /// first value of the map. The values of the
3116 3152
    /// map can be accessed in the <tt>[beginValue, endValue)</tt>
3117 3153
    /// range.
... ...
@@ -3121,7 +3157,7 @@
3121 3157

	
3122 3158
    /// \brief Returns an iterator after the last value.
3123 3159
    ///
3124
    /// Returns an stl compatible iterator after the
3160
    /// Returns an STL compatible iterator after the
3125 3161
    /// last value of the map. The values of the
3126 3162
    /// map can be accessed in the <tt>[beginValue, endValue)</tt>
3127 3163
    /// range.
0 comments (0 inline)