SPRAAK
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Functions
API_HighLvl::lib::data
+ Collaboration diagram for API_HighLvl::lib::data:

Functions

int spr_extern_check_break (void)
 
void * spr_extern_stream_open_r (const char *fname)
 
void * spr_extern_stream_open_w (const char *fname, ssize_t dim1, ssize_t dim2, const char *el_desc, const char *keys[][2])
 
ssize_t spr_extern_stream_read (void *dst, void *fd, ssize_t Nel)
 
ssize_t spr_extern_stream_read_string (char **dst, void *fd, const char *flags)
 
ssize_t spr_extern_stream_write_string (void *fd, const char *str, ssize_t sz)
 
const char * spr_extern_keyset_iter (void *fd, int *ndx, const char **val)
 
int spr_extern_keyset_decode (void *fd, ssize_t *dim1, ssize_t *dim2, ssize_t *el_sz, const char **el_desc, const char **layout, int *Nkeys)
 
int spr_extern_stream_write (void *fd, const void *src, ssize_t Nel)
 
int spr_extern_stream_close (void *fd)
 

Detailed Description

Function Documentation

int spr_extern_check_break ( void  )
Returns
a non-zero value if there is a request to abort the current operation.
void* spr_extern_stream_open_r ( const char *  fname)

Open a SPRAAK file fname for reading.

Returns
the file handle (as an opaque structure) or NULL on error.
void* spr_extern_stream_open_w ( const char *  fname,
ssize_t  dim1,
ssize_t  dim2,
const char *  el_desc,
const char *  keys[][2] 
)

Open the SPRAAK file fname for writing. The data that will be written is of the type el_desc and will be written in a matrix form of dim1xdim2 elements, .i.e. dim1 vectors containing dim2 elements each. A value of -1 means that a dimension is unknown. Other keys can be given in the array keys: a 2xN array containing N (key,value) pairs, terminated by a (NULL,NULL) pair. Next to the standard numerical datatype ([IU]8..64, F32, F64), the routine also supports the datatype CUSTOM (a simple byte stream) and STRING (a LIST of strings).

Returns
the file handle (as an opaque structure) or NULL on error.
Note
dim2 may on be -1 when writing strings (el_desc="STRING")
when writing sample data (keys contains {"DATA","SAMPLE"}), dim1 and dim2 correspond to the number of samples in a channel and the number of channels respectively.
See Also
datatype.c for more info on data types
keyset.c for more info on keys
ssize_t spr_extern_stream_read ( void *  dst,
void *  fd,
ssize_t  Nel 
)

Read Nel elements from the SPRAAK stream fd and store in dst. It is the callers responsability to assure that dst is large enough to contain all Nel data elements.

Returns
the number of elements read or (-1) on error.
Note
elements of the type "STRING" must be read by means of spr_extern_stream_read_string()
ssize_t spr_extern_stream_read_string ( char **  dst,
void *  fd,
const char *  flags 
)

Read a single string from the SPRAAK stream fd. The flags argument can specify the following flags:

  • '<' keep leading space
  • '>' keep trailing space
  • 'n' keep the terminating CR/LF combination
  • '+' allow multi-line combination for lines ending with a back-slash ('\') (will lead to an embeded '\n')

The '\0' terminated string will be written in the allocated buffer *dst. This buffer is managed by SPRAAK, this means that:

  • *dst should be set to NULL before the first call to spr_extern_stream_read_string()
  • the content of *dst should be copied or processed after calling this function (one can modify the content of the buffer, but the length of the buffer is only guaranteed to be as long as the returned string)
  • the content of *dst must be freed by calling spr_extern_stream_read_string() with fd set to NULL
Returns
the length of the string stored in *dst + 1 or 0 when the end of the file is reached or (-1) on failure.
Note
the flags argument may be NULL, this is equivalent to an empty string
other characters than '<>n+' is the flags argument may lead to undefined behaviour
ssize_t spr_extern_stream_write_string ( void *  fd,
const char *  str,
ssize_t  sz 
)

Write a '\0' terminated string (sz==-1) or a string of lenth sz (sz!=-1) to the SPRAAK stream fd.

Returns
the number of characters written on success and (-1) on failure.
const char* spr_extern_keyset_iter ( void *  fd,
int *  ndx,
const char **  val 
)

Iterate over all keys in the keyset of SPRAAK stream fd. The function returns the key. The value is returned in *val. ndx is the iterator.

Example code:

int ndx = 0;
char *key,*val;
while((key=spr_extern_keyset_iter(fd,&ndx,&val)) != NULL)
{// do something
...
}
Returns
the key or NULL when all keys were handled; in the latter case, *val is not set.
int spr_extern_keyset_decode ( void *  fd,
ssize_t *  dim1,
ssize_t *  dim2,
ssize_t *  el_sz,
const char **  el_desc,
const char **  layout,
int *  Nkeys 
)

Decode the main keys from the keyset of SPRAAK stream fd. The string returned in *layout indicates the main layout of the data (LIST, MATRIX, CUSTOM); See The standard keys for more details. The values returned in *el_desc and *el_sz indicate the data type of the elements in the file; See datatype.c for more details. The values returned in *dim1 and *dim2 indicate the number of elements in the file; See The standard keys for more details. The number of keys in the keyset is returned in *Nkeys.

Note
any of the pointers dim1, dim2, el_sz, el_desc, layout or Nkeys may be NULL.
for sample files, dim1 and dim2 will contain the number of samples in a channel and the number of channels respectively.
Returns
0 on success, -1 on failure.
int spr_extern_stream_write ( void *  fd,
const void *  src,
ssize_t  Nel 
)

Write the Nel data elements located at address src and upwards to the open SPRAAK stream fd.

Returns
the number of elements written or -1 on failure.
int spr_extern_stream_close ( void *  fd)

Close an open SPRAAK stream.

Returns
0 on success, (-1) on failure (trailing data in the buffer could not be written back).
Note
fd may be NULL.