s2data.h File Reference

The 'data' type for holding arbitrary data. More...

#include "s2obj.h"

Macros
#define	s2_is_data(obj)

Typedefs
typedef T	s2data_t
	the working context for the 'data' type s2data_t. In the following prose, s2data_t will be abbreviated as T.

Functions
T *	s2data_create (size_t len)
T *	s2data_from_str (const char *s)
size_t	s2data_len (T *restrict ctx)
void *	s2data_map (T *restrict ctx, size_t offset, size_t len)
int	s2data_unmap (T *restrict ctx)
void *	s2data_weakmap (T *restrict ctx)
int	s2data_trunc (T *restrict ctx, size_t len)
int	s2data_cmp (T *restrict s1, T *restrict s2)
	byte-collation total order,
int	s2data_putc (T *restrict ctx, int c)
	adds a byte to the accumulation staging area.
int	s2data_puts (T *restrict ctx, void const *str, size_t len)
	adds a string of bytes to the accumulation staging area.
int	s2data_putfin (T *restrict ctx)
	flush bytes in the staging area into the internal buffer.

Detailed Description

The 'data' type for holding arbitrary data.

Macro Definition Documentation

s2_is_data

#define s2_is_data

(

obj

)

Value:

((((s2obj_t *)obj)->type & 0x3000) == 0x0000)

Parameters

obj	the object handle the type of which is being checked.

Returns

true if the object handle of 'data' type, false otherwise.

Typedef Documentation

s2data_t

typedef T s2data_t

the working context for the 'data' type s2data_t. In the following prose, s2data_t will be abbreviated as T.

The design goal has been to make it easy to access datum within the address range of the underlaying buffer, and to safely resize the buffer when needed.

Function Documentation

s2data_cmp()

int s2data_cmp	(	T *restrict	s1,
		T *restrict	s2 )

byte-collation total order,

Parameters

s1	the first 'data' object.
s2	the second 'data' object.

Returns

-1 if s1 is ordered before s2, 1 if after, and 0 if they're same. if one of them is a prefix of the other, the shorter one orders before the longer one.

s2data_create()

T * s2data_create

(

size_t

len

)

Parameters

len	the initial length of the created 'data' handle.

Returns

the s2data_t * object handle. NULL is returned on failure.

s2data_from_str()

T * s2data_from_str

(

const char *

s

)

Parameters

s	a nul-terminated string.

Returns

the s2data_t * object handle. NULL is returned on failure.

s2data_len()

size_t s2data_len

(

T *restrict

ctx

)

Parameters

ctx	the handle to the 'data' object whose length is queried.

Returns

the length in bytes of the 'data' object.

s2data_map()

void * s2data_map	(	T *restrict	ctx,
		size_t	offset,
		size_t	len )

Parameters

ctx	the handle to the 'data' object where a map is requested.
offset	the offset from the beginning of the buffer of the request.
len	the requested length of the map.

Returns

a pointer to the requested map range.

The function does a simple range check - if it passes, a pointer at appropriate offset is returned, otherwise, a NULL pointer is returned.

The function doesn't record the regions requested - it only keeps a number, which is checked by s2data_trunc.

[2024-03-06-nul-term]: In the version suchly labelled, it is safe to pass the entire mapped pointer to functions that expect nul-terminated strings, as the implementation internally adds an extra nul byte just one byte beyond the effective length of the buffer.

Note

The implementation allocates a buffer in addition to the s2data_t context working data structure to hold the actual data. In versions after 2024-09-11, when the requested buffer size is small (less than or equal to 19 bytes), the data is held "inline" in the context working data structure to save the additional allocation of the buffer to save heap space, and to accelerate processing of small datum.

s2data_putc()

int s2data_putc	(	T *restrict	ctx,
		int	c )

adds a byte to the accumulation staging area.

Parameters

ctx	the 'data' object handle to put the byte.
c	the value of the byte to put.

Returns

0 on success and -1 on failure.

s2data_putfin()

int s2data_putfin

(

T *restrict

ctx

)

flush bytes in the staging area into the internal buffer.

Parameters

ctx	the 'data' object handle to flush.

Returns

0 on success and -1 on failure.

s2data_puts()

int s2data_puts	(	T *restrict	ctx,
		void const *	str,
		size_t	len )

adds a string of bytes to the accumulation staging area.

Parameters

ctx	the 'data' object handle to put the bytes.
str	the byte string to put.
len	the number of bytes in the string.

Returns

0 on success and -1 on failure.

The function is defined in terms of s2data_putc, this means that the user don't have to call s2data_putfin before calling this function, but does have to call it afterwards. This function has no atomicity guarantee - if error occur during putting, the actual number of bytes put may be less than len.

s2data_trunc()

int s2data_trunc	(	T *restrict	ctx,
		size_t	len )

Parameters

ctx	the handle to the 'data' object to which the length is changed.
len	len the requested new length of the 'data' object.

Returns

0 on success, and -1 on error.

If there's someone mapping the data (i.e. more s2data_map than s2data_unmap), then this function returns -1; it also returns -1 when the memory reallocation fails. Otherwise, the internal buffer is resized. Contrary to what the name suggests, expansion is also possible, and this is in fact a resize operation (it internally invokes realloc).

s2data_unmap()

int s2data_unmap

(

T *restrict

ctx

)

Parameters

ctx	the handle to the 'data' object where a map was requested.

Returns

0 on success, see below.

The function decreases what's increased by s2data_map. The numbers of s2data_map and s2data_unmap should match. Currently there's no error defined, and 0 is returned.

s2data_weakmap()

void * s2data_weakmap

(

T *restrict

ctx

)

Parameters

ctx	the handle to the 'data' object.

Added 2025-01-04. Request a transient map from the beginning of the 'data' object. The caller shall ensure no resize or simultaneous modification occur, as otherwise will result in undefined behavior.