bug in RC
[anna.git] / include / anna / core / util / Average.hpp
1 // ANNA - Anna is Not Nothingness Anymore                                                         //
2 //                                                                                                //
3 // (c) Copyright 2005-2015 Eduardo Ramos Testillano & Francisco Ruiz Rayo                         //
4 //                                                                                                //
5 // See project site at http://redmine.teslayout.com/projects/anna-suite                           //
6 // See accompanying file LICENSE or copy at http://www.teslayout.com/projects/public/anna.LICENSE //
7
8
9 #ifndef anna_core_util_Average_hpp
10 #define anna_core_util_Average_hpp
11
12 #include <anna/core/util/Millisecond.hpp>
13 #include <anna/core//util/DelayMeter.hpp>
14 #include <anna/core/functions.hpp>
15
16 namespace anna {
17
18 /**
19    Template para calcular la media de una sucesion de valores numericos.
20
21    Internamente trabaja con Microsegundos porque los métodos que los proporcionan son
22    más eficientes.
23 */
24 template <class T> class Average {
25 public:
26   /**
27      Constructor.
28      \param name Nombre logico de esta instancia.
29      \param measure Unidad de medida. Solo se usa a efecto de salida de datos.
30   */
31   Average(const char* name, const char* measure = NULL) :
32     a_name(name), a_accumulator(0), a_n(0), a_measure(measure) {;}
33
34   /**
35      Devuelve el indicador de validez de esta media.
36      \return \em true Si la media no tiene ningun valor o \em false en caso contrario.
37   */
38   bool isEmpty() const throw()  { return (a_n == 0); }
39
40   /**
41      Devuelve \em true si el valor de la media es cero, bien por no tener valores o
42      bien porque todos ellos eran cero.
43      \return \em true el valor de la media es cero o \em false en otro caso.
44   */
45   bool isZero() const throw() { return a_n == 0 || a_accumulator == 0; }
46
47   /**
48      Devuelve el numero de elementos de contiene la media.
49      \return el numero de elementos de contiene la media.
50   */
51   int size() const throw() { return a_n; }
52
53   /**
54      Devuelve el valor acumulado.
55      \return el valor acumulado.
56   */
57   T getAccumulator() const throw() { return a_accumulator; }
58
59   /**
60      Devuelve la media de la sucesion de valores numericos asociados a esta.
61      \return La media de la sucesion de valores numericos asociados a esta.
62      \warning Antes de invocar a este operador hay que verificar que #isEmpty devuelve \em false.
63   */
64   T value() const throw() { return (isEmpty() == true) ? T(0) : (a_accumulator / a_n);  }
65
66   /**
67      Inicializa el valor de la media.
68   */
69   void clear() throw() {  a_accumulator = 0; a_n = 0; }
70
71   /**
72    * Establece manualmente el valor de la estadística.
73    * \param value Valor que tomará el acumulador de este instancia.
74    * \param _n valor que tomará el conteador de esta instancia.
75    */
76   void setValue(const T& value, const unsigned int _n) throw() {
77     a_accumulator = value;
78     a_n = _n;
79   }
80
81   /**
82      Devuelve la media de la sucesion de valores numericos asociados a esta.
83      \return La media de la sucesion de valores numericos asociados a esta.
84      \warning Antes de invocar a este operador hay que verificar que #isEmpty devuelve \em false.
85   */
86   operator T() const throw() { return value(); }
87
88   /**
89      Inicializa el valor de esta media.
90      \param value Valor con el que iniciar la media.
91      \return La referencia a esta instancia.
92   */
93   Average<T>& operator = (const T value)
94   throw() {
95     a_accumulator = value;
96     a_n = 1;
97     return *this;
98   }
99
100   /**
101      Contructor copia.
102      \param other Objeto del que obtener los valores.
103      \return La referencia a esta instancia.
104   */
105   Average<T>& operator = (const Average<T>& other)
106   throw() {
107     a_accumulator = other.a_accumulator;
108     a_n = other.a_n;
109     return *this;
110   }
111
112   /**
113      Incrementa la media con el valor recibido.
114      \param v Valor con el que incrementar la media.
115      \return La referencia a esta instancia.
116   */
117   Average<T>& operator += (const T& v)
118   throw() {
119     const T backup(a_accumulator);
120
121     if((a_accumulator += v) < backup) {
122       a_accumulator = v;
123       a_n = 1;
124     } else
125       a_n ++;
126
127     return *this;
128   }
129
130   /**
131      Decrementa la media con el valor recibido.
132      \param v Valor con el que incrementar la media.
133      \return La referencia a esta instancia.
134   */
135   Average<T>& operator -= (const T v)
136   throw() {
137     if(a_accumulator > v && a_n > 1) {
138       a_accumulator -= v;
139       a_n --;
140     } else {
141       a_accumulator = 0;
142       a_n = 0;
143     }
144
145     return *this;
146   }
147
148   /**
149      Devuelve una cadena con la informacion referente a esta clase.
150      \return Una cadena con la informacion referente a esta clase.
151   */
152   std::string asString() const
153   throw() {
154     std::string msg(a_name);
155     msg += " { Accumulate: ";
156     msg += functions::asString(a_accumulator);
157
158     if(a_measure != NULL)
159       msg += " " + std::string(a_measure);
160
161     msg += functions::asString(" | N: %u | avg: ", a_n);
162     msg += functions::asString(value());
163
164     if(a_measure != NULL)
165       msg += " " + std::string(a_measure);
166
167     return msg += " }";
168   }
169
170 private:
171   const char* a_name;
172   const char* a_measure;
173   T a_accumulator;
174   unsigned int a_n;
175 };
176
177 }
178
179 #endif
180
181
182