#ifndef pz_symbol_H
#define pz_symbol_H

/* Small signed integers coded into printable characters. */
/* Last edited on 2008-02-08 13:34:48 by stolfi */

#include <pz_types.h>

typedef char pz_symbol_t;
  /* Encoding: 'a'..'z' == -1..-26, '0' == 0, 'A'..'Z' == +1..+26. */

bool_t pz_symbol_is_valid ( int c );
  /* True if {c} is the (signed) {char} value of a valid {pz_symbol_t},
    i.e. an upper or lower case letter, or the digit '0'. */

int pz_symbol_to_int ( pz_symbol_t ch );
  /* The integer (signed) numeric value of {ch}. */

pz_symbol_t pz_symbol_from_int ( int i );
  /* The coded representation of value {i}. */

pz_symbol_t pz_symbol_encode ( double x, double sigma );
  /* Compresses, quantizes, and encodes the curvature {x} which is
    assumed to have Gaussian distribution with standard deviation
    {sigma}. */

double pz_symbol_decode ( pz_symbol_t c, double sigma );
  /* Inverse of {pz_symbol_encode} - decodes a quantized and encoded curvature. */

double pz_symbol_error_var ( pz_symbol_t c, double sigma );
  /* Returns the estimated variance of the quantization error for
    the given encoded value. */

double_vec_t pz_symbol_make_decode_table ( double sigma );
  /* Creates a table {tb} that maps {pz_symbol_t} symbols to real values,
    i.e. {tb[c] == pz_symbol_decode(c, sigma)}. */

double_vec_t pz_symbol_make_error_var_table ( double sigma );
  /* Creates a table {tb} that maps {pz_symbol_t} symbols to quant. error variance,
    i.e. {tb[c] == pz_symbol_error_var(c, sigma)}. */

pz_symbol_t pz_symbol_complement ( pz_symbol_t ch );
  /* Negates the numeric value of {ch} */

double pz_symbol_dist_sqr
  ( pz_symbol_t a,
    pz_symbol_t b,
    bool_t complement,
    double_vec_t *decode,
    double_vec_t *errorVar
  );
  /* A discrepancy measure, squared, between {a} and {b}: basically,
    the square of the difference {d == decode[a] - decode[b]}, plus
    {errorVar[a] + errorVar[b]}.

    If {complement==TRUE}, uses {pz_symbol_complement(b)} instead of {b}. */

double pz_symbol_intg_dist_sqr
  ( pz_symbol_t a1,
    pz_symbol_t a2,
    pz_symbol_t b1,
    pz_symbol_t b2,
    bool_t complement,
    double_vec_t *decode,
    double_vec_t *errorVar
  );
  /* The integral of {pz_symbol_dist_sqr(a(t), b(t), complement, de)} where {a(t)}
    interpolates linearly between {a1} and {a2}
    as {t} goes from 0 to 1; and similarly for {b(t)}. */

#endif