1.1 --- a/lemon/counter.h Sun May 25 17:01:11 2008 +0200
1.2 +++ b/lemon/counter.h Mon May 26 13:31:41 2008 +0200
1.3 @@ -96,38 +96,97 @@
1.4 /// \addtogroup timecount
1.5 /// @{
1.6
1.7 - ///A counter class
1.8 + /// A counter class
1.9
1.10 - ///This class makes it easier to count certain events. You can increment
1.11 - ///or decrement the counter using operator++ and operator--.
1.12 - ///A report is automatically printed on destruction.
1.13 - ///\todo More doc
1.14 + /// This class makes it easier to count certain events (e.g. for debug
1.15 + /// reasons).
1.16 + /// You can increment or decrement the counter using \c operator++,
1.17 + /// \c operator--, \c operator+= and \c operator-=. You can also
1.18 + /// define subcounters for the different phases of the algorithm or
1.19 + /// for different types of operations.
1.20 + /// A report containing the given title and the value of the counter
1.21 + /// is automatically printed on destruction.
1.22 + ///
1.23 + /// The following example shows the usage of counters and subcounters.
1.24 + /// \code
1.25 + /// // Bubble sort
1.26 + /// std::vector<T> v;
1.27 + /// ...
1.28 + /// Counter op("Operations: ");
1.29 + /// Counter::SubCounter as(op, "Assignments: ");
1.30 + /// Counter::SubCounter co(op, "Comparisons: ");
1.31 + /// for (int i = v.size()-1; i > 0; --i) {
1.32 + /// for (int j = 0; j < i; ++j) {
1.33 + /// if (v[j] > v[j+1]) {
1.34 + /// T tmp = v[j];
1.35 + /// v[j] = v[j+1];
1.36 + /// v[j+1] = tmp;
1.37 + /// as += 3; // three assignments
1.38 + /// }
1.39 + /// ++co; // one comparison
1.40 + /// }
1.41 + /// }
1.42 + /// \endcode
1.43 + ///
1.44 + /// This code prints out something like that:
1.45 + /// \code
1.46 + /// Comparisons: 45
1.47 + /// Assignments: 57
1.48 + /// Operations: 102
1.49 + /// \endcode
1.50 + ///
1.51 + /// \sa NoCounter
1.52 class Counter
1.53 {
1.54 std::string _title;
1.55 std::ostream &_os;
1.56 int count;
1.57 public:
1.58 - ///\e
1.59
1.60 - ///\todo document please.
1.61 + /// SubCounter class
1.62 +
1.63 + /// This class can be used to setup subcounters for a \ref Counter
1.64 + /// to have finer reports. A subcounter provides exactly the same
1.65 + /// operations as the main \ref Counter, but it also increments and
1.66 + /// decrements the value of its parent.
1.67 + /// Subcounters can also have subcounters.
1.68 + ///
1.69 + /// The parent counter must be given as the first parameter of the
1.70 + /// constructor. Apart from that a title and an \c ostream object
1.71 + /// can also be given just like for the main \ref Counter.
1.72 ///
1.73 + /// A report containing the given title and the value of the
1.74 + /// subcounter is automatically printed on destruction. If you
1.75 + /// would like to turn off this report, use \ref NoSubCounter
1.76 + /// instead.
1.77 + ///
1.78 + /// \sa NoSubCounter
1.79 typedef _SubCounter<Counter> SubCounter;
1.80 - ///\e
1.81
1.82 - ///\todo document please.
1.83 + /// SubCounter class without printing report on destruction
1.84 +
1.85 + /// This class can be used to setup subcounters for a \ref Counter.
1.86 + /// It is the same as \ref SubCounter but it does not print report
1.87 + /// on destruction. (It modifies the value of its parent, so 'No'
1.88 + /// only means 'do not print'.)
1.89 ///
1.90 + /// Replacing \ref SubCounter "SubCounter"s with \ref NoSubCounter
1.91 + /// "NoSubCounter"s makes it possible to turn off reporting
1.92 + /// subcounter values without actually removing the definitions
1.93 + /// and the increment or decrement operators.
1.94 + ///
1.95 + /// \sa SubCounter
1.96 typedef _NoSubCounter<Counter> NoSubCounter;
1.97
1.98 - ///\e
1.99 + /// Constructor.
1.100 Counter() : _title(), _os(std::cerr), count(0) {}
1.101 - ///\e
1.102 + /// Constructor.
1.103 Counter(std::string title,std::ostream &os=std::cerr)
1.104 : _title(title), _os(os), count(0) {}
1.105 - ///\e
1.106 + /// Constructor.
1.107 Counter(const char *title,std::ostream &os=std::cerr)
1.108 : _title(title), _os(os), count(0) {}
1.109 - ///Destructor. Prints the given title and the value of the counter.
1.110 + /// Destructor. Prints the given title and the value of the counter.
1.111 ~Counter() {
1.112 _os << _title << count <<std::endl;
1.113 }
1.114 @@ -143,16 +202,23 @@
1.115 Counter &operator+=(int c) { count+=c; return *this;}
1.116 ///\e
1.117 Counter &operator-=(int c) { count-=c; return *this;}
1.118 - ///\e
1.119 + /// Resets the counter to the given value.
1.120 void reset(int c=0) {count=c;}
1.121 - ///\e
1.122 + /// Returns the value of the counter.
1.123 operator int() {return count;}
1.124 };
1.125
1.126 - ///'Do nothing' version of \ref Counter
1.127 + /// 'Do nothing' version of Counter.
1.128
1.129 - ///'Do nothing' version of \ref Counter.
1.130 - ///\sa Counter
1.131 + /// This class can be used in the same way as \ref Counter however it
1.132 + /// does not count at all and does not print report on destruction.
1.133 + ///
1.134 + /// Replacing a \ref Counter with a \ref NoCounter makes it possible
1.135 + /// to turn off all counting and reporting (SubCounters should also
1.136 + /// be replaced with NoSubCounters), so it does not affect the
1.137 + /// efficiency of the program at all.
1.138 + ///
1.139 + /// \sa Counter
1.140 class NoCounter
1.141 {
1.142 public: