COIN-OR::LEMON - Graph Library

Changeset 160:b1bd0c2a7f57 in lemon for lemon/counter.h


Ignore:
Timestamp:
05/26/08 13:31:41 (16 years ago)
Author:
Peter Kovacs <kpeter@…>
Branch:
default
Phase:
public
Message:

Improved documentation for counters

File:
1 edited

Legend:

Unmodified
Added
Removed
  • lemon/counter.h

    r121 r160  
    9797  /// @{
    9898
    99   ///A counter class
    100 
    101   ///This class makes it easier to count certain events. You can increment
    102   ///or decrement the counter using operator++ and operator--.
    103   ///A report is automatically printed on destruction.
    104   ///\todo More doc
     99  /// A counter class
     100
     101  /// This class makes it easier to count certain events (e.g. for debug
     102  /// reasons).
     103  /// You can increment or decrement the counter using \c operator++,
     104  /// \c operator--, \c operator+= and \c operator-=. You can also
     105  /// define subcounters for the different phases of the algorithm or
     106  /// for different types of operations.
     107  /// A report containing the given title and the value of the counter
     108  /// is automatically printed on destruction.
     109  ///
     110  /// The following example shows the usage of counters and subcounters.
     111  /// \code
     112  /// // Bubble sort
     113  /// std::vector<T> v;
     114  /// ...
     115  /// Counter op("Operations: ");
     116  /// Counter::SubCounter as(op, "Assignments: ");
     117  /// Counter::SubCounter co(op, "Comparisons: ");
     118  /// for (int i = v.size()-1; i > 0; --i) {
     119  ///   for (int j = 0; j < i; ++j) {
     120  ///     if (v[j] > v[j+1]) {
     121  ///       T tmp = v[j];
     122  ///       v[j] = v[j+1];
     123  ///       v[j+1] = tmp;
     124  ///       as += 3;          // three assignments
     125  ///     }
     126  ///     ++co;               // one comparison
     127  ///   }
     128  /// }
     129  /// \endcode
     130  ///
     131  /// This code prints out something like that:
     132  /// \code
     133  /// Comparisons: 45
     134  /// Assignments: 57
     135  /// Operations: 102
     136  /// \endcode
     137  ///
     138  /// \sa NoCounter
    105139  class Counter
    106140  {
     
    109143    int count;
    110144  public:
    111     ///\e
    112 
    113     ///\todo document please.
     145
     146    /// SubCounter class
     147   
     148    /// This class can be used to setup subcounters for a \ref Counter
     149    /// to have finer reports. A subcounter provides exactly the same
     150    /// operations as the main \ref Counter, but it also increments and
     151    /// decrements the value of its parent.
     152    /// Subcounters can also have subcounters.
     153    ///
     154    /// The parent counter must be given as the first parameter of the
     155    /// constructor. Apart from that a title and an \c ostream object
     156    /// can also be given just like for the main \ref Counter.
    114157    ///
     158    /// A report containing the given title and the value of the
     159    /// subcounter is automatically printed on destruction. If you
     160    /// would like to turn off this report, use \ref NoSubCounter
     161    /// instead.
     162    ///
     163    /// \sa NoSubCounter
    115164    typedef _SubCounter<Counter> SubCounter;
    116     ///\e
    117 
    118     ///\todo document please.
     165
     166    /// SubCounter class without printing report on destruction
     167   
     168    /// This class can be used to setup subcounters for a \ref Counter.
     169    /// It is the same as \ref SubCounter but it does not print report
     170    /// on destruction. (It modifies the value of its parent, so 'No'
     171    /// only means 'do not print'.)
    119172    ///
     173    /// Replacing \ref SubCounter "SubCounter"s with \ref NoSubCounter
     174    /// "NoSubCounter"s makes it possible to turn off reporting
     175    /// subcounter values without actually removing the definitions
     176    /// and the increment or decrement operators.
     177    ///
     178    /// \sa SubCounter
    120179    typedef _NoSubCounter<Counter> NoSubCounter;
    121180
    122     ///\e
     181    /// Constructor.
    123182    Counter() : _title(), _os(std::cerr), count(0) {}
    124     ///\e
     183    /// Constructor.
    125184    Counter(std::string title,std::ostream &os=std::cerr)
    126185      : _title(title), _os(os), count(0) {}
    127     ///\e
     186    /// Constructor.
    128187    Counter(const char *title,std::ostream &os=std::cerr)
    129188      : _title(title), _os(os), count(0) {}
    130     ///Destructor. Prints the given title and the value of the counter.
     189    /// Destructor. Prints the given title and the value of the counter.
    131190    ~Counter() {
    132191      _os << _title << count <<std::endl;
     
    144203    ///\e
    145204    Counter &operator-=(int c) { count-=c; return *this;}
    146     ///\e
     205    /// Resets the counter to the given value.
    147206    void reset(int c=0) {count=c;}
    148     ///\e
     207    /// Returns the value of the counter.
    149208    operator int() {return count;}
    150209  };
    151210
    152   ///'Do nothing' version of \ref Counter
    153 
    154   ///'Do nothing' version of \ref Counter.
    155   ///\sa Counter
     211  /// 'Do nothing' version of Counter.
     212
     213  /// This class can be used in the same way as \ref Counter however it
     214  /// does not count at all and does not print report on destruction.
     215  ///
     216  /// Replacing a \ref Counter with a \ref NoCounter makes it possible
     217  /// to turn off all counting and reporting (SubCounters should also
     218  /// be replaced with NoSubCounters), so it does not affect the
     219  /// efficiency of the program at all.
     220  ///
     221  /// \sa Counter
    156222  class NoCounter
    157223  {
Note: See TracChangeset for help on using the changeset viewer.