new home directory
[feisty_meow.git] / nucleus / library / mathematics / averager.h
1 #ifndef AVERAGER_CLASS
2 #define AVERAGER_CLASS
3
4 /*****************************************************************************\
5 *                                                                             *
6 *  Name   : averager                                                          *
7 *  Author : Chris Koeritz                                                     *
8 *                                                                             * 
9 *******************************************************************************
10 * Copyright (c) 1997-$now By Author.  This program is free software; you can  *
11 * redistribute it and/or modify it under the terms of the GNU General Public  *
12 * License as published by the Free Software Foundation; either version 2 of   *
13 * the License or (at your option) any later version.  This is online at:      *
14 *     http://www.fsf.org/copyleft/gpl.html                                    *
15 * Please send any updates to: fred@gruntose.com                               *
16 \*****************************************************************************/
17
18 #include <basis/array.h>
19 #include <basis/functions.h>
20
21 namespace mathematics {
22
23 //! Maintains a list of numbers and provides the average for them.
24 /*!
25   The list entries can be weighted if desired.  If the list grows too large,
26   the first chunk of the entries is added as a weighted average and the list's
27   size is reduced appropriately.
28 */
29
30 template <class contents>
31 class averager
32 {
33 public:
34   averager(int entries = 100, bool compacting = true);
35     //!< creates an averager whose list length is restricted to "entries".
36     /*!< if "entries" that is zero, then the maximum length is used.  if
37     "compacting" is true, then the entries which need to be removed during
38     a compaction will be added to the list as a weighted average.  if it's
39     false, then the unfortunate entries are just eliminated.  the first style
40     leads to a more steady state version of the average while the other is
41     more recent history.  note that the lowest reasonable value for "entries"
42     is eight due to the compaction algorithm; lower values will work, but the
43     averager will allow the list to grow to eight anyway. */
44
45   void add(contents value, int count = 1);
46     //!< adds a new "value" to the averager, with an optional "count".
47
48   contents average() const { return average(0, length() - 1); }
49     //!< reports the overall average of the whole list.
50
51   int samples() const;
52     //!< returns the total number of samples recorded in the average.
53
54   int length() const { return _averages.length(); }
55     //!< returns the current length of the averages list.
56
57   contents average(int start, int end) const;
58     //!< reports the average over the range from "start" to "end" inclusive.
59
60   struct weighted_entry { contents value; int count; };
61     //!< structure holding a weighted chunk of the average.
62     /*!< an entry in the list of averages has a "value" and a "count" that
63     measures the weight with which that "value" is considered. */
64
65   weighted_entry get(int index) const { return _averages.get(index); }
66     //!< accesses the entry stored at the "index" specified.
67
68   void compact();
69     //!< chops off the oldest portion of the averager.
70     /*!< if this is a compacting style averager, then the older data is
71     coalesced and added as a weighted entry. */
72
73   void check_for_compaction();
74     //!< checks whether the averager needs to be compacted yet or not.
75     /*!< the decision is made according to the maximum allowable size in
76     "entries" passed to the constructor.  if "entries" is zero, the maximum
77     allowable size is used instead. */
78
79 private:
80   bool _do_compaction;  //!< do truncated values coalesce to a weighted entry?
81   basis::array<weighted_entry> _averages;  //!< current list.
82   int _entries;  //!< maximum length of list.
83 };
84
85 //////////////
86
87 //! keeps an average on a stream of integers.
88 class int_averager : public averager<int>
89 {
90 public:
91   int_averager(int entries = 100, bool compacting = true)
92           : averager<int>(entries, compacting) {}
93 };
94
95 //////////////
96
97 // implementations below...
98
99 const int AVERAGER_SIZE_LIMIT = 180000;  // the most items we'll try to handle.
100
101 template <class contents>
102 averager<contents>::averager(int entries, bool compacting)
103 : _do_compaction(compacting), _averages(), _entries(entries)
104 {
105   int unit_size = sizeof(weighted_entry);
106   if (basis::negative(_entries) || !_entries)
107     _entries = int(AVERAGER_SIZE_LIMIT / unit_size);
108 }
109
110 template <class contents>
111 void averager<contents>::compact()
112 {
113   if (length() < 8) return;  // sorry, you're too short for this wild ride.
114   int end_whacking = _averages.length() / 4;
115   if (_do_compaction) {
116     contents whacked_average = average(0, end_whacking);
117     _averages.zap(1, end_whacking);
118     _averages[0].value = whacked_average;
119     _averages[0].count = end_whacking + 1;
120   } else _averages.zap(0, end_whacking);
121 }
122
123 template <class contents>
124 void averager<contents>::check_for_compaction()
125 {
126   // make sure that we don't go over our allotted space.
127   int unit_size = sizeof(weighted_entry);
128   int limit = basis::minimum(AVERAGER_SIZE_LIMIT, _entries * unit_size);
129   if (int(_averages.length() + 2) * unit_size >= limit) compact();
130 }
131
132 template <class contents>
133 void averager<contents>::add(contents value, int count)
134 {
135   weighted_entry to_add;
136   to_add.value = value;
137   to_add.count = count;
138   check_for_compaction();
139   _averages += to_add;
140 }
141
142 template <class contents>
143 contents averager<contents>::average(int start, int end) const
144 {
145   bounds_return(start, 0, length() - 1, 0);
146   bounds_return(end, start, length() - 1, 0);
147   bounds_return(end - start + 1, 1, length(), 0);
148
149   contents accum = 0;
150   contents count = 0;
151   for (int i = start; i <= end; i++) {
152     accum += get(i).value * get(i).count;
153     count += get(i).count;
154   }
155   if (!count) count = 1;
156   return accum / count;
157 }
158
159 template <class contents>
160 int averager<contents>::samples() const
161 {
162   int to_return = 0;
163   for (int i = 0; i < length(); i++) to_return += get(i).count;
164   return to_return;
165 }
166
167 } //namespace.
168
169 #endif
170