Synesis Software

Main Page   Modules   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

H:/freelibs/cstring/3.4.x/src/cstring.c File Reference


Detailed Description

The implementation of the cstring API.

#include <cstring/cstring.h>
#include <assert.h>
#include <stdlib.h>
#include <string.h>

Defines

#define CSTRING_ALLOC_GRANULARITY   (8)
#define CSTRING_OFFSET_SIZE   (16)
#define cstring_assert(expr)   assert(expr)

Typedefs

typedef int(* PfnAllocFailHandler )(void *pv, size_t cb, cstring_flags_t flags, void *param)

Functions

CSTRING_EXTERN_C CSTRING_RC cstring_apiInit (void)
CSTRING_EXTERN_C void cstring_apiUninit (void)
CSTRING_EXTERN_C char const * cstring_error (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 len)
 Creates a cstring instance from a fixed number of characters.

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 len, 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_createLenFn (struct cstring_t *pcs, char const *s, size_t len, cstring_flags_t flags, void *arena, size_t capacity, void *pfnAllocFailHandler, void *param)
 This is an experimental feature.

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_yield (struct cstring_t *pcs, char **ppBuff)
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_setCapacityFn (struct cstring_t *pcs, size_t capacity, void *pfnAllocFailHandler, void *param)
 This is an experimental feature.

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_assignFn (struct cstring_t *pcs, char const *s, void *pfnAllocFailHandler, void *param)
 This is an experimental feature.

CSTRING_EXTERN_C CSTRING_RC cstring_assignLen (struct cstring_t *pcs, char const *s, size_t len)
 Assigns a fixed number of characters to the cstring instance.

CSTRING_EXTERN_C CSTRING_RC cstring_assignLenFn (struct cstring_t *pcs, char const *s, size_t len, void *pfnAllocFailHandler, void *param)
 This is an experimental feature.

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_appendFn (struct cstring_t *pcs, char const *s, void *pfnAllocFailHandler, void *param)
 This is an experimental feature.

CSTRING_EXTERN_C CSTRING_RC cstring_appendLen (struct cstring_t *pcs, char const *s, size_t len)
 Appends a fixed number of characters to the cstring instance.

CSTRING_EXTERN_C CSTRING_RC cstring_appendLenFn (struct cstring_t *pcs, char const *s, size_t len, void *pfnAllocFailHandler, void *param)
 This is an experimental feature.

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.


Define Documentation

#define CSTRING_ALLOC_GRANULARITY   (8)
 

#define cstring_assert expr       assert(expr)
 

#define CSTRING_OFFSET_SIZE   (16)
 


Typedef Documentation

typedef int(* PfnAllocFailHandler)(void *pv, size_t cb, cstring_flags_t flags, void *param)
 


Function Documentation

CSTRING_EXTERN_C CSTRING_RC cstring_apiInit void   
 

CSTRING_EXTERN_C void cstring_apiUninit void   
 

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_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_EXTERN_C CSTRING_RC cstring_appendFn struct cstring_t   pcs,
char const *    s,
void *    pfnAllocFailHandler,
void *    param
 

This is an experimental feature.

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_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_EXTERN_C CSTRING_RC cstring_appendLenFn struct cstring_t   pcs,
char const *    s,
size_t    len,
void *    pfnAllocFailHandler,
void *    param
 

This is an experimental feature.

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_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_EXTERN_C CSTRING_RC cstring_assignFn struct cstring_t   pcs,
char const *    s,
void *    pfnAllocFailHandler,
void *    param
 

This is an experimental feature.

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_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_EXTERN_C CSTRING_RC cstring_assignLenFn struct cstring_t   pcs,
char const *    s,
size_t    len,
void *    pfnAllocFailHandler,
void *    param
 

This is an experimental feature.

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_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_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_OK  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_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_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_OK  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_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_EXTERN_C CSTRING_RC cstring_createLenFn struct cstring_t   pcs,
char const *    s,
size_t    len,
cstring_flags_t    flags,
void *    arena,
size_t    capacity,
void *    pfnAllocFailHandler,
void *    param
 

This is an experimental feature.

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_OK  the capacity was destroyed

CSTRING_EXTERN_C 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_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
Note:
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_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_EXTERN_C CSTRING_RC cstring_setCapacityFn struct cstring_t   pcs,
size_t    capacity,
void *    pfnAllocFailHandler,
void *    param
 

This is an experimental feature.

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_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_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_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_EXTERN_C CSTRING_RC cstring_yield struct cstring_t   pcs,
char **    ppBuff
 

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_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