Synesis Software

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

/include/cstring/cstring.h File Reference


Detailed Description

Definition of the cstring API.

#include <stddef.h>

Go to the source code of this file.

Compounds

struct  cstring_t
 The cstring structure. More...


Defines

#define CSTRING_VER_MAJOR   3
 The major version number of cstring.

#define CSTRING_VER_MINOR   2
 The minor version number of cstring.

#define CSTRING_VER_REVISION   1
 The revision version number of cstring.

#define CSTRING_VER   0x03020100
 The current composite version number of cstring.

#define CSTRING_EXTERN_C   extern "C"
#define cstring_t_DEFAULT   { 0, NULL, 0, 0 }
 Default initialised value for a cstring_t instance.

#define CSTRING_F_TYPE_MASK   (0x003f)
#define CSTRING_F_MEMORY_IS_INTERNAL_HEAP   (0x0000)
#define CSTRING_F_MEMORY_IS_BORROWED   (0x0001)
#define CSTRING_F_MEMORY_IS_FIXED   (0x0002)
#define CSTRING_F_MEMORY_IS_READONLY   (0x0004)
#define CSTRING_F_MEMORY_IS_CONST   CSTRING_F_MEMORY_IS_READONLY
#define CSTRING_F_ARENA_MASK   (0xff00)
#define CSTRING_F_USE_REALLOC   (0x0000)
#define CSTRING_F_USE_WIN32_GLOBAL_MEMORY   (0x0100)
#define CSTRING_F_USE_WIN32_PROCESSHEAP_MEMORY   (0x0200)
#define CSTRING_F_USE_WIN32_COM_TASK_MEMORY   (0x0400)
#define CSTRING_F_USE_CUSTOMARENAFUNCTIONS   (0x2000)
#define CSTRING_F_CUSTOMARENA_CC_CDECL   (0x0000)
#define CSTRING_F_CUSTOMARENA_CC_STDCALL   (0x0040)

Typedefs

typedef enum CSTRING_RC CSTRING_RC
typedef cstring_t cstring_t

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
}
 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, size_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, size_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_yield (struct cstring_t *pcs, char **ppBuff)
 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_EXTERN_C   extern "C"
 

#define CSTRING_F_ARENA_MASK   (0xff00)
 

#define CSTRING_F_CUSTOMARENA_CC_CDECL   (0x0000)
 

Treats the externally supplied allocator function as having CDecl calling convention (de-)allocation (NOT CURRENTLY SUPPORTED)

#define CSTRING_F_CUSTOMARENA_CC_STDCALL   (0x0040)
 

Treats the externally supplied allocator function as having StdCall calling convention (de-)allocation (NOT CURRENTLY SUPPORTED)

#define CSTRING_F_MEMORY_IS_BORROWED   (0x0001)
 

Memory is supplied external to the API, and may not be deallocated, moved or expanded.

Note:
Implies CSTRING_F_MEMORY_IS_FIXED

#define CSTRING_F_MEMORY_IS_CONST   CSTRING_F_MEMORY_IS_READONLY
 

Equivalent to CSTRING_F_MEMORY_IS_READONLY

Deprecated:

#define CSTRING_F_MEMORY_IS_FIXED   (0x0002)
 

Memory is of fixed size, and any operation that requires expansion will fail

#define CSTRING_F_MEMORY_IS_INTERNAL_HEAP   (0x0000)
 

Memory is allocated by the heap function, and is owned by the cstring instance

#define CSTRING_F_MEMORY_IS_READONLY   (0x0004)
 

cstring instance may not be modified

#define CSTRING_F_TYPE_MASK   (0x003f)
 

#define CSTRING_F_USE_CUSTOMARENAFUNCTIONS   (0x2000)
 

Uses an externally supplied allocator function for all memory (de-)allocation (NOT CURRENTLY SUPPORTED)

#define CSTRING_F_USE_REALLOC   (0x0000)
 

Uses C standard library function realloc() for all memory (de-)allocation

#define CSTRING_F_USE_WIN32_COM_TASK_MEMORY   (0x0400)
 

Uses COM Task Allocator for all memory (de-)allocation (Windows only)

#define CSTRING_F_USE_WIN32_GLOBAL_MEMORY   (0x0100)
 

Uses Win32 Global Memory API for all memory (de-)allocation (Windows only)

#define CSTRING_F_USE_WIN32_PROCESSHEAP_MEMORY   (0x0200)
 

Uses Win32 Global Process Heap for all memory (de-)allocation (Windows only)

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

Default initialised value for a cstring_t instance.

#define CSTRING_VER   0x03020100
 

The current composite version number of cstring.

#define CSTRING_VER_MAJOR   3
 

The major version number of cstring.

#define CSTRING_VER_MINOR   2
 

The minor version number of cstring.

#define CSTRING_VER_REVISION   1
 

The revision version number of cstring.


Typedef Documentation

typedef enum CSTRING_RC CSTRING_RC
 

typedef struct cstring_t cstring_t
 


Enumeration Type Documentation

enum CSTRING_RC
 

The return code type of the cstring API.

Enumeration values:
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


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,
size_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,
size_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
Note:
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_yield struct cstring_t   pcs,
char **    ppBuff
 

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

Parameters:
pcs  the cstring instance whose buffer is to be retrieved
ppBuff  pointer to a buffer pointer which will receive the yielded buffer
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 Library documentation © Matthew Wilson and Synesis Software Pty Ltd, 1994-2005