Collaboration diagram for API_LowLvl::lib::core:

Data Structures
struct	SprAtomicSlot

struct	SprDTCvtAux

struct	SprDTCvtAuxSrm

class	SprDT

class	SprDT_ET
	A base type. More...

class	SprDT_EnumT

struct	SprMPool

struct	SprStdKeys

struct	SprSrmDir
	Return structure for the spr_srm_dir() function. More...

struct	SprStrSplit
	structure to indicate fields in a multi field line More...

union	SprScanfDst

struct	SprScanfErr

struct	SprExprScanErr
	Give detailed feedback on a parse error when looking for the end of an expression. More...

struct	SprStreamOpenInfo

struct	SprStreamOpenCPHInfo

class	SprStream
	The generic stream pointer. For more info, see stream.c. More...

Namespaces
	xref_spr_sec_srm_code
	Typical usage scenarios of shared resources

Macros
#define	spr_dt_f64

#define	spr_dt_f32

#define	spr_dt_i64

#define	spr_dt_u64

#define	spr_dt_i32

#define	spr_dt_u32

#define	spr_dt_i16

#define	spr_dt_u16

#define	spr_dt_i8

#define	spr_dt_u8

#define	spr_dt_char

#define	spr_dt_alaw

#define	spr_dt_ulaw

#define	spr_dt_dynstr

#define	spr_dt_int

#define	spr_dt_uint

#define	spr_dt_long

#define	spr_dt_ulong

#define	spr_dt_ssize

#define	spr_dt_size

#define	spr_dt_ptr

#define	spr_dt_bool

#define	spr_dt_true

#define	spr_dt_false

#define	spr_dt_string

#define	spr_od_end
	Indicate the end of an argument description list. More...

#define	spr_od_info(title, info)

#define	spr_od_include(other_opt_spec, offs)

#define	spr_od_alias(alias, original)

#define	spr_od_funcarg0(name, flags, brief, detailed, func)

#define	spr_od_funcarg1(name, flags, brief, detailed, func, def_val)

#define	spr_od_posarg(flags, brief, detailed, type, offs, def_val)

#define	SPR_MPOOL_CHUNK_SZ

#define	SPR_MPOOL_INITIALIZER(type, next_el)

#define	SPR_MPOOL_INIT(mpool, type, next_el)

#define	SPR_DEFAULT_FSHIFT
	The default frame shift (10 msec). More...

#define	SPR_DEFAULT_SAMPLEFREQ
	The default sample frequency (8kHz). More...

#define	SPR_MSG_ID(var, name)

#define	SPR_SET_THREAD_ID(thread_name)

#define	spr_error(routine,...)
	Send an error message. More...

#define	spr_warning(routine,...)
	Send a warning message. More...

#define	spr_info(routine,...)
	Send an info message. More...

#define	spr_msg_long_start(lvl, routine,...)
	Send a long debug message at a given level lvl. More...

#define	spr_msg_async_start(lvl, routine,...)

#define	SPR_CAST(spr__base, spr__class, spr__object)
	Cast the type of a class object. More...

#define	SPR_CLASSID_FORM_CLASS(spr__class)

#define	SPR_DO(spr__class, spr__method,...)
	Call a method from a class. More...

#define	SPR_DO_FPTR(spr__class, spr__method, spr__object)
	Get function pointer for a given method. More...

#define	SPR_DO_OPTR(spr__class, spr__method, spr__object)
	Get the adjusted object pointer for a given method. More...

#define	SprMethodPtr(spr__class, spr__method)
	Generate a method function pointer type. More...

#define	SPR_OBJECT_INIT(spr__class, spr__object)
	Initialize RTTI of a dynamically allocated object. More...

#define	SPR_LVAR_OBJECT_INIT(spr__class, spr__object)
	Initialize RTTI of a statically allocated object. More...

#define	spr_stderr
	Stream handler for the 'stderr' stream. More...

Typedefs
typedef SprDTCvtAux (	_FuncPtr1_DATATYPE_ )(struct SprDTCvtAuxSrm aux_data, const SprDT dt_dst, const SprDT *dt_src)

typedef void (	SprDTCvt1Func )(void restrict dst, const void restrict src, const SprDTCvtAux *restrict aux)

typedef void (	SprDTCvtNFunc )(void restrict dst, const void restrict src, size_t Nel, const SprDTCvtAux *restrict aux)

typedef void (	SprDTCvtNsiFunc )(void restrict dst, const void restrict src, size_t Nel, size_t offs_src_next, const SprDTCvtAux *restrict aux)

typedef void (	SprDTCvtNdiFunc )(void restrict dst, const void restrict src, size_t Nel, size_t offs_dst_next, const SprDTCvtAux *restrict aux)

typedef void (	SprDTCvtNsdiFunc )(void restrict dst, const void restrict src, size_t Nel, size_t offs_src_next, size_t offs_dst_next, const SprDTCvtAux *restrict aux)

typedef int(*	SprDTRead1Func )(const SprDT dt, SprStream restrict fd, void *restrict dst)

typedef ssize_t(*	SprDTReadNFunc )(const SprDT dt, SprStream restrict fd, void *restrict dst, size_t Nel)

typedef ssize_t(*	SprDTReadNiFunc )(const SprDT dt, SprStream restrict fd, void *restrict dst, size_t Nel, size_t offs_next)

typedef int(*	SprDTWrite1Func )(const SprDT dt, SprStream restrict fd, const void *restrict src)

typedef int(*	SprDTWriteNFunc )(const SprDT dt, SprStream restrict fd, const void *restrict src, size_t Nel)

typedef int(*	SprDTWriteNiFunc )(const SprDT dt, SprStream restrict fd, const void *restrict src, size_t Nel, size_t offs_next)

typedef ssize_t(*	SprDTSkipNFunc )(const SprDT dt, SprStream restrict fd, size_t Nel)

typedef struct SprHtblStr	SprHtblStr

typedef void(*	SprMsgCatchFunc )(int lvl, const char thread, const char routine, const char format, va_list list)

typedef struct spr_t_object	SprObject

typedef struct SprSrmEl	SprSrmEl

typedef void(*	SprSrmFree )(SprSrmEl srm_el, SprMsgId routine)
	Prototype of a function to free the content of a resource. More...

typedef struct SprStreamOpenParam	SprStreamOpenParam

typedef int(*	SprStreamOpenProtocol )(SprStreamOpenInfo info, SprStreamOpenParam param)

typedef int(*	SprStreamOpenCoder )(SprStreamOpenInfo info, SprStreamOpenParam param)

typedef char (	SprStreamOpenDecodeParam )(SprStreamOpenParam *param_info, char param_desc, SprStreamOpenInfo *info)

typedef SprStreamOpenParam (	SprStreamOpenFreeParam )(SprStreamOpenInfo info, SprStreamOpenParam param_data)

typedef int(*	SprStreamOpenHdrRead )(SprStreamOpenInfo info, SprStreamOpenParam param)

typedef int(*	SprStreamOpenHdrWrite )(SprStreamOpenInfo info, SprStreamOpenParam param)

typedef int(*	SprStreamOpenCheck )(SprStreamOpenInfo info, SprStreamOpenParam param)

typedef const uint8_t (	SprStream_buf_fill )(struct SprStream *restrict fd, int min_fill)

typedef uint8_t (	SprStream_buf_flush )(struct SprStream *restrict fd)

typedef size_t(*	SprStream_ebuf_read )(struct SprStream restrict fd, void restrict buf, size_t size)

typedef int(*	SprStream_ebuf_write )(struct SprStream restrict fd, const void restrict buf, size_t size)

Enumerations
enum	SprOptFlags { SPR_OD_REQUIRED, SPR_OD_OPTIONAL, SPR_OD_ALLOW_REDEF, SPR_OD_ABS_DST }

enum	SPR_KEY_FORMAT { SPR_KEY_FORMAT_BIN01, SPR_KEY_FORMAT_BIN10, SPR_KEY_FORMAT_ASCII, SPR_KEY_FORMAT_NR }

enum	SPR_KEY_LAYOUT { SPR_KEY_LAYOUT_LIST, SPR_KEY_LAYOUT_MATRIX, SPR_KEY_LAYOUT_CUSTOM, SPR_KEY_LAYOUT_NR }

enum	SPR_KEY_DATA { SPR_KEY_DATA_SAMPLE, SPR_KEY_DATA_TRACK, SPR_KEY_DATA_CORPUS, SPR_KEY_DATA_SEG, SPR_KEY_DATA_DICTIONARY, SPR_KEY_DATA_PARAM, SPR_KEY_DATA_MATRIX, SPR_KEY_DATA_DES, SPR_KEY_DATA_NR }

enum	{ SPR_ERROR, SPR_WARNING, SPR_INFO }
	Predefined message levels for error, warning and info messages. More...

enum	{ SPR_MSG_SET, SPR_MSG_RM, SPR_MSG_ADD }

enum	{ SPR_SIGNAL_NONE, SPR_SIGNAL_CTRLC, SPR_SIGNAL_QUIT, SPR_SIGNAL_ERROR, SPR_SIGNAL_PIPE, SPR_SIGNAL_USR1, SPR_SIGNAL_USR2 }

enum	{ SPR_SRM_EXPORT, SPR_SRM_RELEASE, SPR_SRM_RELEASE2, SPR_SRM_RELEASE_DELAYED, SPR_SRM_CHECK_RELEASE, SPR_SRM_AD_ENLIST, SPR_SRM_AD_DELIST, SPR_SRM_RELEASE_UNLOCKED }
	Possible actions for the spr_srm_release() routine. More...

enum	{ SPR_SRM_CID_CLASSID, SPR_SRM_CID_DATATYPE, SPR_SRM_CID_DTCVT, SPR_SRM_CID_DYNLIB, SPR_SRM_CID_GLOBVAR, SPR_SRM_CID_VFS_OPEN, SPR_SRM_CID_VFS_EXT, SPR_SRM_CID_VFS_DEV, SPR_SRM_CID_VFS_MEM, SPR_SRM_CID_RESERVED }

enum	SprExprScanCodes { SPR_SCAN_BRC, SPR_SCAN_NL, SPR_SCAN_SEMI, SPR_SCAN_COMMA, SPR_SCAN_COL, SPR_SCAN_QMARK, SPR_SCAN_OP, SPR_SCAN_SYNTAX, SPR_SCAN_OP_SPC, SPR_SCAN_OP_ASSIGN, SPR_SCAN_OP_ORL, SPR_SCAN_OP_ANDL, SPR_SCAN_OP_ORB, SPR_SCAN_OP_ANDB, SPR_SCAN_OP_CMP, SPR_SCAN_OP_SHIFT, SPR_SCAN_OP_ADD, SPR_SCAN_OP_MUL, SPR_SCAN_OP_POW, SPR_SCAN_OP_MEMBER, SPR_SCAN_OP_MSK, SPR_SCAN_COMMENT_C, SPR_SCAN_COMMENT_S, SPR_SCAN_COMMENT_M, SPR_SCAN_MOD_NO_NL, SPR_SCAN_MOD_SPC, SPR_SCAN_MOD_POW, SPR_SCAN_MOD_CHR, SPR_SCAN_MOD_STRCAT, SPR_SCAN_NLC_DOTS, SPR_SCAN_NLC_BSLASH }
	Specify when an expression ends: scan until a valid seperator is found. More...

enum	SprStreamFlags { SPR_STREAM_CREATE, SPR_STREAM_TRUNC, SPR_STREAM_APPEND, SPR_STREAM_READ, SPR_STREAM_WRITE, SPR_STREAM_RW, SPR_STREAM_LINEBUF, SPR_STREAM_UNBUF, SPR_STREAM_SILENT, SPR_STREAM_SILENTEOF, SPR_STREAM_NONBLOCK, SPR_STREAM_KEEPKSET, SPR_STREAM_NOHDR, SPR_STREAM_SEEK, SPR_STREAM_REWIND, SPR_STREAM_AUTOCLOSE, SPR_STREAM_AUTORM, SPR_STREAM_ASCII }
	Flags for opening a file. More...

enum	{ SPR_STREAM_MODE_BIN, SPR_STREAM_MODE_BINSWAP, SPR_STREAM_MODE_ASCII }

Functions
void	spr_atomic_nop_MBwrite (void)

void	spr_atomic_nop_MBread (void)

void	spr_atomic_nop_MBfull (void)
	Impose a full (read+write) memory barrier. More...

uint32_t	spr_atomic_get32_MBacquire (volatile uint32_t *ptr)

uint32_t	spr_atomic_twinget32_MBnone (uint32_t ptr, uint32_t val2)

uint64_t	spr_atomic_twingetc48_18_MBnone (uint64_t ptr, uint64_t val2)

void	spr_atomic_set32_MBrelease (volatile uint32_t *ptr, uint32_t value)

void	spr_atomic_twinset32_MBrelease (volatile uint32_t *ptr, uint32_t value1, uint32_t value2)

void	spr_atomic_inc32_MBnone (volatile uint32_t *ptr)

uint32_t	spr_atomic_dec32_MBnone (volatile uint32_t *ptr)

uint32_t	spr_atomic_add32_MBnone (volatile uint32_t *ptr, uint32_t value)

uint32_t	spr_atomic_or32_MBnone (volatile uint32_t *ptr, uint32_t value)

uint32_t	spr_atomic_and32_MBnone (volatile uint32_t *ptr, uint32_t value)

uint32_t	spr_atomic_swap32_MBnone (volatile uint32_t *ptr, uint32_t value)

int	spr_atomic_cas32_MBnone (volatile uint32_t *ptr, uint32_t tst_value, uint32_t new_value)

int	spr_atomic_twincas32_MBnone (volatile uint32_t *ptr, uint32_t tst_value1, uint32_t tst_value2, uint32_t new_value1, uint32_t new_value2)

int	spr_atomic_bitset32_MBnone (volatile uint32_t *ptr, int bit_ndx)

int	spr_atomic_bitclr32_MBnone (volatile uint32_t *ptr, int bit_ndx)

int	spr_atomic_slot_acquire_nowait (SprAtomicSlot *slot)

int	spr_atomic_slot_acquire_wait (SprAtomicSlot *slot)

int	spr_atomic_slot_acquire0_wait (SprAtomicSlot *slot)

int	spr_atomic_slot_acquire_all (SprAtomicSlot *slot)

double	spr_strtod (const char str, const char str_end, char **eptr)

char *	spr_dt_qstr_cvt_insitu (char *restrict str)

char *	spr_dt_qstr_skip (const char *str)

int	spr_dt_alaw2short (int aval)

int	spr_dt_short2alaw (int sval)

int	spr_dt_ulaw2short (int uval)

int	spr_dt_short2ulaw (int sval)

int32_t	spr_atoi32 (const char str, int err)

uint32_t	spr_atou32 (const char str, int err)

int64_t	spr_atoi64 (const char str, int err)

uint64_t	spr_atou64 (const char str, int err)

float	spr_atof32 (const char str, int err)

double	spr_atof64 (const char str, int err)

ssize_t	spr_dt_print_vec (SprStream fd, const SprDT dt, const void vec, int vlen, const char info)

int	spr_dt_str2vec (const char str, const SprDT dt, void *restrict vec, int N)

int	spr_dt_str2vec_dyn (const char str, const SprDT dt, void **dst)

SprDynStr	spr_dt_vec2str (SprDynStr dst, const SprDT dt, const void vec, int N)

void *	spr_free (void ptr, const SprMsgId routine, const char *item)

void *	spr_malloc (size_t size, const SprMsgId routine, const char item)

void *	spr_realloc (void ptr, size_t size, const SprMsgId routine, const char *item)

unsigned int	spr_dynmem_check (SprMsgId routine, const char id)
	Check if the heap is corrupted. This routine is not mult-threading safe. More...

char *	spr_strdup (const char src, const SprMsgId routine, const char *item)

char *	spr_strndup (const char src, size_t size, const SprMsgId routine, const char *item)

char *	spr_strcpy (char *restrict dst, const char restrict src)

char *	spr_strcat (char restrict str1, const char restrict str2, int restrict str1_len, int str2_len, int restrict alen)

char *	spr_dynstr2alloc (SprDynStr str)

SprDynStr	spr_dynstr_free (SprDynStr str, const SprMsgId routine, const char item)

SprDynStr	spr_dynstr_alloc (size_t size, const SprMsgId routine, const char item)

SprDynStr	spr_dynstr_realloc (SprDynStr str, size_t size, const SprMsgId routine, const char item)

SprDynStr	spr_dynstr_enlarge (SprDynStr str, size_t size, const SprMsgId routine, const char item)

size_t	spr_dynstr_maxlen (SprDynStr str)

SprDynStr	spr_dynstr_cpy (SprDynStr dst, const char *src)

SprDynStr	spr_dynstr_ncpy (SprDynStr dst, const char *src, size_t src_len)

SprDynStr	spr_dynstr_dup (const char src, const SprMsgId routine, const char *item)

SprDynStr	spr_dynstr_ndup (const char *src, size_t src_len)

SprDynStr	spr_dynstr_cat (SprDynStr restrict str1, const char restrict str2, int restrict str1_len, int str2_len)

const char *	spr_str_nonull_ (const char *str)

const char *	spr_str_nonull (const char str, const char str_null)

size_t	spr_dynmem_pool_count_alloc (const SprMPool *mpool)

size_t	spr_dynmem_pool_count_free (const SprMPool *mpool)

size_t	spr_dynmem_pool_free (SprMPool mpool, SprMsgId routine)

void *	spr_dynmem_pool_enlarge (SprMPool *mpool)

int	spr_fmsnzb32 (uint32_t val)

int	spr_fmsnzb32x0 (uint32_t val)

int	spr_fmsnzb64 (uint64_t val)

int	spr_fmsnzb64x0 (uint64_t val)

int	spr_flsnzb32 (uint32_t val)

int	spr_flsnzb32x0 (uint32_t val)

int	spr_flsnzb64 (uint64_t val)

int	spr_flsnzb64x0 (uint64_t val)

int	spr_popcount16 (uint16_t val)
	Return the number of 1 bits in val. More...

int	spr_popcount32 (uint32_t val)
	Return the number of 1 bits in val. More...

int	spr_popcount64 (uint64_t val)
	Return the number of 1 bits in val. More...

uint32_t	spr_rotl32 (uint32_t val, unsigned int ndx)
	Rotate the value val ndx bits to the left. More...

uint32_t	spr_rotr32 (uint32_t val, unsigned int ndx)
	Rotate the value val ndx bits to the right. More...

uint64_t	spr_rotl64 (uint64_t val, unsigned int ndx)
	Rotate the value val ndx bits to the left. More...

uint64_t	spr_rotr64 (uint64_t val, unsigned int ndx)
	Rotate the value val ndx bits to the right. More...

uint64_t	spr_wide_umul32 (uint32_t val1, uint32_t val2)
	Double wide unsigned multiplication. More...

uint32_t	spr_wide_umul32hi (uint32_t val1, uint32_t val2)

int64_t	spr_wide_smul32 (int32_t val1, int32_t val2)
	Double wide signed multiplication. More...

int32_t	spr_wide_smul32hi (int32_t val1, int32_t val2)

int	spr_bittest (const unsigned int *bitarray, int ndx)

void	spr_bitset (unsigned int *bitarray, int ndx)
	Set the value of bit ndx in bit array bitarray to 1. More...

void	spr_bitclr (unsigned int *bitarray, int ndx)
	Set the value of bit ndx in bit array bitarray to 0. More...

uint16_t	spr_bswap16 (uint16_t val)

uint32_t	spr_bswap32 (uint32_t val)

uint64_t	spr_bswap64 (uint64_t val)

unsigned int	spr_sqrt_u32 (unsigned int nr)

int	spr_prime_check (unsigned int nr)

unsigned int	spr_prime_find (unsigned int nr)

unsigned int	spr_hash_str (const char *str)

unsigned int	spr_hash_str2 (const char *str, size_t str_len)

unsigned int	spr_hash_str_len (const char str, size_t len)

void	spr_htbl_str_init (SprHtblStr *restrict htbl, unsigned int flags, int keystr_offs)

SprHtblStr *	spr_htbl_str_new (unsigned int flags, int keystr_offs)

SprHtblStr *	spr_htbl_str_free (SprHtblStr *restrict htbl)

unsigned int	spr_htbl_str_Nel (const SprHtblStr *restrict htbl)

const char *	spr_htbl_str_iter (const SprHtblStr restrict htbl, int restrict ndx)

const char *	spr_htbl_str_ndx2str (const SprHtblStr *restrict htbl, int ndx)

int	spr_htbl_str_find_ndx (const SprHtblStr restrict htbl, const char restrict str)

int	spr_htbl_str_find_ndx2 (const SprHtblStr restrict htbl, const char restrict str, size_t str_len)

const char *	spr_htbl_str_find_key (const SprHtblStr restrict htbl, const char restrict str)

int	spr_htbl_str_add (SprHtblStr restrict htbl, const char restrict str)

int	spr_htbl_str_cadd (SprHtblStr restrict htbl, const char restrict str, int *restrict duplicate)

int	spr_htbl_str_add_replace (SprHtblStr restrict htbl, const char restrict str)

int	spr_htbl_str_rm_key (SprHtblStr restrict htbl, const char restrict str)

int	spr_htbl_str_rm_ndx (SprHtblStr *restrict htbl, int ndx)

int	spr_hash_strlin_search (const char restrict const hlst[], int Nel, const char restrict str)

int	spr_hash_strlin_search_err (const char restrict const hlst[], int Nel, const char restrict str)

int	spr_hash_strnlin_search (const char restrict const hlst[], const char restrict str, size_t str_len)

int	spr_hash_strnlin_search_err (const char restrict const hlst[], const char restrict str, size_t str_len)

SprKeySet *	spr_kset_alloc (void)

SprKeySet *	spr_kset_reset (SprKeySet *keys)

SprKeySet *	spr_kset_free (SprKeySet *keys)
	Free a previously allocated keyset. More...

int	spr_kset_set (SprKeySet keys, const char key, const char *value)

int	spr_kset_cset (SprKeySet keys, const char key, const char *value)

int	spr_kset_set_value (SprKeySet keys, const char key, const SprDT dt, const void value)

int	spr_kset_set_value_size (SprKeySet keys, const char key, ssize_t value)

int	spr_kset_set_value_double (SprKeySet keys, const char key, double value)

int	spr_kset_set_value_float (SprKeySet keys, const char key, float value)

const char *	spr_kset_get (const SprKeySet keys, const char key)

const char *	spr_kset_get_err (const SprKeySet keys, const char key)

int	spr_kset_get_value (const SprKeySet keys, const char key, const SprDT dt, void dst, const void *def_val)

ssize_t	spr_kset_get_value_size (const SprKeySet keys, const char key, ssize_t nf_val)

double	spr_kset_get_value_double (const SprKeySet keys, const char key, double nf_val)

float	spr_kset_get_value_float (const SprKeySet keys, const char key, float nf_val)

int	spr_kset_rm (SprKeySet keys, const char key)

int	spr_kset_get_value_format (const SprKeySet *keys)

int	spr_kset_get_value_format_alt (const SprKeySet *keys, int alt_val)

int	spr_kset_get_value_layout (const SprKeySet *keys)

const SprDT *	spr_kset_get_value_type (const SprKeySet *keys)

const SprDT *	spr_kset_get_value_type_alt (const SprKeySet keys, const SprDT alt_val)

ssize_t	spr_kset_get_value_dim1 (const SprKeySet *keys)

ssize_t	spr_kset_get_value_dim1_alt (const SprKeySet *keys, ssize_t alt_val)

ssize_t	spr_kset_get_value_dim2 (const SprKeySet *keys)

ssize_t	spr_kset_get_value_dim2_alt (const SprKeySet *keys, ssize_t alt_val)

ssize_t	spr_kset_get_value_nchan (const SprKeySet *keys)

ssize_t	spr_kset_get_value_nchan_alt (const SprKeySet *keys, ssize_t alt_val)

ssize_t	spr_kset_get_value_chanlen (const SprKeySet *keys)

ssize_t	spr_kset_get_value_chanlen_alt (const SprKeySet *keys, ssize_t alt_val)

double	spr_kset_get_value_fshift (const SprKeySet *keys)

double	spr_kset_get_value_fshift_alt (const SprKeySet *keys, double alt_val)

double	spr_kset_get_value_foffset (const SprKeySet *keys)

double	spr_kset_get_value_foffset_alt (const SprKeySet *keys, double alt_val)

int	spr_kset_get_values_dim_and_type (const SprKeySet keys, int dim1, int dim2, const SprDT dt, const char fname, SprMsgId *routine)

int	spr_kset_set_value_dim1 (SprKeySet *keys, ssize_t value)

int	spr_kset_set_value_dim2 (SprKeySet *keys, ssize_t value)

SprKeySet *	spr_kset_cpy (const SprKeySet *keys)

const char *	spr_kset_iter (const SprKeySet restrict keys, int restrict iter, const char **restrict value)

int	spr_kset_print (SprStream restrict fd, const SprKeySet restrict keys)

void	spr_kset_get_stdset (SprStdKeys restrict res, const SprKeySet restrict keys)
	Retrieve the 'standard' keys from keys. More...

SprKeySet *	spr_kset_set_defaults (SprKeySet restrict keys, SprStream restrict fd, const char *restrict fname)

SprKeySet *	spr_kset_check (const SprKeySet keys, const char fname)

ssize_t	spr_kset_sample_adjust (SprKeySet restrict keys, const double restrict fshift_ptr, const double *restrict flength_ptr, int htk_convention)

int	spr_kset_stream_modif (SprStream *restrict fd)

int	spr_msg (int lvl, SprMsgId routine, const char fmt,...)

int	spr_msg_check (int lvl, SprMsgId *routine)

int	spr_set_thread_id (const char *name)

void	spr_msg_modif_lvl (int lvl)
	Set the global message filter level to lvl, i.e. only messages with a level equal to or lower than lvl will be output (unless routine or thread specific levels are defined. More...

int	spr_msg_get_lvl (void)

int	spr_msg_modif_in (const char *filter_desc, int action)

int	spr_msg_modif_from (const char *filter_desc, int action)

SprDynStr	spr_msg_get_in (void)

SprDynStr	spr_msg_get_from (void)

int	spr_msg_modif_stream (SprStream restrict stream, const char restrict fname)

void	spr_msg_modif_catch_func (SprMsgCatchFunc handler)

char *	spr_path_ext_ptr (const char *fname)

int	spr_path_dir_len (const char *fname)

char *	spr_path_split_insitu (char path, char suffix, char *fname)

int	spr_signal_report (int action_mask)

const char *	SPR_CLASSID_FROM_OBJ (const void *object)

SprSrmEl *	spr_srm_retrieve (unsigned int class_id, const char *name)

SprSrmEl *	spr_srm_retrieve_alt (unsigned int class_id, const char *name, size_t sz)

SprSrmEl *	spr_srm_get (unsigned int class_id, const char *name)

SprSrmEl *	spr_srm_create (unsigned int class_id, const char *name, int name_is_persistent)

SprSrmEl *	spr_srm_retrieve_or_create (unsigned int class_id, const char *name, int name_is_persistent)

int	spr_srm_release (SprSrmEl *srm_el, int action)

void	spr_srm_release_quick (SprSrmEl *srm_el)

void	spr_srm_release_nocheck (SprSrmEl *srm_el)

SprSrmDir *	spr_srm_dir (unsigned int class_id)

int	spr_srm_check_initialized (SprSrmEl *srm_el)

int	spr_srm_set_free_routine (SprSrmEl *srm_el, SprSrmFree free_func)

int	spr_srm_set_info_val1_ptr (SprSrmEl srm_el, void val)

int	spr_srm_set_info_val1_ndx (SprSrmEl *srm_el, unsigned int val)

int	spr_srm_set_info_val2_ptr (SprSrmEl srm_el, void val)

int	spr_srm_set_info_val2_ndx (SprSrmEl *srm_el, unsigned int val)

void *	spr_srm_get_info_val1_ptr (const SprSrmEl srm_el, int err)

unsigned int	spr_srm_get_info_val1_ndx (const SprSrmEl srm_el, int err)

void *	spr_srm_get_info_val2_ptr (const SprSrmEl srm_el, int err)

unsigned int	spr_srm_get_info_val2_ndx (const SprSrmEl srm_el, int err)

int	spr_isspace (unsigned int chr)

int	spr_isspace0 (unsigned int chr)

int	spr_isupper (unsigned int chr)

int	spr_islower (unsigned int chr)

int	spr_toupper (unsigned int chr)

int	spr_tolower (unsigned int chr)

int	spr_isalpha (unsigned int chr)

int	spr_isalpha_ (unsigned int chr)

int	spr_isalnum (unsigned int chr)

int	spr_isalnum_ (unsigned int chr)

int	spr_isalphax_ (unsigned int chr)

int	spr_isalnumx_ (unsigned int chr)

int	spr_isdigit (unsigned int chr)

int	spr_isxdigit (unsigned int chr)

char *	spr_str_skip_space (const char *str)
	Skip 0 or more initial spaces. More...

char *	spr_str_skip_word (const char *str)

int	spr_str_split (char str, char tok, int max_tok, char *rem)

int	spr_str_split_ref (const char str, SprStrSplit tok, int max_tok, const char **rem)

char **	spr_str_split_dyn (char str, int max_tok)

int	spr_str_trim_spaces (char *str)

int	spr_scanf_simple (const char str, const char fmt, SprScanfDst dst, SprScanfErr err)

char *	spr_expr_scan (const char str, int len, unsigned int flags, SprExprScanErr err)

size_t	spr_stream_read (SprStream restrict fd, void restrict buf, size_t size)
	Read from a stream. More...

int	spr_stream_write (SprStream restrict fd, const void restrict buf, size_t size)
	Write to a stream. More...

size_t	spr_stream_skip (SprStream *restrict fd, size_t size)
	Skip data from a stream. More...

int	spr_stream_fill (SprStream *restrict fd, int chr, size_t size)

int	spr_stream_mkdir_parents (SprMsgId routine, char path)

SprStream *	spr_stream_dynbuf_make (const char name, void buf, size_t alen, size_t fill, unsigned int flags, SprKeySet *keys)

SprStream *	spr_stream_dynstr_make (const char name, SprDynStr str, size_t fill, unsigned int flags, SprKeySet keys)

SprStream *	spr_stream_open_write (const char restrict fname, unsigned int flags, const char def_keys,...)

unsigned int	spr_stream_check (const char *restrict fname, unsigned int flags)

int	spr_fgetc (SprStream *restrict fd)

int	spr_fgetc_utf8 (SprStream *restrict fd)

int	spr_ungetc (SprStream *restrict fd, int chr)

int	spr_ungetc_utf8 (SprStream *restrict fd, int chr)

int	spr_fputc (SprStream *restrict fd, int chr)

int	spr_fputc_utf8 (SprStream *restrict fd, int chr)

SprDynStr	spr_fgets (SprDynStr restrict str, SprStream restrict fd, unsigned int flags, int restrict pos)

char *	spr_fgets_alt (char restrict str, int restrict alen, SprStream restrict fd, unsigned int flags, int restrict pos)

ssize_t	spr_fputs (SprStream restrict fd, const char restrict str)

ssize_t	spr_fputsq (SprStream restrict fd, const char restrict str)

ssize_t	spr_fputsoq (SprStream restrict fd, const char restrict str)

int	spr_stream_hex_write (SprStream restrict fd, const void restrict data, size_t Nel, size_t el_size)

int	spr_stream_hex_read (SprStream restrict fd, void restrict data, size_t Nel, size_t el_size)

off_t	spr_stream_copy_data (SprStream restrict dst, SprStream restrict src)

int	spr_fprintf (SprStream restrict fd, const char restrict fmt,...)

int	spr_vfprintf (SprStream restrict fd, const char restrict fmt, va_list args)

size_t	spr_snprintf (char restrict buf, size_t size, const char restrict fmt,...)

size_t	spr_snprintf0 (char restrict buf, size_t size, const char restrict fmt,...)

size_t	spr_vsnprintf (char restrict buf, size_t size, const char restrict fmt, va_list args)

SprDynStr	spr_sprintf (SprDynStr restrict str, const char *restrict fmt,...)

SprDynStr	spr_vsprintf (SprDynStr restrict str, const char *restrict fmt, va_list args)

SprDynStr	spr_soprintf (SprDynStr restrict str, size_t restrict offset, const char restrict fmt,...)

SprDynStr	spr_vsoprintf (SprDynStr restrict str, size_t restrict offset, const char restrict fmt, va_list args)

char *	spr_sprintf_alt (SprDynStr restrict str, int restrict alen, const char restrict fmt,...)

char *	spr_vsprintf_alt (char restrict str, int restrict alen, const char *restrict fmt, va_list args)

char *	spr_soprintf_alt (char restrict str, int restrict alen, int restrict pos, const char restrict fmt,...)

SprDynStr	spr_vsoprintf_alt (char restrict str, int restrict alen, int restrict pos, const char restrict fmt, va_list args)

SprStream *	spr_stream_open_tmp (const char *template_str, unsigned int flags,...)

size_t	spr_utf8_len (const char *str)

char *	spr_utf8_next (const char *str)

char *	spr_utf8_nextN (const char *str, int N)

char *	spr_utf8_prev (const char *str)

char *	spr_utf8_get_advance (int utf_chr, const char str)

char *	spr_utf8_check (const char str, SprMsgId routine)

int	spr_utf8_chr_len (unsigned int chr)

char *	spr_utf8_chr_put_advance (char *str, unsigned int chr)

Variables
SprDT	spr_dt_dt [1]

SprDT	spr_dt_custom [1]

const SprOptDesc	spr_od_common []

const SprHtblStr	spr_htbl_str_empty

const char	spr_kset_key_data []
	the string "DATA" More...

const char	spr_kset_key_layout []
	the string "LAYOUT" More...

const char	spr_kset_key_format []
	the string "FORMAT" More...

const char	spr_kset_key_type []
	the string "TYPE" More...

const char	spr_kset_key_dim1 []
	the string "DIM1" More...

const char	spr_kset_key_dim2 []
	the string "DIM2" More...

const char	spr_kset_key_fshift []
	the string "FSHIFT" More...

const char	spr_kset_key_foffset []
	the string "FOFFSET" More...

const char	spr_kset_key_flength []
	the string "FLENGTH" More...

const char	spr_kset_key_nchan []
	the string "NCHAN" More...

const char	spr_kset_key_chanlen []
	the string "CHANLEN" More...

const char	spr_kset_key_vlen []
	the string "VLEN" More...

const char	spr_kset_key_vnum []
	the string "VNUM" More...

const char	spr_kset_key_compress []
	the string "COMPRESS" More...

const char	spr_kset_key_samplefreq []
	the string "SAMPLEFREQ" More...

const char	spr_kset_val_minus1 []

const char *const	spr_kset_format_str []

const char *const	spr_kset_layout_str []

const char *const	spr_kset_data_str [SPR_KEY_DATA_NR+1]

SprStream *	spr_msg_stream

volatile int	spr_signal_flag
	break requested ? More...

const char	spr_str_srm_cid_classid []

const char	spr_str_srm_cid_datatype []

const char	spr_str_srm_cid_datatype_cvt []

const char	spr_str_srm_cid_dynlib []

const char	spr_str_srm_cid_globvar []

const char	spr_str_srm_cid_vfs_open []

const char	spr_str_srm_cid_vfs_ext []

const char	spr_str_srm_cid_vfs_dev []

const char	spr_str_srm_cid_vfs_mem []

const char *	spr_stream_tmpdir

Detailed Description

Macro Definition Documentation

#define spr_dt_f64

The SPRAAK data type identifier (SprDT element) for a double precision (64 bits) float. The string respresentation (used in file headers, messages, ...) of this type is "F64".

#define spr_dt_f32

The SPRAAK data type identifier (SprDT element) for a single precision (32 bits) float. The string respresentation (used in file headers, messages, ...) of this type is "F32".

#define spr_dt_i64

The SPRAAK data type identifier (SprDT element) for a 64 bits signed integer. The string respresentation (used in file headers, messages, ...) of this type is "I64".

#define spr_dt_u64

The SPRAAK data type identifier (SprDT element) for a 64 bits unsigned integer. The string respresentation (used in file headers, messages, ...) of this type is "U64".

#define spr_dt_i32

The SPRAAK data type identifier (SprDT element) for a 32 bits signed integer. The string respresentation (used in file headers, messages, ...) of this type is "I32".

#define spr_dt_u32

The SPRAAK data type identifier (SprDT element) for a 32 bits unsigned integer. The string respresentation (used in file headers, messages, ...) of this type is "U32".

#define spr_dt_i16

The SPRAAK data type identifier (SprDT element) for a 16 bits signed integer. The string respresentation (used in file headers, messages, ...) of this type is "I16".

#define spr_dt_u16

The SPRAAK data type identifier (SprDT element) for a 16 bits unsigned integer. The string respresentation (used in file headers, messages, ...) of this type is "U16".

#define spr_dt_i8

The SPRAAK data type identifier (SprDT element) for an 8 bits signed integer. The string respresentation (used in file headers, messages, ...) of this type is "I8".

#define spr_dt_u8

The SPRAAK data type identifier (SprDT element) for an 8 bits unsigned integer. The string respresentation (used in file headers, messages, ...) of this type is "U8".

#define spr_dt_char

The SPRAAK data type identifier (SprDT element) for a dynamically allocated string. The string respresentation (used in file headers, messages, ...) of this type is "DYNSTR".

Note: Previous values will be freed, so make sure the destination is initialized to NULL.

#define spr_dt_alaw

The SPRAAK data type identifier (SprDT element) for an alaw code (8 bits unsigned integer). The string respresentation (used in file headers, messages, ...) of this type is "ALAW".

#define spr_dt_ulaw

The SPRAAK data type identifier (SprDT element) for an ulaw code (8 bits unsigned integer). The string respresentation (used in file headers, messages, ...) of this type is "ULAW".

#define spr_dt_dynstr

The SPRAAK data type identifier (SprDT element) for a dynamically allocated string. The string respresentation (used in file headers, messages, ...) of this type is "DYNSTR".

Note: Previous values will be freed, so make sure the destination is initialized to NULL.

#define spr_dt_int

The SPRAAK data type identifier (SprDT element) for a standard integer (int). The string respresentation (used in file headers, messages, ...) of this type is "I32".

#define spr_dt_uint

The SPRAAK data type identifier (SprDT element) for a standard unsigned integer (unsigned int). The string respresentation (used in file headers, messages, ...) of this type is "U32".

#define spr_dt_long

#define spr_dt_ulong

#define spr_dt_ssize

#define spr_dt_size

#define spr_dt_ptr

Some generic pointer type. Useful for dumping the values to the screen.

#define spr_dt_bool

The SPRAAK data type identifier (SprDT element) for a boolean (an integer having the values 0 or 1). The string respresentation (used in file headers, messages, ...) of this type is "BOOL".

#define spr_dt_true

The SPRAAK data type identifier (SprDT element) for a boolean (an integer having the values 0 or 1) that has as default value 1 (true). The string respresentation (used in file headers, messages, ...) of this type is "BOOL".

#define spr_dt_false

The SPRAAK data type identifier (SprDT element) for a boolean (an integer having the values 0 or 1) that has as default value 0 (false). The string respresentation (used in file headers, messages, ...) of this type is "BOOL".

#define spr_dt_string

The SPRAAK data type identifier (SprDT element) for a string pointer. The string respresentation (used in file headers, messages, ...) of this type is "STRING".

#define spr_od_end

Indicate the end of an argument description list.

#define spr_od_info	(	title,
		info
	)

Specify some (global) comment instead of an argument. The title and info arguments are strings containing the paragraph title (optional) and the actual information.

#define spr_od_include	(	other_opt_spec,
		offs
	)

Include the content of an other (pre-existent) option description other_opt_spec.

#define spr_od_alias	(	alias,
		original
	)

Define an alias alias for an other (earlier defined) options original.

#define spr_od_funcarg0	(	name,
		flags,
		brief,
		detailed,
		func
	)

Define an option that will trigger a call to the function (*func)(const SprOptDesc*od_match,const SprOptDesc*od_list) when specified (the normal result of specifying an option is decoding the argument and storing its values). The function must return 0 on success and -1 on failure.

#define spr_od_funcarg1	(	name,
		flags,
		brief,
		detailed,
		func,
		def_val
	)

Define an option that will trigger a call to the function (*func)(const SprOptDesc*od_match,const char *arg_val) when specified (the normal result of specifying an option is decoding the argument and storing its values). The function must return 0 on success and -1 on failure.

#define spr_od_posarg	(	flags,
		brief,
		detailed,
		type,
		offs,
		def_val
	)

Define a positional (ordinal) argument, i.e. an argument with no option name. Ordinal arguments are filled in on a first come first served base.

Note: From the moment the first positional argument is encountered, all remaining arguments are assumed to be positional arguments!; Use a collector data type if you want to collect all remaining arguments.

#define SPR_MPOOL_CHUNK_SZ

Number of elements allocated per chunk (i.e. per call to spr_dynmem_pool_enlarge()).

#define SPR_MPOOL_INITIALIZER	(	type,
		next_el
	)

Initialize a memory pool for a certain type type using type->next_el to link the free elements together.

#define SPR_MPOOL_INIT	(	mpool,
		type,
		next_el
	)

Initialize a memory pool for a certain type type using type->next_el to link the free elements together.

#define SPR_DEFAULT_FSHIFT

The default frame shift (10 msec).

#define SPR_DEFAULT_SAMPLEFREQ

The default sample frequency (8kHz).

#define SPR_MSG_ID	(	var,
		name
	)

Macro to set the routine id (requires that the name is static). For examples, see the global comment.

#define SPR_SET_THREAD_ID ( thread_name )

#define spr_error	(	routine,
		...
	)

Send an error message.

Is identical to spr_msg(SPR_ERROR,routine,fmt,...)

#define spr_warning	(	routine,
		...
	)

Send a warning message.

Is identical to spr_msg(SPR_WARNING,routine,...)

#define spr_info	(	routine,
		...
	)

Send an info message.

Is identical to spr_msg(SPR_INFO,routine,...)

#define spr_msg_long_start	(	lvl,
		routine,
		...
	)

Send a long debug message at a given level lvl.

#define spr_msg_async_start	(	lvl,
		routine,
		...
	)

Try to send a long debug message at a given level lvl from s signal handler. No message will be sent if the message system is busy (should be fixed).

#define SPR_CAST	(	spr__base,
		spr__class,
		spr__object
	)

Cast the type of a class object.

Cast the type of the object spr__object of type spr__class to one of its base classes spr__base.

#define SPR_CLASSID_FORM_CLASS ( spr__class )

Get the id (a unique pointer to a string) of the class the object belongs to.

#define SPR_DO	(	spr__class,
		spr__method,
		...
	)

Call a method from a class.

Call method spr__method from and object of class spr__class. For non static methods the first argument must be the object.

SPR_DO(class,method,object);
// or
SPR_DO(class,method,object,method_arguments...);

For static methods with no arguments, the last argument must be empty, i.e. call the method by using a

SPR_DO(class,method,);

construct.

#define SPR_DO_FPTR	(	spr__class,
		spr__method,
		spr__object
	)

Get function pointer for a given method.

Get the function pointer for method spr__method from class spr__class given object spr__object. For static methods, the third argument must be empty or NULL. For an example see SprMethodPtr.

#define SPR_DO_OPTR	(	spr__class,
		spr__method,
		spr__object
	)

Get the adjusted object pointer for a given method.

Get the adjusted object pointer for method <spr__method) from class spr__class given object spr__object. For an example see SprMethodPtr.

#define SprMethodPtr	(	spr__class,
		spr__method
	)

Generate a method function pointer type.

Generate the type for a function pointer to method spr__method from class spr__class.

Example:

SprMethodPtr(MyClass,method_do_something) fptr = SPR_DO_FPTR(MyClass,method_do_something,obj);
void *optr = SPR_DO_OPTR(MyClass,method_do_something,obj);    // we usualy do not know the required base class, so we settle for <void*>
for(int i=0;i<1000000;i++)                                    // a long loop
 {...
  (*fptr)(optr,...);
  ...
 }

#define SPR_OBJECT_INIT	(	spr__class,
		spr__object
	)

Initialize RTTI of a dynamically allocated object.

Initialize the run-time type information (RTTI) of an object that is dynamically allocated. This must be done for every new allocated object!

Example:

MyClass *obj;
if((obj=spr_malloc(sizeof(MyClass),routine,"obj")) == NULL)
  goto ERROR_;
SPR_OBJECT_INIT(MyClass,obj);   // don't forget this!
...                             // rest of the initialisation needed to make this a functional object

#define SPR_LVAR_OBJECT_INIT	(	spr__class,
		spr__object
	)

Initialize RTTI of a statically allocated object.

Initialize the RTTI of an object that is statically allocated. This must be done for every local or static variable that is an object!

Example:

MyClass obj;
SPR_LVAR_OBJECT_INIT(MyClass,obj);      // don't forget this!
...                                     // rest of the initialisation needed to make this a functional object

#define spr_stderr

Stream handler for the 'stderr' stream.

Typedef Documentation

typedef SprDTCvtAux*(* _FuncPtr1_DATATYPE_)(struct SprDTCvtAuxSrm *aux_data, const SprDT *dt_dst, const SprDT *dt_src)

typedef void*(* SprDTCvt1Func)(void *restrict dst,const void *restrict src,const SprDTCvtAux *restrict aux)

Function pointer to a function that converts data from one type to another and returns &dst[1] if successfull or NULL on failure. See SprDT::get_cvt1_func() for more details.

typedef void*(* SprDTCvtNFunc)(void *restrict dst,const void *restrict src,size_t Nel,const SprDTCvtAux *restrict aux)

Function pointer to a function that converts data from one type to another and returns &dst[Nel] if successfull or NULL on failure. See SprDT::get_cvtN_func() for more details.

typedef void*(* SprDTCvtNsiFunc)(void *restrict dst,const void *restrict src,size_t Nel,size_t offs_src_next,const SprDTCvtAux *restrict aux)

Function pointer to a function that converts data from one type to another and returns &dst[Nel] if successfull or NULL on failure. See SprDT::get_cvtNsi_func() for more details.

typedef void*(* SprDTCvtNdiFunc)(void *restrict dst,const void *restrict src,size_t Nel,size_t offs_dst_next,const SprDTCvtAux *restrict aux)

Function pointer to a function that converts data from one type to another and returns (dst+Nel*offs_dst_next) if successfull or NULL on failure. See SprDT::get_cvtNdi_func() for more details.

typedef void*(* SprDTCvtNsdiFunc)(void *restrict dst,const void *restrict src,size_t Nel,size_t offs_src_next,size_t offs_dst_next,const SprDTCvtAux *restrict aux)

Function pointer to a function that converts data from one type to another and returns (dst+Nel*offs_dst_next) if successfull or NULL on failure. See SprDT::get_cvtNsdi_func() for more details.

typedef int(* SprDTRead1Func)(const SprDT *dt, SprStream *restrict fd, void *restrict dst)

Pointer to a SprDT::read1() method, see SprDT::get_read1_func() and SprDT::read1() for more details.

typedef ssize_t(* SprDTReadNFunc)(const SprDT *dt, SprStream *restrict fd, void *restrict dst, size_t Nel)

Pointer to a SprDT::readN() method, see SprDT::get_readN_func() and SprDT::readN() for more details.

typedef ssize_t(* SprDTReadNiFunc)(const SprDT *dt, SprStream *restrict fd, void *restrict dst, size_t Nel, size_t offs_next)

Pointer to a SprDT::readNi() method, see SprDT::get_readNi_func() and SprDT::readNi() for more details.

typedef int(* SprDTWrite1Func)(const SprDT *dt, SprStream *restrict fd, const void *restrict src)

Pointer to a SprDT::write1() method, see SprDT::get_write1_func() and SprDT::write1() for more details.

typedef int(* SprDTWriteNFunc)(const SprDT *dt, SprStream *restrict fd, const void *restrict src, size_t Nel)

Pointer to a SprDT::writeN() method, see SprDT::get_writeN_func() and SprDT::writeN() for more details.

typedef int(* SprDTWriteNiFunc)(const SprDT *dt, SprStream *restrict fd, const void *restrict src, size_t Nel, size_t offs_next)

Pointer to a SprDT::writeNi() method, see SprDT::get_writeNi_func() and SprDT::writeNi() for more details.

typedef ssize_t(* SprDTSkipNFunc)(const SprDT *dt, SprStream *restrict fd, size_t Nel)

Pointer to a SprDT::skipN() method, see SprDT::get_skipN_func() and SprDT::skipN() for more details.

typedef struct SprHtblStr SprHtblStr

A hash table that stores strings (the keys) and, if desired, allows to user to map these keys to corresponding values. The hash table is designed to be compact (especially when only few keys need to be stored), and can be easily embedded in a larger structure. Assigning values to the keys in the hash table can be done in two ways (which can even be combined).

The first method uses the fact that the keys are internally mapped to sequential indexes. I.e. the indices returned by e.g. spr_htbl_qstr2ndx_find() will be 0...N-1, N being the numbers of strings in the hash table. Otherwise said, the keys are mapped to indexes 0...N-1 and the indeces equal the order in which the keys were added to the hash table. In case elements are removed, gaps occur in the sequential ordering (unless it was the last added key that was removed). When adding new keys afterwards, the gaps created in the sequential numbering by removing elements are filled first, after which the indices for new strings will again be sequential.

Instead of relaying on the sequential indexes, the user can also embed extra information (the value) in the strings (the keys) stored in the hash table. The extra information can either follow the terminating '\0' of the key-string or it can precede the key-string. Note that all functions (except for spr_htbl_str_free()) are agnostic concerning extra information preceding or following the key-string. In practice, this means that when using embedded extra information preceding the key-string one should always offset the pointer to point to the key-string field when calling any of the 'add' routines, and know that all returned pointers will again point to the key-string field (and hence should be negatively offset if one want to access the embedded extra information).

Below is an example of how extra information can be embedded:

typedef struct          // map a key (string) to a (string,int,double) tuple
 {char   *value_str;
  int    value_int;
  double value_flt;
  char   key[];
 } KeyVal;
SprHtblStr htbl[1];
spr_htbl_str_init(htbl,SPR_HTBL_STR_FREE_STR,offsetof(KeyVal,key));
...
KeyVal *kv;
if((kv=spr_malloc(offsetof(KeyVal,key)+strlen(key)+1,routine,"key_value")) == NULL)
  goto LBL_ERROR;
strcpy(kv->key,key);
kv->value_str = "test";
kv->value_int = 13;
kv->value_flt = 3.14159;
if(spr_htbl_str_add(htbl,&kv->key) == -1)
  goto LBL_ERROR;
...
if((kv=(KeyVal*)spr_htbl_str_find_key(htbl,key)) == NULL)
  goto LBL_ERROR;
kv = (KeyVal*)((char*)kv-offsetof(KeyVal,key));
spr_info(routine,"str=%s, int=%i, flt=%g",kv->value_str,kv->value_int,kv->value_flt);
...
LBL_ERROR:
spr_htbl_str_free(&htbl);

typedef void(* SprMsgCatchFunc)(int lvl,const char *thread,const char *routine,const char *format,va_list *list)

Function to catch severe (WARNING & ERROR) messages with. Calls to such a function will be serialized (protected by a mutex). Only one handler can be installed.

typedef struct spr_t_object SprObject

An empty object (except for the the pointer to the run-time type information). The presence of the RTTI-pointer allows classes that derive directly or indirectly from this class to have virtual methods.

typedef struct SprSrmEl SprSrmEl

The basic type for a shared resource. This is an opaque type. All modifiable content can be accessed by means of (inline) functions.

typedef void(* SprSrmFree)(SprSrmEl *srm_el, SprMsgId *routine)

Prototype of a function to free the content of a resource.

typedef struct SprStreamOpenParam SprStreamOpenParam

typedef int(* SprStreamOpenProtocol)(SprStreamOpenInfo *info, SprStreamOpenParam *param)

Pointer to a function that opens the stream with as "path name" info->fname. The param argument is either NULL or a structure made earlier by a call to the corresponding SprStreamOpenDecodeParam function. The remaining information (keyset, flags) can be found in info. See spr_stream_open() for the meaning of the bits in info->flags.

Returns: 0 on success and (-1) on failure. On success, the new stream handler must be stored in info->fd.

Note: A SprStreamOpenProtocol function may also push coders, see SprStreamOpenCoder for details on how this is done.; A SprStreamOpenProtocol may change info->fname to reflect the actual file name used, as long as the new name (inclusing the final '\0') fits withing info->fname_maxlen bytes.

typedef int(* SprStreamOpenCoder)(SprStreamOpenInfo *info, SprStreamOpenParam *param)

Point to a function to push and extra coder (or several) on top of the open file info->fd. The param argument is either NULL or a structure made earlier by a call to the corresponding SprStreamOpenDecodeParam function.

Returns: 0 on success and (-1) on failure. On return (success or failure), info->fd should be set on to the latest successfully pushed (de)coder (or the original stream).

typedef char*(* SprStreamOpenDecodeParam)(SprStreamOpenParam **param_info, char *param_desc, SprStreamOpenInfo *info)

Point to a function to decode the parameters specified in param_desc and store whatever data that will be needed in the corresponding SprStreamOpenProtocol, SprStreamOpenCoder, SprStreamOpenHdrRead or SprStreamOpenHdrWrite function in a newly allocated data structure.

How the parameters in param_desc are formatted free although the format "key=value;" (value van be a quoted string) is strongly advised since this is consistent with how all the other parameters are passed. The only real constraint on the parameter description is that it starts with an square bracket open character ('[') and stops at an square bracket close character (']'). Note that the square bracket open character may have been replaced by a '\0' beforehand.

The processed part of param_desc may be used as temporary buffer (or scratch pad) which is guaranteed to last until the parameter info *param_info is freed.

Returns: A pointer right after the closing bracket in param_desc or NULL on failure.

typedef SprStreamOpenParam*(* SprStreamOpenFreeParam)(SprStreamOpenInfo *info, SprStreamOpenParam *param_data)

Point to a function to free the parameter data param_data made by a previous call to the corresponding SprStreamOpenDecodeParam function. The info argument is typically not needed, but is given for the sake of orthogonality w.r.t. the other functions.

Returns: NULL

typedef int(* SprStreamOpenHdrRead)(SprStreamOpenInfo *info, SprStreamOpenParam *param)

Point to a function to read the file header from info->fd and fill in the keys in info->keys (any previously present keys are considered to be default values). On entry, info->keys may be NULL. The param argument points to the data structure made by a call to the corresponding SprStreamOpenDecodeParam function.

Returns: 0 on success or (-1) on failure.

Note: On failure, info->fd and info->keys must still be valid. In other words, do not try to close/free them when reading the keyset fails.

typedef int(* SprStreamOpenHdrWrite)(SprStreamOpenInfo *info, SprStreamOpenParam *param)

Pointer to a function to write a file header containing the keys in info->keys to info->fd. On entry, info->keys may be NULL (is a valid keyset for some header formats), so do not forget to check this if you need a non NULL keyset. The param argument points to the data structure made by a call to the corresponding SprStreamOpenDecodeParam function.

Returns: 0 on success or (-1) on failure.

Note: On failure, info->fd and info->keys must still be valid. In other words, do not try to close/free them when reading the keyset fails.

typedef int(* SprStreamOpenCheck)(SprStreamOpenInfo *info, SprStreamOpenParam *param)

Pointer to a function to check the capabilities of a stream.

Returns

1: if the stream info->fname exists (when coping with coders or headers this is not relevant) and the capabilities requested in info->flags are possible
0: if the above is not the case
-1: if an error occurred

typedef const uint8_t*(* SprStream_buf_fill)(struct SprStream *restrict fd, int min_fill)

See Also: SprStream::buf_fill().

typedef uint8_t*(* SprStream_buf_flush)(struct SprStream *restrict fd)

See Also: SprStream::buf_flush().

typedef size_t(* SprStream_ebuf_read)(struct SprStream *restrict fd, void *restrict buf, size_t size)

See Also: SprStream::ebuf_read().

typedef int(* SprStream_ebuf_write)(struct SprStream *restrict fd, const void *restrict buf, size_t size)

See Also: SprStream::ebuf_write().

Enumeration Type Documentation

enum SprOptFlags

Enumerator
SPR_OD_REQUIRED	The option is required.
SPR_OD_OPTIONAL	The option is optional.
SPR_OD_ALLOW_REDEF	The option can be specified multiple times, the last specification dictates the final value.
SPR_OD_ABS_DST	Write the decoded argument to some absolute address instead of having an offset within a structure. The offset part should now be initialized using the construct "(intptr_t)\&var".

enum SPR_KEY_FORMAT

Possible values for the 'FORMAT' key. This is a closed list (i.e. these are the only legal values). The values written in the header should be one of the following:

BIN01: binary data, little endian format
BIN10: binary data, big endian format
ASCII: ascii data

Enumerator
SPR_KEY_FORMAT_BIN01	Binary data, little endian format.
SPR_KEY_FORMAT_BIN10	Binary data, big endian format.
SPR_KEY_FORMAT_ASCII	Ascii data.
SPR_KEY_FORMAT_NR

enum SPR_KEY_LAYOUT

Possible values for the 'LAYOUT' key. This is a closed list (i.e. these are the only legal values). The values written in the header should be one of the following:

LIST: a list (sequence) of entries, e.g. a corpus, a lexicon
MATRIX: a matrix or vector, e.g. feature vectors, samples, matrices
CUSTOM: some custom (usualy complex) layout; in practice this will almost always result in a non base-type value for the TYPE key as well

Enumerator
SPR_KEY_LAYOUT_LIST	A list (sequence) of entries, e.g. a corpus, a lexicon.
SPR_KEY_LAYOUT_MATRIX	A matrix or vector, e.g. feature vectors, samples, matrices.
SPR_KEY_LAYOUT_CUSTOM	Some custom (usualy complex) layout. In practice this will almost always result in a complex TYPE key as well.
SPR_KEY_LAYOUT_NR

enum SPR_KEY_DATA

Possible values for the 'DATA' key. This is an open list (i.e. these are more legal values then listed here). Typical values found in headers are:

SAMPLE: the file contains audio data (samples)
TRACK: the file contains feature vectors (frames)
CORPUS: the file is a corpus file
SEG: the file is a segmentation file
DICTIONARY: the file is a dictionary (lexicon) file
PARAM: the file contains parameters of some kind
MATRIX: the file contain a matrix
DES: the file contain a list (of strings)

The string representations belonging to the different SPR_KEY_DATA_XXX constants.

Enumerator
SPR_KEY_DATA_SAMPLE	Samples (audio data).
SPR_KEY_DATA_TRACK	Frames (feature vectors).
SPR_KEY_DATA_CORPUS	Corpus entries.
SPR_KEY_DATA_SEG	Segmentation entries.
SPR_KEY_DATA_DICTIONARY	Dictionary entries.
SPR_KEY_DATA_PARAM	Parameters of some kind.
SPR_KEY_DATA_MATRIX	A matrix.
SPR_KEY_DATA_DES	A list.
SPR_KEY_DATA_NR

anonymous enum

Predefined message levels for error, warning and info messages.

Enumerator
SPR_ERROR
SPR_WARNING
SPR_INFO

anonymous enum

Possible actions for spr_msg_modif_in() and spr_msg_modif_from().

Enumerator
SPR_MSG_SET
SPR_MSG_RM
SPR_MSG_ADD

anonymous enum

Enumerator
SPR_SIGNAL_NONE	The default value: nothing is signaled.
SPR_SIGNAL_CTRLC	Ctrl-C pressed (break requested).
SPR_SIGNAL_QUIT	Program is requested to stop (typically by means of the kill command / task manager).
SPR_SIGNAL_ERROR	A fatal error (segfaul or other) has occured. this is typically not reported back since one cannot recover from that.
SPR_SIGNAL_PIPE	The other size closed the pipe/socket we were trying to read from or write to.
SPR_SIGNAL_USR1	The USR1 signal was received. Typically used to report the progress back to the user.
SPR_SIGNAL_USR2	The USR2 signal was received. Typically used to report the progress back to the user in combination with a stack trace.

anonymous enum

Possible actions for the spr_srm_release() routine.

Enumerator
SPR_SRM_EXPORT
SPR_SRM_RELEASE
SPR_SRM_RELEASE2
SPR_SRM_RELEASE_DELAYED
SPR_SRM_CHECK_RELEASE
SPR_SRM_AD_ENLIST
SPR_SRM_AD_DELIST
SPR_SRM_RELEASE_UNLOCKED

anonymous enum

A set of default classes with known index for storing shared resources in.

Enumerator
SPR_SRM_CID_CLASSID	Class-id are also shared resources and hence hace a class to store them in. 'val1' contains the class number.
SPR_SRM_CID_DATATYPE	Datatypes. 'val1' is a pointer to the corresponding SprDT structure.
SPR_SRM_CID_DTCVT	Conversion rules between datatypes. 'val1' is a pointer to the actual conversion routine; 'val2' is a pointer to the auxilary data (of the type SprDtCvtAuxSrm).
SPR_SRM_CID_DYNLIB	Dynamic libraries. 'val1' is a pointer to the handle for the dynamic labrary (see dlopen()).
SPR_SRM_CID_GLOBVAR	Global variables. 'val1' is a pointer to ???
SPR_SRM_CID_VFS_OPEN	Handler to cope with a stream coder/protocol/header. 'val1' is a pointer to a SprStreamOpenCPHInfo strcuture.
SPR_SRM_CID_VFS_EXT	Information about file name extensions and their meaning. 'val1' is a pointer to a SprStreamOpenExtInfo strcuture.
SPR_SRM_CID_VFS_DEV	Device in the virtual file system. 'val1' is a pointer to ???
SPR_SRM_CID_VFS_MEM	File in meory in the virtual file system. 'val1' is a pointer to ???
SPR_SRM_CID_RESERVED	These low valued class-id are reserved, i.e. they cannot be released, destroyed, ...

enum SprExprScanCodes

Specify when an expression ends: scan until a valid seperator is found.

See Also: spr_expr_scan() for details

Enumerator
SPR_SCAN_BRC	stop at a bracket close (unless nested within brackets)
SPR_SCAN_NL	stop at a newline (unless nested within brackets), unless a line continuation is indicated (see SPR_SCAN_NLC_... below)
SPR_SCAN_SEMI	stop at a semicolumn ';' (unless nested within brackets)
SPR_SCAN_COMMA	stop at a comma ',' (unless nested within brackets)
SPR_SCAN_COL	stop at a column ':' (unless nested withing brackets)
SPR_SCAN_QMARK	stop at a questionmark '?' (unless nested withing brackets)
SPR_SCAN_OP	stop at a binary operator with a precedence lower or equal to what is specified with one of the SPR_SCAN_OP_... values
SPR_SCAN_SYNTAX	stop at a syntax error (note: the parsing uses a very weak syntax)
SPR_SCAN_OP_SPC	a whitespace character that looks like a seperator between values in a list (unless nested withing brackets)
SPR_SCAN_OP_ASSIGN	an assign operator '=' '+=' '*=' ... (unless nested withing brackets)
SPR_SCAN_OP_ORL	a logical or operator '\|\|' (unless nested withing brackets)
SPR_SCAN_OP_ANDL	a logical and operator '&&' (unless nested withing brackets)
SPR_SCAN_OP_ORB	a binary or operator '\|' '^' (unless nested withing brackets; no effect on '^' if SPR_SCAN_MOD_POW is set)
SPR_SCAN_OP_ANDB	a binary and operator '&' (unless nested withing brackets)
SPR_SCAN_OP_CMP	a comparison operator '==' '!=' '<=' '>=' '<' '>' '~' '~=' '!~' operator (unless nested withing brackets)
SPR_SCAN_OP_SHIFT	a shift operator '<<' '>>' (unless nested withing brackets)
SPR_SCAN_OP_ADD	a addition operator '+' '-' (unless nested withing brackets)
SPR_SCAN_OP_MUL	a multiplication operator '*' '/' '%' (unless nested withing brackets)
SPR_SCAN_OP_POW	a power operator '^' (unless nested withing brackets, and only if SPR_SCAN_MOD_POW is set as well)
SPR_SCAN_OP_MEMBER	a.b or a->b operator
SPR_SCAN_OP_MSK
SPR_SCAN_COMMENT_C	allow C-style comments, i.e. // ... newline and /\star ... \star/
SPR_SCAN_COMMENT_S	allow shell-style comments, i.e. # ... newline
SPR_SCAN_COMMENT_M	allow matlab-style comments, i.e. % ... newline
SPR_SCAN_MOD_NO_NL	a newline is equivalent to a string end
SPR_SCAN_MOD_SPC	a whitespace character can be a silent ',' when enumerating values (in a list)
SPR_SCAN_MOD_POW	a '^' acts as the power operator (Matlab convention) instead of logical xor (C-convention)
SPR_SCAN_MOD_CHR	a single quote character can be a unary post operator (instead of starting a C-style character or Matlab-style string)
SPR_SCAN_MOD_STRCAT	two succeeding strings are considered to be an automatic string concatenation
SPR_SCAN_NLC_DOTS	three dots '...' followed by a newline indicates a line continuation
SPR_SCAN_NLC_BSLASH	a backslash '\' followed by a newline indicates a line continuation

enum SprStreamFlags

Flags for opening a file.

Flags for internal use.

Enumerator
SPR_STREAM_CREATE	Create the file if it does not exist.
SPR_STREAM_TRUNC	When opening a file for writing, truncate the file to length 0.
SPR_STREAM_APPEND	Open the file and position the write pointer to the end of the file.
SPR_STREAM_READ	Open the file for reading (the default).
SPR_STREAM_WRITE	Open the file for writing.
SPR_STREAM_RW	Open the file for reading and writing. The stream will be put in WRITE mode initialy if the CREATE, TRUNC or APPEND flag is set as well, otherwise the initial mode for the stream will be the READ mode.
SPR_STREAM_LINEBUF	Buffer the IO read operations on a line by line base instead of the normal 4K blocks.
SPR_STREAM_UNBUF	Do minimal (i.e. almost no) buffering on the IO operations.
SPR_STREAM_SILENT	Do not report errors on this stream via the message system.
SPR_STREAM_SILENTEOF	Do not report EOF errors on this stream via the message system.
SPR_STREAM_NONBLOCK	Open the file in a non-blocking mode, i.e. reads will return the available amount of data only, writes may not write all requested data, so retries may be needed.
SPR_STREAM_KEEPKSET	Do not free the keyset given as argument to the spr_stream_open() routine when opening the stream fails.
SPR_STREAM_NOHDR	Open the file without writing/reading a header.
SPR_STREAM_SEEK	Make sure random seeks on the file are possible.
SPR_STREAM_REWIND	Make sure a rewind (full restart) on the file is possible.
SPR_STREAM_AUTOCLOSE	Automatically close the file when the program terminates.
SPR_STREAM_AUTORM	Automatically close and remove the file when the program terminates.
SPR_STREAM_ASCII	Force the stream in ASCII mode after opening it.

anonymous enum

Possible 'modes' as stream can be in. The 'mode' is used primarily by the SprDT read and write methods.

Enumerator
SPR_STREAM_MODE_BIN	Indicates that the data send to (or read from) the stream must be (or is) stored in binary format, no endian swapping.
SPR_STREAM_MODE_BINSWAP	Indicates that the data send to (or read from) the stream must be (or is) stored in binary format, with additional endian swapping.
SPR_STREAM_MODE_ASCII	Indicates that the data send to (or read from) the stream must be (or is) stored in ascii format.

Function Documentation

void spr_atomic_nop_MBwrite ( void )

Impose a write memory barrier. This means that to the outside world, it must appear as if all writes before the barrier have been finished before any of the writes after the barrier are executed.

void spr_atomic_nop_MBread ( void )

Impose a read memory barrier. This means that all reads (from the out-side world) before the barrier must have been finished before any of the reads after the barrier are executed.

void spr_atomic_nop_MBfull ( void )

Impose a full (read+write) memory barrier.

uint32_t spr_atomic_get32_MBacquire ( volatile uint32_t * ptr )

Read a 32bits value from memory and ensure that later memory reads from the outside world are started after this atomic read, i.e. do not read values older than what was read in the atomic operation.

Note: Other variants (different data sizes or memory barriers) may exist as well, but they are not exhaustively listed in this manual. See the general documentation for more info on how to access them.

uint32_t spr_atomic_twinget32_MBnone	(	uint32_t *	ptr,
		uint32_t *	val2
	)

Read two 32 bit values from memory in a single atomic operation (very usefull for cache tables).

uint64_t spr_atomic_twingetc48_18_MBnone	(	uint64_t *	ptr,
		uint64_t *	val2
	)

Read a pointer (48bits) and a transaction counter (18bits) from memory in a single (64bits) atomic operation. This is a poor-mans solution for 64bits machines that do not provide real twin-ops on 64bits quantities (and only use 48 of the 64 bits for pointers + assures that pointers are aligned to al least 32bits quantities). The chance of having an ABA-problems with a 64bits transaction counters is practically zero (it would take current computers 100+ years to warp-around the counter). 18bits counter are a lot less safe, so avoid this construct for essential code.

Note: All twin operations can have this variant.; The get and set operations can have an 18 and 48 variant as well.

void spr_atomic_set32_MBrelease	(	volatile uint32_t *	ptr,
		uint32_t	value
	)

Write value to the given memory location and ensure that all earlier memory writes become visible to the outside world before the atomic write.

Note: Other variants (different data sizes or memory barriers) may exist as well, but they are not exhaustively listed in this manual. See the general documentation for more info on how to access them.

void spr_atomic_twinset32_MBrelease	(	volatile uint32_t *	ptr,
		uint32_t	value1,
		uint32_t	value2
	)

Write (value1,value2) to the given memory location in a single atomic operation (very usefull for cache tables).

void spr_atomic_inc32_MBnone ( volatile uint32_t * ptr )

Increment the value on the given memory address by one.

Note: Other variants (different data sizes or memory barriers) may exist as well, but they are not exhaustively listed in this manual. See the general documentation for more info on how to access them.

uint32_t spr_atomic_dec32_MBnone ( volatile uint32_t * ptr )

Decrement the value on the given memory address by one and test for zero.

Returns: 0 or 1 if the value after decrementing is zero or non zero respectively.

Note: Other variants (different data sizes or memory barriers) may exist as well, but they are not exhaustively listed in this manual. See the general documentation for more info on how to access them.

uint32_t spr_atomic_add32_MBnone	(	volatile uint32_t *	ptr,
		uint32_t	value
	)

Add value to the value on a given memory address.

Returns: The old memory value.

Note: Other variants (different data sizes or memory barriers) may exist as well, but they are not exhaustively listed in this manual. See the general documentation for more info on how to access them.

uint32_t spr_atomic_or32_MBnone	(	volatile uint32_t *	ptr,
		uint32_t	value
	)

Or the value on a given memory address with value.

Returns: The old memory value.

Note: Other variants (different data sizes or memory barriers) may exist as well, but they are not exhaustively listed in this manual. See the general documentation for more info on how to access them.

uint32_t spr_atomic_and32_MBnone	(	volatile uint32_t *	ptr,
		uint32_t	value
	)

And the value on a given memory address with value.

Returns: The old memory value.

Note: Other variants (different data sizes or memory barriers) may exist as well, but they are not exhaustively listed in this manual. See the general documentation for more info on how to access them.

uint32_t spr_atomic_swap32_MBnone	(	volatile uint32_t *	ptr,
		uint32_t	value
	)

Store value on the given memory address ptr and return the old value stored at the memory location. In other words, swap or exchange values.

Note: Other variants (different data sizes or memory barriers) may exist as well, but they are not exhaustively listed in this manual. See the general documentation for more info on how to access them.

int spr_atomic_cas32_MBnone	(	volatile uint32_t *	ptr,
		uint32_t	tst_value,
		uint32_t	new_value
	)

Test if *ptr (still) equals tst_value, and if so, store new_value in ptr.

Returns: 1 if the update failed (memory value was not updated), 0 otherwise.

Note: Other variants (different data sizes or memory barriers) may exist as well, but they are not exhaustively listed in this manual. See the general documentation for more info on how to access them.

int spr_atomic_twincas32_MBnone	(	volatile uint32_t *	ptr,
		uint32_t	tst_value1,
		uint32_t	tst_value2,
		uint32_t	new_value1,
		uint32_t	new_value2
	)

Test if *ptr (still) equals {tst_value1,tst_value2} and if so, store {new_value1,new_value2} in *ptr.

Returns: 1 if the update failed (memory value was not updated), 0 otherwise.

Note: Other variants (different data sizes or memory barriers) may exist as well, but they are not exhaustively listed in this manual. See the general documentation for more info on how to access them.

int spr_atomic_bitset32_MBnone	(	volatile uint32_t *	ptr,
		int	bit_ndx
	)

Set a bit bit_ndx in bit array ptr to 1.

Returns: The old bit value.

Note: Other variants (different data sizes or memory barriers) may exist as well, but they are not exhaustively listed in this manual. See the general documentation for more info on how to access them.

int spr_atomic_bitclr32_MBnone	(	volatile uint32_t *	ptr,
		int	bit_ndx
	)

Set a bit bit_ndx in bit array ptr to 0.

Returns: The old bit value.

Note: Other variants (different data sizes or memory barriers) may exist as well, but they are not exhaustively listed in this manual. See the general documentation for more info on how to access them.

int spr_atomic_slot_acquire_nowait ( SprAtomicSlot * slot )

Try to get slot 0 (the main resource), and if that slot is not available, try to get any other free slot (an auxilary resource).

If a free slot is found, lock it (clear the appropriate bit in slot->msk) and return the slot number.

Returns: The slot number or (-1) if no free slots were found

Note: This function is defined as a macro. It may not exist if the platform does not support it.

int spr_atomic_slot_acquire_wait ( SprAtomicSlot * slot )

Try to get slot 0, and if that slot is not available, try to get any other free slot. If there are no free slots, then wait until a slot becomes free.

Returns: The slot number or (-1) when there seems to be a deadlock.

int spr_atomic_slot_acquire0_wait ( SprAtomicSlot * slot )

Try to get slot 0. If slot 0 is not available, then wait.

Returns: 0 on success and (-1) when there seems to be a deadlock.

int spr_atomic_slot_acquire_all ( SprAtomicSlot * slot )

Acquire all slots, i.e. make sure this thread is the only one using the system.

Returns: 0 on success and (-1) when there seems to be a deadlock.

double spr_strtod	(	const char *	str,
		const char *	str_end,
		char **	eptr
	)

Convert the initial portion of the string pointed to by str to a double value. The string str ends either in a '\0' or at the location pointed to by str_end (whichever condition occurs first). If eptr is not NULL, a pointer to the character after the last character used in the conversion is stored in the location referenced by eptr.

Returns: the converted value, if any and -1.0 otherwise. On error, *eptr will equal to str.

char* spr_dt_qstr_cvt_insitu ( char *restrict str )

Convert the quoted string str to an unquoted string (with all escape codes converted). The converted string is written over the quoted source string. The final '"' in the source string is replaced by a '\0' after which the conversion stops.

Returns: A pointer pointing right after the final '"' in the source string or NULL when the conversion failed (no closing '"' found).

Note: The first character in str is assumed to be '"' (but his is not checked)!

char* spr_dt_qstr_skip ( const char * str )

Go to the end of the quoted string str.

Returns: A pointer pointing right after the final '"' in the source string or NULL when the conversion failed (no closing '"' found).

Note: The first character in str is assumed to be '"' (but his is not checked)!

int spr_dt_alaw2short ( int aval )

Returns: 16 bits PCM value corresponding to the a-law value aval.

Note: SPRAAK uses the full 16 bits PCM range instead of just 13 bits, i.e. we multiply the normal a-law->PCM values with 8.

int spr_dt_short2alaw ( int sval )

Returns: The a-law value corresponding to the 16 bits PCM value sval.

Note: SPRAAK uses the full 16 bits PCM range instead of just 13 bits, i.e. we multiply the normal a-law->PCM values with 8.

int spr_dt_ulaw2short ( int uval )

Returns: 16 bits PCM value corresponding to the u-law value uval.

Note: SPRAAK uses the full 16 bits PCM range instead of just 14 bits, i.e. we multiply the normal u-law->PCM values with 4.

int spr_dt_short2ulaw ( int sval )

Returns: The u-law value corresponding to the 16 bits PCM value sval.

Note: SPRAAK uses the full 16 bits PCM range instead of just 14 bits, i.e. we multiply the normal u-law->PCM values with 4.

int32_t spr_atoi32	(	const char *	str,
		int *	err
	)

Convert str to a signed 32 bits interger.

Returns: 0 on success, -1 on error and a positve value on a partial successful conversion (the returned value is the number of successfully converted characters).

Note: err may equal NULL.; the function does not issue a warning if things go wrong!

uint32_t spr_atou32	(	const char *	str,
		int *	err
	)

Convert str to an unsigned 32 bits interger.

Returns: 0 on success, -1 on error and a positve value on a partial successful conversion (the returned value is the number of successfully converted characters).

Note: err may equal NULL.; the function does not issue a warning if things go wrong!

int64_t spr_atoi64	(	const char *	str,
		int *	err
	)

Convert str to a signed 64 bits interger.

Returns: 0 on success, -1 on error and a positve value on a partial successful conversion (the returned value is the number of successfully converted characters).

Note: err may equal NULL.; the function does not issue a warning if things go wrong!

uint64_t spr_atou64	(	const char *	str,
		int *	err
	)

Convert str to an unsigned 64 bits interger.

Returns: 0 on success, -1 on error and a positve value on a partial successful conversion (the returned value is the number of successfully converted characters).

Note: err may equal NULL.; the function does not issue a warning if things go wrong!

float spr_atof32	(	const char *	str,
		int *	err
	)

Convert str to a 32 bits floating point value.

Returns: 0 on success, -1 on error and a positve value on a partial successful conversion (the returned value is the number of successfully converted characters).

Note: err may equal NULL.; the function does not issue a warning if things go wrong!

double spr_atof64	(	const char *	str,
		int *	err
	)

Convert str to a 64 bits floating point value.

Returns: 0 on success, -1 on error and a positve value on a partial successful conversion (the returned value is the number of successfully converted characters).

Note: err may equal NULL.; the function does not issue a warning if things go wrong!

ssize_t spr_dt_print_vec	(	SprStream *	fd,
		const SprDT *	dt,
		const void *	vec,
		int	vlen,
		const char *	info
	)

Print a vector vec of vlen data elements of type dt to the stream fd. Each printed element is preceeded by a single space and the last elements is followed by new-line character. If the string info is not NULL, that string will be printed before the vector is.

Returns: The total number of bytes written or (-1) on error.

Parameters

fd	Destination stream.
dt	Type of the data elements.
vec	Data vector
vlen	Vector length.
info	Extra string.

int spr_dt_str2vec	(	const char *	str,
		const SprDT *	dt,
		void *restrict	vec,
		int	N
	)

Convert the ASCII string str to an array vec containing values of the type dt. Values are assumed to be seperated be spaces. Only the first N values are stored in vec. The remainder of the string is still processed (must contain valid values) and the remaining values are counted.

Returns: the number of values found or (-1) on error.

int spr_dt_str2vec_dyn	(	const char *	str,
		const SprDT *	dt,
		void **	dst
	)

Convert the ASCII string str to an array *dst containing values of the type dt. Values are assumed to be seperated be spaces.

Returns: the number of values found or (-1) on error.

SprDynStr spr_dt_vec2str	(	SprDynStr	dst,
		const SprDT *	dt,
		const void *	vec,
		int	N
	)

Convert the array vec containing N values of the type dt to a dynamic string. Each value is seperated by a space. If not NULL, the dynamic string dst is used to write the result to.

Returns: the resulting dynamic string or NULL on error.

void* spr_free	(	void *	ptr,
		const SprMsgId *	routine,
		const char *	item
	)

Free the memory space pointed to by ptr, which must have been returned by a previous call to spr_malloc() or spr_realloc(). If ptr is NULL, no operation is performed.

Note: Trying to free items allocated by other means (e.g. the C-functions malloc() or realloc(), or the SPRAAK functions for dynamic strings or blocks of identical elements) or trying to free the same item twice will result in undefined behaviour. Use the appropriate free function for each allocated item!; Once the item has been freed, the memory should not be used anymore. Therefore, a good practice is to set the variable that pointed to that memory area to NULL. To facilitate this, the spr_free() function returns NULL:
ptr = spr_free(ptr,routine,"ptr");

Returns: NULL.

Parameters

ptr	Item to free.
routine	Identify the calling routine.
item	Name of the item.

void* spr_malloc	(	size_t	size,
		const SprMsgId *	routine,
		const char *	item
	)

Allocate size bytes and return the pointer to the newly allocated memory. The content of memory area is random (the bytes have not been zeroed).

Note: Allocating 0 bytes is allowed and behaves as if a non zero amount of bytes was requested i.e. on success a unique non NULL pointer is returned for each allocation. The usable data space is however 0 bytes long (as requested). Such elements also need to be deallocated.; For good practice, the pointer should be casted to the proper type before assigning it. This enforces type checking.

Returns: A pointer to the allocated memory area, which is suitably aligned for any kind of variable, or NULL if the request failed.

Parameters

size	Requested memory size (in butes).
routine	Identify the calling routine.
item	Name of the item.

void* spr_realloc	(	void *	ptr,
		size_t	size,
		const SprMsgId *	routine,
		const char *	item
	)

Changes the size of the memory block pointed to by ptr to be size bytes long. The contents will be unchanged up till the minimum of the old and new sizes; extra allocated memory is uninitialized. The returned pointer may differ from the original pointer ptr, i.e. the memory area may have been moved to acquire the necessary space. In that case, the original memory area is automatically freed. If ptr is NULL, the call is equivalent to spr_malloc(size,...). If size is equal to zero, the call is equivalent to (spr_free(ptr),spr_malloc(0,routine,size)). Unless ptr is NULL, it must have been returned by an earlier call to spr_malloc() or spr_realloc().

Returns: A pointer to the resized and possibly moved memory area or NULL if the request failed. In the later case, the original memory area is left untouched (i.e. the original memory area is still there and must still be freed if no longer needed).

Parameters

ptr	Item to reallocate.
size	Requested memory size (in butes).
routine	Identify the calling routine.
item	Name of the item.

unsigned int spr_dynmem_check	(	SprMsgId *	routine,
		const char *	id
	)

Check if the heap is corrupted. This routine is not mult-threading safe.

it should only be called from the main thread after all helper threads have stopped or are idling.

Returns: The number of errors detected (should be 0).

Parameters

routine	Identify the calling routine.
id	Identify the call.

char* spr_strdup	(	const char *	src,
		const SprMsgId *	routine,
		const char *	item
	)

Returns: A pointer to a newly allocated string which is a duplicate of the string src. If the allocation fails, a NULL is returned.

Note: Memory for the new string is obtained with spr_malloc(), and must be freed with spr_free().

Parameters

src	Source string.
routine	Identify the calling routine.
item	Name of the new string.

char* spr_strndup	(	const char *	src,
		size_t	size,
		const SprMsgId *	routine,
		const char *	item
	)

Returns: A pointer to a newly allocated string which is a duplicate of the first size characters in string src followed by a terminating '\0'. If the allocation fails, a NULL is returned.

Note: Memory for the new string is obtained with spr_malloc(), and must be freed with spr_free().

Parameters

src	Source string.
size	Size of the string.
routine	Identify the calling routine.
item	Name of the new string.

char* spr_strcpy	(	char **restrict	dst,
		const char *restrict	src
	)

Make a copy of src to a (re)allocated chunk of memory in *dst.

Returns: A pointer to a new string which is a duplicate of the string src. If the (re)allocation fails, a NULL is returned and the old string in *dst is freed.

Note: Memory for the new string is obtained with spr_malloc(), and must be freed with spr_free().

Parameters

dst	Destination string.
src	Source string.

char* spr_strcat	(	char *restrict	str1,
		const char *restrict	str2,
		int *restrict	str1_len,
		int	str2_len,
		int *restrict	alen
	)

Append str2 to the dynamically allocated string str1.

Parameters

str1	Source string.
str2	String to append.
str1_len	Length of str1. If not NULL, *str1_len is used to specify the length of str1 on entry and to return the total length of the newly formed (concattenated) string. A value of (-1) on input is equivalent to the value strlen(str1).
str2_len	Length of str2. Contains the length of str2. A value of (-1) is equivalent to the value strlen(str1).
alen	Allocated length of str1. If not NULL. *alen must contain the allocated length of str1 on entry (or an under estimate) and will contain the new allocated length (or the old value if no reallocation was needed) of the newly formed (concattenated) string when returning.

Returns: A pointer to a possibly reallocated str1 appended by str2 or NULL on failure.

Note: str1 may be NULL, allowing for simple 'collect all items' constructs.; On failure, str1 will be freeed.

char* spr_dynstr2alloc ( SprDynStr str )

Change the dynamic string str into a plain allocate string.

Returns: The plain allocated string.

Note: str may not be NULL!

SprDynStr spr_dynstr_free	(	SprDynStr	str,
		const SprMsgId *	routine,
		const char *	item
	)

Free the dynamic string str, which must have been returned by a previous call to str_dynstr_alloc() or equiavlent. If str is NULL, no operation is performed. For more details see spr_free().

Parameters

str	String to free.
routine	Identify the calling routine.
item	Name of the item.

SprDynStr spr_dynstr_alloc	(	size_t	size,
		const SprMsgId *	routine,
		const char *	item
	)

Allocate a dynamic string capable of holding size bytes (this includes the terminating '\0'). For more details see spr_malloc().

Parameters

size	Requested size (in butes).
routine	Identify the calling routine.
item	Name of the item.

SprDynStr spr_dynstr_realloc	(	SprDynStr	str,
		size_t	size,
		const SprMsgId *	routine,
		const char *	item
	)

Resize the string str to fit the given length size (don't forget to count the trailing '\0'). If you are not interested in saving space but just want to make sure the dynamic string is large enough, use spr_dynstr_enlarge() instead. If the string is truncated, a terminating '\0' will be placed at the end.

Returns: The resize dynamic string on success and NULL on failure.

Note: On failure, the old string is freed, this in contrast to spr_realloc() which preserves the old data.

Parameters

str	String to reallocate.
size	Requested size (in butes).
routine	Identify the calling routine.
item	Name of the item.

SprDynStr spr_dynstr_enlarge	(	SprDynStr	str,
		size_t	size,
		const SprMsgId *	routine,
		const char *	item
	)

Resize the string str to fit at least the given length size (don't forget to count the trailing '\0').

Returns: The enlarged dynamic string on success and NULL on failure.

Note: On failure, the old string is freed, this in contrast to spr_realloc() which preserves the old data.

Parameters

str	String to reallocate.
size	Requested size.
routine	Identify the calling routine.
item	Name of the item.

size_t spr_dynstr_maxlen ( SprDynStr str )

Determine the maximum size (including the final '\0') the string str may become before it must be reallocated (or enlarged).

Parameters

str	The string.

SprDynStr spr_dynstr_cpy	(	SprDynStr	dst,
		const char *	src
	)

Copy the string src to the dynamic string dst. If necessary, dst is enlarged.
For more details, see strcpy().

Returns: The copied dynamic string on success and NULL on failure.

Note: On failure, the old string is freed!

Parameters

dst	Destination string.
src	Source string.

SprDynStr spr_dynstr_ncpy	(	SprDynStr	dst,
		const char *	src,
		size_t	src_len
	)

Copy the string src of length src_len (not including the final '\0') to the dynamic string dst. If src is longer than src_len, dst will be truncated to src_len and a final '\0' will be added. If src_len equals (-1), the length is calculated using strlen(). If necessary, dst is enlarged.
For more details, see strncpy().

Returns: The copied dynamic string on success and NULL on failure.

Note: On failure, the old string is freed!

Parameters

dst	Destination string.
src	Source string.
src_len	Length of the source string.

SprDynStr spr_dynstr_dup	(	const char *	src,
		const SprMsgId *	routine,
		const char *	item
	)

Make a new dynamic string containing a copy of src. For more details, see strdup().

Returns: The copied dynamic string on success and NULL on failure.

Parameters

src	Source string.
routine	Identify the calling routine.
item	Name of the new string.

SprDynStr spr_dynstr_ndup	(	const char *	src,
		size_t	src_len
	)

Make a new dynamic string containing a copy of the string src of length src_len (length not including the final '\0'). If src is longer than src_len, the copy will be truncated to src_len and a final '\0' will be added. If src_len equals (-1), the length is calculated using strlen().
For more details, see strdup().

Returns: The copied dynamic string on success and NULL on failure.

Parameters

src	Source string.
src_len	Length of the source string.

SprDynStr spr_dynstr_cat	(	SprDynStr restrict	str1,
		const char *restrict	str2,
		int *restrict	str1_len,
		int	str2_len
	)

Append str2 to the dynamic string str1.

Parameters

str1	Source string.
str2	String to append.
str1_len	Length of str1. If not NULL, *str1_len is used a length of str1 on entry and will contain the total length of the newly formed (concattenated) string when returning. If value of (-1) on input is equivalent to strlen(str1).
str2_len	Length of str2. Contains the length of str2. A value of (-1) is equivalent to strlen(str1).

Returns: A pointer to a possibly reallocated dynamic string str1 appended by str2 or NULL on failure.

Note: str1 may be NULL, hence allowing for simple 'collect all items' constructs.

const char* spr_str_nonull_ ( const char * str )

Returns: The given string str or "(NULL)" if str is NULL.

Parameters

str	String to check.

const char* spr_str_nonull	(	const char *	str,
		const char *	str_null
	)

Returns: The given string str or str_null if str is NULL.

Parameters

str	String to check.
str_null	Alternative.

size_t spr_dynmem_pool_count_alloc ( const SprMPool * mpool )

Returns: The total number of elements allocated.

Note: To know the number of elements in use, you still have to substract the number of elements in the free list.

Parameters

mpool The pool of identical sized objects.

size_t spr_dynmem_pool_count_free ( const SprMPool * mpool )

Returns: The total number of elements in the free list.

Note: To know the number of elements in use, you have to substract the number of elements allocated by the number of elements in the free list.

Parameters

mpool The pool of identical sized objects.

size_t spr_dynmem_pool_free	(	SprMPool *	mpool,
		SprMsgId *	routine
	)

Free all allocated data in the memory pool mpool by freeing all allocated chunks of memory.

Note: The caller must guarantee that non of the elements allocated via this pool is still in use.

Returns: The number of elements that were allocated.

Parameters

mpool	The pool of identical sized objects.
routine	Identify the calling routine.

void* spr_dynmem_pool_enlarge ( SprMPool * mpool )

Allocate a set of objects of size mpool->el_size. The elements are linked together with a pointer at offset mpool->link_ptr_offs in each element, thus making a list of new/free elements. The element size and how they are linked together should be set once when initializing mpool, e.g. by using the SPR_MPOOL_INIT() or SPR_MPOOL_INITIALIZER() macros, and must not be changed there after or unexpected bahaviour is to be expected.

Returns: The first element of the newly allocated list/array.

Note: Code using this routine typically looks like:
if(spr_expect((el=mpool->free_list)==NULL,0) && spr_expect((el=spr_dynmem_pool_enlarge(mpool))==NULL,0))

goto LBL_DONE;

mpool->free_list = el->next; // remove element from the free list

Parameters

mpool The pool of identical sized objects.

int spr_fmsnzb32 ( uint32_t val )

Return the index (31...0) of the most significant non zero bit of val. If val is zero, a (-1) is returned.

int spr_fmsnzb32x0 ( uint32_t val )

Return the index (31...0) of the most significant non zero bit of val. If val is zero, the return value is undefined.

int spr_fmsnzb64 ( uint64_t val )

Return the index (63...0) of the most significant non zero bit of val. If val is zero, a (-1) is returned.

int spr_fmsnzb64x0 ( uint64_t val )

Return the index (63...0) of the most significant non zero bit of val. If val is zero, a the return value is undefined.

int spr_flsnzb32 ( uint32_t val )

Return the index (31...0) of the least significant non zero bit of val. If val is zero, a (-1) is returned.

int spr_flsnzb32x0 ( uint32_t val )

Return the index (31...0) of the least significant non zero bit of val. If val is zero, the return value is undefined.

int spr_flsnzb64 ( uint64_t val )

Return the index (63...0) of the least significant non zero bit of val. If val is zero, a (-1) is returned.

int spr_flsnzb64x0 ( uint64_t val )

Return the index (63...0) of the least significant non zero bit of val. If val is zero, a the return value is undefined.

int spr_popcount16 ( uint16_t val )

Return the number of 1 bits in val.

int spr_popcount32 ( uint32_t val )

Return the number of 1 bits in val.

int spr_popcount64 ( uint64_t val )

Return the number of 1 bits in val.

uint32_t spr_rotl32	(	uint32_t	val,
		unsigned int	ndx
	)

Rotate the value val ndx bits to the left.

uint32_t spr_rotr32	(	uint32_t	val,
		unsigned int	ndx
	)

Rotate the value val ndx bits to the right.

uint64_t spr_rotl64	(	uint64_t	val,
		unsigned int	ndx
	)

Rotate the value val ndx bits to the left.

uint64_t spr_rotr64	(	uint64_t	val,
		unsigned int	ndx
	)

Rotate the value val ndx bits to the right.

uint64_t spr_wide_umul32	(	uint32_t	val1,
		uint32_t	val2
	)

Double wide unsigned multiplication.

Returns: val1*val2

uint32_t spr_wide_umul32hi	(	uint32_t	val1,
		uint32_t	val2
	)

Double wide unsigned multiplication and shift. Typically used for fixed point multiplications.

Returns: (val1*val2)>>32

int64_t spr_wide_smul32	(	int32_t	val1,
		int32_t	val2
	)

Double wide signed multiplication.

Returns: val1*val2

int32_t spr_wide_smul32hi	(	int32_t	val1,
		int32_t	val2
	)

Double wide signed multiplication and shift. Typically used for fixed point multiplications.

Returns: (val1*val2)>>32

int spr_bittest	(	const unsigned int *	bitarray,
		int	ndx
	)

Returns: The value of bit ndx in bit array bitarray.

void spr_bitset	(	unsigned int *	bitarray,
		int	ndx
	)

Set the value of bit ndx in bit array bitarray to 1.

void spr_bitclr	(	unsigned int *	bitarray,
		int	ndx
	)

Set the value of bit ndx in bit array bitarray to 0.

uint16_t spr_bswap16 ( uint16_t val )

Returns: val with the 2 individual bytes swapped (endian conversion).

uint32_t spr_bswap32 ( uint32_t val )

Returns: val with the 4 individual bytes swapped (endian conversion).

uint64_t spr_bswap64 ( uint64_t val )

Returns: val with the 8 individual bytes swapped (endian conversion).

unsigned int spr_sqrt_u32 ( unsigned int nr )

Calculate the square root of an unsigned integer (without using the FPU). The result is rounded towards zero.

Returns: the square root of nr, rounded towards zero.

int spr_prime_check ( unsigned int nr )

Check if the given number nr is a prime number.

Returns: 1 if the number is prime, 0 otherwise.

Note: 2 is flagged as not being a prime!

unsigned int spr_prime_find ( unsigned int nr )

Find the first prime number that is larger or equal to the given argument nr.

Returns: The first prime number greater or equal to nr.

Note: spr_prime_find(2) returns 3!

unsigned int spr_hash_str ( const char * str )

Calculate a hash value for the string str.

Returns: The hash value.

Note: The string str may be empty but may not equal NULL.

unsigned int spr_hash_str2	(	const char *	str,
		size_t	str_len
	)

Calculate the hash value for the string str of length str_len.

Returns: The hash value.

unsigned int spr_hash_str_len	(	const char *	str,
		size_t *	len
	)

Calculate both the length and the hash value for the string str.

Returns: The hash value. The length is returned in *len.

Note: The string str may be empty but may not equal NULL.

void spr_htbl_str_init	(	SprHtblStr *restrict	htbl,
		unsigned int	flags,
		int	keystr_offs
	)

Initialize the static allocated or embedded string hash table htbl. The flags argument can be a combination of the following:

SPR_HTBL_STR_DUP_STR: Make a private copy of the strings (and extra data) when adding them to the hash table. If this flag is not set, then the caller must guarantee that all strings added to the hash table will exist as long as the hash table exists (or the strings are removed).
SPR_HTBL_STR_CP_STR_ONLY: Do not copy the extra data when making a private copy of the item (string+data) to add to the hash table.
SPR_HTBL_STR_FREE_STR: Free the strings present in the hash table when freeing the hash table or when removing an element.
SPR_HTBL_STR_NO_FREE_STR_RM: Do not free the strings when removing elements from the hash table (spr_htbl_qstr2ndx_rm_str() or spr_htbl_qstr2ndx_rm_ndx()). Only relevant when the SPR_HTBL_STR_FREE_STR flag is set.

The keystr_offs allows one to preceed each string added to the hash table by some element specific structure (e.g. a pointer). For more details, see the documentation on the SprHtblStr structure.

Note: When SPR_HTBL_STR_DUP_STR is set and SPR_HTBL_STR_FREE_STR is not set, the caller must ensure that the strings are freed afterwards or memory leakage will occur.; When SPR_HTBL_STR_FREE_STR is set and SPR_HTBL_STR_DUP_STR is not set, the caller must ensure that all strings added to the hash table are properly allocated.

SprHtblStr* spr_htbl_str_new	(	unsigned int	flags,
		int	keystr_offs
	)

Allocate and initialize a new string hash table. For the meaning of the flags and keystr_offs, see spr_htbl_str_init().

Returns: The newly created and initialized hash table or (NULL) on failure.

SprHtblStr* spr_htbl_str_free ( SprHtblStr *restrict htbl )

Free the string hash table htbl. Whether the strings in the hash table are freed or not depends on the flags given when creating the hash table.

See Also: spr_htbl_str_init() and spr_htbl_str_new().

Returns: The NULL pointer.

Note: This routine can also be used as a reset if the hash table was embedded, i.e. initialized with spr_htbl_str_init() routine.

unsigned int spr_htbl_str_Nel ( const SprHtblStr *restrict htbl )

Returns: The number of elements in the hash table htbl.

const char* spr_htbl_str_iter	(	const SprHtblStr *restrict	htbl,
		int *restrict	ndx
	)

Iterator over all strings stored in the hash table:

int ndx = 0;
char *str;
while((str=spr_htbl_str_iter(htbl,&ndx)) != NULL)
 {// do something
  ...
 }

Returns: The string with index *ndx or a higher index if there is a gap created by removing elements from the hash table. If there is no string with an index *ndx or higher, a NULL is returned (end of the iteration).

const char* spr_htbl_str_ndx2str	(	const SprHtblStr *restrict	htbl,
		int	ndx
	)

Returns: The string for index ndx.

Note: Make sure ndx is a valid index. There are no safety checks!

int spr_htbl_str_find_ndx	(	const SprHtblStr *restrict	htbl,
		const char *restrict	str
	)

Search string str in the hash table htbl and return the index.

Returns: The index of the string str or (-1) when the strings was not found in the hash table.

int spr_htbl_str_find_ndx2	(	const SprHtblStr *restrict	htbl,
		const char *restrict	str,
		size_t	str_len
	)

Search string str of length str_len in the hash table htbl and return the index. If str_len equals (-1) the full length of str is used.

Returns: The index of the string str or (-1) when the strings was not found in the hash table.

const char* spr_htbl_str_find_key	(	const SprHtblStr *restrict	htbl,
		const char *restrict	str
	)

Search string str in the hash table htbl and return the pointer to the key-string from the hash table.

Returns: The string as stored in the hash table or NULL when the strings was not found.

Note: This routine only makes sense if the original string somehow contains additional information (e.g. a second string after the termination '\0', or a structure right before the string pointer, see the documentation on the SprHtblStr structure for more details).

int spr_htbl_str_add	(	SprHtblStr *restrict	htbl,
		const char *restrict	str
	)

Add string str to the hash table htbl and return the index.

Returns: The index of the string str or (-1) when the strings could not be added.

Note: If the same string is added twice, only one instance can be found; see spr_htbl_str_cadd() and spr_htbl_str_add_replace() for solutions.

int spr_htbl_str_cadd	(	SprHtblStr *restrict	htbl,
		const char *restrict	str,
		int *restrict	duplicate
	)

Search string str in the hash table htbl and add the string if not found. The flag *duplicate, if not NULL, will be set to 1 or 0 if the string is found or added respectively. See spr_htbl_str_add() about which string gets which index.

Returns: The index of the string str or (-1) when the string could not be added.

int spr_htbl_str_add_replace	(	SprHtblStr *restrict	htbl,
		const char *restrict	str
	)

Search string str in the hash table htbl, replace the hash table entry when found or add the string if not found. See spr_htbl_str_add() about which string gets which index.

Returns: The index of the string str or (-1) when the strings could not be added.

Note: This routine may only be called when the SPR_HTBL_STR_FREE_STR flag is set and the SPR_HTBL_STR_NO_FREE_STR_RM flag is not set (any other combination would lead to memory leaks anyhow)!

int spr_htbl_str_rm_key	(	SprHtblStr *restrict	htbl,
		const char *restrict	str
	)

Find string str in the hash table htbl and remove it.

Returns: The index of the removed string str or (-1) if the string was not found.

int spr_htbl_str_rm_ndx	(	SprHtblStr *restrict	htbl,
		int	ndx
	)

Remove the string at index ndx from the hash table htbl.

Returns: The index of the removed string or (-1) if the string was not in the hash table.

int spr_hash_strlin_search	(	const char *restrict const	hlst[],
		int	Nel,
		const char *restrict	str
	)

Lookup string str in the lookup table (a list of strings) hlst. Nel is the number of elements in the array hlst. If Nel equals -1, the lookup table is assumed to be NULL terminated.

Returns: The index at which str was found in the lookup table hlst, or -1 if the string could not be located.

Note: No warning is given when the string is not found.; str may equal NULL; this results in a (-1) return value.

int spr_hash_strlin_search_err	(	const char *restrict const	hlst[],
		int	Nel,
		const char *restrict	str
	)

Lookup string str in the lookup table (a list of strings) hlst. Nel is the number of elements in the array hlst. If Nel equals -1, the lookup table is assumed to be NULL terminated.

Returns: The index at which str was found in the lookup table hlst, or -1 if the string could not be located.

Note: An error message is given when the string is not found.; str may equal NULL; this results in a (-1) return value and error message.

int spr_hash_strnlin_search	(	const char *restrict const	hlst[],
		const char *restrict	str,
		size_t	str_len
	)

Lookup string str[0:str_len-1] in the lookup table (a NULL terminated list of strings) hlst.

Returns: The index at which str was found in the lookup table hlst, or -1 if the string could not be located.

Note: No warning is given when the string is not found.; str may equal NULL; this results in a (-1) return value.

int spr_hash_strnlin_search_err	(	const char *restrict const	hlst[],
		const char *restrict	str,
		size_t	str_len
	)

Lookup string str[0:str_len-1] in the lookup table (a NULL terminated list of strings) hlst.

Returns: The index at which str was found in the lookup table hlst, or -1 if the string could not be located.

Note: An error message is given when the string is not found.; str may equal NULL; this results in a (-1) return value and error message.

SprKeySet* spr_kset_alloc ( void )

Allocate a new keyset.

Returns: The newly allocated (and thus empty) keyset.

SprKeySet* spr_kset_reset ( SprKeySet * keys )

Clear the content of a previously allocated keyset.

Returns: The input keyset keys.

SprKeySet* spr_kset_free ( SprKeySet * keys )

Free a previously allocated keyset.

Returns: NULL.

int spr_kset_set	(	SprKeySet *	keys,
		const char *	key,
		const char *	value
	)

Adds the key-value pair (key,value) to the key-set keys. Both key and value must be valid strings (non NULL, '\0' terminated). The strings are copied, so key nor value have to be preserved after this call.

Returns: 0 on success, (-1) on failure and (1) if the value was problematic (not befitting the key).

int spr_kset_cset	(	SprKeySet *	keys,
		const char *	key,
		const char *	value
	)

Adds the key-value pair (key,value) to the key-set keys if the key is not yet present in the keyset.

Returns: 0 if the key was added, 1 if the key was added but the value proved to be problematic (not befitting the key), 2 if the key was already present with an equal value, 4 if the key was already present with a different value, and -1 on failure.

int spr_kset_set_value	(	SprKeySet *	keys,
		const char *	key,
		const SprDT *	dt,
		const void *	value
	)

Adds the key-value pair (key,str(value)) to the key-set keys. The key key must be valid strings (non NULL, '\0' terminated). The value must be of the data type dt. Both the key and the value are copied, so key nor value have to be preserved after this call.

Returns: 0 on success and (-1) on failure.

int spr_kset_set_value_size	(	SprKeySet *	keys,
		const char *	key,
		ssize_t	value
	)

Adds the key-value pair (key,str(value)) to the key-set keys. Behaves identical to spr_kset_set_value(keys,key,spr_dt_ssize,&value) (assuming one can take the addres of value).

Returns: 0 on success and (-1) on failure.

int spr_kset_set_value_double	(	SprKeySet *	keys,
		const char *	key,
		double	value
	)

Adds the key-value pair (key,str(value)) to the key-set keys. Behaves identical to spr_kset_set_value(keys,key,spr_dt_f64,&value) (assuming one can take the addres of value).

Returns: 0 on success and (-1) on failure.

int spr_kset_set_value_float	(	SprKeySet *	keys,
		const char *	key,
		float	value
	)

Adds the key-value pair (key,str(value)) to the key-set keys. Behaves identical to spr_kset_set_value(keys,key,spr_dt_f32,&value) (assuming one can take the addres of value).

Returns: 0 on success and (-1) on failure.

const char* spr_kset_get	(	const SprKeySet *	keys,
		const char *	key
	)

Search the key key in the key-set keys and returns the corresponding value if found.

Returns: The value correspoding to key or NULL when the key was not present.

Note: No error message is given if the key was not present.

const char* spr_kset_get_err	(	const SprKeySet *	keys,
		const char *	key
	)

Search the key key in the key-set keys and returns the corresponding value if found.

Returns: The value correspoding to key or NULL when the key was not present.

Note: If the key was not present, an error message is given.

int spr_kset_get_value	(	const SprKeySet *	keys,
		const char *	key,
		const SprDT *	dt,
		void *	dst,
		const void *	def_val
	)

Search the key key in the key-set keys. If the key was found, the corresponding value (a string) is converted to something of the type dt and store in *dst. If not found (or if the conversion fails), *def_val (if not NULL) is copied to *dst.

Returns

(0): if the key was found and could be successfully converted;
(1): if the key was not found and def_val was used instead;
(-2): if there was a serious problem (key was found but could not be converted or could only be partially converted) but *dst contains a legal value (either the partially converted value or def_val);
(-1): if *dst does not contain a legal value (key was found and def_val was NULL, or copying def_val failed).

Note: Problems (except for not finding the key and falling back to the given default) are reported via the message system.; It is allowed to have identical values for dst and def_val.

ssize_t spr_kset_get_value_size	(	const SprKeySet *	keys,
		const char *	key,
		ssize_t	nf_val
	)

Search the key key in the key-set keys. If the key was found, and the corresponding value (a string) could be converted successfuly to a ssize_t value, this value will be returned. Otherwise (key not found or unable to convert to ssize_t), the value nf_val will be returned.

Returns: The value of the key key converted to ssize_t or nf_val if the key was not found or could not be converted to a ssize_t.

double spr_kset_get_value_double	(	const SprKeySet *	keys,
		const char *	key,
		double	nf_val
	)

Search the key key in the key-set keys. If the key was found, and the corresponding value (a string) could be converted successfuly to a double, this value will be returned. Otherwise (key not found or unable to convert to a double), the value nf_val will be returned.

Returns: The value of the key key converted to a double or nf_val if the key was not found or could not be converted to a double.

float spr_kset_get_value_float	(	const SprKeySet *	keys,
		const char *	key,
		float	nf_val
	)

Search the key key in the key-set keys. If the key was found, and the corresponding value (a string) could be converted successfuly to a float, this value will be returned. Otherwise (key not found or unable to convert to a float), the value nf_val will be returned.

Returns: The value of the key key converted to a float or nf_val if the key was not found or could not be converted to a float.

int spr_kset_rm	(	SprKeySet *	keys,
		const char *	key
	)

Remove the key key from the key-set keys.

Returns: 0 if the key could be removed and -1 if the key was not found.

int spr_kset_get_value_format ( const SprKeySet * keys )

Get the 'FORMAT' key from the keyset keys.

Returns

The 'format' of the data, which can have the following values:

SPR_KEY_FORMAT_ASCII: the data in the corresponding stream is written in ascii format
SPR_KEY_FORMAT_BIN01: the data in the corresponding stream is written in binary format, little endian convention
SPR_KEY_FORMAT_BIN10: the data in the corresponding stream is written in binary format, big endian convention
(-1): the format is unspecified (this keyset does not correspond to a file)

Note: The format of a stream is also known by the stream handler (pointer to SprStream) and all read routines (see dataformat.c) will adpat automatically, so in practice one should almost never need to query this information.

int spr_kset_get_value_format_alt	(	const SprKeySet *	keys,
		int	alt_val
	)

Returns: The 'format' of the data or alt_val if FORMAT was not present in the keyset. See spr_kset_get_value_format() for more details.

int spr_kset_get_value_layout ( const SprKeySet * keys )

Get the 'LAYOUT' key from the keyset keys.

Returns

The 'layout' of the data, which can have the following values:

SPR_KEY_LAYOUT_LIST: a list (corpus, lexicon, ...)
SPR_KEY_LAYOUT_MATRIX: a matrix or vector
SPR_KEY_LAYOUT_CUSTOM: some custom (usualy complex) layout
(-1): the layout is unspecified (this keyset does not correspond to a file)

const SprDT* spr_kset_get_value_type ( const SprKeySet * keys )

Get the 'TYPE' key from the keyset keys.

Returns: The 'type' of the data elements or NULL when the type is unknown or could not be decoded.

const SprDT* spr_kset_get_value_type_alt	(	const SprKeySet *	keys,
		const SprDT *	alt_val
	)

Returns: The type of the data elements in the stream of data or alt_val if TYPE was not present in the keyset. See spr_kset_get_value_type() for more details.

ssize_t spr_kset_get_value_dim1 ( const SprKeySet * keys )

Get the 'DIM1' key from the keyset keys. DIM1 corresponds to:

the number of entries in a lexicon or corpus file
the number of segments in a segmentation file
the number of frames in a track or sample file

Returns: The primary dimension of the stream of data or the default value (-1) if DIM1 was not present in the keyset.

ssize_t spr_kset_get_value_dim1_alt	(	const SprKeySet *	keys,
		ssize_t	alt_val
	)

Returns: The primary dimension of the stream of data or alt_val if DIM1 was not present in the keyset. See spr_kset_get_value_dim1() for more details.

ssize_t spr_kset_get_value_dim2 ( const SprKeySet * keys )

Get the 'DIM2' key from the keyset keys. DIM2 corresponds to

the number of entries in a segmentation file
the number of parameters per frame in a track or sample file

Returns: The secondary dimension of the stream of data or the default value (-1) if DIM2 was not present in the keyset.

ssize_t spr_kset_get_value_dim2_alt	(	const SprKeySet *	keys,
		ssize_t	alt_val
	)

Returns: The secondary dimension of the stream of data or alt_val if DIM2 was not present in the keyset. See spr_kset_get_value_dim2() for more details.

ssize_t spr_kset_get_value_nchan ( const SprKeySet * keys )

Get the 'NCHAN' key from the keyset keys. NCHAN corresponds to the number of audio channels in the recording. The data for the different channels is stored in an interleaved fashion. For track files, this means that each vector of size DIM2 contains NCHAN feature vectors stored in an interleved fashion.

Returns: The secondary dimension of the stream of data or the default value (1) if NCHAN was not present in the keyset.

ssize_t spr_kset_get_value_nchan_alt	(	const SprKeySet *	keys,
		ssize_t	alt_val
	)

Returns: The number of audio channels in the recording or alt_val if NCHAN was not present in the keyset. See spr_kset_get_value_nchan() for more details.

ssize_t spr_kset_get_value_chanlen ( const SprKeySet * keys )

Get the 'CHANLEN' key from the keyset keys. CHANLEN corresponds to the number of sample points in the recording.

Returns: The number of sample points in the recording or the default value (-1) if CHANLEN was not present in the keyset.

ssize_t spr_kset_get_value_chanlen_alt	(	const SprKeySet *	keys,
		ssize_t	alt_val
	)

Returns: The number of sample points in the recording or alt_val if CHANLEN was not present in the keyset. See spr_kset_get_value_chanlen() for more details.

double spr_kset_get_value_fshift ( const SprKeySet * keys )

Get the 'FSHIFT' key (frame shift in seconds) from the keyset keys.

Returns: The frame shift (in seconds) or the default value (SPR_DEFAULT_FSHIFT) if FSHIFT was not present in the keyset.

double spr_kset_get_value_fshift_alt	(	const SprKeySet *	keys,
		double	alt_val
	)

Returns: The frame shift or alt_val if FSHIFT was not present in the keyset. See spr_kset_get_value_fshift() for more details.

double spr_kset_get_value_foffset ( const SprKeySet * keys )

Get the 'FOFFSET' key (frame offset in seconds) from the keyset keys.

Returns: The frame offset (in seconds) or the defulat value (0.0) if FOFFSET was not present in the keyset.

double spr_kset_get_value_foffset_alt	(	const SprKeySet *	keys,
		double	alt_val
	)

Returns: The frame offset or alt_val if FOFFSET was not present in the keyset. See spr_kset_get_value_foffset() for more details.

int spr_kset_get_values_dim_and_type	(	const SprKeySet *	keys,
		int *	dim1,
		int *	dim2,
		const SprDT **	dt,
		const char *	fname,
		SprMsgId *	routine
	)

Get the values for the keys DIM1, DIM2 and TYPE. An error message is sent if any of these keys does not exists. An error message is also sent if there values differ from the values found in dim1, *dim2 or *dt respectively. This check on the value can be disabled by setting *dim1, *dim2 or *dt to -1, -1 or NULL respectively. In that case, the value(s) read from the keys will be written in *dim1, *dim2 or *dt.

Returns: 0 on success and -1 on failure.

int spr_kset_set_value_dim1	(	SprKeySet *	keys,
		ssize_t	value
	)

Set the value for the DIM1 key in keyset keys to value.

Returns: 0 on success and -1 on failure (and give a message).

int spr_kset_set_value_dim2	(	SprKeySet *	keys,
		ssize_t	value
	)

Set the value for the DIM2 key in keyset keys to value.

Returns: 0 on success and -1 on failure (and give a message).

SprKeySet* spr_kset_cpy ( const SprKeySet * keys )

Allocate a new keyset and copy the content of keys to it.

Returns: The newly created keyset or NULL on failure.

const char* spr_kset_iter	(	const SprKeySet *restrict	keys,
		int *restrict	iter,
		const char **restrict	value
	)

Iterator over all key-value pairs stored in the keyset.

int iter = 0;
const char *key,*val;
while((key=spr_kset_iter(htbl,&iter,&val)) != NULL)
 {// do something
  ...
 }

Returns: The Nth key (N being the number of times this routine was called) or NULL when all keys were handled. The associated value is returned in *value (if value != NULL).

int spr_kset_print	(	SprStream *restrict	fd,
		const SprKeySet *restrict	keys
	)

Print the content of the keyset (raw dump).

Returns: 0 if all keys could be printed and (-1) on failure.

void spr_kset_get_stdset	(	SprStdKeys *restrict	res,
		const SprKeySet *restrict	keys
	)

Retrieve the 'standard' keys from keys.

SprKeySet* spr_kset_set_defaults	(	SprKeySet *restrict	keys,
		SprStream *restrict	fd,
		const char *restrict	fname
	)

Set default values for the keys in keyset keys, or if keys equals NULL, the keys associated to fd.

If fd is not NULL, and if the stream contains sample data or if the number of frames, vectors, entries, ... is unknown, the silent-eof flag of the stream will be turned on (see SprStream::silenteof() for more info).

The fname argument is used for error reporting. If fname equals NULL, the name will be extracted from the stream descriptor fd.

Returns: keys on success and NULL on error.

SprKeySet* spr_kset_check	(	const SprKeySet *	keys,
		const char *	fname
	)

Check the legality of the keys in the keyset keys under the assumption of having one of the standard 'DATA' types: SAMPLE, TRACK, CORPUS, SEG

Returns: keys if all is OK and NULL otherwise.

ssize_t spr_kset_sample_adjust	(	SprKeySet *restrict	keys,
		const double *restrict	fshift_ptr,
		const double *restrict	flength_ptr,
		int	htk_convention
	)

Adjust the keys (DIM1,DIM2,FSHIFT,FLENGTH,FOFFSET) given some new values for the frame shift (*fshift_ptr if fshift_ptr!=NULL) and/or the frame length (*flength_ptr if flength_ptr!=NULL), and given the key SAMPLEFREQ and the limitation that frames have a fixed (integer) length. If the parameter htk_convention is not 0, a non-zero frame offset equal to (flength-fshift)/2.0 will be assumed.

Returns: DIM2 if all is OK and (-1) otherwise.

int spr_kset_stream_modif ( SprStream *restrict fd )

Try to write a header in the same location as the old header and if this fails, try to create the necessary space by moving the data block. This only works for the key and SPRAAK header formats.

Returns: 0 on success and -1 on failure.

Note: The stream will be turned in write mode.; On a successful return, the stream's write position will be directly after the header.

int spr_msg	(	int	lvl,
		SprMsgId *	routine,
		const char *	fmt,
			...
	)

Signal an error (lvl==SPR_ERROR), warning(lvl==SPR_WARNING), info(lvl==SPR_INFO) or debug(lvl>=1) message.

Error and warning messages are always output. Most other messages will be ignored. Whether a message is ignored depends on the current active triggers and filters and on the global message level (see spr_msg_modif_lvl(), spr_msg_modif_in() and spr_msg_modif_from()).

The messages are sent as a single printf(fmt,...) command. The messages should be short, i.e. no longer than 1023 characters, and if they consist of multiple lines, all extra lines must start with a tab ('\t').

Returns: 1 if the message is send, -1 if the message should have been sent but failed somehow, and 0 otherwise.

Parameters

lvl	Message level.
routine	Identifies the calling routine.
fmt	Format for printing.

int spr_msg_check	(	int	lvl,
		SprMsgId *	routine
	)

Check if a message from the given routine at level lvl would be printed (i.e. not ignored).

Returns: 1 if a message at that level would send, and 0 otherwise.

Parameters

lvl	Message level.
routine	Identifies the calling routine.

int spr_set_thread_id ( const char * name )

Set the thread id for dynamic names. Ssee the global comment for more details.

Returns: (-1) on failure, 0 otherwise.

void spr_msg_modif_lvl ( int lvl )

Set the global message filter level to lvl, i.e. only messages with a level equal to or lower than lvl will be output (unless routine or thread specific levels are defined.

see spr_msg_modif_in() and spr_msg_modif_from()).

Note: WARNINGS and ERRORS are always output, i.e. they can't be blocked by patterns or message levels.

Parameters

lvl	The new message level.

int spr_msg_get_lvl ( void )

Get the current global message level.

Returns: The current global message level.

int spr_msg_modif_in	(	const char *	filter_desc,
		int	action
	)

Update the filters for the message system. Filters allow you to let pass only those messages that come from selected routines and threads. The action argument can have the following values:

SPR_MSG_SET: Install a new set of filters (removes any old filters).
SPR_MSG_RM: Remove the filters given in filter_desc; silently ignores any name in filter_desc that does not match to any active filter
SPR_MSG_ADD: Add (or replace) the filters given in filter_desc.

The filter description filter_desc is either a NULL pointer (only relevant for the SPR_MSG_SET action) or a string containing zero, one or more patterns seperated by spaces. Each pattern has the following format (regular expression format):

#?\*?\w+\*?(\([0-9][0-9]?\))?

For those who prefer a textual description, the pattern consists of a name (a sequences of letters, numbers and underscores) optionally preceded and followed by a '*'. Following this there is an optional message level (a one or two digit number) in between round brackets '()'. This whole construct can be preceded by a pound sign '#'. The pound sign indicates that the pattern applies to a thread name instead of to a routine name. The wild-char '*' behaves similar to the '*' in file name matching, i.e. it matches 0 or more arbitrary characters.

When filters are active, only messages from matching routines and/or threads will be output. If no level is given in the pattern, the global message level (see spr_msg_modif_lvl()) will be used. If no filter patterns are set, all routines and/or threads match (given that the level is lower or equal to the global message level).

Note: WARNINGS and ERRORS are always output, i.e. they can't be blocked by patterns or message levels.

Returns: 0 on success and (-1) on failure.

Parameters

filter_desc	List of function/thread patterns and optional levels.
action	Action: set, remove or add the patterns.

int spr_msg_modif_from	(	const char *	filter_desc,
		int	action
	)

Set triggers for the message system, i.e. let only start passing messages once a message has come along for which the originating routine and/or thread matches the specified filter description filter_desc and the level of the message is equal or lower then the routine/thread specific threshold (or global threshold if no specific routine/thread threshold is specified). From that moment on, the filters (see spr_msg_modif_in()) will become active.

This function also automatically switches the message system in trigger mode if the routine and/or thread trigger list is non empty.
For more details on the arguments, see spr_msg_modif_in().

Returns: 0 on success and (-1) on failure.

Parameters

filter_desc	List of function/thread patterns and optional levels.
action	Flag: replace or augment the list.

SprDynStr spr_msg_get_in ( void )

Get the list of currently active filters. For a description of the format, see spr_msg_modif_in().

Returns: The list of active filter (or the empty string if there are none) or NULL if an error occurs

SprDynStr spr_msg_get_from ( void )

Get the list of currently active triggers. For a description of the format, see spr_msg_modif_in().

Returns: The list of active filter (or the empty string if there are none) or NULL if an error occurs

int spr_msg_modif_stream	(	SprStream *restrict	stream,
		const char *restrict	fname
	)

Change the stream the messages are send to, to stream if stream!=NULL and to a stream corresponding to fname otherwise.

The previous message stream will be closed after the new has been opened. By default all messages are witten to 'stderr'.

Returns: (-1) on failure and 0 otherwise.

Parameters

stream	The new stream to send messages to.
fname	The file to open (stream==NULL).

void spr_msg_modif_catch_func ( SprMsgCatchFunc handler )

Install (or uninstall if handler equals NULL) a handler that will be called on errors and warnings.

Parameters

handler The new handler to call on warning/errors.

char* spr_path_ext_ptr ( const char * fname )

Returns: a pointer to the extension of the given file-name fname, including the leading '.'. If the file has no extension, the returned pointer points to the final '\0' of the file-name.

int spr_path_dir_len ( const char * fname )

Return the length of the leading directory component (including the last '/') in the given file-name fname or zero if no path component was found.

char* spr_path_split_insitu	(	char **	path,
		char **	suffix,
		char *	fname
	)

Split the given filename in path, base name and suffix. The original string is corrupted by this operation.

Returns: the pointer to the base name.

Remarks: suffix and path may equal NULL

int spr_signal_report ( int action_mask )

Install a signal handler.

The action_mask flag is combination of the SPR_SIGNAL_{CTRLC,QUIT,ERROR,PIPE,USR1/2} bit mask flags. When a bit is set, the occurence of a signal that maps that action is reported back to the main program using the global variable spr_signal_flag (by setting the corresponding bit). It is up to all routines to check for the global variable spr_signal_flag and act upon its value.

When a bit in action_mask is not set, the default reaction on that action is triggered.

When action_mask equals -1, the current value of the mask is used to reset the whole system.

The signal handler reacts on the following signals (the bit the signal maps to in spr_signal_flag and the default action are given between brackets):

SIGINT: Interrupt from keyboard, i.e. Ctr-C pressed
(SPR_SIGNAL_CTRLC; quit)
SIGQUIT: Quit from keyboard
(SPR_SIGNAL_QUIT; quit)
SIGTERM: Terminate signal
(SPR_SIGNAL_QUIT; quit)
SIGBUS: Bus Error (incorreclty aligned data)
(SPR_SIGNAL_ERROR; quit)
SIGFPE: Arithmetic Exception
(no bit set; ignore)
SIGILL: Illegal Instruction
(SPR_SIGNAL_QUIT; quit)
SIGSEGV: Segmentation Fault
(SPR_SIGNAL_ERROR; quit)
SIGXCPU: CPU time limit exceeded
(SPR_SIGNAL_QUIT; quit)
SIGXFSZ: File size limit exceeded
(SPR_SIGNAL_QUIT; quit)
SIGPIPE: Broken Pipe
(SPR_SIGNAL_PIPE; ignore)
SIGXUSR1: User signal1
(SPR_SIGNAL_USR1; ignore)
SIGXUSR2: User signal2
(SPR_SIGNAL_USR2; print back trace)

An avalance of identical signals will automatically trigger the SPR_SIGNAL_ERROR action.

Some SPRAAK programs use the two user signals to report back on their current status (progress) by e.g. reporting on which entry in the corpus they are working.

Returns: 0 on success and (-1) on failure (mode not supported on this plaform).

Note: currently not operational for Windows.

const char* SPR_CLASSID_FROM_OBJ ( const void * object )

Get the id (a unique pointer to a string) of the class the object object belongs to.

SprSrmEl* spr_srm_retrieve	(	unsigned int	class_id,
		const char *	name
	)

Lookup the shared resource (class_id,name) and if its found lock it down so nobody can destroy it while you use it.

Returns: A handler to an existing and initialized resource matching the given class_id and name or (NULL) if such resource could not be found.

Note: Do not forget to unlock the SRM-element when no longer needed using a call to

Parameters

class_id	Class-id for the resource (type of resource).
name	Name of the resource.

SprSrmEl* spr_srm_retrieve_alt	(	unsigned int	class_id,
		const char *	name,
		size_t	sz
	)

Lookup the shared resource (class_id,name[0:sz-1]) and if its found lock it down so nobody can destroy it while you use it.

Returns: A handler to an existing and initialized resource matching the given class_id and name or (NULL) if such resource could not be found.

Parameters

class_id	Class-id for the resource (type of resource).
name	Name of the resource.
sz	Length of name.

SprSrmEl* spr_srm_get	(	unsigned int	class_id,
		const char *	name
	)

Retrieve and lock a shared resource.

Returns: A handler to an existing and initialized resource matching the given class_id and name or (NULL) if the operation failed (resource could not be found).

Note: This functions differs from spr_srm_retrieve() only in the fact that this routine will output an error message if the resource was not found.

Parameters

class_id	Class-id for the resource (type of resource).
name	Name of the resource.

SprSrmEl* spr_srm_create	(	unsigned int	class_id,
		const char *	name,
		int	name_is_persistent
	)

Create a new resource and lock it down. The resource is not yet initialized. Once it is fully initialized (using the routines of the form srm_set_xxx()) the resource must be released (see spr_srm_release()) in order for other routines, threads, ... to be able to use the resource. In the time between the creation of the resource and releasing it (signaling that is is initialized), all threads trying to access the resource will be blocked. This makes the whole system MT-safe at the cost of possible dead-locks if your code is not well behaving.

Returns: A handler to the freshly created (but not yet initialized) resource with the given class_id and name, or (NULL) if the creation failed (an identically named resource already exists or the operation ran out of memory).

Parameters

class_id	Class-id for the resource (type of resource).
name	Name of the resource.
name_is_persistent	Indicate that the given string is persistent, and hence no copy must be made.

SprSrmEl* spr_srm_retrieve_or_create	(	unsigned int	class_id,
		const char *	name,
		int	name_is_persistent
	)

Retrieve an existing or create a new resource. If another thread is in the process of initializing a resource, the calling thread will be blocked until the other thread releases the initialized resource (or destroys it if the initialization fails). See spr_srm_create() for more details.

Returns

A handler to either

an existing an initialized resource: if there exists an initialized resource matching the given class_id and name.
a freshly created, uninitialized resource: if no resource matched the search criteria.
(NULL): if the creation of a new uninitialized resource failed (out of memory).

Parameters

class_id	Class-id for the resource (type of resource).
name	Name of the resource.
name_is_persistent	Indicate that the given string is persistent, and hence no copy must be made.

int spr_srm_release	(	SprSrmEl *	srm_el,
		int	action
	)

Release or export a previously retrieved or created shared resource srm_el. Each retrieve and create operation puts one extra lock on the resource. A resource is only kept alive as long as there is at least a single lock on the resource. If the last lock is released, the resource is destroyed.

The action flag can have the following values:

SPR_SRM_EXPORT: Export a freshly initialized share resource. This action will keep the lock made by the spr_srm_create() or spr_srm_retrieve_or_create() call in place, assuring that the resource is kept alive so that others can use it.
SPR_SRM_RELEASE: Release the lock made by a previous retrieve or create operation.
SPR_SRM_RELEASE2: Release two locks made by previous retrieve or create operations.
SPR_SRM_RELEASE_DELAYED: Release the lock but do not destroy the resource if there are no more locks. This allows the creation of create-once, use-once resources.
SPR_SRM_CHECK_RELEASE: Check if the item can be destroyed, hence undoing a previous SPR_SRM_RELEASE_DELAYED action.

In combination with the above actions, you can also enlist or delist the shared resource for auto destruction, i.e. automatic destruction of the resource when SPRAAK is closed down:

SPR_SRM_AD_ENLIST: enlist for auto destruction.
SPR_SRM_AD_DELIST: delist from auto destruction.

If (and only if) the routine is called from a destroy routine then the action flag must also contain ('+' or '|' operator) the SPR_SRM_RELEASE_UNLOCKED flag.

When exporting a class-id resource (i.e. srm_el belongs to the class SPR_SRM_CID_CLASSID) this routine will check the given class-id (the value of 'val1') or search for a suitable class-id ('val1' not set). If registering the class-id resource is successful, the class-id will be returned.

Returns: (-1) on failure (out-of-memory, resource invalid, invalid class-id), the selected class-id when exporting a class-id resource, and (0) otherwise.

Parameters

srm_el	Shared resource handler.
action	Requested operation.

void spr_srm_release_quick ( SprSrmEl * srm_el )

Release a previously retrieved shared resource srm_el. This routine is equivalent to spr_srm_release(srm_el,SPR_SRM_RELEASE), except that it executes a lot faster.

void spr_srm_release_nocheck ( SprSrmEl * srm_el )

Release a previously retrieved shared resource srm_el, do not check if the shared resource is no longer needed and hence should be destroyed. This routine is equivalent to spr_srm_release(srm_el,SPR_SRM_RELEASE_DELAYED), except that it executes a lot faster.

SprSrmDir* spr_srm_dir ( unsigned int class_id )

List all available resources for a given class_id.

Note: This is a snapshot. By the time you access anything, the resource may already be destroyed or new resources may have been added.

Returns: A SprSrmDir structure or NULL if the operation failed (out of memory). The returned structure must be freed using spr_free() when no longer needed. This will free the structure and all names, so make sure to make copies if needed.

int spr_srm_check_initialized ( SprSrmEl * srm_el )

Check if a resource handler returned by spr_srm_retrieve_or_create() points to an existing resource or to a freshly created and hence uninitialized resource.

Parameters

srm_el Shared resource handler.

int spr_srm_set_free_routine	(	SprSrmEl *	srm_el,
		SprSrmFree	free_func
	)

If a resource is no longer needed (no one has a lock on it), its content will be destroyed. The routine allows you to install a resource specific free routine.

Returns: 0 on success and (-1) on failure (resource was already exported and is hence unmodifiable).

Parameters

srm_el	Shared resource handler.
free_func	Function to call when the resource is destroyed.

int spr_srm_set_info_val1_ptr	(	SprSrmEl *	srm_el,
		void *	val
	)

Set value1 of resource srm_el to val.

Returns: 0 on success and (-1) on failure (resource was already exported and is hence unmodifiable).

Parameters

srm_el Shared resource handler.

int spr_srm_set_info_val1_ndx	(	SprSrmEl *	srm_el,
		unsigned int	val
	)

Set value1 of resource srm_el to val.

Returns: 0 on success and (-1) on failure (resource was already exported and is hence unmodifiable).

Parameters

srm_el Shared resource handler.

int spr_srm_set_info_val2_ptr	(	SprSrmEl *	srm_el,
		void *	val
	)

Set value2 of resource srm_el to val.

Returns: 0 on success and (-1) on failure (resource was already exported and is hence unmodifiable).

Parameters

srm_el Shared resource handler.

int spr_srm_set_info_val2_ndx	(	SprSrmEl *	srm_el,
		unsigned int	val
	)

Set value2 of resource srm_el to val.

Returns: 0 on success and (-1) on failure (resource was already exported and is hence unmodifiable).

Parameters

srm_el Shared resource handler.

void* spr_srm_get_info_val1_ptr	(	const SprSrmEl *	srm_el,
		int *	err
	)

Get value1 of resource srm_el. If err is not NULL, a possible error condition will be signaled as well.

Returns: The requested pointer or (NULL) on failure (value1 of the resource was not set). If the value of the pointer could as well be NULL, you should use a non NULL err pointer to get further status information: *err will be 0 on success and -1 on failure.

Parameters

srm_el	Shared resource handler.
err	Signal if the operation failed.

unsigned int spr_srm_get_info_val1_ndx	(	const SprSrmEl *	srm_el,
		int *	err
	)

Get value1 of resource srm_el. If err is not NULL, a possible error condition will be signaled as well.

Returns: The requested value or (~0u) on failure (value1 of the resource was not set). If the value of the pointer could as well be (~0u), you should use a non NULL err pointer to get further status information: *err will be 0 on success and -1 on failure.

Parameters

srm_el	Shared resource handler.
err	Signal if the operation failed.

void* spr_srm_get_info_val2_ptr	(	const SprSrmEl *	srm_el,
		int *	err
	)

Get value2 of resource srm_el. If err is not NULL, a possible error condition will be signaled as well.

Returns: The requested pointer or (NULL) on failure (value1 of the resource was not set). If the value of the pointer could as well be NULL, you should use a non NULL err pointer to get further status information: *err will be 0 on success and -1 on failure.

Parameters

srm_el	Shared resource handler.
err	Signal if the operation failed.

unsigned int spr_srm_get_info_val2_ndx	(	const SprSrmEl *	srm_el,
		int *	err
	)

Get value2 of resource srm_el. If err is not NULL, a possible error condition will be signaled as well.

Returns: The requested value or (~0u) on failure (value1 of the resource was not set). If the value of the pointer could as well be (~0u), you should use a non NULL err pointer to get further status information: *err will be 0 on success and -1 on failure.

Parameters

srm_el	Shared resource handler.
err	Signal if the operation failed.

int spr_isspace ( unsigned int chr )

Check if the given character is within the normal ASCII range (0...127) and is a space.

int spr_isspace0 ( unsigned int chr )

Check if the given character is within the normal ASCII range (0...127) and is a space or '\0'.

int spr_isupper ( unsigned int chr )

Check if the given character is within the normal ASCII range (0...127) and is an uppercase letter.

int spr_islower ( unsigned int chr )

Check if the given character is within the normal ASCII range (0...127) and is an lowercase letter.

int spr_toupper ( unsigned int chr )

Convert a character to uppercase if it lays is within the normal ASCII range (0...127) and is a letter.

int spr_tolower ( unsigned int chr )

Convert a character to lowercase if it lays is within the normal ASCII range (0...127) and is a letter.

int spr_isalpha ( unsigned int chr )

Check if the given character is within the normal ASCII range (0...127) and is an alphabetic character (a letter).

int spr_isalpha_ ( unsigned int chr )

Check if the given character is within the normal ASCII range (0...127) and is an alphabetic character (a letter) or '_'.

int spr_isalnum ( unsigned int chr )

Check if the given character is within the normal ASCII range (0...127) and is an alphanumeric character (letter or number).

int spr_isalnum_ ( unsigned int chr )

Check if the given character is within the normal ASCII range (0...127) and is an alphanumeric character (letter or number) or '_'.

int spr_isalphax_ ( unsigned int chr )

Check if the given character is an alphabetic character (a letter) or '_' or is an UTF-8 character (character in the range [128...255]).

int spr_isalnumx_ ( unsigned int chr )

Check if the given character is an alphanumeric character (letter or number) or '_' or is an UTF-8 character (character in the range [128...255]).

int spr_isdigit ( unsigned int chr )

Check if the given character is within the normal ASCII range (0...127) and is a digit.

int spr_isxdigit ( unsigned int chr )

Check if the given character is within the normal ASCII range (0...127) and is a hexadecimal digit ([0-9A-Fa-f]).

char* spr_str_skip_space ( const char * str )

Skip 0 or more initial spaces.

char* spr_str_skip_word ( const char * str )

Advance till the end of the word, i.e. the first space or the terminating '\0'.

int spr_str_split	(	char *	str,
		char **	tok,
		int	max_tok,
		char **	rem
	)

Split the input string str in-situ into tokens ('\0' terminated). The tokens must either start and stop with a double-quote (C-strings) or must be seperated by white-space characters. The pointers to the first max_tok strings are stored in the array tok. The remaining part of the string str is no further split into tokens. If *rem is not NULL, it will point to the remaining part or the terminating '\0' in str when there were max_tok or less fields present. Leading and trailing white-space characters of all tokens and of the remaining part are removed. All tokens starting (and ending) with double quotes \" are assumed to be quoted C-strings and will be converted to plain strings.

Returns: the number of fields stored in tok (may be less than max_tok) on success and -1 on failure (invalid quoted string).

int spr_str_split_ref	(	const char *	str,
		SprStrSplit *	tok,
		int	max_tok,
		const char **	rem
	)

Split the input string str into tokens. The start and length of the first max_tok (or less) tokens is returned in tok (not '\0' terminated). The tokens must either start and stop with a double-quote (C-strings) or must be seperated by white-space characters. The C-strings are left unchanged, i.e. the escaped characters are not converted. The remaining part of the string str is no further split into tokens. If *rem is not NULL, it will point to the remaining part or the terminating '\0' in str when there were max_tok or less fields present. Leading and trailing white-space characters are ignored.

Returns: the number of fields stored in tok (may be less than max_tok) on success and -1 on failure (invalid quoted string).

char** spr_str_split_dyn	(	char *	str,
		int *	max_tok
	)

Split the input string str in-situ into tokens ('\0' terminated) using the same conventions as spr_str_split(). If max_tok is not NULL, it must contain the maximum number of tokens desired (use -1 for all tokens) on entry and it will contain the number of tokens found on exit. The returned array will be NULL terminated, except when max_tok is not NULL and (*max_tok!=-1) and more tokens are available. In that case, the returned array will contain *max_tok+1 elements with the last element pointing to the remaining part of the string str.

Returns: a dynamically allocated array containing the requested tokens or (-1) on error.

int spr_str_trim_spaces ( char * str )

Remove trailing spaces and new-lines from a string.

Returns: the new length of the string.

int spr_scanf_simple	(	const char *	str,
		const char *	fmt,
		SprScanfDst *	dst,
		SprScanfErr *	err
	)

Decode a the content of the string str based on the format encoded in fmt. The output is stored in dst. If not NULL, err will contain information to see up till where the input could be decoded. The format string is a concattenation of '%' constructions, which match some high level construct such as a number or some white-space, and any other character which must match the input verbatim. All decoding is greedy.

The following '%' constructions are supported:

'%%' match '%' verbatim
'%d[<type>]' read some data of the type <type> (with <type> any of the 'SprDT' data types defined in datatype.c) and store the result in the next free location in dst.
'%.', '% ', '%_': match exactly one, zero or more, or one or more white space(s).
'%w[<characters>]', %w[^<characters>]', '%W...' scan a word, scanning stops when a characters outside the set <characters> are found or ('^' option) when a character from the set of characters in <characters> is found. The set <characters> can also contain character regions, i.e. <char0>-<char1> constructions. The result is stored in two consequetive fields in dst, first comes the starting position in dst[].pos, followed by the length of the matching string in dst[].len. The variants with capital 'W' allow empty words as well.
'%?[<opt0>,<opt1>,...]' any of the options <opt0>, <opt1>, ...; The result is stored in dst[].iopt (0 for 'opt0', 1 for 'opt1', etc.).
'%p' store the current location in the string str in dst[].pos.
'%l' store the length relative to the last stored location ('%p' or '%[w]' construction) in dst[].len.

Any character that has a contextual meaning in the '%' constructions (e.g. the ',' in the '%[?]' construction can be treated as a normal character by prefixing it with a '\' character (requires two '\' in a C-string).

Returns: (-2) if there was a mismatch in the format string fmt, (-1) if there was a mismatch between the format and the string, (1) if the end of the format string fmt was reached while there was still data in str and 0 otherwise.

char* spr_expr_scan	(	const char *	str,
		int	len,
		unsigned int	flags,
		SprExprScanErr *	err
	)

Scan for the end of a C-alike expression. Scanning start at the beginning of str and, depending on the flags set in flags expects a term (something that evaluates to a value) or a statement. Note: if there are still brackets open, then the routine will scan until all brackets are close and only then check for a matching stop.

The scanning stops if one of the conditions set in flags is met (without any pending open brackets):

SPR_SCAN_BRC: stop at a bracket close
SPR_SCAN_NL: stop at a newline, unless a line continuation is indicated (see also SPR_SCAN_MOD_NO_NL)
SPR_SCAN_SEMI: stop at a semicolumn
SPR_SCAN_COMMA: stop at a comma
SPR_SCAN_COL: stop at a column
SPR_SCAN_QMARK: stop at a questionmark
SPR_SCAN_OP: stop at a binary operator with a precedence lower or equal to what is specified with one of the SPR_SCAN_OP_... values listed below
SPR_SCAN_SYNTAX: stop at a syntax error (the enforced syntax is very weak, so this for sure does not guarantee well formed expressions)

When specifying the SPR_SCAN_OP flag, the minimal operator precedence on which to stop can be specified as well (listed from low to high precedence; only one of these flags should be given):

SPR_SCAN_OP_SPC: whitespace that acts as a seperator between values in a list (fuzy rules)
SPR_SCAN_OP_ASSIGN: an assign operator '=' '+=' '*=' ...
SPR_SCAN_OP_ORL: logical or ('||')
SPR_SCAN_OP_ANDL: logical and ('&&')
SPR_SCAN_OP_ORB: binary or ('|' '^'); note: the meaning of '^' can be modified with the SPR_SCAN_MOD_POW flag
SPR_SCAN_OP_ANDB: binary and ('&')
SPR_SCAN_OP_CMP: a comparison ('==' '!=' '<=' '>=' '<' '>' '~' '~=' '!~')
SPR_SCAN_OP_SHIFT: shift left/right ('<<' '>>')
SPR_SCAN_OP_ADD: addition ('+' '-')
SPR_SCAN_OP_MUL: multiplication ('*' '/' '\' '%')
SPR_SCAN_OP_POW: power ('^'); note: only works in combination with the SPR_SCAN_MOD_POW flag
SPR_SCAN_OP_MEMBER: a.b or a->b operation

If needed, comments can be skipped. The possible comment formats are controled with the following flags:

SPR_SCAN_COMMENT_C: allow C-style comments, i.e. // ... newline and /\star ... \star/
SPR_SCAN_COMMENT_S: allow shell-style comments, i.e. # ... newline
SPR_SCAN_COMMENT_M: allow matlab-style comments, i.e. % ... newline

The interpretation of certain characters can be modified with the following flags:

SPR_SCAN_MOD_NO_NL: a newline is equivalent to a string end
SPR_SCAN_MOD_SPC: a whitespace character can be a silent ',' when enumerating values (in a list)
SPR_SCAN_MOD_POW: a '^' acts as the power operator (Matlab convention) instead of logical xor (C-convention)
SPR_SCAN_MOD_CHR: a single quote character can be a unary post operator (instead of starting a C-style character or Matlab-style string)
SPR_SCAN_MOD_STRCAT: two succeeding strings are considered to be an automatic string concatenation
SPR_SCAN_NLC_DOTS: three dots '...' followed by a newline indicates a line continuation
SPR_SCAN_NLC_BSLASH: a backslash '\' followed by a newline indicates a line continuation

If err is not NULL, details concerning an error will be stored in the following fields:

estr: an explicative error message (set to NULL if no error occurred)
err: an error number (set to 0 if no error occured)
pos1,pos2: begin and end location of the problem (e.g. a bracet open + the non-matching bracket close); set to (-1) if not relevant

The following error conditions are known:

unbalanced brackets; err->pos1 refers to the bracket open position (or is set to -1 if there is no corresponding bracket open; err->pos2 refers to the bracket close position or the position where a bracket close was expected
non terminated string/character; err->pos1 refers to the string/character start position; err->pos2 refers to where the string/character should have ended
non terminated comment; err->pos1 refers to the comment start position; err->pos2 refers to where the comment should have ended
a syntax error (unexpected symbol given the preceeding symbols)

Returns: pointer to the first character not part of the expression (e.g. the ';' when using the SPR_SCAN_SEMI flag) or NULL if no valid end was found

Note: this routine does not check if the expression is valid

Parameters

str	scan in this string
len	lenght of the string or (-1) if '\0' terminted string
flags	flags specifying what an 'end of the expression' constitutes
err	give details on an error

size_t spr_stream_read	(	SprStream *restrict	fd,
		void *restrict	buf,
		size_t	size
	)

Read from a stream.

Attempt to read size bytes from stream fd into the buffer buf and advance the read position by the number of bytes actually read.

Returns: Zero if all size bytes could be read successfully and the number of bytes that should still be read in order to have read size bytes otherwise. A non-zero return value does not necessarily indicates an error: on non-blocking devices this could also signal that the requested data is not yet available. If a non-zero value is returned, fd->err and fd->eof will be set to indicate the cause of the problem.

Note: This function may also be called directly (i.e. without using the object interface SPR_DO()). The SPR_DO() approach may point to a faster (but 100% compatible) implementation at the cost of a somewhat higher call overhead.

Parameters

fd	Stream object.
buf	Buffer to write the data to.
size	Number of bytes to read.

int spr_stream_write	(	SprStream *restrict	fd,
		const void *restrict	buf,
		size_t	size
	)

Write to a stream.

Attempt to write size bytes from buffer buf to stream fd and advance the write position by the number of bytes actually written.

Returns: 0 if the operation was successful and -1 otherwise (one or more bytes could not be written). fd->err (errno) is set in the latter case.

Note: This function may also be called directly (i.e. without using the object interface SPR_DO()). The SPR_DO() approach may point to a faster (but 100% compatible) implementation at the cost of a somewhat higher call overhead.

Parameters

fd	Stream object.
buf	Buffer containing the data to write.
size	Number of bytes to write.

size_t spr_stream_skip	(	SprStream *restrict	fd,
		size_t	size
	)

Skip data from a stream.

Skip size bytes (i.e. read but do not store) from the stream fd.

Returns: Zero if all size bytes could be read successfully and the number of bytes that should still be skipped in order to have skipped size bytes otherwise. A non-zero return value does not necessarily indicates an error: on non-blocking devices this could also signal that the requested data is not yet available. If a non-zero value is returned, fd->err and fd->eof will be set to indicate the cause of the problem.

Note: This function may also be called directly (i.e. without using the object interface SPR_DO()). The SPR_DO() approach may point to a faster (but 100% compatible) implementation at the cost of a somewhat higher call overhead.

Parameters

fd	Stream object.
size	Number of bytes to skip.

int spr_stream_fill	(	SprStream *restrict	fd,
		int	chr,
		size_t	size
	)

Attempt to write size times the character chr to stream fd and advance the write position by the number of bytes actually written.

Returns: 0 if the operation was successful and -1 otherwise (one or more bytes could not be written). fd->err (errno) is set in the latter case.

Note: This function may also be called directly (i.e. without using the object interface SPR_DO()). The SPR_DO() approach may point to a faster (but 100% compatible) implementation at the cost of a somewhat higher call overhead.

Parameters

fd	Stream object.
chr	Character used for filling.
size	Repeat factor.

int spr_stream_mkdir_parents	(	SprMsgId *	routine,
		char *	path
	)

Make the directory path and if necessary the parent directories.

Returns: 0 on success and the value of errno on error.

Note: if routine equals NULL, error messages are supressed.; path must be writable. Make a copy if this cannot be guaranteed.

SprStream* spr_stream_dynbuf_make	(	const char *	name,
		void *	buf,
		size_t	alen,
		size_t	fill,
		unsigned int	flags,
		SprKeySet *	keys
	)

Create a stream named name that maps to the dynamically allocated buffer buf of length alen assuming fill characters/bytes are readily available for reading. The flags and keys arguments behave identically as in spr_stream_open().

Returns: The newly created stream handle or (NULL) on error.

Note: The name argument must point to data that will be persistent for as long as this stream is in use (i.e. not closed).; From this call on the buffer buf belong to the stream and hence should not be used for any other purpose. At the end of the stream operations, the (modified) buffer can be reclaimed using the spr_stream_dynbuf_close_getdata() function.

SprStream* spr_stream_dynstr_make	(	const char *	name,
		SprDynStr	str,
		size_t	fill,
		unsigned int	flags,
		SprKeySet *	keys
	)

Create a stream named name that maps to the dynamic string str assuming fill characters/bytes are readily available for reading. The flags and keys arguments behave identically as in spr_stream_open().

Returns: The newly created stream handle or (NULL) on error.

Note: The name argument must point to data that will be persistent for as long as this stream is in use (i.e. not closed).; From this call on the dynamic string belong to the stream and hence should not be used for any other purpose. At the end of the stream operations, the (modified) dynamic string can be reclaimed using the spr_stream_dynstr_close_getdata() function.

SprStream* spr_stream_open_write	(	const char *restrict	fname,
		unsigned int	flags,
		const char *	def_keys,
			...
	)

Create a new keyset and open the stream (file) the file name fname refers to for writing using that keyset.
The flags argument has the same meaning as with spr_stream_open(), except the that SPR_STREAM_WRITE, SPR_STREAM_CREATE, and SPR_STREAM_TRUNC bits are automatically set.
The def_keys argument must contain one or more of the following characters (exactly in the order as listed below, except for 'X', 'Y' and 'Z' which may be intermixed):

D: The next argument in the varargs list (of type enum SPR_KEY_DATA) is the value for the DATA key.
L: The next argument in the varargs list (of type enum SPR_KEY_LAYOUT) is the value for the LAYOUT key.
T: The next argument in the varargs list (of type SprDT*) is the value for the TYPE key.
A: Use the ASCII format when writing the data, i.e. the the FORMAT key to ASCII. The same effect can be had by setting the SPR_STREAM_ASCII flags in flags.
1: The next argument in the varargs list (of type ssize_t) is the value for the DIM1 key.
2: The next argument in the varargs list (of type ssize_t) is the value for the DIM2 key.
X: There next two arguments (both of type const char*) give an additional key and its value for the keyset.
Y: There next two arguments (of type const char* and ssize_t) give an additional key and its numerical value for the keyset.
Z: There next two arguments (of type const char* and double) give an additional key and its numerical value for the keyset.

All flags, except for 'X', 'Y' and 'Z' may be specified only once.

Returns: A valid stream handler or NULL on error.

unsigned int spr_stream_check	(	const char *restrict	fname,
		unsigned int	flags
	)

Check if the stream (file) the (rich) file name fname refers to exists, and could be opened in the mode indicated by the argument flags (see spr_stream_open() for more details on the flags).

Returns: 1 if the stream exists and can (most likely) provide the capabilities requested in flags, 0 if the file does not exist (and the SPR_STREAM_CREATE was not set) or cannot provide the requested capabilities, and (-1) if an error occured.

int spr_fgetc ( SprStream *restrict fd )

Read a single character from the file fd.

Returns: The character read or (-1) on error. In the latter case, fd->err and fd->eof are set to indicate the cause of the error.

int spr_fgetc_utf8 ( SprStream *restrict fd )

Read a single UTF-8 character from the file fd.

Returns: The character read or (-1) on error. In the latter case, fd->err and fd->eof are set to indicate the cause of the error.

int spr_ungetc	(	SprStream *restrict	fd,
		int	chr
	)

Push a single character back to the read stream fd.

Returns: The character pushed back (with all non relevant bits cleared) or (-1) on error. In the latter case, fd->err is set to indicate the cause of the error.

int spr_ungetc_utf8	(	SprStream *restrict	fd,
		int	chr
	)

Push a single UTF-8 character (can map to multiple bytes) back to the read stream fd.

Returns: The character pushed back (with all non relevant bits cleared) or (-1) on error. In the latter case, fd->err is set to indicate the cause of the error.

int spr_fputc	(	SprStream *restrict	fd,
		int	chr
	)

Write the character chr to the stream fd.

Returns: The character written to fd (with all non relevant bits cleared) on success and (-1) on error.

int spr_fputc_utf8	(	SprStream *restrict	fd,
		int	chr
	)

Write the UTF-8 character chr (can map to multiple bytes) to the stream fd.

Returns: chr on success and (-1) on error.

SprDynStr spr_fgets	(	SprDynStr restrict	str,
		SprStream *restrict	fd,
		unsigned int	flags,
		int *restrict	pos
	)

Read a string (dynamically allocated) from to the stream fd. If the pos argument is not NULL, then the read string will be written in the string starting at position *pos and *pos will be updated to reflect to total length of the string (excluding the final '\0'). The str argument can be either NULL or an existing dynamic string. The returned string is a dynamic string and must be treated as such (e.g. using spr_dynstr_free() to release the allocated memory). The flags argument can be a combination of the following bitmap flags:

SPR_FGETS_KEEP_CR_LF: do not strip the terminating CR/LF combination.
SPR_FGETS_KEEP_LEAD_SPACE: do not strip the leading space.
SPR_FGETS_KEEP_TRAIL_SPACE: do not strip the trailing space.
SPR_FGETS_MULTI_LINE: concatenate the next line when the line ends with a back-slash ('\') (will lead to an embeded '\n')

Returns: The string read (a dynamic string) on success and (NULL) on error. If pos is not NULL, *pos will be set tot the length of the string.

Note: On error, any non NULL input string str will be freed.; SPR_FGETS_KEEP_CR_LF implicitly implies SPR_FGETS_KEEP_TRAIL_SPACE

char* spr_fgets_alt	(	char *restrict	str,
		int *restrict	alen,
		SprStream *restrict	fd,
		unsigned int	flags,
		int *restrict	pos
	)

Read a string (dynamically allocated) from to the stream fd. The argument str can be either NULL (*alen must then equal 0) or an existing allocated chunk of memory of length *alen. If the pos argument is not NULL, then the read string will be written in the string starting at position *pos and *pos will be updated to reflect to total length of the string (excluding the final '\0'). The returned string is an allocated chunk of memory of length *alen and must be treated as such (e.g. using spr_free() to release the allocated memory). The argument flags can be a combination of the following bitmap flags:

SPR_FGETS_KEEP_CR_LF: do not strip the terminating CR/LF combination.
SPR_FGETS_KEEP_LEAD_SPACE: do not strip the leading space.
SPR_FGETS_KEEP_TRAIL_SPACE: do not strip the trailing space.
SPR_FGETS_MULTI_LINE: concatenate the next line when the line ends with a back-slash ('\') (will lead to en embeded '\n')

Returns: The string read on success and (NULL) on error. If pos is not NULL, pos will be set tot the length of the string.

Note: On error, any non NULL input memory chunk str will be freed.; SPR_FGETS_KEEP_CR_LF implicitly implies SPR_FGETS_KEEP_TRAIL_SPACE; alen and/or str may equal NULL.

ssize_t spr_fputs	(	SprStream *restrict	fd,
		const char *restrict	str
	)

Write the '\0' terminated string str to the stream fd.

Returns: The number of bytes written (equals strlen(str)) on success and (-1) on error. fd->err (errno) is set in case of an error.

ssize_t spr_fputsq	(	SprStream *restrict	fd,
		const char *restrict	str
	)

Write the '\0' terminated string str to the stream fd as a quoted string, i.e. surrounded by double quotes and all problematic characters replaced by equivalent escape codes.

Returns: The number of bytes written (equals spr_strlenq(str)) on success and (-1) on error. fd->err (errno) is set in case of an error.

ssize_t spr_fputsoq	(	SprStream *restrict	fd,
		const char *restrict	str
	)

Write the '\0' terminated string str to the stream fd, either as is (unquoted) of if needed surrounded by double quotes and all problematic characters replaced by equivalent escape codes.

Returns: The number of bytes written on success and -1 on error. fd->err (errno) is set in case of an error.

int spr_stream_hex_write	(	SprStream *restrict	fd,
		const void *restrict	data,
		size_t	Nel,
		size_t	el_size
	)

Write the binary data *data consisting of Nel elements of size el_size to the stream fd as hexadecimal data. The elements should be atomic data types (char, short, int, long, long long, float, double).

Returns: 0 on success and -1 on failure. In the latter case, fd->err will contain the error code.

Note: make sure to use the correct el_size, otherwise you may end up with byte swapped data when reading on an other platform.

int spr_stream_hex_read	(	SprStream *restrict	fd,
		void *restrict	data,
		size_t	Nel,
		size_t	el_size
	)

Read Nel elements of size el_size as hexadecimal data from fd. The data is stored in binary form in the buffer data. The elements should be atomic data types (char, short, int, long, long long, float, double).

Returns: 0 on success and -1 on failure. In the latter case, fd->err will contain the error code.

Note: make sure to use the correct el_size, otherwise you may end up with byte swapped data.

off_t spr_stream_copy_data	(	SprStream *restrict	dst,
		SprStream *restrict	src
	)

Copy all data from stream src (till end-of-file) to stream dst. On entry, src and dst must be in read and write mode respectively, and the stream read and write pointers must be positioned as desired (typically right after the header).

Returns: The amount of data copied or (-1) on failure (even if part of the data could be copied).

Note: On success, the stream read pointer (src) will point to the end of the file and the eof flag will be set. The stream read write pointer (dst) will point right after the last written byte (typically this will also be the end of the file, but if one is writing in an existing file, it may still be somewhere in the middle of the file).

int spr_fprintf	(	SprStream *restrict	fd,
		const char *restrict	fmt,
			...
	)

Formatted output of data. See fprintf() for more details.

Note: Illegal format specifiers are echoed back to the output preceded by a question mark.

int spr_vfprintf	(	SprStream *restrict	fd,
		const char *restrict	fmt,
		va_list	args
	)

Formatted output of data. See vfprintf() and spr_fprintf() for more details.

size_t spr_snprintf	(	char *restrict	buf,
		size_t	size,
		const char *restrict	fmt,
			...
	)

Formatted output of data to a string. See snprintf() for more details.

Note: If you want to be sure the resulting string will be '\0' terminated, use spr_snprintf0() or use the following construction:
char buf[SOME_SIZE];

...

buf[sizeof(buf)-1] = '\0';

spr_snprintf(buf,sizeof(buf)-1,"%desired %format\n",dec_nr,flt_nr);

size_t spr_snprintf0	(	char *restrict	buf,
		size_t	size,
		const char *restrict	fmt,
			...
	)

Identical to spr_snprintf(), except that the result is guaranteed to be '\0' terminated (except if size equals 0). A warning is given in case the result needed to be truncated.

size_t spr_vsnprintf	(	char *restrict	buf,
		size_t	size,
		const char *restrict	fmt,
		va_list	args
	)

Formatted output of data to a string. See snprintf() and spr_snprintf() for more details.

SprDynStr spr_sprintf	(	SprDynStr restrict	str,
		const char *restrict	fmt,
			...
	)

Formatted output of data to the dynamic string str. This routine automatically expands the string to meet the data requirements. See sprintf() for more details on the format specifier fmt.

Returns: The (reallocated) string on success, or (NULL) on error.

SprDynStr spr_vsprintf	(	SprDynStr restrict	str,
		const char *restrict	fmt,
		va_list	args
	)

Formatted output of data to a string. See sprintf() and spr_sprintf() for more details.

SprDynStr spr_soprintf	(	SprDynStr restrict	str,
		size_t *restrict	offset,
		const char *restrict	fmt,
			...
	)

Formatted output of data to a dynamic string str. Output start at *offset. The output starts at offset offset. See sprintf() and spr_sprintf() for more details.

Returns: The (reallocated) string on success, or (NULL) on error. The total length of the string is returned in *offset.

SprDynStr spr_vsoprintf	(	SprDynStr restrict	str,
		size_t *restrict	offset,
		const char *restrict	fmt,
		va_list	args
	)

Formatted output of data to a dynamic string str. The output starts at offset offset. See vsprintf() and spr_vsprintf() for more details.

char* spr_sprintf_alt	(	SprDynStr restrict	str,
		int *restrict	alen,
		const char *restrict	fmt,
			...
	)

Formatted output of data to the dynamically allocated string str with alen bytes allocated. This routine automatically expands the string to meet the data requirements. See sprintf() for more details on the format specifier fmt.

Returns: The (reallocated) string on success, or (NULL) on error.

char* spr_vsprintf_alt	(	char *restrict	str,
		int *restrict	alen,
		const char *restrict	fmt,
		va_list	args
	)

Formatted output of data to the dynamically allocated string str with alen bytes allocated. See sprintf() and spr_sprintf() for more details.

char* spr_soprintf_alt	(	char *restrict	str,
		int *restrict	alen,
		int *restrict	pos,
		const char *restrict	fmt,
			...
	)

Formatted output of data to the dynamically allocated string str with alen bytes allocated. Output starts at *pos. This routine automatically expands the string to meet the data requirements. See sprintf() for more details on the format specifier fmt.

Returns: The (reallocated) string on success, or (NULL) on error. The total length of the string is returned in *pos.

SprDynStr spr_vsoprintf_alt	(	char *restrict	str,
		int *restrict	alen,
		int *restrict	pos,
		const char *restrict	fmt,
		va_list	args
	)

Formatted output of data to the dynamically allocated string str with alen bytes allocated. Output starts at *pos. This routine automatically expands the string to meet the data requirements. See sprintf() for more details on the format specifier fmt.

Returns: The (reallocated) string on success, or (NULL) on error. The total length of the string is returned in *pos.

SprStream* spr_stream_open_tmp	(	const char *	template_str,
		unsigned int	flags,
			...
	)

Create a headerless temporary file and open for writing and reading. Other flags such as buffering can be specified in flags. If template_str is not NULL, then use the provided template and extra arguments to create a filename. If template_str is NULL, then generate a random name.

Note: make sure to set the SPR_STREAM_AUTORM flags if you want the temporary file to be automatically removed when closed.

Returns: the newly created (and thus empty) temporary file (in write mode) on success, and NULL on error.

size_t spr_utf8_len ( const char * str )

Count how many utf-8 characters a given string contains.

Returns: The number of utf-8 characters.

char* spr_utf8_next ( const char * str )

Advance to the next utf-8 character.

Returns: The pointer to the next character.

Note: If the current character is non-ascii, the routine will scan up till and including the next character, so make sure that the string is either '\0' terminated or that the calling routine does no try to jump past the last character (and the tring is properly utf-8 encoded).

char* spr_utf8_nextN	(	const char *	str,
		int	N
	)

Advance to the next utf-8 character N times.

Returns: The character pointer after having advanced N times.

char* spr_utf8_prev ( const char * str )

Back-up till the previous utf-8 character.

Returns: The pointer to the previous character.

Note: The routine will scan up till and including the previous character, so make sure not to try backing-up till before the start of the string.

char* spr_utf8_get_advance	(	int *	utf_chr,
		const char *	str
	)

Get the current utf-8 character from str, store the character value in utf_chr and advance to the next character.

Returns: The pointer to the next character. *utf_chr will contain the UTF character or (-1) if the encoding was invalid.

char* spr_utf8_check	(	const char *	str,
		SprMsgId *	routine
	)

Test if str is a valid utf-8 encoded string. If not, and if routine is not NULL, a warning is printed.

Returns: A pointer pointing to the termination '\0' if str is a valid utf-8 encoded string and (NULL) otherwise.

int spr_utf8_chr_len ( unsigned int chr )

Determine the length required to encode chr in utf-8 format.

Returns: The required number of bytes.

Note: Any '\0' character send to this routine is assumed to be an embedded '\0' and hence a length of 2 is returned (see spr_utf8_chr_put_advance()).

char* spr_utf8_chr_put_advance	(	char *	str,
		unsigned int	chr
	)

Encode the character chr as a utf-8 (multi-byte) code and write it to str.

Returns: The location where the next utf-8 character in str should start, i.e. str+spr_utf8_chr_len(chr).

Note: Any '\0' character send to this routine is assumed to be an embedded '\0' and is hence encoded using the two byte code 0xc080.

Variable Documentation

SprDT spr_dt_dt[1]

The SPRAAK data type identifier (SprDT element) for data type identifiers. The string respresentation (used in file headers, messages, ...) of this type is "TYPE".

Note: Previous values will be freed, so make sure the destination is initialized to NULL.

SprDT spr_dt_custom[1]

The SPRAAK data type identifier (SprDT element) for something we can't handle. The string respresentation (used in file headers, messages, ...) of this type is "CUSTOM".

const SprOptDesc spr_od_common[]

const SprHtblStr spr_htbl_str_empty

const char spr_kset_key_data[]

the string "DATA"