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