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.