include/anna/core/functions.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_functions_hpp
  10 #define anna_core_functions_hpp
  11
  12 #include <stdlib.h>
  13
  14 #include <anna/core/util/ComponentManager.hpp>
  15 #include <anna/core/util/defines.hpp>
  16 #include <anna/core/RuntimeException.hpp>
  17
  18 #include <anna/core/util/ExclusiveHash.hpp>
  19 #include <anna/core/util/Second.hpp>
  20 #include <anna/core/util/Millisecond.hpp>
  21 #include <anna/core/util/Microsecond.hpp>
  22
  23 #include <anna/core/DataBlock.hpp>
  24
  25
  26 #include <time.h>
  27 #include <sys/time.h>
  28 #include <string>
  29 #include <vector>
  30
  31
  32 //------------------------------------------------------------------------------
  33 //---------------------------------------------------------------------- #define
  34 //------------------------------------------------------------------------------
  35 #define s_REGEXP_IPv4_ADDRESSES "\\b(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\b"
  36 //#define s_REGEXP_IPv6_ADDRESSES "s*((([0-9A-Fa-f]{1,4}:){7}(([0-9A-Fa-f]{1,4})|:))|(([0-9A-Fa-f]{1,4}:){6}(:|((25[0-5]|2[0-4]\\d|[01]?\\d{1,2})(\\.(25[0-5]|2[0-4]\\d|[01]?\\d{1,2})){3})|(:[0-9A-Fa-f]{1,4})))|(([0-9A-Fa-f]{1,4}:){5}((:((25[0-5]|2[0-4]\\d|[01]?\\d{1,2})(\\.(25[0-5]|2[0-4]\\d|[01]?\\d{1,2})){3})?)|((:[0-9A-Fa-f]{1,4}){1,2})))|(([0-9A-Fa-f]{1,4}:){4}(:[0-9A-Fa-f]{1,4}){0,1}((:((25[0-5]|2[0-4]\\d|[01]?\\d{1,2})(\\.(25[0-5]|2[0-4]\\d|[01]?\\d{1,2})){3})?)|((:[0-9A-Fa-f]{1,4}){1,2})))|(([0-9A-Fa-f]{1,4}:){3}(:[0-9A-Fa-f]{1,4}){0,2}((:((25[0-5]|2[0-4]\\d|[01]?\\d{1,2})(\\.(25[0-5]|2[0-4]\\d|[01]?\\d{1,2})){3})?)|((:[0-9A-Fa-f]{1,4}){1,2})))|(([0-9A-Fa-f]{1,4}:){2}(:[0-9A-Fa-f]{1,4}){0,3}((:((25[0-5]|2[0-4]\\d|[01]?\\d{1,2})(\\.(25[0-5]|2[0-4]\\d|[01]?\\d{1,2})){3})?)|((:[0-9A-Fa-f]{1,4}){1,2})))|(([0-9A-Fa-f]{1,4}:)(:[0-9A-Fa-f]{1,4}){0,4}((:((25[0-5]|2[0-4]\\d|[01]?\\d{1,2})(\\.(25[0-5]|2[0-4]\\d|[01]?\\d{1,2})){3})?)|((:[0-9A-Fa-f]{1,4}){1,2})))|(:(:[0-9A-Fa-f]{1,4}){0,5}((:((25[0-5]|2[0-4]\\d|[01]?\\d{1,2})(\\.(25[0-5]|2[0-4]\\d|[01]?\\d{1,2})){3})?)|((:[0-9A-Fa-f]{1,4}){1,2})))|(((25[0-5]|2[0-4]\\d|[01]?\\d{1,2})(\\.(25[0-5]|2[0-4]\\d|[01]?\\d{1,2})){3})))(%.+)?\\s*"
  37 #define s_REGEXP_IPv6_ADDRESSES "s*((([0-9A-Fa-f]{1,4}:){7}(([0-9A-Fa-f]{1,4})|:))|(([0-9A-Fa-f]{1,4}:){6}(:|((25[0-5]|2[0-4]\\d|[01]?\\d{1,2})\
  38 (\\.(25[0-5]|2[0-4]\\d|[01]?\\d{1,2})){3})|(:[0-9A-Fa-f]{1,4})))|(([0-9A-Fa-f]{1,4}:){5}((:((25[0-5]|2[0-4]\\d|[01]?\\d{1,2})(\\.(25[0-5]|2[0-4]\
  39 \\d|[01]?\\d{1,2})){3})?)|((:[0-9A-Fa-f]{1,4}){1,2})))|(([0-9A-Fa-f]{1,4}:){4}(:[0-9A-Fa-f]{1,4}){0,1}((:((25[0-5]|2[0-4]\\d|[01]?\\d{1,2})(\\.(\
  40 25[0-5]|2[0-4]\\d|[01]?\\d{1,2})){3})?)|((:[0-9A-Fa-f]{1,4}){1,2})))|(([0-9A-Fa-f]{1,4}:){3}(:[0-9A-Fa-f]{1,4}){0,2}((:((25[0-5]|2[0-4]\\d|[01]?\
  41 \\d{1,2})(\\.(25[0-5]|2[0-4]\\d|[01]?\\d{1,2})){3})?)|((:[0-9A-Fa-f]{1,4}){1,2})))|(([0-9A-Fa-f]{1,4}:){2}(:[0-9A-Fa-f]{1,4}){0,3}((:((25[0-5]|2\
  42 [0-4]\\d|[01]?\\d{1,2})(\\.(25[0-5]|2[0-4]\\d|[01]?\\d{1,2})){3})?)|((:[0-9A-Fa-f]{1,4}){1,2})))|(([0-9A-Fa-f]{1,4}:)(:[0-9A-Fa-f]{1,4}){0,4}((:\
  43 ((25[0-5]|2[0-4]\\d|[01]?\\d{1,2})(\\.(25[0-5]|2[0-4]\\d|[01]?\\d{1,2})){3})?)|((:[0-9A-Fa-f]{1,4}){1,2})))|(:(:[0-9A-Fa-f]{1,4}){0,5}((:((25[0-\
  44 5]|2[0-4]\\d|[01]?\\d{1,2})(\\.(25[0-5]|2[0-4]\\d|[01]?\\d{1,2})){3})?)|((:[0-9A-Fa-f]{1,4}){1,2})))|(((25[0-5]|2[0-4]\\d|[01]?\\d{1,2})(\\.(25[\
  45 0-5]|2[0-4]\\d|[01]?\\d{1,2})){3})))(%.+)?\\s*"
  46
  47 // Helpers for alarm parsing parameters:
  48 #define STRING_WITH_QUOTATION_MARKS__C_STR(x)   ((anna::functions::addQuotationMarks(x)).c_str())
  49 #define ANNA_AS_STRING__C_STR(x)             ((anna::functions::asString(x)).c_str())
  50
  51
  52
  53 namespace anna {
  54
  55 class DataBlock;
  56
  57 #ifdef __CYGWIN__
  58 #define CLOCK_PROCESS_CPUTIME_ID CLOCK_PROCESS_CPUTIME
  59 #endif
  60
  61
  62 /**
  63    functions - Métodos y variables
  64 */
  65 struct functions {
  66   /**
  67      Tamao de la memoria reservada que debe tener la variable usada para guardar
  68      el resultado de convertir el 'time' en texto.
  69
  70      @see asString
  71   */
  72   static const int DateTimeSizeString = 21;
  73
  74   /**
  75      @return La versin de functions con la que hemos linkado nuestra aplicacion.
  76   */
  77   static std::string getVersion() throw();
  78
  79   /**
  80      @return Un literal con la arquitectura sobre la que hemos compilado nuestra aplicacion.
  81   */
  82   static std::string getArchitecture() throw();
  83
  84   /**
  85      Indica el número de bits de un entero.
  86   */
  87   static const int intBitSize = sizeof(int) * 8;
  88
  89   /*
  90    * Indica el número de bits de un entero largo.
  91    */
  92   static const int int64BitSize = sizeof(S64) * 8;
  93
  94   /**
  95      \param number Numero a convertir.
  96      @return Un literal con el numero convertido a cadena decimal.
  97   */
  98   static std::string asString(const int number) throw();
  99
 100   /**
 101      \param number Numero a convertir.
 102      @return Un literal con el numero sin signo convertido a cadena decimal.
 103   */
 104   static std::string asString(const unsigned int number) throw();
 105
 106   /**
 107      \param number Numero a convertir.
 108      @return Un literal con el numero sin signo convertido a cadena decimal.
 109   */
 110   static std::string asString(const unsigned long long int number) throw() {
 111     return asString((U64)number);
 112   }
 113
 114   /**
 115      \param number Numero a convertir.
 116      @return Un literal con el numero sin signo convertido a cadena decimal.
 117   */
 118   static std::string asString(const long long int number) throw() {
 119     return asString((S64)number);
 120   }
 121
 122   /**
 123      Devuelve un literal con tel numero convertido a cadena decimal
 124      @return Un literal con el numero signo convertido a cadena decimal.
 125   */
 126   static std::string asString(const S64 number) throw();
 127
 128   /**
 129      Devuelve un literal con tel numero convertido a cadena decimal
 130      @return Un literal con el numero signo convertido a cadena decimal.
 131   */
 132   static std::string asString(const U64 number) throw();
 133
 134   /**
 135      \param _bool Booleano a convertir.
 136      \return Un literal con el boolean convertido a cadena.
 137   */
 138   static const char* asString(const bool _bool) throw() { return (_bool == true) ? "true" : "false"; }
 139
 140   /**
 141      Devuelve una cadena con el bloque de datos decodificado en grupos de 16 bytes.
 142      @param dataBlock Bloque de datos a interpretar.
 143      \param characterByLine Número de caracteres en cada línea.
 144      @return Devuelve una cadena con el bloque de datos decodificado en grupos de 16 bytes.
 145   */
 146   static std::string asString(const DataBlock& dataBlock, const int characterByLine = 16) throw();
 147
 148   /**
 149      Devuelve una cadena con el numero en coma flotante.
 150      \param v Numero a tratar.
 151      \param format Formato aplicado para convertir el numero a cadena. Ver \em man printf.
 152      \return una cadena con el numero en coma flotante.
 153   */
 154   static std::string asString(const double v, const char* format = "%e") throw();
 155
 156   /**
 157      Devuelve una cadena con el numero en coma flotante.
 158      \param v Numero a tratar.
 159      \param format Formato aplicado para convertir el numero a cadena. Ver \em man printf.
 160      \return una cadena con el numero en coma flotante.
 161   */
 162   static std::string asString(const float v, const char* format = "%f") throw();
 163
 164   /**
 165      \param comment Comentario que precede al valor.
 166      \param number Numero a convertir.
 167      @return Un literal con el numero convertido a cadena decimal.
 168   */
 169   static std::string asText(const char* comment, const int number)
 170   throw() {
 171     std::string result(comment);
 172     return result += asString(number);
 173   }
 174
 175   /**
 176      \param comment Comentario que precede al valor.
 177      \param number Numero a convertir.
 178      @return Un literal con el numero convertido a cadena decimal.
 179   */
 180   static std::string asText(const char* comment, const S64 number)
 181   throw() {
 182     std::string result(comment);
 183     return result += asString(number);
 184   }
 185
 186   /**
 187       \param comment Comentario que precede al valor.
 188       \param _bool Booleano a convertir.
 189       @return Un literal con el numero convertido a cadena decimal.
 190    */
 191   static std::string asText(const char* comment, const bool _bool)
 192   throw() {
 193     std::string result(comment);
 194     return result += asString(_bool);
 195   }
 196
 197   /**
 198      \param comment Comentario que precede al valor.
 199      \param dataBlock Bloque de datos a interpretar.
 200      \param characterByLine Número de caracteres en cada línea.
 201      @return Un literal con el numero convertido a cadena decimal.
 202   */
 203   static std::string asText(const char* comment, const DataBlock& dataBlock, const int characterByLine = 16)
 204   throw() {
 205     std::string result(comment);
 206     return result += asString(dataBlock, characterByLine);
 207   }
 208
 209   /**
 210      \param comment Comentario que precede al valor.
 211      \param value Numero a tratar.
 212      \param format Formato aplicado para convertir el numero a cadena. Ver \em man printf.
 213      \return Un literal con el numero convertido a cadena.
 214   */
 215   static std::string asText(const char* comment, const float value, const char* format = "%f")
 216   throw() {
 217     std::string result(comment);
 218     return result += asString(value, format);
 219   }
 220
 221   /**
 222      \param comment Comentario que precede al valor.
 223      \param value Numero a tratar.
 224      \param format Formato aplicado para convertir el numero a cadena. Ver \em man printf.
 225      \return Un literal con el numero convertido a cadena.
 226   */
 227   static std::string asText(const char* comment, const double value, const char* format = "%e")
 228   throw() {
 229     std::string result(comment);
 230     return result += asString(value, format);
 231   }
 232
 233   /**
 234      \param number Numero a convertir.
 235      @return Un literal con el numero convertido a cadena hexadecimal.
 236   */
 237   static std::string asHexString(const int number) throw();
 238
 239   /**
 240      \param number Numero a convertir.
 241      @return Un literal con el numero convertido a cadena hexadecimal.
 242   */
 243   static std::string asHexString(const S64 number) throw();
 244
 245   /**
 246      \param number Numero a convertir.
 247      @return Un literal con el numero convertido a cadena hexadecimal.
 248   */
 249   static std::string asHexString(const U64 number) throw() { return asHexString((S64) number); }
 250
 251   /**
 252      \param comment Comentario que precede al valor.
 253      \param number Numero a convertir.
 254      @return Un literal con el numero convertido a cadena decimal.
 255   */
 256   static std::string asHexText(const char* comment, const int number)
 257   throw() {
 258     std::string result(comment);
 259     return result += asHexString(number);
 260   }
 261
 262   /**
 263      \param comment Comentario que precede al valor.
 264      \param number Numero a convertir.
 265      @return Un literal con el numero convertido a cadena decimal.
 266   */
 267   static std::string asHexText(const char* comment, const S64 number)
 268   throw() {
 269     std::string result(comment);
 270     return result += asHexString(number);
 271   }
 272
 273   /**
 274     * Devuelve un cadena con el contenido del bloque de datos interpretado como BCD, pero pasa
 275     * cada valor binario a su correspondiente carácter. Por ejemplo, el buffer aa210c quedará como una cadena "AA210C".
 276     *
 277     * \param dataBlock Bloque a codificar.
 278     * \return La cadena que contiene el valor literal del buffer de datos.
 279     */
 280   static std::string asHexString(const DataBlock& dataBlock) throw();
 281
 282   /**
 283    * Obtiene el valor original de una cadena obtenido con #asHexString (const DataBlock&).
 284    * \param hexString Cadena que contiene el búfer.
 285    * \param target Bloque de datos sobre el que decodificar la cadena.
 286    * \return El bloque de datos original correspondiente a la cadena recibida.
 287    */
 288   static DataBlock& fromHexString(const std::string& hexString, DataBlock& target) throw(RuntimeException);
 289
 290   /**
 291      Devuelve una cadena con la hora en formato 'dd/mm/yyyy hh:mm:ss'.
 292
 293      @param second Hora que deseamos traducir.
 294
 295      @return Un literal con la hora en el formato 'dd/mm/yyyy hh:mm:ss'.
 296   */
 297   static std::string asDateTime(const Second &second) throw();
 298
 299   /**
 300       Devuelve una cadena con la hora en formato 'dd/mm/yyyy hh:mm:ss'.
 301
 302       @param second Hora que deseamos traducir.
 303       @param result Puntero donde vamos a guardar el resultado de la conversin.
 304       Debe tener espacio reservado para contener #TimeSizeAsString caracteres.
 305
 306       @return El puntero recibido como parametro conteniendo el literal con la hora
 307       en el formato 'dd/mm/yyyy hh:mm:ss'.
 308    */
 309   static const char* asDateTime(const Second &second, char* result) throw();
 310
 311   /**
 312      Calcula la funcion hash de la cadena recibida como parametro.
 313      \param str Cadena a la que aplicar la funcion hash.
 314   */
 315   static S64 hash(const char* str) throw();
 316
 317   /**
 318      Calcula la funcion hash de la cadena recibida como parametro.
 319      \param str Cadena a la que aplicar la funcion hash.
 320   */
 321   static S64 hash(const std::string& str) throw() { return hash(str.c_str()); }
 322
 323   /**
 324      Devuelve la cadena que contiene el resultado de aplicar la especificacion \em format
 325      sobre el resto de los parametros.
 326
 327      \param format especificacion de formato similiar al empleado en las funciones \em printf,
 328      \em scanf, etc.
 329
 330      \return la cadena que contiene el resultado de aplicar la especificacion \em format
 331      sobre el resto de los parametros.
 332   */
 333   static std::string asString(const char* format, ...) throw();
 334
 335   /**
 336      Devuelve el resultado de invocar a metodo asString de la clase recibida como parametro.
 337      Si t es NULL devolvera el texto indicando la sitacion.
 338      \param t Instancia de la clase a usar. Puede ser NULL.
 339      \return el resultado de invoca a T::asString () si t es distinto de NULL.
 340      \warning La clase T debe tener un metodo estatico con la signatura:
 341      \code
 342         static const char* className () throw ();
 343      \endcode
 344   */
 345   template <typename T> static std::string asString(const T* t)
 346   throw() {
 347     if(t == NULL) {
 348       std::string result(T::className());
 349       result += " { <null> }";
 350       return result;
 351     }
 352
 353     return t->asString();
 354   }
 355
 356   /**
 357      Metodo identididad. Facilita la implementacion de patrones donde no se conoce el tipo de dato recibido.
 358
 359      \param str Instancia de la cadena.
 360      \return La misma instancia recibida como parametro.
 361   */
 362   static const std::string& asString(const std::string& str) throw() { return str; }
 363
 364   /**
 365      Detiene la ejecucion del thread durante el numero de milisegundos indicados.
 366
 367      \param millisecond Numero de milisegundos que vamos a detener la ejecucion de este thread.
 368   */
 369   static void sleep(const Millisecond &millisecond) throw();
 370
 371   /**
 372      Obtiene el numero de segundos transcurridos desde el 1 del 1 de 1970.
 373      \return El numero de segundos transcurridos desde el 1 del 1 de 1970.
 374   */
 375   static Second second() throw() {
 376     Second result(::time(NULL));
 377     return result;
 378   }
 379
 380   /**
 381      Obtiene el numero de microsegundos transcurridos desde el 1 del 1 de 1970.
 382      \return El numero de microsegundos transcurridos desde el 1 del 1 de 1970.
 383   */
 384   static Microsecond microsecond() throw() {
 385     struct timeval tv;
 386     gettimeofday(&tv, NULL);
 387     Microsecond result((Microsecond::type_t)1000000 * tv.tv_sec + tv.tv_usec);
 388     return result;
 389   }
 390
 391   /**
 392      Obtiene el numero de milisegundos transcurridos desde el 1 del 1 de 1970.
 393      \return El numero de milisegundos transcurridos desde el 1 del 1 de 1970.
 394   */
 395   static Millisecond millisecond() throw() {
 396     struct timeval tv;
 397     gettimeofday(&tv, NULL);
 398     Millisecond result((Millisecond::type_t)1000 * tv.tv_sec + tv.tv_usec / 1000);
 399     return result;
 400   }
 401
 402   /**
 403      Devuelve la referencia interna de los microsegundos transcurrido en el procesador.
 404      \return la referencia interna de los microsegundos transcurrido en el procesador.
 405   */
 406   static Microsecond hardwareClock() throw() {
 407     timespec ts;
 408     //clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &ts); // DONT works (original)
 409     //clock_gettime(CLOCK_THREAD_CPUTIME_ID, &ts); // DONT works
 410     //clock_gettime(CLOCK_MONOTONIC, &ts); // works
 411       // Note that CLOCK_MONOTONIC is subject to discontinuities from system time
 412       //  adjustment in Linux. CLOCK_MONOTONIC_RAW was defined to get around this
 413       //  (gets hardware time not adjusted by NTP).
 414     clock_gettime(CLOCK_MONOTONIC, &ts); // works
 415
 416     Microsecond result((Microsecond::type_t)1000000 * ts.tv_sec + ts.tv_nsec / 1000);
 417     return result;
 418   }
 419
 420   /**
 421      Interpreta la cadena recibida como parametro como un dato de tipo boolean.
 422
 423      Si la cadena vale NULL, o contiene los literales "false" o "0" devolvera \em false,
 424      si contiene los literales "true" o "1" devolvera \em true, en otro caso devolvera un excepcion.
 425
 426      \param str Cadena a interpretar.
 427
 428      \return El valor booleano correspondiente a la cadena recibida.
 429   */
 430   static bool asBool(const char* str) throw(RuntimeException);
 431
 432   /**
 433      Interpreta la cadena recibida como parametro como un entero de 32 bits.
 434      \return
 435    */
 436   static int asInteger(const char* str) throw() { return atoi(str); }
 437
 438   /**
 439      Interpreta la cadena recibida como parametro como un entero de 32 bits.
 440      \return
 441    */
 442   static S64 asInteger64(const char* str) throw();
 443
 444   /**
 445      Devuelve el identificador de thread desde el que es invocado este metodo.
 446      Si el programa no tuviera soporta para MT siempre devolvera 0.
 447      \return el identificador de thread desde el que es invocado este metodo.
 448   */
 449   static pthread_t getCurrentThread() throw();
 450
 451   /**
 452      Devuelve \em true si la version de nucleo que estamos ejecutado soporta multithread o \em false en otro
 453      caso.
 454      \return \em true si la version de nucleo que estamos ejecutado soporta multithread o \em false en otro
 455   */
 456   static bool supportMultithread() throw() {
 457     WHEN_SINGLETHREAD(return false);
 458     WHEN_MULTITHREAD(return true);
 459   }
 460
 461   /**
 462      Devuelve \em true si el valor recibido cumple el patron establecido o \em false en otro caso.
 463      \param pattern Expresion regular que describe el patron a cumplir.
 464      \param value Cadena a comparar con el patron.
 465      \return \em true si el valor recibido cumple el patron establecido o \em false en otro caso.
 466
 467      \see regexec para mas informacion sobre las expresiones regulares.
 468   */
 469   static bool isLike(const char* pattern, const std::string& value) throw(RuntimeException);
 470
 471   /**
 472    * Devuelve el número de bits necesarios para representar el valor recibido como parámetro.
 473    * \param n Valor a estudiar.
 474    * \return el número de bits necesarios para representar el valor recibido como parámetro.
 475    */
 476   static int bitsize(const int n) throw() {  return (n == 0) ? 1 : functions::log2(n) + 1; }
 477
 478   /**
 479    * Devuelve el número de bits necesarios para representar el valor recibido como parámetro.
 480    * \param n Valor a estudiar.
 481    * \return el número de bits necesarios para representar el valor recibido como parámetro.
 482    */
 483   static int bitsize(const S64 n) throw() {
 484     int aux = n >> intBitSize;
 485     return (aux != 0) ? (bitsize(aux) + intBitSize) : bitsize((int) n);
 486   }
 487
 488   /**
 489    * Calcula la operación (n1 << bitShit) | n2. Establece las comprobaciones necesarias para verificar
 490    * que la operación se realiza correctamente, teniendo especial cuidado de que no se puedan solapar
 491    * ninguno de los valores.
 492    *
 493    * \param whatis Literal que debería identificar el punto de invocación en caso de que haya algún error.
 494    * \param n1 Número a desplazar el nº de bits indicado por \em bitShift.
 495    * \param bitShift Número de bits a desplazar.
 496    * \param n2 Número a combinar con el resultado de la operación (n1 << bitShift).
 497    */
 498   static S64 merge(const char* whatis, const int n1, const int n2, const int bitShift) throw(RuntimeException);
 499
 500   /**
 501    * Calcula el logaritmo en base 2 del número recibo como parámetro.
 502    * \param v Valor a calcular.
 503    * \return El algoritmo en base 2 del número recibido como parámetro o -1 si el parámetro recibido es 0.
 504    */
 505   static int log2(const unsigned int v) throw();
 506
 507
 508
 509
 510   //////////////////////////////////////////////////////////////////////////////////////////////////
 511   // Text format resources /////////////////////////////////////////////////////////////////////////
 512   //////////////////////////////////////////////////////////////////////////////////////////////////
 513   struct TextHighlightMode {
 514     enum _v {
 515       None = -1, // Initialized
 516       Overline,
 517       Underline,
 518       OverAndUnderline,
 519       Leftline,
 520       Rightline,
 521       LeftAndRightline
 522     };
 523   };
 524
 525   struct TextJustifyMode {
 526     enum _v {
 527       None = -1, // Initialized
 528       Left,
 529       Center,
 530       Right
 531     };
 532   };
 533
 534   /**
 535      Solve singular/plural literal expression for any number.
 536      <pre>
 537      Provide (0): returns "no entries"
 538      Provide (1): returns "1 entry"
 539      Provide (2): returns "2 entries"
 540
 541      Provide (0, 'table'): returns "no tables"
 542      Provide (1, 'table'): returns "1 table"
 543      Provide (2, 'table'): returns "2 tables"
 544
 545      Provide (0, 'query', 'queries'): returns "no queries"
 546      Provide (1, 'query', 'queries'): returns "1 query"
 547      Provide (2, 'query', 'queries'): returns "2 queries"
 548      </pre>
 549
 550      @param number Amount processed
 551      @param wordForSingular Word used as singular, 'entry' by default.
 552      @param wordForPlural Word used as plural, 'entries' by default.
 553
 554      @return Coherent literal as '%d <singular word/plural word>'
 555   */
 556   static std::string entriesAsString(int number, const char * wordForSingular = NULL, const char * wordForPlural = NULL) throw();
 557
 558   /**
 559      Justify text (traces and output improvement)
 560
 561      @param title Title processed
 562      @param mode Justify mode: Left (default), Center, Right
 563      @param filler Filler character used (space by default)
 564
 565      @return Processed text
 566   */
 567   static std::string justify(const std::string & title, TextJustifyMode::_v mode = TextJustifyMode::Left, char filler = ' ') throw();
 568
 569   /**
 570      Highligth text (traces and output improvement)
 571
 572      @param title Title processed
 573      @param mode Highlight mode: Overline, Underline(default), OverAndUnderline, Leftline, Rightline, LeftAndRightline
 574      @param filler Filler character used (dash by default)
 575      @param appendCR Carriage return inclusion (true by default)
 576
 577      @return Processed text
 578   */
 579   static std::string highlight(const std::string & title, TextHighlightMode::_v mode = TextHighlightMode::Underline, char filler = '-', bool appendCR = true) throw();
 580
 581   /**
 582      Highligth and justify text (traces and output improvement)
 583
 584      @param title Title processed
 585      @param hMode Highlight mode: Overline, Underline(default), OverAndUnderline, Leftline, Rightline, LeftAndRightline
 586      @param jMode Justify mode: Left (default), Center, Right
 587      @param highlightFiller Filler character used (double dash ('=') by default)
 588      @param justifyFiller Filler character used when justify (space by default)
 589      @param appendCR Carriage return inclusion (true by default)
 590
 591      @return Processed text
 592   */
 593   static std::string highlightJustify(const std::string & title, TextHighlightMode::_v hMode = TextHighlightMode::OverAndUnderline, TextJustifyMode::_v jMode = TextJustifyMode::Center, char highlightFiller = '=', char justifyFiller = ' ', bool appendCR = true) throw() {
 594     return(highlight(justify(title, jMode, justifyFiller), hMode, highlightFiller, appendCR));
 595   }
 596
 597   /**
 598      Tabulate text (traces and output improvement)
 599
 600      @param text Text processed
 601      @param tabSpaces Tab spaces (three by default)
 602   */
 603   static std::string tab(const std::string & text, int tabSpaces = 3) throw();
 604
 605
 606   //////////////////////////////////////////////////////////////////////////////////////////////////
 607   // Conversions and helpers ///////////////////////////////////////////////////////////////////////
 608   //////////////////////////////////////////////////////////////////////////////////////////////////
 609
 610   /**
 611      Pattern to obtain a multi named component instance easily.
 612      Parameters are usually replaced by the macro C <b>FILE_LOCATION</b>.
 613
 614      \param className Component class name
 615      \param fromFile File which called the method
 616      \param fromLine Line number within the file from where the method is called.
 617
 618      \return Component instance for the class provided at the pattern
 619      \see Component
 620   */
 621   template <typename T> static T* componentByName(const char *className, const char* fromFile, const int fromLine)
 622   throw(RuntimeException) {
 623     ComponentManager &cm = ComponentManager::instantiate();
 624     T* result = static_cast <T*>(cm.find(className));
 625
 626     if(result == NULL) {
 627       std::string msg(className);
 628       msg += " | Unregistered component";
 629       throw RuntimeException(msg, fromFile, fromLine);
 630     }
 631
 632     return result;
 633   }
 634
 635   /**
 636      Pattern to obtain a single named component instance easily.
 637      Parameters are usually replaced by the macro C <b>FILE_LOCATION</b>.
 638
 639      \param fromFile File which called the method
 640      \param fromLine Line number within the file from where the method is called.
 641
 642      \return Component instance for the class provided at the pattern
 643      \warning T class must implement a method in the form:
 644      \code
 645          static const char* getClassName () throw ();
 646      \endcode
 647      \see Component
 648   */
 649   template <typename T> static T* component(const char* fromFile, const int fromLine)
 650   throw(RuntimeException) {
 651     return functions::componentByName<T> (T::getClassName(), fromFile, fromLine);
 652   }
 653
 654   /**
 655      Finds string at the end of another
 656
 657      @param pattern String where we find
 658      @param suffix Searched string
 659
 660      @return Boolean about ocurrency
 661   */
 662   static bool endsWith(const std::string & pattern, const std::string & suffix) throw() {
 663     std::string dummy;
 664     return endsWith(pattern, suffix, dummy);
 665   }
 666
 667   /**
 668      Similar to #endsWith but returning additional preffix string by reference (pattern without suffix)
 669   */
 670   static bool endsWith(const std::string & pattern, const std::string & suffix, std::string & preffix) throw();
 671
 672   /**
 673      Finds string at the begining of another
 674
 675      @param pattern String where we find
 676      @param preffix Searched string
 677
 678      @return Boolean about ocurrency
 679   */
 680   static bool startsWith(const std::string & pattern, const std::string & preffix) throw() {
 681     std::string dummy;
 682     return startsWith(pattern, preffix, dummy);
 683   }
 684
 685   /**
 686      Similar to #startsWith but returning additional suffix string by reference (pattern without preffix)
 687   */
 688   static bool startsWith(const std::string & pattern, const std::string & preffix, std::string & suffix) throw();
 689
 690   /**
 691      Finds 'item' and replaces it with 'target' within the string provided ('text').
 692      The result is returned.
 693
 694      @param text Original string
 695      @param item Searched string
 696      @param target String which replaces the item
 697      @param all Boolean about replace all items or only the first found. True by default.
 698
 699      @return Modified string
 700   */
 701   static std::string replace(const std::string & text, const char *item, const char *target, bool all = true) throw();
 702
 703   /**
 704   * Coverts original string without quotation into quoted one: '\%s'
 705   */
 706   static std::string addQuotationMarks(const std::string & str) throw();
 707   static std::string addQuotationMarks(const char * str) throw();
 708   static std::string addQuotationMarks(const int & integer) throw();
 709
 710   /**
 711   * Generates space-separated string lists based on integer elements
 712   * Also, another separator could be used.
 713   */
 714   static std::string vectorToStringRepresentation(const std::vector<int> & v, const char separator = ' ') throw();
 715
 716   /**
 717   * Generates space-separated string lists based on string elements.
 718   * Also, another separator could be used.
 719   */
 720   static std::string vectorToStringRepresentation(const std::vector<std::string> & v, const char separator = ' ') throw();
 721
 722   /**
 723      Returns socket notation 'Address:Port'
 724   */
 725   static std::string socketLiteralAsString(const std::string & address, int port) throw();
 726
 727   /**
 728      Ascii string for buffer/size data block
 729
 730      @param buffer Octet string buffer
 731      @param size Buffer size
 732      @param isFullyPrintable Returned by reference
 733
 734      @return Ascii string representation, and dots for non-printable cheracters
 735   */
 736   static std::string asAsciiString(const char * buffer, int size, bool & isFullyPrintable) throw();
 737
 738   /**
 739      Same as #asAsciiString but without interest about if is printable or not
 740   */
 741   static std::string asAsciiString(const char * buffer, int size) throw() {
 742     bool isFullyPrintable;
 743     return asAsciiString(buffer, size, isFullyPrintable);
 744   }
 745
 746   /**
 747      Same as #asAsciiString providing anna::DataBlock
 748   */
 749   static std::string asAsciiString(const DataBlock & db, bool & isFullyPrintable) throw() {
 750     return asAsciiString(db.getData(), db.getSize(), isFullyPrintable);
 751   }
 752
 753   /**
 754      Same as #asAsciiString providing DataBlock and without interest about if is printable or not
 755   */
 756   static std::string asAsciiString(const DataBlock & db) throw() {
 757     bool isFullyPrintable;
 758     return asAsciiString(db.getData(), db.getSize(), isFullyPrintable);
 759   }
 760
 761
 762   /**
 763    * IP Address enconding based on common database 'human-readable raw presentation':
 764    * <pre>
 765    *    Example for IPv4: 'AABBCCDD' will be DataBlock for '170.187.204.221'
 766    *    Example for IPv6: '20010DB885A3000000008A2E03707334' will be DataBlock for '2001:0db8:85a3:0000:0000:8a2e:0370:7334'
 767    *
 768    *    '000000000000000000000000AABBCCDD' will be encoded as 16-sized Datablock, not IPv4 (4 bytes). Is not recommended to
 769    *    put IPv4 on this way because of ambiguity regarding IPv4-compatible format. It is application responsability to trim
 770    *    leading zeros in order to use this method for IPv4 source.
 771    * </pre>
 772    *
 773    * @param rawPresentation Input IP address as raw presentation. Must be 8 or 32 sized for IPv4 and IPv6 respectively.
 774    *
 775    * @return Encoded DataBlock
 776    */
 777   static DataBlock rawIpPresentationAsRaw(const std::string & rawPresentation) throw(RuntimeException);
 778
 779
 780   /**
 781    * IP Address decoding from raw presentation:
 782    * <pre>
 783    *    Example for IPv4: 'AABBCCDD' will be '170.187.204.221'
 784    *    Example for IPv6: '20010DB885A3000000008A2E03707334' will be '2001:0db8:85a3:0000:0000:8a2e:0370:7334'
 785    *
 786    *    '000000000000000000000000AABBCCDD' will be internally encoded as 16-sized Datablock, not IPv4 (4 bytes).
 787    *    Is not recommended to put IPv4 on this way because of ambiguity regarding IPv4-compatible format. It is
 788    *    application responsability to trim leading zeros in order to use this method for IPv4 source.
 789    * </pre>
 790    *
 791    * @param rawPresentation Input IP address as raw presentation. Must be 8 or 32 sized for IPv4 and IPv6 respectively.
 792    * @param normalize Normalize returned address representation, 'false' by default (to avoid IPv4 to IPv6 conversion)
 793    *
 794    * @return Decoded IP address
 795    */
 796   static std::string rawIpPresentationToIpAsString(const std::string & rawPresentation, bool normalize = false) throw(RuntimeException) {
 797     return rawIpAsString(rawIpPresentationAsRaw(rawPresentation), normalize);
 798   }
 799
 800
 801   /**
 802    * IP Address decoding to 'human-readable raw presentation':
 803    * <pre>
 804    *    Example for IPv4: DataBlock for '170.187.204.221' will be 'AABBCCDD' (a pure IPv4 will never contain leading zeros outside of its scope (i.e., 24 zeros on a 32-character presentation)
 805    *    Example for IPv6: DataBlock for '2001:0db8:85a3:0000:0000:8a2e:0370:7334' will be '20010DB885A3000000008A2E03707334'
 806    *
 807    *    DataBlock for '::170.187.204.221' will be represented as IPv4 compatible: '000000000000000000000000AABBCCDD'
 808    * </pre>
 809    *
 810    * @param db Encoded DataBlock with 4 or 16 bytes to represent Ipv4 or Ipv6.
 811    *
 812    * @return Human-readable raw IP presentation
 813    */
 814   static std::string rawIpAsRawIpPresentation(const DataBlock & db) throw(RuntimeException);
 815
 816
 817   /**
 818    * Gets the host name (system name)
 819    *
 820    * @return Hostname
 821    */
 822   static std::string getHostname() throw();
 823
 824   /**
 825    * Gets the domain name
 826    *
 827    * @return Domainname
 828    */
 829   static std::string getDomainname() throw();
 830
 831   /**
 832    * Gets the FQDN (Fully Qualified Domain Name)
 833    *
 834    * @param hostname Specific provided hostname. Automatically solved if missing. Empty string implies exclusion from FQDN.
 835    * @param domainname Specific provided domainname. Automatically solved if missing. Empty string implies exclusion from FQDN.
 836    *
 837    * @return FQDN (<hostname>.<domainname>)
 838    */
 839   static std::string getFQDN(const char *hostname = NULL, const char  *domainname = NULL) throw();
 840
 841   /**
 842    * Gets the IP based on hostname (#getHostname)
 843    *
 844    * @return Hostname-based IP
 845    */
 846   static std::string getHostnameIP() throw();
 847
 848
 849
 850   //////////////////////////////////////////////////////////////////////////////////////////////////
 851   // IP Address resources //////////////////////////////////////////////////////////////////////////
 852   //////////////////////////////////////////////////////////////////////////////////////////////////
 853
 854   /**
 855   * IPv4 subtype (Estrict/Compatible)
 856   */
 857   struct IPv4Type {
 858     enum _v {
 859       Estrict = -1, // Initialized,
 860       Compatible,
 861       Mapped
 862     };
 863   };
 864
 865   /**
 866   * IPv4 address family detection
 867   *
 868   * @param ip IP address
 869   * @param ipv4Type Check for IPv4-compatible (i.e. '::192.168.0.1'), IPv4-mapped (i.e. '2001:0db8:85a3:0000:0000:8a2e:192.168.0.1') or estrict IPv4 format.
 870   *
 871   * @return Boolean for IPv4 nature
 872   */
 873   static bool isIPv4(const std::string & ip, IPv4Type::_v ipv4Type = IPv4Type::Estrict) throw();
 874
 875   /**
 876   * IPv6 address family detection
 877   *
 878   * @param ip IP address
 879   *
 880   * @return Boolean for IPv6 nature
 881   */
 882   static bool isIPv6(const std::string & ip) throw();
 883
 884   /**
 885    * Convert an IPv4 address to IPv6. Also removes dots from IPv4-mapped format.
 886    *
 887    * @param ipv4 IP Address in dot notation (192.168.1.100)
 888    *
 889    * @return string IPv6 formatted address or launch exception if invalid input
 890    */
 891   static std::string IPv4To6(const std::string & ipv4) throw(RuntimeException);
 892
 893   /**
 894    * Normalizes an IP address to long notation. Specially used for IPv6, but valid for IPv4 (via IPv4To6 conversion).
 895    *
 896    * Examples:
 897    *  ::1 ->                          0000:0000:0000:0000:0000:0000:0000:0001
 898    *  2001:db8:85a3::8a2e:370:7334 -> 2001:0db8:85a3:0000:0000:8a2e:0370:7334
 899    *
 900    * @param ip Input IP address
 901    *
 902    * @return Normalized IP address
 903    */
 904   static std::string normalizeIP(const std::string & ip) throw(RuntimeException);
 905
 906   /**
 907    * Compare two IP addresses by mean normalization
 908    *
 909    * @param ip1 First IP address compared
 910    * @param ip2 Second IP address compared
 911    *
 912    * @return Boolean about IP's comparison
 913    */
 914   static bool sameIP(const std::string & ip1, const std::string & ip2) throw(RuntimeException);
 915
 916   /**
 917    * Compare two IP addresses by mean internal comparison after ipv6 preffix restriction
 918    *
 919    * @param ipv6 IPv6 address matched
 920    * @param preffixedIpv6 Preffixed IPv6 address (<ipv6>/<preffix length>: only values from 0 (always match) to 128 (maximum restriction) are allowed).
 921    *
 922    * @return Boolean about subnet matching
 923    */
 924   static bool matchIPv6(const std::string & ipv6, const std::string & preffixedIpv6) throw(RuntimeException);
 925
 926   /**
 927    * IP Address serialization
 928    *
 929    * @param ip Input IP address
 930    *
 931    * @return Encoded DataBlock
 932    */
 933   static DataBlock ipAsRaw(const std::string & ip) throw(RuntimeException);
 934
 935   /**
 936    * IP Address decoding
 937    *
 938    * @param db Encoded DataBlock with 4 or 16 bytes to represent Ipv4 or Ipv6.
 939    * @param normalize Normalize returned address representation, 'false' by default (to avoid IPv4 to IPv6 conversion)
 940    *
 941    * @return Decoded IP address
 942    */
 943   static std::string rawIpAsString(const DataBlock & db, bool normalize = false) throw(RuntimeException) {
 944     return (rawIpAsString(db.getData(), db.getSize(), normalize));
 945   }
 946
 947   /**
 948    * IP Address decoding
 949    *
 950    * @param buffer Encoded buffer with 4 or 16 bytes to represent Ipv4 or Ipv6.
 951    * @param bufferLength Encoded buffer length with 4 or 16 bytes to represent Ipv4 or Ipv6.
 952    * @param normalize Normalize returned address representation, 'false' by default (to avoid IPv4 to IPv6 conversion)
 953    *
 954    * @return Decoded IP address
 955    */
 956   static std::string rawIpAsString(const char *buffer, int bufferLength, bool normalize = false) throw(RuntimeException);
 957
 958   /**
 959    * Abbreviates an IP address. Specially used for IPv6, but valid for IPv4.
 960    *
 961    * Examples:
 962    *  0000:0000:0000:0000:0000:0000:0000:0001 -> ::1
 963    *  2001:0db8:85a3:0000:0000:8a2e:0370:7334 -> 2001:db8:85a3::8a2e:370:7334
 964    *
 965    * @param ip Input IP address
 966    *
 967    * @return Abbreviated IP address
 968    */
 969   static std::string abbreviateIP(const std::string & ip) throw(RuntimeException) {
 970     return (rawIpAsString(ipAsRaw(ip)));
 971   }
 972
 973
 974
 975
 976   // socket literal description typedef, vectors and conversion tools
 977
 978   /**
 979   * Extract ADDRESS (ip or hostname ro resolve) and PORT from socket literal description ('<ip|hostname>:<port>').
 980   *
 981   * @param literal Socket literal in format '<ip|hostname>:<port>'
 982   * @param address Address extracted by reference
 983   * @param port Port extracted by reference
 984   */
 985   static void getAddressAndPortFromSocketLiteral(const std::string &literal, std::string &address, int &port) throw();
 986
 987   /**
 988   * Translate pipe-separated socket literal list into Address/Port vector.
 989   *
 990   * @param list Comma-separated Address/Port list. I.e.: '10.95.10.25:4000,10.95.10.25:4001', or 'fed1:4000,fed2:4001'
 991   * @return Address/Port socket items vector
 992   */
 993   static socket_v getSocketVectorFromString(const std::string & list) throw();
 994
 995   /**
 996   * Translate Address/Port vector into comma-separated Address/Port list.
 997   *
 998   * @param socketVector Address/Port vector
 999   *
1000   * @return Comma-separated Address/Port list. I.e.: '10.95.10.25:4000,10.95.10.25:4001', or 'fed1:4000,fed2:4001'
1001   */
1002   static std::string socketVectorAsString(const socket_v & socketVector) throw();
1003
1004
1005   /**
1006     Endianess of the system
1007
1008     @result Returns true when the system is little endian, false if big endian
1009   */
1010   static bool littleEndian() throw();
1011
1012   /**
1013      Encodes an integer number with 32 bits over a buffer with at least 4 bytes of length.
1014      @param result Buffer where the number is encoded.
1015      @param n Number to encode.
1016      \return Buffer with the encoded number.
1017    */
1018   static const char* codeInteger(char* result, const int n) throw();
1019
1020   /**
1021      Encodes an integer number with 16 bits over a buffer with at least 2 bytes of length.
1022      @param result Buffer where the number is encoded.
1023      @param n Number to encode.
1024      \return Buffer with the encoded number.
1025   */
1026   static const char* codeShort(char* result, const short int n) throw();
1027
1028   /**
1029      Encodes an integer number with 64 bits over a buffer with at least 8 bytes of length.
1030      @param result Buffer where the number is encoded.
1031      @param n Number to encode.
1032      \return Buffer with the encoded number.
1033    */
1034   static const char* codeInteger64(char* result, const S64 n) throw();
1035
1036   /**
1037      Encodes a floating number with 32 bits (according to the standard IEEE-754) over a buffer with at least 4 bytes of length.
1038      @param result Buffer where the number is encoded.
1039      @param n Number to encode.
1040      \return Buffer with the encoded number.
1041    */
1042   static const char* codeFloat(char* result, const float n) throw();
1043
1044   /**
1045      Encodes a floating number with 64 bits (according to the standard IEEE-754) over a buffer with at least 8 bytes of length.
1046      @param result Buffer where the number is encoded.
1047      @param n Number to encode.
1048      \return Buffer with the encoded number.
1049    */
1050   static const char* codeDouble(char* result, const double n) throw();
1051
1052   /**
1053      Decodes an 32 bits integer number contained in a 4-bytes buffer.
1054      @param data Buffer with the encoded number.
1055      @return Value for the number contained in the buffer.
1056   */
1057   static int decodeInteger(const char* data)  throw();
1058
1059   /**
1060      Decodes an 16 bits integer number contained in a 2-bytes buffer.
1061      @param data Buffer with the encoded number.
1062      @return Value for the number contained in the buffer.
1063   */
1064   static short int decodeShort(const char* data)  throw();
1065
1066   /**
1067      Decodes an 64 bits integer number contained in a 8-bytes buffer.
1068      @param data Buffer with the encoded number.
1069      @return Value for the number contained in the buffer.
1070   */
1071   static S64 decodeInteger64(const char* data)  throw();
1072
1073   /**
1074      Decodes an 32 bits floating number (according to the standard IEEE-754) contained in a 4-bytes buffer.
1075      @param data Buffer with the encoded number.
1076      @return Value for the number contained in the buffer.
1077   */
1078   static float decodeFloat(const char* data)  throw();
1079
1080   /**
1081      Decodes an 64 bits floating number (according to the standard IEEE-754) contained in a 8-bytes buffer.
1082      @param data Buffer with the encoded number.
1083      @return Value for the number contained in the buffer.
1084   */
1085   static double decodeDouble(const char* data)  throw();
1086
1087
1088   /**
1089   * Decodes an ISUP Number (called or calling party number).
1090   *
1091   * @param buffer Isup number content buffer.
1092   * @param length Isup number content length.
1093   * @param isupNumber Isup number decoded by reference.
1094   * @param calledOrCalling True for called party number, false for calling
1095   */
1096   static void decodeIsupNumber(const char *buffer, int length, isup_number_t & isupNumber, bool calledOrCalling) throw(RuntimeException);
1097
1098   /**
1099   * Encodes an ISUP Number (called or calling party number).
1100   *
1101   * @param isupNumber Isup number.
1102   * @param calledOrCalling True for called party number, false for calling
1103   * @param buffer Isup number content encoded buffer.
1104   * @param length Isup number content encoded length.
1105   */
1106   static void codeIsupNumber(const isup_number_t & isupNumber, bool calledOrCalling, char * buffer, int & length) throw(RuntimeException);
1107
1108   /**
1109   * Encodes an ISUP Number (called or calling party number).
1110   *
1111   * @param isupNumber Isup number.
1112   * @param calledOrCalling True for called party number, false for calling
1113   * @param target Isup number octet string.
1114   */
1115   static void codeIsupNumber(const isup_number_t & isupNumber, bool calledOrCalling, std::string & target) throw(RuntimeException);
1116 };
1117
1118 }
1119
1120 #endif
1121