string.h File Reference

Interface for operating on a sequence of characters. More...

#include <FACE/types.h>
#include <limits.h>
#include "FACE/sequence.h"

Data Structures
struct	FACE_string
	Interface for operating on a sequence of characters. More...

Macros
#define	FACE_STRING_UNBOUNDED_SENTINEL   UINT_MAX
	Value representing the bound of an unbounded FACE_string.

Typedefs
typedef enum FACE_string_return	FACE_string_return
	Return codes used to report certain runtime errors.

Enumerations
enum	FACE_string_return {   FACE_STRING_NO_ERROR, FACE_STRING_INSUFFICIENT_BOUND, FACE_STRING_INSUFFICIENT_MEMORY, FACE_STRING_PRECONDITION_VIOLATED,   FACE_STRING_NULL_THIS, FACE_STRING_NULL_PARAM, FACE_STRING_INVALID_PARAM }
	Return codes used to report certain runtime errors. More...

Functions
FACE_string_return	FACE_string_init_unmanaged_cstring (FACE_string *this_obj, const char *src)
	Unmanaged initialization from a C-string literal.
FACE_string_return	FACE_string_init_managed_unbounded (FACE_string *this_obj)
	Managed unbounded initialization - initializes empty managed unbounded FACE_string.
FACE_string_return	FACE_string_init_managed_bounded (FACE_string *this_obj, FACE_unsigned_long bound)
	Managed bounded initialization - initializes empty managed FACE_string of specified bound.
FACE_string_return	FACE_string_init_managed_copy (FACE_string *this_obj, FACE_string *src)
	Managed copy initialization.
FACE_string_return	FACE_string_init_managed_cstring (FACE_string *this_obj, const char *cstr)
	Managed C-string initialization.
FACE_string_return	FACE_string_init_unmanaged (FACE_string *this_obj, char *src, FACE_unsigned_long length, FACE_unsigned_long bound)
	Unmanaged initialization.
FACE_string_return	FACE_string_free (FACE_string *this_obj)
	Frees any data managed by this_obj.
FACE_string_return	FACE_string_clear (FACE_string *this_obj)
	Clears this_obj's data.
FACE_string_return	FACE_string_append (FACE_string *this_obj, const FACE_string *src)
	Adds a copy of src's data to the this_obj's data.
FACE_string_return	FACE_string_append_elem (FACE_string *this_obj, const FACE_char elem)
	Adds a copy of elem to the this_obj's data.
FACE_string_return	FACE_string_reserve (FACE_string *this_obj, FACE_unsigned_long capacity)
	Attempt to reserve memory to store capacity characters.
const char *	FACE_string_at (const FACE_string *this_obj, FACE_unsigned_long index)
	Gets the character at a given index.
const char *	FACE_string_buffer (const FACE_string *this_obj)
	Returns C-string representation of this_obj's data.
FACE_string_return	FACE_string_length (const FACE_string *this_obj, FACE_unsigned_long *length)
	Gets the length of this_obj.
FACE_string_return	FACE_string_capacity (const FACE_string *this_obj, FACE_unsigned_long *capacity)
	Gets the capacity of this_obj.
FACE_string_return	FACE_string_bound (const FACE_string *this_obj, FACE_unsigned_long *bound)
	Gets the bound of this_obj.
FACE_string_return	FACE_string_is_managed (const FACE_string *this_obj, FACE_boolean *is_managed)
	Gets whether or not this_obj is managed.
FACE_string_return	FACE_string_is_bounded (const FACE_string *this_obj, FACE_boolean *is_bounded)
	Gets whether or not this_obj is bounded.
FACE_string_return	FACE_string_is_valid (const FACE_string *this_obj, FACE_boolean *is_valid)
	Gets whether or not this_obj is in the invalid state.

---

Detailed Description

Interface for operating on a sequence of characters.

---

Macro Definition Documentation

#define FACE_STRING_UNBOUNDED_SENTINEL   UINT_MAX

Value representing the bound of an unbounded FACE_string.

---

Typedef Documentation

typedef enum FACE_string_return FACE_string_return

Return codes used to report certain runtime errors.

---

Enumeration Type Documentation

enum FACE_string_return

Return codes used to report certain runtime errors.

Enumerator:

FACE_STRING_NO_ERROR	No error has occurred.
FACE_STRING_INSUFFICIENT_BOUND	Executing a function would cause a FACE_string's length to exceed its bound.
FACE_STRING_INSUFFICIENT_MEMORY	A FACE_string is unable to allocate enough memory to perform some function.
FACE_STRING_PRECONDITION_VIOLATED	A precondition of some function has been violated.
FACE_STRING_NULL_THIS	The "this_obj" parameter is a NULL pointer
FACE_STRING_NULL_PARAM	One or more other parameters is a NULL pointer
FACE_STRING_INVALID_PARAM	A FACE_string parameter is invalid.

---

Function Documentation

FACE_string_return FACE_string_init_unmanaged_cstring	(	FACE_string *	this_obj,
		const char *	src
	)

Unmanaged initialization from a C-string literal.

After initialization, this_obj does not manage its own data, but instead serves as a wrapper to the data pointed to by src.

This function has exactly the same behavior, preconditions, and possible return codes as calling FACE_string_init_unmanaged where the values for length and &p bound are both strlen(&p src).

The motivation for this function is to initialize a FACE_string from a C-string literal. C-string literals are often stored in read-only memory. Calling a FACE_string interface function that modifies the string value on a string instance that was initialized from read-only memory results in implementation-defined behavior such as as access violation.

Parameters:

this_obj	a pointer to the FACE_string to be initialized
src	pointer to externally managed memory

FACE_string_return FACE_string_init_managed_unbounded

(

FACE_string *

this_obj

)

Managed unbounded initialization - initializes empty managed unbounded FACE_string.

No memory is allocated. After initialization,

• length will be 0
• capacity will be 0
• bound will be FACE_STRING_UNBOUNDED_SENTINEL
• FACE_string_buffer() will get the empty string

Parameters:

this_obj

the FACE_string to be initialized.

Return values:

FACE_STRING_NULL_THIS	if this_obj is null
FACE_STRING_PRECONDITION_VIOLATED	if this_obj is already initialized
FACE_STRING_NO_ERROR	otherwise.

FACE_string_return FACE_string_init_managed_bounded	(	FACE_string *	this_obj,
		FACE_unsigned_long	bound
	)

Managed bounded initialization - initializes empty managed FACE_string of specified bound.

Memory may or may not be allocated.

Preconditions:

• bound != 0
• bound != FACE_STRING_UNBOUNDED_SENTINEL When calling this function, if any of these preconditions are false,
• FACE_STRING_PRECONDITION_VIOLATED will be returned
• this_obj is put into the invalid state

While the implementation does not have to allocate memory equal in size to the requested bound, memory allocation may still fail. If no preconditions are violated and memory allocation fails:

• FACE_STRING_INSUFFICIENT_MEMORY will be returned
• this_obj is put into the invalid state

Otherwise:

• length will be 0
• capacity will be the current capacity
• bound will be the specified bound
• FACE_string_buffer() will get the empty string

Parameters:

this_obj	the FACE_string to be initialized
bound	the specified bound for the this_obj to be initialized with

Return values:

FACE_STRING_NULL_THIS	if this_obj is null
FACE_STRING_PRECONDITION_VIOLATED	if this_obj is already initialized or if any other preconditions are false
FACE_STRING_INSUFFICIENT_MEMORY	if memory allocation fails
FACE_STRING_NO_ERROR	otherwise.

FACE_string_return FACE_string_init_managed_copy	(	FACE_string *	this_obj,
		FACE_string *	src
	)

Managed copy initialization.

After initialization, this_obj manages its own data, which is a copy of src's data, and has the same bound as src.

Preconditions:

• src != NULL
• src is initialized When calling this function, if any of these preconditions are false,
• FACE_STRING_NULL_PARAM will be returned (if src is NULL) or FACE_STRING_PRECONDITION_VIOLATED will be returned (if src is not initialized)
• this_obj is put into the invalid state

If no preconditions are violated and memory allocation fails:

• FACE_STRING_INSUFFICIENT_MEMORY will be returned
• this_obj is put into the invalid state

Parameters:

this_obj	the FACE_string to be initialized
src	the FACE_string to initialize this_obj with

Return values:

FACE_STRING_NULL_THIS	if this_obj is null
FACE_STRING_PRECONDITION_VIOLATED	if this_obj is already initialized or if src is not initialized
FACE_STRING_NULL_PARAM	if src is null
FACE_STRING_INVALID_PARAM	if src is in the invalid state
FACE_STRING_INSUFFICIENT_MEMORY	if memory allocation fails
FACE_STRING_NO_ERROR	otherwise.

FACE_string_return FACE_string_init_managed_cstring	(	FACE_string *	this_obj,
		const char *	cstr
	)

Managed C-string initialization.

After initialization, this_obj manages its own data, which is a copy of cstr, and the bound of this_obj is equal to cstr's length.

Preconditions:

• cstr != NULL
• cstr is not empty When calling this function, if any of these preconditions are false,
• FACE_STRING_NULL_PARAM will be returned (if cstr is NULL) or FACE_STRING_PRECONDITION_VIOLATED will be returned (if cstr is not empty)
• this_obj is put into the invalid state

If no preconditions are violated and memory allocation fails:

• FACE_STRING_INSUFFICIENT_MEMORY will be returned
• this_obj is put into the invalid state

Parameters:

this_obj	the FACE_string to be initialized
cstr	a NUL-terminated string to initialize this_obj's data with

Return values:

FACE_STRING_NULL_THIS	if this_obj is null
FACE_STRING_PRECONDITION_VIOLATED	if this_obj is already initialized or if cstr is empty
FACE_STRING_NULL_PARAM	if cstr is null
FACE_STRING_INSUFFICIENT_MEMORY	if memory allocation fails
FACE_STRING_NO_ERROR	otherwise.

FACE_string_return FACE_string_init_unmanaged	(	FACE_string *	this_obj,
		char *	src,
		FACE_unsigned_long	length,
		FACE_unsigned_long	bound
	)

Unmanaged initialization.

After initialization, this_obj does not manage its own data, but instead serves as a wrapper to the data pointed to by src.

The caller must ensure bound (plus space for NUL) is not greater than the size of the memory allocated at src. If this condition is violated, the result is implementation-defined behavior and may result in an attempt to access restricted memory.

The capacity of this_obj will be equal to its bound, because the externally managed memory has a fixed size, which is both a bound and a capacity.

Preconditions:

• src != NULL
• length <= bound
• bound != 0 (no empty unmanaged strings)
• bound != UNBOUNDED_SENTINEL (no unbounded unmanaged strings) When calling this function, if any of these preconditions are false,
• FACE_STRING_NULL_PARAM will be returned (if src is NULL) or
• FACE_STRING_PRECONDITION_VIOLATED will be returned (if any other preconditions are violated)
• this_obj is put into the invalid state

Otherwise:

• FACE_STRING_NO_ERROR will be returned
• length will be the specified length
• capacity will return the specified capacity (bound)
• bound() will return the specified bound
• FACE_string_buffer() will return a pointer to the externally managed memory

Parameters:

this_obj	a pointer to the FACE_string to be initialized
src	pointer to externally managed memory
length	the number of characters (excluding the NUL character) in the memory pointed to by src
bound	the number of characters (excluding the NUL character) the externally managed memory can hold. Also serves as a capacity.

Return values:

FACE_STRING_NULL_THIS	if this_obj is null
FACE_STRING_PRECONDITION_VIOLATED	if this_obj is already initialized or any other preconditions are false
FACE_STRING_NULL_PARAM	if src is null
FACE_STRING_NO_ERROR	otherwise.

FACE_string_return FACE_string_free

(

FACE_string *

this_obj

)

Frees any data managed by this_obj.

If any preconditions are violated, this_obj's state remains unchanged.

Preconditions:

• this_obj is managed

Return values:

FACE_STRING_NULL_THIS	if this_obj is null
FACE_STRING_PRECONDITION_VIOLATED	if this_obj is not initialized or any other preconditions are false
FACE_STRING_NO_ERROR	otherwise.

FACE_string_return FACE_string_clear

(

FACE_string *

this_obj

)

Clears this_obj's data.

If any preconditions are violated, this_obj's state remains unchanged.

Otherwise, all data is cleared, and this_obj's length will be set to 0. Memory allocation remains unchanged.

Return values:

FACE_STRING_NULL_THIS	if this_obj is null
FACE_STRING_PRECONDITION_VIOLATED	if this_obj is not initialized or any other preconditions are false
FACE_STRING_NO_ERROR	otherwise.

FACE_string_return FACE_string_append	(	FACE_string *	this_obj,
		const FACE_string *	src
	)

Adds a copy of src's data to the this_obj's data.

This is one of two FACE_string functions that may reallocate managed memory. If append is successful, the length of this String changes accordingly; capacity may or may not be changed. If append is unsuccessful, this_obj's state remains unchanged.

Preconditions:

• src != NULL
• src is initialized When calling this function, if any of these preconditions are false,
• FACE_STRING_NULL_PARAM will be returned (if src is NULL) or
• FACE_STRING_PRECONDITION_VIOLATED will be returned (if any other preconditions are violated)

Return values:

FACE_STRING_NULL_THIS	if this_obj is null
FACE_STRING_PRECONDITION_VIOLATED	if this_obj is not initialized or if src is not initialized
FACE_STRING_NULL_PARAM	if src is null
FACE_STRING_INSUFFICIENT_BOUND	if append would exceed logical bound
FACE_STRING_INSUFFICIENT_MEMORY	if append exceeds available memory
FACE_STRING_NO_ERROR	otherwise

FACE_string_return FACE_string_append_elem	(	FACE_string *	this_obj,
		const FACE_char	elem
	)

Adds a copy of elem to the this_obj's data.

This is one of two FACE_string functions that may reallocate managed memory. If append is successful, the length of this String changes accordingly; capacity may or may not be changed. If append is unsuccessful, this_obj's state remains unchanged.

Return values:

FACE_STRING_NULL_THIS	if this_obj is null
FACE_STRING_PRECONDITION_VIOLATED	if this_obj is not initialized
FACE_STRING_INSUFFICIENT_BOUND	if append would exceed logical bound
FACE_STRING_INSUFFICIENT_MEMORY	if append exceeds available memory
FACE_STRING_NO_ERROR	otherwise

FACE_string_return FACE_string_reserve	(	FACE_string *	this_obj,
		FACE_unsigned_long	capacity
	)

Attempt to reserve memory to store capacity characters.

This function is useful when this_obj is initialized as a managed-unbounded string with an implementation-defined capacity in order to perform potential reallocation at a known point of program execution, such as during program initialization.

On success, the implementation can store a string value of capacity capacity. The function may succeed without reallocation if the implementation-defined capacity exceeds capacity and the implementation does not reallocate to a smaller capacity.

If any preconditions are violated, this_obj's state remains unchanged.

Preconditions:

• this_obj is valid
• this_obj is managed
• this_obj is unbounded

Return values:

FACE_STRING_NULL_THIS	if this_obj is null
FACE_STRING_PRECONDITION_VIOLATED	if this_obj is not initialized or any other preconditions are false
FACE_STRING_INSUFFICIENT_MEMORY	if memory allocation fails
FACE_STRING_NO_ERROR	otherwise.

const char* FACE_string_at	(	const FACE_string *	this_obj,
		FACE_unsigned_long	index
	)

Gets the character at a given index.

FACE_strings use a zero-based index.

Parameters:

this_obj	a const pointer to the FACE_string being indexed.
index	The index of the element to be retrieved.

Return values:

NULL	if this_obj is null or not initialized
NUL	if index is out of range (null character)
a	const pointer to the character at the given index otherwise

const char* FACE_string_buffer

(

const FACE_string *

this_obj

)

Returns C-string representation of this_obj's data.

Return values:

NULL	if this_obj is null or not initialized
a	pointer to a NUL-terminated (C-style) string equivalent to this_obj's underlying string data otherwise

FACE_string_return FACE_string_length	(	const FACE_string *	this_obj,
		FACE_unsigned_long *	length
	)

Gets the length of this_obj.

Parameters:

this_obj	a const pointer to the FACE_string to get the length of
length	A pointer where the length will be stored.

Return values:

FACE_STRING_NULL_THIS	if this_obj is null
FACE_STRING_PRECONDITION_VIOLATED	if this_obj is not initialized
FACE_STRING_NULL_PARAM	if length is null
FACE_STRING_NO_ERROR	otherwise.

FACE_string_return FACE_string_capacity	(	const FACE_string *	this_obj,
		FACE_unsigned_long *	capacity
	)

Gets the capacity of this_obj.

Parameters:

this_obj	a const pointer to the FACE_string to get the capacity of
capacity	A pointer where the capacity will be stored.

Return values:

FACE_STRING_NULL_THIS	if this_obj is null
FACE_STRING_PRECONDITION_VIOLATED	if this_obj is not initialized
FACE_STRING_NULL_PARAM	if capacity is null
FACE_STRING_NO_ERROR	otherwise.

FACE_string_return FACE_string_bound	(	const FACE_string *	this_obj,
		FACE_unsigned_long *	bound
	)

Gets the bound of this_obj.

Parameters:

this_obj	a const pointer to the FACE_string to get the bound of
bound	A pointer where the bound will be stored.

Return values:

FACE_STRING_NULL_THIS	if this_obj is null
FACE_STRING_PRECONDITION_VIOLATED	if this_obj is not initialized
FACE_STRING_NULL_PARAM	if bound is null
FACE_STRING_NO_ERROR	otherwise.

FACE_string_return FACE_string_is_managed	(	const FACE_string *	this_obj,
		FACE_boolean *	is_managed
	)

Gets whether or not this_obj is managed.

Parameters:

this_obj	a const pointer to the FACE_string to check
is_managed	A pointer where the result will be stored. is_managed will be 1 if this_obj manages its own memory, and 0 otherwise.

Return values:

FACE_STRING_NULL_THIS	if this_obj is null
FACE_STRING_PRECONDITION_VIOLATED	if this_obj is not initialized
FACE_STRING_NULL_PARAM	if is_managed is null
FACE_STRING_NO_ERROR	otherwise.

FACE_string_return FACE_string_is_bounded	(	const FACE_string *	this_obj,
		FACE_boolean *	is_bounded
	)

Gets whether or not this_obj is bounded.

Parameters:

this_obj	a const pointer to the FACE_string to check
is_bounded	A pointer where the result will be stored. is_bounded will be 1 if this_obj is bounded, and 0 otherwise.

Return values:

FACE_STRING_NULL_THIS	if this_obj is null
FACE_STRING_PRECONDITION_VIOLATED	if this_obj is not initialized
FACE_STRING_NULL_PARAM	if is_bounded is null
FACE_STRING_NO_ERROR	otherwise.

FACE_string_return FACE_string_is_valid	(	const FACE_string *	this_obj,
		FACE_boolean *	is_valid
	)

Gets whether or not this_obj is in the invalid state.

(see FACE_string details)

Parameters:

this_obj	a const pointer to the FACE_string to check
is_valid	A pointer where the result will be stored. is_valid will be 0 if this_obj is in the invalid state, and 1 otherwise.

Return values:

FACE_STRING_NULL_THIS	if this_obj is null
FACE_STRING_PRECONDITION_VIOLATED	if this_obj is not initialized
FACE_STRING_NULL_PARAM	if is_valid is null
FACE_STRING_NO_ERROR	otherwise.