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

Default initialised value for a cstring_t instance.

Flags type.

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.
CSTRING_RC_ARENAOVERLOADED	cannot use arena parameter for both borrowed memory and custom arena
CSTRING_RC_INVALIDSTREAM	the stream handle is invalid
CSTRING_RC_EOF	reached the end of stream
CSTRING_RC_INVALIDSECTION	the given section is invalid
CSTRING_RC_IOERROR	an I/O error occurred

CSTRING_EXTERN_C 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_SUCCESS	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 instance is marked fixed (CSTRING_F_MEMORY_IS_FIXED)
	CSTRING_RC_EXCEEDBORROWEDCAPACITY	the cstring instance is marked borrowed (CSTRING_F_MEMORY_IS_BORROWED)
	CSTRING_RC_OUTOFMEMORY	insufficient memory to carry out the operation

CSTRING_EXTERN_C 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_SUCCESS	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 instance is marked fixed (CSTRING_F_MEMORY_IS_FIXED)
	CSTRING_RC_EXCEEDBORROWEDCAPACITY	the cstring instance is marked borrowed (CSTRING_F_MEMORY_IS_BORROWED)
	CSTRING_RC_OUTOFMEMORY	insufficient memory to carry out the operation

CSTRING_EXTERN_C 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_SUCCESS	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 instance is marked fixed (CSTRING_F_MEMORY_IS_FIXED)
	CSTRING_RC_EXCEEDBORROWEDCAPACITY	the cstring instance 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_EXTERN_C 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_SUCCESS	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 instance is marked fixed (CSTRING_F_MEMORY_IS_FIXED)
	CSTRING_RC_EXCEEDBORROWEDCAPACITY	the cstring instance is marked borrowed (CSTRING_F_MEMORY_IS_BORROWED)
	CSTRING_RC_OUTOFMEMORY	insufficient memory to carry out the operation

CSTRING_EXTERN_C 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_SUCCESS	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 instance is marked fixed (CSTRING_F_MEMORY_IS_FIXED)
	CSTRING_RC_EXCEEDBORROWEDCAPACITY	the cstring instance is marked borrowed (CSTRING_F_MEMORY_IS_BORROWED)
	CSTRING_RC_OUTOFMEMORY	insufficient memory to carry out the operation

CSTRING_EXTERN_C 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_SUCCESS	the capacity was adjusted
	CSTRING_RC_OUTOFMEMORY	insufficient memory to carry out the operation

CSTRING_EXTERN_C 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_SUCCESS	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_EXTERN_C 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_SUCCESS	the capacity was adjusted
	CSTRING_RC_OUTOFMEMORY	insufficient memory to carry out the operation

CSTRING_EXTERN_C 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_SUCCESS	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_EXTERN_C CSTRING_RC cstring_createN	(	struct cstring_t *	pcs,
		char	ch,
		size_t	n
	)

Creates a cstring instance consisting of a number of repetitions of a character.

Parameters:

	pcs	The uninitialised cstring instance to be created
	ch	The character to be repeated
	n	The number of repetitions of character `c`

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

Return values:

	CSTRING_RC_SUCCESS	the capacity was adjusted
	CSTRING_RC_OUTOFMEMORY	insufficient memory to carry out the operation

CSTRING_EXTERN_C 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_SUCCESS

the capacity was destroyed

CSTRING_EXTERN_C char const* cstring_getStatusCodeString ( 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_EXTERN_C 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_EXTERN_C 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_SUCCESS	the capacity was adjusted
	CSTRING_RC_READONLY	the cstring instance is marked readonly (CSTRING_F_MEMORY_IS_READONLY)
	CSTRING_RC_EXCEEDFIXEDCAPACITY	the cstring instance is marked fixed (CSTRING_F_MEMORY_IS_FIXED)
	CSTRING_RC_EXCEEDBORROWEDCAPACITY	the cstring instance is marked borrowed (CSTRING_F_MEMORY_IS_BORROWED)
	CSTRING_RC_OUTOFMEMORY	insufficient memory to carry out the operation

CSTRING_EXTERN_C 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_SUCCESS	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_EXTERN_C 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_SUCCESS	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_EXTERN_C 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_SUCCESS	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 API

Detailed Description

Modules

Classes

Defines

Typedefs

Enumerations

Functions

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation


Modules
	Function Control Flags
	These flags control the behaviour of the various functions in the library.
Classes
struct	cstring_t
	The cstring structure. More...
Defines
#define	cstring_t_DEFAULT { 0, NULL, 0, 0 }
	Default initialised value for a cstring_t instance.
Typedefs
typedef int	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, CSTRING_RC_ARENAOVERLOADED, CSTRING_RC_INVALIDSTREAM, CSTRING_RC_EOF, CSTRING_RC_INVALIDSECTION, CSTRING_RC_IOERROR }
	The return code type of the cstring API. More...
Functions
CSTRING_EXTERN_C char const *	cstring_getStatusCodeString (CSTRING_RC rc)
	Returns a non-NULL nul-terminated character string describing the given error code.
CSTRING_EXTERN_C CSTRING_RC	cstring_init (struct cstring_t *pcs)
	Initialises a cstring instance to a default form.
CSTRING_EXTERN_C CSTRING_RC	cstring_create (struct cstring_t pcs, char const s)
	Creates a cstring instance from a C-style string.
CSTRING_EXTERN_C 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_EXTERN_C CSTRING_RC	cstring_createN (struct cstring_t *pcs, char ch, size_t n)
	Creates a cstring instance consisting of a number of repetitions of a character.
CSTRING_EXTERN_C 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_EXTERN_C 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_EXTERN_C CSTRING_RC	cstring_destroy (struct cstring_t *pcs)
	Releases resources and resets the attributes of the cstring instance.
CSTRING_EXTERN_C 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_EXTERN_C CSTRING_RC	cstring_setCapacity (struct cstring_t *pcs, size_t capacity)
	Sets the capacity of the cstring instance.
CSTRING_EXTERN_C CSTRING_RC	cstring_assign (struct cstring_t pcs, char const s)
	Assigns a C-style string to the cstring instance.
CSTRING_EXTERN_C 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_EXTERN_C CSTRING_RC	cstring_copy (struct cstring_t pcs, struct cstring_t const pcsSrc)
	Copies the contents of one cstring instance to another.
CSTRING_EXTERN_C CSTRING_RC	cstring_append (struct cstring_t pcs, char const s)
	Appends a C-style string to the cstring instance.
CSTRING_EXTERN_C 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_EXTERN_C CSTRING_RC	cstring_truncate (struct cstring_t *pcs, size_t len)
	Truncates the cstring instance.
CSTRING_EXTERN_C CSTRING_RC	cstring_swap (struct cstring_t pcs1, struct cstring_t pcs2)
	Swaps the contents of the two cstring instances.