Updated license

[anna.git] / source / core / functions.cpp

// ANNA - Anna is Not Nothingness Anymore
//
// (c) Copyright 2005-2014 Eduardo Ramos Testillano & Francisco Ruiz Rayo
//
// https://bitbucket.org/testillano/anna
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions
// are met:
//
//     * Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
//     * Redistributions in binary form must reproduce the above
// copyright notice, this list of conditions and the following disclaimer
// in the documentation and/or other materials provided with the
// distribution.
//     * Neither the name of Google Inc. nor the names of its
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
// Authors: eduardo.ramos.testillano@gmail.com
//          cisco.tierra@gmail.com


#include <stdarg.h>
#include <ctype.h>
#include <poll.h>
#include <time.h>
#include <sys/time.h>
#include <pthread.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/types.h>
#include <regex.h>
#include <sys/utsname.h>
#include <arpa/inet.h>
#include <sys/socket.h> // extraccion de IP del hostname
#include <netinet/in.h> // extraccion de IP del hostname
#include <netdb.h> // extraccion de IP del hostname
#include <unistd.h> // gethostname

#include <anna/core/functions.hpp>
#include <anna/core/DataBlock.hpp>
#include <anna/core/tracing/Logger.hpp>
#include <anna/core/util/Second.hpp>
#include <anna/core/util/Tokenizer.hpp>

#include <algorithm>


using namespace anna;
using namespace std;

#define PAGE_WIDTH_LENGTH      80

ExclusiveHash <std::string> functions::st_stringExclusiveHash;
ExclusiveHash <std::string, int> functions::st_string2intExclusiveHash;

string functions::getVersion() throw() {
  static const int version = ANNA_VERSION;
  string result;
  int mainVersion = (version & 0xff00) >> 8;
  int subVersion = (version & 0xff);
  char aux [32];
  sprintf(aux, "%d.%d", mainVersion, subVersion);
  result = aux;
  return result += getArchitecture();
}

/*
(1) Solo coge los dos primeros digitos del numero de release
*/
string functions::getArchitecture() throw() {
  string result;
  WHEN_MULTITHREAD(result = "/MT");
  WHEN_SINGLETHREAD(result = "/ST");
#ifdef _DEBUG
  result += "/D";
#else
  result += "/O";
#endif
#ifdef _PROFILE
  result += 'P';
#endif
  struct utsname un;
  uname(&un);
  result += '/';
  result += un.sysname;
  result += ' ';
  char* release = anna_strchr(un.release, '.');               // (1)

  if(release != NULL)
    if((release = anna_strchr(release + 1, '.')) != NULL)
      * release = 0;

  result += un.release;
  result += " (";
  result += un.machine;
  result += ")";
  return result;
}

string functions::asString(const int number)
throw() {
  char aux [16];
  sprintf(aux, "%d", number);
  return string(aux);
}

string functions::asString(const unsigned long number)
throw() {
  return asString((U64)number);
}

string functions::asString(const S64 number)
throw() {
  char aux [24];
  sprintf(aux, "%lld", number);
  /*#ifdef __anna64__
     sprintf (aux, "%ld", number);
  #else
     sprintf (aux, "%lld", number);
  #endif
  */
  return string(aux);
}

string functions::asString(const unsigned int number)
throw() {
  char aux [16];
  sprintf(aux, "%u", number);
  return string(aux);
}

string functions::asString(const U64 number)
throw() {
  char aux [16];
  sprintf(aux, "%llu", number);
  /*
  #ifdef __anna64__
     sprintf (aux, "%lu", number);
  #else
     sprintf (aux, "%llu", number);
  #endif
  */
  return string(aux);
}

string functions::asString(const float number, const char* format)
throw() {
  char aux [64];
  sprintf(aux, format, number);
  return string(aux);
}

string functions::asString(const double number, const char* format)
throw() {
  char aux [64];
  sprintf(aux, format, number);
  return string(aux);
}

string functions::asDateTime(const Second &second)
throw() {
  char aux [DateTimeSizeString];
  return std::string(asDateTime(second, aux));
}

const char* functions::asDateTime(const Second &second, char* result)
throw() {
  struct tm* tt = localtime((time_t*) & second);
  sprintf(
    result, "%02d/%02d/%4d %02d:%02d:%02d",
    tt->tm_mday, tt->tm_mon + 1, tt->tm_year + 1900,
    tt->tm_hour, tt->tm_min, tt->tm_sec
  );
  return result;
}

std::string functions::asString(const DataBlock& dataBlock, const int characterByLine)
throw() {
  return dataBlock.asString(characterByLine);
}

string functions::asHexString(const int number)
throw() {
  char aux [16];
  sprintf(aux, "0x%x", number);
  return string(aux);
}

string functions::asHexString(const long number)
throw() {
  return asHexString((S64)number);
}

string functions::asHexString(const S64 number)
throw() {
  char aux [32];
  sprintf(aux, "0x%llx", number);
  /*
  #ifdef __anna64__
     sprintf (aux, "0x%lx", number);
  #else
     sprintf (aux, "0x%llx", number);
  #endif
  */
  return string(aux);
}

// from a version by Allen Holub (see Andrew Binstock, "Hashing Revisited"
// Dr. Dobb's Journal, April 1996)
S64 functions::hash(const char* p)
throw() {
  static const int long_bits = sizeof(S64) << 3;
  static const int one_eighth = long_bits >> 3;
  static const int three_fourths = long_bits * 3 / 4;
  static const S64 high_bits = ((S64)(~0L)) << (long_bits - one_eighth);
  S64 result = 0;
  S64 temp;

  while(*p != 0) {
    result = (result << one_eighth) + *p ++;

    if((temp = result & high_bits) != 0)
      result = (result ^(temp >> three_fourths)) &~ high_bits;
  }

  return result;
}

//static
std::string functions::asHexString(const DataBlock& dataBlock)
throw() {
  const char* buffer = dataBlock.getData();
  const int size = dataBlock.getSize();
  string result;
  int byte;

  for(int ii = 0; ii < size; ii ++) {
    byte = (buffer [ii] & 0xf0) >> 4;
    result += (byte >= 0 && byte <= 9) ? (byte + '0') : ((byte - 0xa) + 'a');
    byte = (buffer [ii] & 0x0f);
    result += (byte >= 0 && byte <= 9) ? (byte + '0') : ((byte - 0xa) + 'a');
  }

  return result;
}

/**
 * Obtiene el valor original de una cadena obtenido con #asHexString (const DataBlock&).
 * \param hexString Cadena que contiene el búfer.
 * \param target Bloque de datos sobre el que decodificar la cadena.
 * \return El bloque de datos original correspondiente a la cadena recibida.
 */
//static
DataBlock& functions::fromHexString(const std::string& hexString, DataBlock& target)
throw(RuntimeException) {
  if((hexString.length() % 2) != 0)
    throw RuntimeException("functions::fromHexString | Invalid string length", ANNA_FILE_LOCATION);

  target.clear();
  const char* src = hexString.data();
  unsigned char hex;
  int aux;
  int j = 0;

  for(register int ii = 1, maxii = hexString.length(); ii < maxii; ii += 2) {
    if(isxdigit(aux = src [ii - 1]) == 0)
      throw RuntimeException("Invalid HexString", ANNA_FILE_LOCATION);

    hex = ((aux >= '0' && aux <= '9') ? (aux - '0') : ((aux - 'a') + 0x0a)) << 4;

    if(isxdigit(aux = src [ii]) == 0)
      throw RuntimeException("Invalid HexString", ANNA_FILE_LOCATION);

    hex |= (aux >= '0' && aux <= '9') ? (aux - '0') : ((aux - 'a') + 0x0a);
    target += hex;
  }

  return target;
}

string functions::asString(const char* format, ...)
throw() {
  va_list ap;
  char aux [1024];
  va_start(ap, format);
  vsnprintf(aux, sizeof(aux), format, ap);
  va_end(ap);
  return string(aux);
}

void functions::sleep(const Millisecond &millisecond)
throw() {
  timespec req;
  timespec rem;
  req.tv_sec = millisecond.getValue() / 1000;                          // segundos
  req.tv_nsec = (millisecond.getValue() % 1000);                       // milisegundos
  req.tv_nsec *= 1000000;                                   // mili = 10e-3, nano=10-9
  int r;

  while((r = nanosleep(&req, &rem)) != 0) {
    if(errno == EINTR)
      req = rem;
    else {
      string msg(asText("functions::sleep | timespec { sec: ", (int) req.tv_sec));
      msg += functions::asText("| nsec: ", (int) req.tv_nsec);
      msg += " }";
      RuntimeException ex(msg, errno, ANNA_FILE_LOCATION);
      ex.trace();
      break;
    }
  }
}

bool functions::asBool(const char* str)
throw(RuntimeException) {
  if(str == NULL)
    return false;

  if(strcasecmp(str, "true") == 0 || anna_strcmp(str, "1") == 0)
    return true;

  if(strcasecmp(str, "false") == 0 || anna_strcmp(str, "0") == 0)
    return false;

  string msg("anna::funcions::asBool | Cannot interpret '");
  msg += str;
  msg += "' as boolean";
  throw RuntimeException(msg, ANNA_FILE_LOCATION);
}

S64 functions::asInteger64(const char* str)
throw() {
  S64 number = 0;
  sscanf(str, "%lld", &number);
  /*
  #ifdef __anna64__
    sscanf (str, "%ld", &number);
  #else
     sscanf (str, "%lld", &number);
  #endif
  */
  return number;
}

pthread_t functions::getCurrentThread()
throw() {
  WHEN_MULTITHREAD(return pthread_self());
  WHEN_SINGLETHREAD(return 0);
}

bool functions::isLike(const char* pattern, const std::string& _value)
throw(RuntimeException) {
  const char* value = _value.c_str();
  regex_t preg;
  int ret;

  if((ret = regcomp(&preg, pattern, REG_EXTENDED)) != 0) {
    char err[256];
    string msg("anna::functions::isLike | ");
    msg += " | Pattern: ";
    msg += pattern;
    msg += " | Value: ";
    msg += value;
    msg += " | ";

    if(regerror(ret, &preg, err, sizeof(err)))
      msg += err;
    else
      msg += "Invalid pattern";

    throw RuntimeException(msg, ANNA_FILE_LOCATION);
  }

  const bool result = (regexec(&preg, value, 0, NULL, 0) == 0) ? true : false;

  regfree(&preg);
  return result;
}

/*static*/
S64 functions::merge(const char* whatis, const int n1, const int n2, const int bitShift)
throw(RuntimeException) {
  if(bitShift > intBitSize) {
    string msg(functions::asString("%s | N1: 0x%x | N2: 0x%x | bitShift: %d | bitShift must be less than %d", whatis, n1, n2, bitShift, intBitSize));
    throw RuntimeException(msg, ANNA_FILE_LOCATION);
  }

  if((bitsize(n1) + bitShift) > int64BitSize) {
    string msg(functions::asString("%s | N1: 0x%x | N2: 0x%x | bitShift: %d | N1 overload", whatis, n1, n2, bitShift));
    throw RuntimeException(msg, ANNA_FILE_LOCATION);
  }

  if(bitsize(n2) > bitShift) {
    string msg(functions::asString("%s | N1: 0x%x | N2: 0x%x | bitShift: %d | N2 overload", whatis, n1, n2, bitShift));
    throw RuntimeException(msg, ANNA_FILE_LOCATION);
  }

  S64 result = n1;
  result <<= bitShift;
  result |= n2;

  if(bitShift == intBitSize) {
    LOGINFORMATION(
      string msg(functions::asString("%s | N1: 0x%x | N2: 0x%x | bitShift: %d | ", whatis, n1, n2, bitShift));
      msg += functions::asHexString(result);
      Logger::information(msg, ANNA_FILE_LOCATION);
    );
  }

  return result;
}

/*static*/
/*
 * Basado en el algoritmo de http://www-graphics.stanford.edu/~seander/bithacks.html#IntegerLogLookup
 */
int functions::log2(const unsigned int v)
throw() {
  static const char LogTable256[] = {
    -1, 0, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3, 3, 3, 3, 3,
    4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4,
    5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5,
    5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5,
    6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6,
    6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6,
    6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6,
    6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6,
    7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7,
    7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7,
    7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7,
    7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7,
    7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7,
    7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7,
    7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7,
    7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7
  };
  int r = -1;     // r will be lg(v)
  register unsigned int t, tt; // temporaries

  if(tt = v >> 16) {
    r = (t = tt >> 8) ? 24 + LogTable256[t] : 16 + LogTable256[tt];
  } else {
    r = (t = v >> 8) ? 8 + LogTable256[t] : LogTable256[v];
  }

  return r;
}

std::string functions::entriesAsString(int number, const char * wordForSingular, const char * wordForPlural) throw() {
  std::string result;
  std::string singular = (wordForSingular ? wordForSingular : "entry");
  std::string plural = (wordForPlural ? wordForPlural : "entries");

  if(wordForSingular && !wordForPlural)
    plural = singular + "s";

  result += ((number != 0) ? anna::functions::asString(number) : "no");
  result += " ";
  result += ((number != 1) ? plural : singular);
  return result;
}


std::string functions::justify(const std::string & title, TextJustifyMode::_v mode, char filler) throw() {
  std::string result;
  int d_size = title.size();
  int repeat = PAGE_WIDTH_LENGTH - d_size - 1;
  bool adjust = false;

  if(mode == TextJustifyMode::Center) {
    repeat = (repeat - 1) / 2;
    adjust = (2 * (repeat + 1) + d_size != PAGE_WIDTH_LENGTH);
  }

  if((mode == TextJustifyMode::Right) || (mode == TextJustifyMode::Center)) {
    for(register int k = 0; k < (repeat + (adjust ? 1 : 0)); k++) result += filler;

    result += " ";
  }

  result += title;

  if((mode == TextJustifyMode::Left) || (mode == TextJustifyMode::Center)) {
    result += " ";

    for(register int k = 0; k < repeat; k++) result += filler;
  }

  return result;
}


std::string functions::highlight(const std::string & title, TextHighlightMode::_v mode, char filler, bool appendCR) throw() {
  std::string result;
  int ou_repeat = title.size();
  int lr_repeat = PAGE_WIDTH_LENGTH - ou_repeat - 1;
  bool adjust = false;

  if(mode == TextHighlightMode::LeftAndRightline) {
    lr_repeat = (lr_repeat - 1) / 2;
    adjust = (2 * (lr_repeat + 1) + ou_repeat != PAGE_WIDTH_LENGTH);
  }

  if((mode == TextHighlightMode::Leftline) || (mode == TextHighlightMode::LeftAndRightline)) {
    for(register int k = 0; k < (lr_repeat + (adjust ? 1 : 0)); k++) result += filler;

    result += " ";
  }

  if((mode == TextHighlightMode::Overline) || (mode == TextHighlightMode::OverAndUnderline)) {
    for(register int k = 0; k < ou_repeat; k++) result += filler;

    result += "\n";
  }

  result += title;

  if((mode == TextHighlightMode::Underline) || (mode == TextHighlightMode::OverAndUnderline)) {
    result += "\n";

    for(register int k = 0; k < ou_repeat; k++) result += filler;
  }

  if((mode == TextHighlightMode::Rightline) || (mode == TextHighlightMode::LeftAndRightline)) {
    result += " ";

    for(register int k = 0; k < lr_repeat; k++) result += filler;
  }

  if(appendCR) result += "\n";

  return result;
}


std::string functions::tab(const std::string & text, int tabSpaces) throw() {
  std::string result;
  size_t pos, from = 0;
  std::string tab, crTab = "\n";

  for(register int k = 0; k < tabSpaces; k++) tab += " ";

  crTab += tab;
  result = tab;
  result += text;

  while(((pos = result.find('\n', from)) != std::string::npos) && (pos != (result.size() - 1)/*exclude last CR if exists*/)) {
    result.replace(pos, 1, crTab);
    from = pos + 1;
  }

  return result;
}


bool functions::endsWith(const std::string & pattern, const std::string & suffix, std::string & preffix) throw() {
  preffix = "";

  if(pattern.size() < suffix.size()) return false;

  size_t pos = pattern.rfind(suffix);

  if(pos == std::string::npos) return false;

  preffix.assign(pattern.c_str(), pos);
  return (pos == (pattern.size() - suffix.size()));
}


bool functions::startsWith(const std::string & pattern, const std::string & preffix, std::string & suffix) throw() {
  suffix = "";

  if(pattern.size() < preffix.size()) return false;

  if(pattern.find(preffix) != 0) return false;

  suffix.assign(pattern.c_str(), preffix.size(), pattern.size() - preffix.size());
  return true;
}


std::string functions::replace(const std::string & text, const char *item, const char *target, bool all) throw() {
  std::string result = text;

  if(!item || !target) return result;  // protection for NULL strings provided

  size_t lengthReplaced = strlen(item);
  size_t pos = result.find(item);

  while(pos != std::string::npos) {
    result.replace(pos, lengthReplaced, target);

    if(!all) break;

    pos = result.find(item);
  }

  return result;
}


std::string functions::addQuotationMarks(const std::string & str) throw() {
  std::string result = "'";
  result += str;
  result += "'";
  return (result);
}


std::string functions::addQuotationMarks(const char * str) throw() {
  std::string result = "'";
  result += (str ? str : "<null>");
  result += "'";
  return (result);
}


std::string functions::addQuotationMarks(const int & integer) throw() {
  std::string result = "'";
  result += anna::functions::asString(integer);
  result += "'";
  return (result);
}


std::string functions::vectorToStringRepresentation(const std::vector<int> & v, const char separator) throw() {
  std::string result = "";

  if(v.size() != 0) {
    std::vector<int>::const_iterator iter;
    std::vector<int>::const_iterator iter_min(v.begin());
    std::vector<int>::const_iterator iter_max(v.end());

    for(iter = iter_min; iter != iter_max; iter++) {
      result += anna::functions::asString(*iter);
      result += separator;
    }

    // Delete the last space: starts at 'size()-1', take 1 caracter:
    result.erase(result.size() - 1, 1);
  }

  return (result);
}


std::string functions::vectorToStringRepresentation(const std::vector<std::string> & v, const char separator) throw() {
  std::string result = "";

  if(v.size() != 0) {
    std::vector<std::string>::const_iterator iter;
    std::vector<std::string>::const_iterator iter_min(v.begin());
    std::vector<std::string>::const_iterator iter_max(v.end());

    for(iter = iter_min; iter != iter_max; iter++) {
      result += (*iter);
      result += separator;
    }

    // Delete the last space: starts at 'size()-1', take 1 caracter:
    result.erase(result.size() - 1, 1);
  }

  return (result);
}


std::string functions::socketLiteralAsString(const std::string & address, int port) throw() {
  std::string result = address;
  result += ":";
  result += anna::functions::asString(port);
  return result;
}


std::string functions::asAsciiString(const char * buffer, int size, bool & isFullyPrintable) throw() {
  std::string result;
  // Supposed printable by default:
  isFullyPrintable = true;

  if(size == 0 || !buffer) {
    result = "<null>";
    isFullyPrintable = false;
    return result;
  }

  for(register int k = 0; k < size; k ++) {
    unsigned char c = (unsigned char) buffer [k];
    int printable = isprint(c);
    result += (printable ? (char) c : '.');

    if(!printable) isFullyPrintable = false;
  }

  return result;
}


std::string functions::getHostname() throw() {
  char aux[255];
  std::string result = "<hostname>";

  if(gethostname(aux, sizeof aux) == 0 /*success*/)
    result = aux;

  return result;
}

std::string functions::getDomainname() throw() {
  char aux[256];
  std::string result = "<domainname>";

  if(getdomainname(aux, sizeof aux) == 0 /*success*/)
    result = aux;

  return result;
}

std::string functions::getFQDN(const char *hostname, const char *domainname) throw() {
  std::string hn = hostname ? hostname : (functions::getHostname());
  std::string dn = domainname ? domainname : (functions::getDomainname());
  // FQDN is limited to 255 bytes, with aditional restriction: 63 bytes label within a domain name.

  if(hn == "") return dn;

  if(dn == "") return hn;

  std::string label(hn, 0, 63);
  std::string fqdn(label + "." + dn, 0, 255);
  return fqdn;
}

std::string functions::getHostnameIP() throw() {
  std::string result = "";
  struct hostent *he;
  struct in_addr **addr_list;
  struct in_addr ipv4addr;
  char hostname[128];
  gethostname(hostname, sizeof hostname);

  if((he = gethostbyname(hostname)) != NULL) {
    // Official name: he->h_name
    // IP addresses:
    addr_list = (struct in_addr **)he->h_addr_list;

    for(int i = 0; addr_list[i] != NULL; i++) {
      //printf("%s ", inet_ntoa(*addr_list[i]));
      result = inet_ntoa(*addr_list[i]);
      return result;
    }
  }

  return result;
}


anna::DataBlock functions::rawIpPresentationAsRaw(const std::string & rawPresentation) throw(anna::RuntimeException) {
  int length = rawPresentation.size();

  if(length != 8 && length != 32)
    throw anna::RuntimeException("functions::rawIpPresentationAsRaw | Expected 8 or 32-sized raw IP presentation provided", ANNA_FILE_LOCATION);

  anna::DataBlock result(true);
  int byte;
  char rByte[3]; // readable byte
  rByte[2] = 0;

  for(register int k = 0; k < length; k += 2) {
    rByte[0] =  rawPresentation[k];
    rByte[1] = rawPresentation[k + 1];
    sscanf(rByte, "%x", &byte);
    result += byte;
  }

  return result;
}


std::string functions::rawIpAsRawIpPresentation(const anna::DataBlock & db) throw(anna::RuntimeException) {
  int length = db.getSize();

  if(length != 4 && length != 16)
    throw anna::RuntimeException("functions::rawIpAsRawIpPresentation | Expected 4 or 16-sized raw IP DataBlock provided", ANNA_FILE_LOCATION);

  std::string result = "";
  int byte;
  char rByte[3]; // readable byte
  rByte[2] = 0;

  for(register int k = 0; k < length; k++) {
    byte = (unsigned char)db[k];
    sprintf(rByte, "%.2X", byte);
    result += rByte;
  }

  return result;
}



////////////////////
// Address Format //
////////////////////
//   IPv6 addresses have two logical parts: a 64-bit network prefix, and a 64-bit host address part. (The host address is often automatically generated from the interface MAC address.[34]) An IPv6 address is represented by 8 groups of 16-bit hexadecimal values separated by colons (:) shown as follows:
//   A typical example of an IPv6 address is
//   2001:0db8:85a3:0000:0000:8a2e:0370:7334
//   The hexadecimal digits are case-insensitive.
//
//   The 128-bit IPv6 address can be abbreviated with the following rules:
//   -Rule one: Leading zeroes within a 16-bit value may be omitted. For example, the address fe80:0000:0000:0000:0202:b3ff:fe1e:8329 may be written as fe80:0:0:0:202:b3ff:fe1e:8329
//   -Rule two: A single occurrence of consecutive groups of zeroes within an address may be replaced by a double colon. For example, fe80:0:0:0:202:b3ff:fe1e:8329 becomes fe80::202:b3ff:fe1e:8329
//   A single IPv6 address can be represented in several different ways, such as 2001:db8::1:0:0:1 and 2001:0DB8:0:0:1::1. RFC 5952 recommends a canonical textual representation.

//      Si la dirección tiene más de una serie de grupos nulos consecutivos la compresión sólo se permite en uno de ellos.
//      Así, las siguientes son representaciones posibles de una misma dirección:
//
//      2001:0DB8:0000:0000:0000:0000:1428:57ab
//      2001:0DB8:0000:0000:0000::1428:57ab
//      2001:0DB8:0:0:0:0:1428:57ab
//      2001:0DB8:0::0:1428:57ab
//      2001:0DB8::1428:57ab
//      son todas válidas y significan lo mismo, pero
//      2001::25de::cade
//          --    --
//      no es válida porque no queda claro cuántos grupos nulos hay en cada lado.
//
//      Los ceros iniciales en un grupo también se pueden omitir:
//      2001:0DB8:02de::0e13
//      2001:DB8:2de::e13
//
//      Si la dirección es una dirección IPv4 empotrada (mapped), los últimos 32 bits pueden escribirse en base decimal, así:
//      ::ffff:192.168.89.9
//      ::ffff:c0a8:5909
//
//      No se debe confundir con:
//      ::192.168.89.9
//      ::c0a8:5909
//
//      El formato ::ffff:1.2.3.4 se denomina dirección IPv4 mapeada, y el formato ::1.2.3.4 dirección IPv4 compatible.
//      Las direcciones IPv4 pueden ser transformadas fácilmente al formato IPv6. Por ejemplo, si la dirección decimal IPv4 es 135.75.43.52
//       (en hexadecimal, 0x874B2B34), puede ser convertida a 0000:0000:0000:0000:0000:0000:874B:2B34 o ::874B:2B34. Entonces, uno puede usar
//       la notación mixta dirección IPv4 compatible, en cuyo caso la dirección debería ser ::135.75.43.52. Este tipo de dirección IPv4 compatible
//       casi no está siendo utilizada en la práctica, aunque los estándares no la han declarado obsoleta.
//
// http://tools.ietf.org/html/rfc5952: canonical text representation recommendation

bool functions::isIPv4(const std::string & ip, IPv4Type::_v ipv4Type) throw() {
  if(ipv4Type == IPv4Type::Estrict) {
    // La expresión regular no controla si hay mas de 3 puntos:
    int n_dot = 0;

    for(register int k = 0; k < ip.length(); k++)
      if(ip[k] == '.') n_dot++;

    if(n_dot > 3)
      return (false);

    bool ipv4 = anna::functions::isLike(s_REGEXP_IPv4_ADDRESSES, ip);
    bool colon = (ip.find(":") != std::string::npos);
    return (ipv4 && !colon);
  }

  if(ipv4Type == IPv4Type::Compatible) {
    std::string pureIPv4 = ip;
    bool firstDoubleColon = (ip.find("::") == 0);

    if(firstDoubleColon) {
      pureIPv4.erase(0, 2);
      bool anotherColon = (pureIPv4.find(":") != std::string::npos);

      if(anotherColon) return (false);

      return (anna::functions::isLike(s_REGEXP_IPv4_ADDRESSES, pureIPv4));
    }
  }

  if(ipv4Type == IPv4Type::Mapped) {
    size_t posLastColon = ip.rfind(":");

    if(posLastColon == std::string::npos)
      return (false);

    if(!isIPv4(ip.substr(posLastColon + 1)))
      return (false);

    unsigned char buf[sizeof(struct in6_addr)];
    int s = inet_pton(AF_INET6, ip.c_str(), buf);

    if(s > 0)
      return (true);
  }

  return false;
}


bool functions::isIPv6(const std::string & ip) throw() {
  // Chequeo de digitos permitidos:
  for(register int k = 0; k < ip.length(); k++) {
    bool digit = isdigit(ip[k]);
    bool hex = ((ip[k] == 'a') ||
                (ip[k] == 'b') ||
                (ip[k] == 'c') ||
                (ip[k] == 'd') ||
                (ip[k] == 'e') ||
                (ip[k] == 'f') ||
                (ip[k] == 'A') ||
                (ip[k] == 'B') ||
                (ip[k] == 'C') ||
                (ip[k] == 'D') ||
                (ip[k] == 'E') ||
                (ip[k] == 'F'));
    bool colon = (ip[k] == ':');

    if(!digit && !hex && !colon)
      return false;
  }

  return (anna::functions::isLike(s_REGEXP_IPv6_ADDRESSES, ip));
}


std::string functions::IPv4To6(const std::string & ip) throw(anna::RuntimeException) {
  if(!isIPv4(ip, IPv4Type::Estrict) && !isIPv4(ip, IPv4Type::Compatible) && !isIPv4(ip, IPv4Type::Mapped))
    throw anna::RuntimeException("functions::IPv4To6 | Expected IPv4, IPv4-compatible or IPv4-mapped address format", ANNA_FILE_LOCATION);

  std::string result, pureIPv4;
  bool firstDoubleColon = (ip.find("::") == 0);

  if(firstDoubleColon) {
    // Clean '::'
    size_t ipv4_pos = ip.rfind(":") /* last ocurrence */ + 1;
    pureIPv4 = ip.substr(ipv4_pos);
  } else {
    if(!isIPv4(ip)) {
      size_t posColon = ip.find(":");

      if(posColon == 0)  // first colon
        throw anna::RuntimeException("functions::IPv4To6 | Invalid IPv4 address format", ANNA_FILE_LOCATION);

      if(posColon != std::string::npos)  // any colon
        return ip; // seems to be IPv6 already?

      throw anna::RuntimeException("functions::IPv4To6 | Unreconized IPv4 address format", ANNA_FILE_LOCATION);
    }

    pureIPv4 = ip;
  }

  // Number of ocurrences for '.'
  int n_dot = 0;

  for(register int k = 0; k < pureIPv4.length(); k++)
    if(pureIPv4[k] == '.') n_dot++;

  if(n_dot > 3)
    throw anna::RuntimeException("functions::IPv4To6 | Wrong IPv4 address format (more than three dots!)", ANNA_FILE_LOCATION);

  anna::Tokenizer tok;
  anna::Tokenizer::const_iterator tok_it;
  std::string token;
  tok.apply(pureIPv4, ".");
  int v[4];
  int cnt = 0;

  for(tok_it = tok.begin(); tok_it != tok.end(); tok_it ++) {
    token = anna::Tokenizer::data(tok_it);
    v[cnt] = atoi(anna::Tokenizer::data(tok_it));

    if(v[cnt] < 0 || v[cnt] > 255)
      throw anna::RuntimeException("functions::IPv4To6 | Wrong IPv4 address format (any value out of range 0-255)", ANNA_FILE_LOCATION);

    cnt++;
  }

  if(isIPv4(ip, IPv4Type::Compatible))
    result = anna::functions::asString("::%04x:%04x", v[0] * 256 + v[1], v[2] * 256 + v[3]);
  else
    result = anna::functions::asString("::ffff:%04x:%04x", v[0] * 256 + v[1], v[2] * 256 + v[3]);

  return result;
}


std::string functions::normalizeIP(const std::string & ip) throw(anna::RuntimeException) {
  std::string result = ip;
//   std::transform(result.begin(), result.end(), result.begin(), (int (*)(int))std::tolower);
  std::transform(result.begin(), result.end(), result.begin(), ::tolower);

  if(isIPv4(ip, IPv4Type::Estrict) || isIPv4(ip, IPv4Type::Compatible) || isIPv4(ip, IPv4Type::Mapped))
    result = IPv4To6(result);

  size_t pos = result.find("::"); // zeroes simplification group
  size_t rpos = result.rfind("::"); // zeroes simplification group

  if(pos != rpos)
    throw anna::RuntimeException("functions::normalizeIP | Wrong IPv6 address format (more than one simplification group '::')", ANNA_FILE_LOCATION);

  if(pos != std::string::npos) {  // zeroes exists
    // string ( size_t n, char c ) -> content is initialized as a string formed by a repetition of character c, n times.
    // Number of ocurrences for ':'
    int n_colon = 0;

    for(register int k = 0; k < result.length(); k++)
      if(result[k] == ':') n_colon++;

    // Generate equivalent to '::'
    std::string equiv_str;

    for(register int k = 0; k < (8 - n_colon); k++)
      equiv_str += ":0";

    equiv_str += ":";
    // Replace with equivalent:
    result.replace(pos, 2, equiv_str);

    // Special case: IP began with '::'
    if(result[0] == ':') {
      result.insert(0, "0");
    }

    // Special case: IP was only '::'
    if(result[result.length() - 1] == ':') {
      result += "0";
    }
  }

  // Protection: it must be seven colons:
  int n_colon = 0;

  for(register int k = 0; k < result.length(); k++)
    if(result[k] == ':') n_colon++;

  if(n_colon != 7)
    throw anna::RuntimeException("functions::normalizeIP | Wrong IPv6 address format (missing any 16-bit group)", ANNA_FILE_LOCATION);

  // Padding with zeroes at left
  anna::Tokenizer ipStr;
  anna::Tokenizer::const_iterator ipStr_it;
  std::string token;
  ipStr.apply(result, ":");
  result = "";

  for(ipStr_it = ipStr.begin(); ipStr_it != ipStr.end(); ipStr_it ++) {
    token = anna::Tokenizer::data(ipStr_it);

    while(token.length() < 4) token.insert(0, "0");

    result += token;
    result += ":";
  }

  // Remove last ':'
  size_t lastPos = result.length() - 1;
  result.erase(lastPos, 1);

  // Chequeo de digitos permitidos:
  for(register int k = 0; k < result.length(); k++) {
    bool digit = isdigit(result[k]);
    bool hex = ((result[k] == 'a') ||
                (result[k] == 'b') ||
                (result[k] == 'c') ||
                (result[k] == 'd') ||
                (result[k] == 'e') ||
                (result[k] == 'f'));
    bool colon = (result[k] == ':');

    if(!digit && !hex && !colon) {
      throw anna::RuntimeException("functions::normalizeIP | Invalid address format (only digits (0-9) and hex digits are allowed)", ANNA_FILE_LOCATION);
    }
  }

  return result;
}


bool functions::sameIP(const std::string & ip1, const std::string & ip2) throw(anna::RuntimeException) {
  //if (ip1 == ip2) return true; it should validate wrong-format addresses
  return (normalizeIP(ip1) == normalizeIP(ip2));
}


bool functions::matchIPv6(const std::string & _ipv6, const std::string & preffixedIpv6) throw(anna::RuntimeException) {
  size_t preffixPos = preffixedIpv6.find("/");

  if(preffixPos == std::string::npos)
    return (sameIP(_ipv6, preffixedIpv6));

  std::string ipv6 = _ipv6;

  if(isIPv4(_ipv6, IPv4Type::Estrict) || isIPv4(_ipv6, IPv4Type::Compatible) || isIPv4(_ipv6, IPv4Type::Mapped)) ipv6 = IPv4To6(_ipv6);

  std::string _ipv6_2 = preffixedIpv6.substr(0, preffixPos);
  std::string ipv6_2 = _ipv6_2;

  if(isIPv4(_ipv6_2, IPv4Type::Estrict) || isIPv4(_ipv6_2, IPv4Type::Compatible) || isIPv4(_ipv6_2, IPv4Type::Mapped)) ipv6_2 = IPv4To6(_ipv6_2);

  std::string preffix = preffixedIpv6.substr(preffixPos + 1);
  int ipv6_2_preffixLength = atoi(preffix.c_str());

  if(ipv6_2_preffixLength < 0 || ipv6_2_preffixLength > 128)
    throw anna::RuntimeException("functions::matchIPv6 | Invalid Ipv6 preffix length: out of range [0,128]", ANNA_FILE_LOCATION);

  // No restriction, all ipv6_2 ignored (special and not usual case)
  if(ipv6_2_preffixLength == 0) return true;

  // Auxiliary data:
  int spare = ipv6_2_preffixLength /* bits */ % 8; // bytes
  int incompletedRestrictionBytes = ipv6_2_preffixLength / 8;
  int completedRestrictionBytes = incompletedRestrictionBytes + ((spare != 0) ? 1 : 0);
  char mask = 0xFF << (8 - spare);
  // Limit ipv6
  anna::DataBlock rawIP1 = ipAsRaw(ipv6);
  anna::DataBlock restrictedIP1(true);
  restrictedIP1.assign(rawIP1.getData(), incompletedRestrictionBytes);

  if(spare != 0) restrictedIP1 += rawIP1[incompletedRestrictionBytes] & mask;

  // Limit ipv6_2
  anna::DataBlock rawIP2 = ipAsRaw(ipv6_2);
  anna::DataBlock realIP2(true);
  realIP2.assign(rawIP2.getData(), incompletedRestrictionBytes);

  if(spare != 0) realIP2 += rawIP2[incompletedRestrictionBytes] & mask;

  // Comparison
  int n = memcmp(restrictedIP1.getData(), realIP2.getData(), completedRestrictionBytes);
  return (n == 0);
}


anna::DataBlock functions::ipAsRaw(const std::string & ip) throw(anna::RuntimeException) {
  anna::DataBlock result(true);

  if(isIPv4(ip)) {
    unsigned char buf[sizeof(struct in6_addr)];
    int s = inet_pton(AF_INET, ip.c_str(), buf);

    if(s > 0) {
      result += (S8)buf[0];
      result += (S8)buf[1];
      result += (S8)buf[2];
      result += (S8)buf[3];
    } else {
      if(s < 0) perror("inet_pton");

      throw anna::RuntimeException("functions::ipAsRaw | Wrong IPv4 address format", ANNA_FILE_LOCATION);
    }
  } else {
    unsigned char buf[sizeof(struct in6_addr)];
    int s = inet_pton(AF_INET6, ip.c_str(), buf);

    if(s > 0) {
      result += (S8)buf[0];
      result += (S8)buf[1];
      result += (S8)buf[2];
      result += (S8)buf[3];
      result += (S8)buf[4];
      result += (S8)buf[5];
      result += (S8)buf[6];
      result += (S8)buf[7];
      result += (S8)buf[8];
      result += (S8)buf[9];
      result += (S8)buf[10];
      result += (S8)buf[11];
      result += (S8)buf[12];
      result += (S8)buf[13];
      result += (S8)buf[14];
      result += (S8)buf[15];
    } else {
      if(s < 0) perror("inet_pton");

      throw anna::RuntimeException("functions::ipAsRaw | Wrong IPv6 address format", ANNA_FILE_LOCATION);
    }
  }

  return result;
  // Alternativa
  //   anna::DataBlock result(true);
  //
  //
  //   if (isIPv4(ip)) {
  //
  //      int dec1, dec2, dec3, dec4; // U32 type is valid, 'int' better: argument for %d must be 'int *' (http://www.cplusplus.com/reference/clibrary/cstdio/sscanf/)
  //      sscanf(ip.c_str(), "%d.%d.%d.%d", &dec1, &dec2, &dec3, &dec4);
  //      result += (S8)dec1;
  //      result += (S8)dec2;
  //      result += (S8)dec3;
  //      result += (S8)dec4;
  //   }
  //   else {
  //
  //      int hex1, hex2, hex3, hex4, hex5, hex6, hex7, hex8; // U16 type is not valid: argument for %X must be 'int *' (http://www.cplusplus.com/reference/clibrary/cstdio/sscanf/)
  //      sscanf(normalizeIP(ip).c_str(), "%X:%X:%X:%X:%X:%X:%X:%X", &hex1, &hex2, &hex3, &hex4, &hex5, &hex6, &hex7, &hex8);
  //      result += ((S8)(hex1 >> 8));
  //      result += ((S8)(hex1 & 0x00FF));
  //      result += ((S8)(hex2 >> 8));
  //      result += ((S8)(hex2 & 0x00FF));
  //      result += ((S8)(hex3 >> 8));
  //      result += ((S8)(hex3 & 0x00FF));
  //      result += ((S8)(hex4 >> 8));
  //      result += ((S8)(hex4 & 0x00FF));
  //      result += ((S8)(hex5 >> 8));
  //      result += ((S8)(hex5 & 0x00FF));
  //      result += ((S8)(hex6 >> 8));
  //      result += ((S8)(hex6 & 0x00FF));
  //      result += ((S8)(hex7 >> 8));
  //      result += ((S8)(hex7 & 0x00FF));
  //      result += ((S8)(hex8 >> 8));
  //      result += ((S8)(hex8 & 0x00FF));
  //   }
  //
  //
  //   return result;
}


std::string functions::rawIpAsString(const char *buffer, int bufferLength, bool normalize) throw(anna::RuntimeException) {
  std::string result = "";
  char str[INET6_ADDRSTRLEN];

  if(bufferLength == 4) {
    if(inet_ntop(AF_INET, buffer, str, INET_ADDRSTRLEN) != NULL)
      result = str;
  } else if(bufferLength == 16) {
    if(inet_ntop(AF_INET6, buffer, str, INET6_ADDRSTRLEN) != NULL)
      result = str;
  } else
    throw anna::RuntimeException("functions::rawIpAsString | Unreconized IP address format (only 4-byte for IPv4, and 16-byte for IPv6 are allowed)", ANNA_FILE_LOCATION);

  if(result == "")
    throw anna::RuntimeException("functions::rawIpAsString | Wrong IP address serialization (check range value)", ANNA_FILE_LOCATION);

  return (normalize ? normalizeIP(result) : result);
  // Alternativa:
  //   std::string result;
  //
  //
  //   if (bufferLength == 4) { // IPv4
  //      result = anna::functions::asString("%d.%d.%d.%d", (U8)buffer[0], (U8)buffer[1], (U8)buffer[2], (U8)buffer[3]);
  //   }
  //   else if (bufferLength == 16) { // IPv6
  //      result = anna::functions::asString("%04x:%04x:%04x:%04x:%04x:%04x:%04x:%04x",
  //                       ((((U8)buffer[0]) << 8) & 0xFF00 /* same as (U16 cast)*/) +
  //                       (((U8)buffer[1])        & 0x00FF),
  //                       ((((U8)buffer[2]) << 8) & 0xFF00) +
  //                       (((U8)buffer[3])        & 0x00FF),
  //                       ((((U8)buffer[4]) << 8) & 0xFF00) +
  //                       (((U8)buffer[5])        & 0x00FF),
  //                       ((((U8)buffer[6]) << 8) & 0xFF00) +
  //                       (((U8)buffer[7])        & 0x00FF),
  //                       ((((U8)buffer[8]) << 8) & 0xFF00) +
  //                       (((U8)buffer[9])        & 0x00FF),
  //                       ((((U8)buffer[10]) << 8) & 0xFF00) +
  //                       (((U8)buffer[11])        & 0x00FF),
  //                       ((((U8)buffer[12]) << 8) & 0xFF00) +
  //                       (((U8)buffer[13])        & 0x00FF),
  //                       ((((U8)buffer[14]) << 8) & 0xFF00) +
  //                       (((U8)buffer[15])        & 0x00FF));
  //   }
  //   else
  //      throw anna::RuntimeException("functions::rawIpAsString | Unreconized IP address format (only 4-byte for IPv4, and 16-byte for IPv6 are allowed)", ANNA_FILE_LOCATION);
  //
  //
  //   return (normalize ? normalizeIP(result):result);
}


void functions::getAddressAndPortFromSocketLiteral(const std::string &literal, std::string &address, int &port) throw() {
  size_t pos = literal.find_last_of(":");
  size_t lastPos = literal.size() - 1;
  address = ""; port = -1; // assume error

  if((pos != std::string::npos) && (pos != lastPos)) {
    address = literal.substr(0, pos);
    port = atoi(literal.substr(pos + 1, lastPos).c_str());
  }
}


socket_v functions::getSocketVectorFromString(const std::string & list) throw() {
  socket_v result;
  std::string address;
  int port;
  anna::Tokenizer lst;
  lst.apply(list, ",");

  if(lst.size() < 1) return result;

  anna::Tokenizer::const_iterator tok_min(lst.begin());
  anna::Tokenizer::const_iterator tok_max(lst.end());
  anna::Tokenizer::const_iterator tok_iter;

  for(tok_iter = tok_min; tok_iter != tok_max; tok_iter++) {
    getAddressAndPortFromSocketLiteral(anna::Tokenizer::data(tok_iter), address, port);

    if(port == -1) { result.clear(); return result; }

    result.push_back(socket_t(address, port));
  }

  return result;
}

std::string functions::socketVectorAsString(const socket_v & socketVector) throw() {
  std::string result;
  socket_v_it it;
  socket_v_it it_min(socketVector.begin());
  socket_v_it it_max(socketVector.end());

  for(it = it_min; it != it_max; it++) {
    result += anna::functions::asString("%s:%d,", (*it).first.c_str(), (*it).second);
  }

  result.erase(result.size() - 1, 1);  // remove last comma
  return result;
}

bool functions::littleEndian()
throw() {
  int i = 1;
  char *p = (char *) &i;
  if (p[0] == 1) return true;
  return false;
}

const char* functions::codeInteger(char* result, const int n)
throw() {
  int aux(htonl(n));
  register char* w((char*) &aux);
  *result = *w;
  *(result + 1) = *(w + 1);
  *(result + 2) = *(w + 2);
  *(result + 3) = *(w + 3);
  return result;
}

const char* functions::codeShort(char* result, const short int n)
throw() {
  short int aux(htons(n));
  register char* w((char*) &aux);
  *result = *w;
  *(result + 1) = *(w + 1);
  return result;
}

const char* functions::codeInteger64(char* result, const S64 n)
throw() {
  S64 aux(0xffffffff);
  int n2;
  aux <<= 32;
  aux &= n;
  n2 = (aux >> 32) & 0xffffffff;
  codeInteger(result, n2);
  n2 = n & 0xffffffff;
  codeInteger(result + sizeof(int), n2);
  return result;
}

/*static*/
const char* functions::codeFloat(char* result, const float n)
throw() {
  int ii;
  anna_memcpy(&ii, &n, sizeof(n));
  return functions::codeInteger(result, ii);
}

/*static*/
const char* functions::codeDouble(char* result, const double n)
throw() {
  S64 ii;
  anna_memcpy(&ii, &n, sizeof(n));
  return functions::codeInteger64(result, ii);
}

int functions::decodeInteger(const char* data)
throw() {
  int result;
  register char* w((char*) &result);
  *w  = *data;
  *(w + 1) = *(data + 1);
  *(w + 2) = *(data + 2);
  *(w + 3) = *(data + 3);
  return ntohl(result);
}

short int functions::decodeShort(const char* data)
throw() {
  short int result;
  register char* w((char*) &result);
  *w  = *data;
  *(w + 1) = *(data + 1);
  return ntohs(result);
}

S64 functions::decodeInteger64(const char* data)
throw() {
  S64 result(decodeInteger(data));
  result <<= 32;
  return result |= (decodeInteger(data + sizeof(int)) & 0xffffffff);
}

/*static*/
float functions::decodeFloat(const char* data)
throw() {
  float result;
  int ii = functions::decodeInteger(data);
  anna_memcpy(&result, &ii, sizeof(result));
  return result;
}

/*static*/
double functions::decodeDouble(const char* data)
throw() {
  double result;
  S64 ii = functions::decodeInteger64(data);
  anna_memcpy(&result, &ii, sizeof(result));
  return result;
}



void functions::decodeIsupNumber(const char *buffer, int length, isup_number_t & isupNumber, bool calledOrCalling) throw(anna::RuntimeException) {
#define DECODE2BYTES_INDX_VALUETYPE(buffer,indx,value_type) ((((value_type)buffer[indx] << 8) & 0xFF00) + ((value_type)buffer[indx+1] & 0x00FF))
  isupNumber.reset();
  isupNumber.OddEven = (short)((buffer[0] >> 7) & 0x01);
  bool filler = isupNumber.OddEven;

  if(filler && ((buffer [length - 1] & 0xf0) != 0x00))
    throw anna::RuntimeException("functions::decodeIsupNumber | Isup number filler must be '0000'", ANNA_FILE_LOCATION);

  isupNumber.NatureOfAddress = (short)(buffer[0] & 0x7F);
  isupNumber.NumberingPlan = (short)((buffer[1] >> 4) & 0x07);

  if(calledOrCalling) {
    isupNumber.InternalNetworkNumber = (short)((buffer[1] >> 7) & 0x01);
  } else {
    isupNumber.NumberIncomplete = (short)((buffer[1] >> 7) & 0x01);
    isupNumber.AddressPresentationRestricted = (short)((buffer[1] >> 2) & 0x03);
    isupNumber.Screening = (short)(buffer[1] & 0x03);
  }

  // Digits:
  isupNumber.Digits = "";
  int byte;

  for(register int k = 2; k < length; k ++) {
    byte = (buffer [k] & 0x0f);
    isupNumber.Digits += (byte >= 0 && byte <= 9) ? (byte + '0') : ((byte - 0xa) + 'a');
    byte = (buffer [k] & 0xf0) >> 4;
    isupNumber.Digits += (byte >= 0 && byte <= 9) ? (byte + '0') : ((byte - 0xa) + 'a');
  }

  if(filler) isupNumber.Digits.erase(isupNumber.Digits.size() - 1, 1);   // remove filler
}


void functions::codeIsupNumber(const isup_number_t & isupNumber, bool calledOrCalling, std::string & target) throw(anna::RuntimeException) {
  // Checkings:
  if(isupNumber.OddEven < 0 || isupNumber.OddEven > 1)
    throw anna::RuntimeException("functions::codeIsupNumber | Isup number 'OddEven' field out of range [0,1]", ANNA_FILE_LOCATION);

  bool odd = isupNumber.OddEven;
  bool oddDigits = (isupNumber.Digits.size() % 2);

  if(odd != oddDigits)
    throw anna::RuntimeException("functions::codeIsupNumber | Isup number 'OddEven' field doesn't correspond to the number of digits on 'Digits' field", ANNA_FILE_LOCATION);

  if(isupNumber.NatureOfAddress < 0 || isupNumber.NatureOfAddress > 127)
    throw anna::RuntimeException("functions::codeIsupNumber | Isup number 'NatureOfAddress' field out of range [0,127]", ANNA_FILE_LOCATION);

  if(isupNumber.NumberingPlan < 0 || isupNumber.NumberingPlan > 7)
    throw anna::RuntimeException("functions::codeIsupNumber | Isup number 'NumberingPlan' field out of range [0,7]", ANNA_FILE_LOCATION);

  if(calledOrCalling) {
    if(isupNumber.NumberIncomplete != 0)
      throw anna::RuntimeException("functions::codeIsupNumber | Isup number 'NumberIncomplete' field present on Called Party Number !", ANNA_FILE_LOCATION);

    if(isupNumber.AddressPresentationRestricted != 0)
      throw anna::RuntimeException("functions::codeIsupNumber | Isup number 'AddressPresentationRestricted' field present on Called Party Number !", ANNA_FILE_LOCATION);

    if(isupNumber.Screening != 0)
      throw anna::RuntimeException("functions::codeIsupNumber | Isup number 'Screening' field present on Called Party Number !", ANNA_FILE_LOCATION);

    if(isupNumber.InternalNetworkNumber < 0 || isupNumber.InternalNetworkNumber > 1)
      throw anna::RuntimeException("functions::codeIsupNumber | Isup number 'InternalNetworkNumber' field out of range [0,1]", ANNA_FILE_LOCATION);
  } else {
    if(isupNumber.InternalNetworkNumber != 0)
      throw anna::RuntimeException("functions::codeIsupNumber | Isup number 'InternalNetworkNumber' field present on Calling Party Number !", ANNA_FILE_LOCATION);

    if(isupNumber.NumberIncomplete < 0 || isupNumber.NumberIncomplete > 1)
      throw anna::RuntimeException("functions::codeIsupNumber | Isup number 'NumberIncomplete' field out of range [0,1]", ANNA_FILE_LOCATION);

    if(isupNumber.AddressPresentationRestricted < 0 || isupNumber.AddressPresentationRestricted > 3)
      throw anna::RuntimeException("functions::codeIsupNumber | Isup number 'AddressPresentationRestricted' field out of range [0,3]", ANNA_FILE_LOCATION);

    if(isupNumber.Screening < 0 || isupNumber.Screening > 3)
      throw anna::RuntimeException("functions::codeIsupNumber | Isup number 'Screening' field out of range [0,3]", ANNA_FILE_LOCATION);
  }

  char byte;
  target = "";
  bool filler = isupNumber.OddEven;
  bool hasDigits = (isupNumber.Digits.size() > 0);
  byte = filler ? 0x80 : 0x00;
  byte = byte |= isupNumber.NatureOfAddress;
  target += byte;

  if(calledOrCalling) {
    byte = isupNumber.InternalNetworkNumber << 7;
    byte = byte |= (isupNumber.NumberingPlan << 4);
  } else {
    byte = isupNumber.NumberIncomplete << 7;
    byte = byte |= (isupNumber.NumberingPlan << 4);
    byte = byte |= (isupNumber.AddressPresentationRestricted << 2);
    byte = byte |= isupNumber.Screening;
  }

  target += byte;
  //int byte;
  unsigned char hex;
  std::string dtlc = isupNumber.Digits; // digits to lower case
  //std::transform(dtlc.begin(), dtlc.end(), dtlc.begin(), std::tolower);
  const char *digits = dtlc.c_str();

  for(register int k = 1; k < isupNumber.Digits.size(); k += 2) {
    if(isxdigit(byte = digits [k - 1]) == 0)
      throw anna::RuntimeException("functions::codeIsupNumber | Isup number 'Digits' field contains invalid digits (non hexadecimal)", ANNA_FILE_LOCATION);

    hex = (byte >= '0' && byte <= '9') ? (byte - '0') : ((byte - 'a') + 0x0a);

    if(isxdigit(byte = digits [k]) == 0)
      throw anna::RuntimeException("functions::codeIsupNumber | Isup number 'Digits' field contains invalid digits (non hexadecimal)", ANNA_FILE_LOCATION);

    hex |= ((byte >= '0' && byte <= '9') ? (byte - '0') : ((byte - 'a') + 0x0a)) << 4;
    target += hex;
  }

  if(hasDigits && filler) {
    if(isxdigit(byte = digits [isupNumber.Digits.size() - 1]) == 0)
      throw anna::RuntimeException("functions::codeIsupNumber | Isup number 'Digits' field contains invalid digits (non hexadecimal)", ANNA_FILE_LOCATION);

    target += ((byte >= '0' && byte <= '9') ? (byte - '0') : ((byte - 'a') + 0x0a));
  }
}


void functions::codeIsupNumber(const isup_number_t & isupNumber, bool calledOrCalling, char * buffer, int & length) throw(anna::RuntimeException) {
  std::string target;
  codeIsupNumber(isupNumber, calledOrCalling, target);
  length = target.size();
  memcpy(buffer, target.c_str(), length);
}