cstring API

Detailed Description

The cstring Public API.

The types, constants and functions that constitute the cstring API.

Modules

Function Control Flags

These flags control the behaviour of the various functions in the library.

Classes

struct cstring_t

The cstring structure
Represents a cstring as a string slice - length + pointer - along with the allocated capacity, and flags controlling the allocation arena and other characteristics. More...

Defines

#define cstring_t_DEFAULT   { 0, NULL, 0, 0 }

Default initialised value for a cstring_t instance.

Typedefs

typedef size_t cstring_flags_t

Flags type.

Enumerations

enum CSTRING_RC {
  CSTRING_RC_SUCCESS = 0,
  CSTRING_RC_OUTOFMEMORY,
  CSTRING_RC_FIXED,
  CSTRING_RC_BORROWED,
  CSTRING_RC_READONLY,
  CSTRING_RC_INVALIDARENA,
  CSTRING_RC_CUSTOMARENANOTSUPPORTED,
  CSTRING_RC_EXCEEDFIXEDCAPACITY,
  CSTRING_RC_EXCEEDBORROWEDCAPACITY,
  CSTRING_RC_CANNOTYIELDFROMSO
}

The return code type of the cstring API. More...

Functions

char const * cstring_error (CSTRING_RC rc)

Returns a non-NULL nul-terminated character string describing the given error code.

CSTRING_RC cstring_init (struct cstring_t *pcs)

Initialises a cstring instance to a default form.

CSTRING_RC cstring_create (struct cstring_t *pcs, char const *s)

Creates a cstring instance from a C-style string.

CSTRING_RC cstring_createLen (struct cstring_t *pcs, char const *s, size_t cch)

Creates a cstring instance from a fixed number of characters.

CSTRING_RC cstring_createEx (struct cstring_t *pcs, char const *s, cstring_flags_t flags, void *arena, size_t capacity)

Creates a cstring instance with special characteristics from a C-style string.

CSTRING_RC cstring_createLenEx (struct cstring_t *pcs, char const *s, size_t cch, cstring_flags_t flags, void *arena, size_t capacity)

Creates a cstring instance with special characteristics from a fixed number of characters.

CSTRING_RC cstring_destroy (struct cstring_t *pcs)

Releases resources and resets the attributes of the cstring instance.

CSTRING_RC cstring_yield2 (struct cstring_t *pcs, char **pPayload, void **pRaw)

Removes the allocated buffer from the cstring instance into a caller supplied pointer.

CSTRING_RC cstring_setCapacity (struct cstring_t *pcs, size_t capacity)

Sets the capacity of the cstring instance.

CSTRING_RC cstring_assign (struct cstring_t *pcs, char const *s)

Assigns a C-style string to the cstring instance.

CSTRING_RC cstring_assignLen (struct cstring_t *pcs, char const *s, size_t cch)

Assigns a fixed number of characters to the cstring instance.

CSTRING_RC cstring_copy (struct cstring_t *pcs, struct cstring_t const *pcsSrc)

Copies the contents of one cstring instance to another.

CSTRING_RC cstring_append (struct cstring_t *pcs, char const *s)

Appends a C-style string to the cstring instance.

CSTRING_RC cstring_appendLen (struct cstring_t *pcs, char const *s, size_t cch)

Appends a fixed number of characters to the cstring instance.

CSTRING_RC cstring_truncate (struct cstring_t *pcs, size_t len)

Truncates the cstring instance.

CSTRING_RC cstring_swap (struct cstring_t *pcs1, struct cstring_t *pcs2)

Swaps the contents of the two cstring instances.

Define Documentation

#define cstring_t_DEFAULT { 0, NULL, 0, 0 }

Default initialised value for a cstring_t instance.

Typedef Documentation

typedef size_t cstring_flags_t

Flags type.

Enumeration Type Documentation

enum CSTRING_RC

The return code type of the cstring API.

Enumerator:

CSTRING_RC_SUCCESS Operation completed successfully

CSTRING_RC_OUTOFMEMORY Out of memory

CSTRING_RC_FIXED Operation cannot procede because the cstring has fixed capacity

CSTRING_RC_BORROWED Operation cannot procede because the cstring is borrowed

CSTRING_RC_READONLY Operation cannot procede because the cstring is readonly

CSTRING_RC_INVALIDARENA Invalid arena

CSTRING_RC_CUSTOMARENANOTSUPPORTED Custom arena functionality not currently supported

CSTRING_RC_EXCEEDFIXEDCAPACITY Operation cannot procede because the current capacity would be exceeded and the cstring has fixed capacity

CSTRING_RC_EXCEEDBORROWEDCAPACITY Operation cannot procede because the current capacity would be exceeded and the cstring is borrowed

CSTRING_RC_CANNOTYIELDFROMSO Yield operation from a dynamic-library version of cstring was not allowed.

Function Documentation

CSTRING_RC cstring_append ( struct cstring_t * pcs,

char const * s

)

Appends a C-style string to the cstring instance.

Parameters:

pcs The cstring to append to

s Pointer to the C-style string to append. May be NULL

Return values:

CSTRING_RC_OK the requested number of bytes were appended to the cstring

CSTRING_RC_READONLY the cstring instance is marked readonly (CSTRING_F_MEMORY_IS_READONLY)

CSTRING_RC_EXCEEDFIXEDCAPACITY the cstring instances is marked fixed (CSTRING_F_MEMORY_IS_FIXED)

CSTRING_RC_EXCEEDBORROWEDCAPACITY the cstring instances is marked borrowed (CSTRING_F_MEMORY_IS_BORROWED)

CSTRING_RC_OUTOFMEMORY insufficient memory to carry out the operation

CSTRING_RC cstring_appendLen ( struct cstring_t * pcs,

char const * s,

size_t cch

)

Appends a fixed number of characters to the cstring instance.

Parameters:

pcs The cstring to append to

s Pointer to the first character in the array from which to append. Must not be NULL, unless cch is 0

cch The number of characters to append

Note:
If the source has embedded nul characters, they will be incorporated into the cstring contents, which means that calling strlen() on the payload pointer may give inconsistent results

Return values:

CSTRING_RC_OK the requested number of bytes were appended to the cstring

CSTRING_RC_READONLY the cstring instance is marked readonly (CSTRING_F_MEMORY_IS_READONLY)

CSTRING_RC_EXCEEDFIXEDCAPACITY the cstring instances is marked fixed (CSTRING_F_MEMORY_IS_FIXED)

CSTRING_RC_EXCEEDBORROWEDCAPACITY the cstring instances is marked borrowed (CSTRING_F_MEMORY_IS_BORROWED)

CSTRING_RC_OUTOFMEMORY insufficient memory to carry out the operation

CSTRING_RC cstring_assign ( struct cstring_t * pcs,

char const * s

)

Assigns a C-style string to the cstring instance.

Parameters:

pcs The cstring to assign to

s Pointer to the C-style string to assign. May be NULL

Return values:

CSTRING_RC_OK the requested number of bytes were assigned to the cstring

CSTRING_RC_READONLY the cstring instance is marked readonly (CSTRING_F_MEMORY_IS_READONLY)

CSTRING_RC_EXCEEDFIXEDCAPACITY the cstring instances is marked fixed (CSTRING_F_MEMORY_IS_FIXED)

CSTRING_RC_EXCEEDBORROWEDCAPACITY the cstring instances is marked borrowed (CSTRING_F_MEMORY_IS_BORROWED)

CSTRING_RC_OUTOFMEMORY insufficient memory to carry out the operation

Note:
The function is safe with respect to 'self-assignment', i.e, s can refer to (part of) the payload of pcs, and the function will still operate correctly to produce the logically desired result.

CSTRING_RC cstring_assignLen ( struct cstring_t * pcs,

char const * s,

size_t cch

)

Assigns a fixed number of characters to the cstring instance.

Parameters:

pcs The cstring to assign to

s Pointer to the first character in the array from which to assign. Must not be NULL, unless cch is 0

cch The number of characters to assign

Note:
If the source has embedded nul characters, they will be incorporated into the cstring contents, which means that calling strlen() on the payload pointer may give inconsistent results

Return values:

CSTRING_RC_OK the requested number of bytes were assigned to the cstring

CSTRING_RC_READONLY the cstring instance is marked readonly (CSTRING_F_MEMORY_IS_READONLY)

CSTRING_RC_EXCEEDFIXEDCAPACITY the cstring instances is marked fixed (CSTRING_F_MEMORY_IS_FIXED)

CSTRING_RC_EXCEEDBORROWEDCAPACITY the cstring instances is marked borrowed (CSTRING_F_MEMORY_IS_BORROWED)

CSTRING_RC_OUTOFMEMORY insufficient memory to carry out the operation

CSTRING_RC cstring_copy ( struct cstring_t * pcs,

struct cstring_t const * pcsSrc

)

Copies the contents of one cstring instance to another.

Parameters:

pcs The cstring to assign to

pcsSrc The cstring whose contents will be copied

Return values:

CSTRING_RC_OK the requested number of bytes were copied to the cstring

CSTRING_RC_READONLY the cstring instance is marked readonly (CSTRING_F_MEMORY_IS_READONLY)

CSTRING_RC_EXCEEDFIXEDCAPACITY the cstring instances is marked fixed (CSTRING_F_MEMORY_IS_FIXED)

CSTRING_RC_EXCEEDBORROWEDCAPACITY the cstring instances is marked borrowed (CSTRING_F_MEMORY_IS_BORROWED)

CSTRING_RC_OUTOFMEMORY insufficient memory to carry out the operation

CSTRING_RC cstring_create ( struct cstring_t * pcs,

char const * s

)

Creates a cstring instance from a C-style string.

Parameters:

pcs The uninitialised cstring instance to be created

s Pointer to the C-style string to copy. May be NULL

Note:
This must only be called on an uninitialised cstring instance

Return values:

CSTRING_RC_OK the capacity was adjusted

CSTRING_RC_OUTOFMEMORY insufficient memory to carry out the operation

CSTRING_RC cstring_createEx ( struct cstring_t * pcs,

char const * s,

cstring_flags_t flags,

void * arena,

size_t capacity

)

Creates a cstring instance with special characteristics from a C-style string.

Parameters:

pcs The uninitialised cstring instance to be created

s Pointer to the C-style string to copy. May be NULL

flags The flags defining the characteristics of the cstring instance

arena The memory buffer for borrowed (CSTRING_F_MEMORY_IS_BORROWED), or a pointer to a custom memory arena. Note that custom memory arenas are not currently supported, and this parameter must be NULL unless the flag CSTRING_F_MEMORY_IS_BORROWED is specified

capacity The capacity of the buffer specified in arena, or otherwise ignored

Note:
This must only be called on an uninitialised cstring instance

Return values:

CSTRING_RC_OK the capacity was adjusted

CSTRING_RC_OUTOFMEMORY insufficient memory to carry out the operation

CSTRING_RC_INVALIDARENA an invalid arena specification was given in the flags parameter

CSTRING_RC_CUSTOMARENANOTSUPPORTED A custom arena was specified, which is not yet supported

CSTRING_RC cstring_createLen ( struct cstring_t * pcs,

char const * s,

size_t cch

)

Creates a cstring instance from a fixed number of characters.

Parameters:

pcs The uninitialised cstring instance to be created

s Pointer to the first character in the array from which to copy. Must not be NULL, unless cch is 0

cch The number of characters to be copied into the cstring instance

Note:
This must only be called on an uninitialised cstring instance

Return values:

CSTRING_RC_OK the capacity was adjusted

CSTRING_RC_OUTOFMEMORY insufficient memory to carry out the operation

CSTRING_RC cstring_createLenEx ( struct cstring_t * pcs,

char const * s,

size_t cch,

cstring_flags_t flags,

void * arena,

size_t capacity

)

Creates a cstring instance with special characteristics from a fixed number of characters.

Parameters:

pcs The uninitialised cstring instance to be created

s Pointer to the first character in the array from which to copy. Must not be NULL, unless cch is 0

cch The number of characters to be copied into the cstring instance

flags The flags defining the characteristics of the cstring instance

arena The memory buffer for borrowed (CSTRING_F_MEMORY_IS_BORROWED), or a pointer to a custom memory arena. Note that custom memory arenas are not currently supported, and this parameter must be NULL unless the flag CSTRING_F_MEMORY_IS_BORROWED is specified

capacity The capacity of the buffer specified in arena, or otherwise ignored

Note:
This must only be called on an uninitialised cstring instance

Return values:

CSTRING_RC_OK the capacity was adjusted

CSTRING_RC_OUTOFMEMORY insufficient memory to carry out the operation

CSTRING_RC_INVALIDARENA an invalid arena specification was given in the flags parameter

CSTRING_RC_CUSTOMARENANOTSUPPORTED A custom arena was specified, which is not yet supported

CSTRING_RC cstring_destroy ( struct cstring_t * pcs )

Releases resources and resets the attributes of the cstring instance.

Parameters:

pcs The cstring instance to be destroyed

Note:
This must only be called on an initialised cstring instance, which is then rendered in the uninitialised state.

Return values:

CSTRING_RC_OK the capacity was destroyed

char const* cstring_error ( CSTRING_RC rc )

Returns a non-NULL nul-terminated character string describing the given error code.

Parameters:

rc The error code. Must be one of the CSTRING_RC enumeration

Returns:
A non-NULL nul-terminated string

CSTRING_RC cstring_init ( struct cstring_t * pcs )

Initialises a cstring instance to a default form.

Note:
This must only be called on an uninitialised cstring instance
This is equivalent to assigning an instance from cstring_t_DEFAULT.

CSTRING_RC cstring_setCapacity ( struct cstring_t * pcs,

size_t capacity

)

Sets the capacity of the cstring instance.

Parameters:

pcs The cstring instance to be adjusted

capacity The capacity to which the cstring instance should be adjusted

Note:
If the specified capacity would cause the string contents to be truncated, the value is adjusted to the minimum possible without requiring truncation.

Return values:

CSTRING_RC_OK the capacity was adjusted

CSTRING_RC_READONLY the cstring instance is marked readonly (CSTRING_F_MEMORY_IS_READONLY)

CSTRING_RC_EXCEEDFIXEDCAPACITY the cstring instances is marked fixed (CSTRING_F_MEMORY_IS_FIXED)

CSTRING_RC_EXCEEDBORROWEDCAPACITY the cstring instances is marked borrowed (CSTRING_F_MEMORY_IS_BORROWED)

CSTRING_RC_OUTOFMEMORY insufficient memory to carry out the operation

CSTRING_RC cstring_swap ( struct cstring_t * pcs1,

struct cstring_t * pcs2

)

Swaps the contents of the two cstring instances.

Parameters:

pcs1 the cstring instance whose contents will be swapped with pcs2

pcs2 the cstring instance whose contents will be swapped with pcs1

Note:
Neither instance can be either readonly or fixed-and-borrowed

Return values:

CSTRING_RC_OK string instance contents were swapped

CSTRING_RC_READONLY one or both instances are marked readonly (CSTRING_F_MEMORY_IS_READONLY)

CSTRING_RC_BORROWED one or both instances are marked fixed (CSTRING_F_MEMORY_IS_BORROWED)

CSTRING_RC cstring_truncate ( struct cstring_t * pcs,

size_t len

)

Truncates the cstring instance.

Parameters:

pcs The cstring to truncate

len The required length. Ignored if not less than the current length

Note:
The cstring instance must not be readonly

Return values:

CSTRING_RC_OK cstring instance contents were truncated (or the truncation length was out of bounds)

CSTRING_RC_READONLY the cstring instance is marked readonly (CSTRING_F_MEMORY_IS_READONLY)

CSTRING_RC cstring_yield2 ( struct cstring_t * pcs,

char ** pPayload,

void ** pRaw

)

Removes the allocated buffer from the cstring instance into a caller supplied pointer.

Parameters:

pcs the cstring instance whose buffer is to be retrieved. May not be NULL.

pRaw pointer to a buffer pointer which will receive the yielded raw memory. May not be NULL. May not be equal to pPayload.

pPayload pointer to a buffer pointer which will receive the yielded payload. May not be NULL. May not be equal to pRaw.

Note:
The values of *pRaw and *pPayload may not be equal

Return values:

CSTRING_RC_OK the buffer was yielded

CSTRING_RC_READONLY the cstring instance is marked readonly (CSTRING_F_MEMORY_IS_READONLY)

CSTRING_RC_BORROWED the cstring instance is marked fixed (CSTRING_F_MEMORY_IS_BORROWED)

CSTRING_RC_CANNOTYIELDFROMSO the cstring instance uses realloc() in a Win32 dynamic library

Note:
When linked to cstring as a Win32 dynamic library, this function will not work for strings allocated via realloc()

cstring Library documentation � Matthew Wilson and Synesis Software Pty Ltd, 1994-2005


Modules
	Function Control Flags
	These flags control the behaviour of the various functions in the library.
Classes
struct	cstring_t
	The cstring structure Represents a cstring as a string slice - length + pointer - along with the allocated capacity, and flags controlling the allocation arena and other characteristics. More...
Defines
#define	cstring_t_DEFAULT { 0, NULL, 0, 0 }
	Default initialised value for a cstring_t instance.
Typedefs
typedef size_t	cstring_flags_t
	Flags type.
Enumerations
enum	CSTRING_RC { CSTRING_RC_SUCCESS = 0, CSTRING_RC_OUTOFMEMORY, CSTRING_RC_FIXED, CSTRING_RC_BORROWED, CSTRING_RC_READONLY, CSTRING_RC_INVALIDARENA, CSTRING_RC_CUSTOMARENANOTSUPPORTED, CSTRING_RC_EXCEEDFIXEDCAPACITY, CSTRING_RC_EXCEEDBORROWEDCAPACITY, CSTRING_RC_CANNOTYIELDFROMSO }
	The return code type of the cstring API. More...
Functions
char const *	cstring_error (CSTRING_RC rc)
	Returns a non-NULL nul-terminated character string describing the given error code.
CSTRING_RC	cstring_init (struct cstring_t *pcs)
	Initialises a cstring instance to a default form.
CSTRING_RC	cstring_create (struct cstring_t pcs, char const s)
	Creates a cstring instance from a C-style string.
CSTRING_RC	cstring_createLen (struct cstring_t pcs, char const s, size_t cch)
	Creates a cstring instance from a fixed number of characters.
CSTRING_RC	cstring_createEx (struct cstring_t pcs, char const s, cstring_flags_t flags, void *arena, size_t capacity)
	Creates a cstring instance with special characteristics from a C-style string.
CSTRING_RC	cstring_createLenEx (struct cstring_t pcs, char const s, size_t cch, cstring_flags_t flags, void *arena, size_t capacity)
	Creates a cstring instance with special characteristics from a fixed number of characters.
CSTRING_RC	cstring_destroy (struct cstring_t *pcs)
	Releases resources and resets the attributes of the cstring instance.
CSTRING_RC	cstring_yield2 (struct cstring_t pcs, char pPayload, void *pRaw)
	Removes the allocated buffer from the cstring instance into a caller supplied pointer.
CSTRING_RC	cstring_setCapacity (struct cstring_t *pcs, size_t capacity)
	Sets the capacity of the cstring instance.
CSTRING_RC	cstring_assign (struct cstring_t pcs, char const s)
	Assigns a C-style string to the cstring instance.
CSTRING_RC	cstring_assignLen (struct cstring_t pcs, char const s, size_t cch)
	Assigns a fixed number of characters to the cstring instance.
CSTRING_RC	cstring_copy (struct cstring_t pcs, struct cstring_t const pcsSrc)
	Copies the contents of one cstring instance to another.
CSTRING_RC	cstring_append (struct cstring_t pcs, char const s)
	Appends a C-style string to the cstring instance.
CSTRING_RC	cstring_appendLen (struct cstring_t pcs, char const s, size_t cch)
	Appends a fixed number of characters to the cstring instance.
CSTRING_RC	cstring_truncate (struct cstring_t *pcs, size_t len)
	Truncates the cstring instance.
CSTRING_RC	cstring_swap (struct cstring_t pcs1, struct cstring_t pcs2)
	Swaps the contents of the two cstring instances.