Interface for operating on a generic sequence of elements. More...

#include <FACE/types.h>
#include <limits.h>
#include <stddef.h>
#include <string.h>

Macros
#define	FACE_SEQUENCE_UNBOUNDED_SENTINEL UINT_MAX
	Value representing the bound of an unbounded FACE_sequence.

Typedefs
typedef void(*	FACE_sequence_copy_elem_fn )(void , const void , FACE_unsigned_long)
	Interface for operating on a generic sequence of elements.
typedef enum FACE_sequence_return	FACE_sequence_return
	Return codes used to report certain runtime errors.

Enumerations
enum	FACE_sequence_return { FACE_SEQUENCE_NO_ERROR, FACE_SEQUENCE_INSUFFICIENT_BOUND, FACE_SEQUENCE_INSUFFICIENT_MEMORY, FACE_SEQUENCE_PRECONDITION_VIOLATED, FACE_SEQUENCE_NULL_THIS, FACE_SEQUENCE_NULL_PARAM, FACE_SEQUENCE_INVALID_PARAM }
	Return codes used to report certain runtime errors. More...

Functions
FACE_sequence_return	FACE_sequence_init_managed_unbounded (FACE_sequence *this_obj, size_t sizeof_T)
	Managed unbounded initialization - initializes empty managed unbounded FACE_sequence.
FACE_sequence_return	FACE_sequence_init_managed_bounded (FACE_sequence *this_obj, size_t sizeof_T, FACE_unsigned_long bound)
	Managed bounded initialization - initializes empty managed FACE_sequence of specified bound.
FACE_sequence_return	FACE_sequence_init_managed_copy (FACE_sequence this_obj, FACE_sequence src)
	Managed copy initialization.
FACE_sequence_return	FACE_sequence_init_managed_data (FACE_sequence this_obj, const void arr, size_t sizeof_T, FACE_unsigned_long length)
	Managed array initialization.
FACE_sequence_return	FACE_sequence_init_unmanaged (FACE_sequence this_obj, void src, size_t sizeof_T, FACE_unsigned_long length, FACE_unsigned_long bound)
	Unmanaged initialization.
FACE_sequence_return	FACE_sequence_free (FACE_sequence *this_obj)
	Frees any data managed by `this_obj`.
FACE_sequence_return	FACE_sequence_clear (FACE_sequence *this_obj)
	Clears `this_obj's` data.
FACE_sequence_return	FACE_sequence_append (FACE_sequence this_obj, const FACE_sequence src)
	Adds a copy of `src's` data to the `this_obj's` data.
FACE_sequence_return	FACE_sequence_append_elem (FACE_sequence this_obj, void src, size_t sizeof_T)
	Adds a copy of `src` to the `this_obj's` data.
FACE_sequence_return	FACE_sequence_reserve (FACE_sequence *this_obj, FACE_unsigned_long capacity)
	Reserve storage for `capacity` elements.
const void *	FACE_sequence_at (const FACE_sequence *this_obj, FACE_unsigned_long index)
	Gets the element at a given index.
const void *	FACE_sequence_buffer (const FACE_sequence *this_obj)
	Returns pointer to `this_obj's` underlying data.
FACE_sequence_return	FACE_sequence_length (const FACE_sequence this_obj, FACE_unsigned_long length)
	Gets the length of `this_obj`.
FACE_sequence_return	FACE_sequence_capacity (const FACE_sequence this_obj, FACE_unsigned_long capacity)
	Gets the capacity of `this_obj`.
FACE_sequence_return	FACE_sequence_bound (const FACE_sequence this_obj, FACE_unsigned_long bound)
	Gets the bound of `this_obj`.
FACE_sequence_return	FACE_sequence_is_managed (const FACE_sequence this_obj, FACE_boolean is_managed)
	Gets whether or not `this_obj` is managed.
FACE_sequence_return	FACE_sequence_is_bounded (const FACE_sequence this_obj, FACE_boolean is_bounded)
	Gets whether or not `this_obj` is bounded.
FACE_sequence_return	FACE_sequence_is_valid (const FACE_sequence this_obj, FACE_boolean is_valid)
	Gets whether or not `this_obj` is in the invalid state.

Detailed Description

Interface for operating on a generic sequence of elements.

Macro Definition Documentation

#define FACE_SEQUENCE_UNBOUNDED_SENTINEL UINT_MAX

Value representing the bound of an unbounded FACE_sequence.

Typedef Documentation

typedef void(* FACE_sequence_copy_elem_fn)(void *, const void *, FACE_unsigned_long)

Interface for operating on a generic sequence of elements.

A FACE_sequence is defined by three characteristics:

length - the current number of elements in the FACE_sequence
element size - the size of each element
bound - the maximum number of elements the FACE_sequence can ever hold. This bound is logical, and is independent from the size of any underlying memory. A FACE_sequence's bound is fixed throughout the lifetime of the FACE_sequence. An "unbounded" FACE_sequence has an infinite bound, represented by FACE_SEQUENCE_UNBOUNDED_SENTINEL.
capacity - the number of elements a FACE_sequence has currently allocated memory for. This may vary by implementation, but length <= capacity <= bound is always true.

A "managed" FACE_sequence is responsible for and manages the lifetime of the memory for the data it represents. An "unmanaged" FACE_sequence essentially wraps a pointer to memory whose lifetime is managed elsewhere.

A FACE_sequence is "initialized" if it is in a state that could have resulted from successful initialization by one of the "_init" functions. Any other state makes the FACE_sequence "uninitialized".

When a memory allocation failure or precondition violation occurs, a FACE_sequence is put into a known "invalid state". In this invalid state:

length, capacity, and bound are 0
FACE_sequence_buffer() will return NULL
FACE_sequence_is_managed() and FACE_sequence_is_bounded() will return FALSE The FACE_sequence_is_valid() function indicates whether or not a FACE_sequence is in this state.

Global preconditions:

In every function, if the this_obj parameter is NULL, the function does nothing and returns FACE_SEQUENCE_NULL_THIS.
In every _init function, if this_obj is already initialized, FACE_SEQUENCE_PRECONDITION_VIOLATED is returned and the state of this_obj is not modified.
In every non _init function, if this_obj has not been initialized, FACE_SEQUENCE_PRECONDITION_VIOLATED is returned and the state of this_obj is not modified.

typedef enum FACE_sequence_return FACE_sequence_return

Return codes used to report certain runtime errors.

Enumeration Type Documentation

enum FACE_sequence_return

Return codes used to report certain runtime errors.

Enumerator:

FACE_SEQUENCE_NO_ERROR	No error has occurred.
FACE_SEQUENCE_INSUFFICIENT_BOUND	Executing a function would cause a FACE_sequence's length to exceed its bound.
FACE_SEQUENCE_INSUFFICIENT_MEMORY	A FACE_sequence is unable to allocate enough memory to perform some function.
FACE_SEQUENCE_PRECONDITION_VIOLATED	A precondition of some function has been violated.
FACE_SEQUENCE_NULL_THIS	The "this_obj" parameter is a NULL pointer
FACE_SEQUENCE_NULL_PARAM	One or more other parameters is a NULL pointer
FACE_SEQUENCE_INVALID_PARAM	A FACE_sequence parameter is invalid.

Function Documentation

FACE_sequence_return FACE_sequence_init_managed_unbounded	(	FACE_sequence *	this_obj,
		size_t	sizeof_T
	)

Managed unbounded initialization - initializes empty managed unbounded FACE_sequence.

(see FACE_string_init_managed_unbounded)

After initialization, FACE_sequence_buffer() will return NULL.

Parameters:

this_obj	the FACE_sequence to be initialized
sizeof_T	the size of each element in `this_obj`

FACE_sequence_return FACE_sequence_init_managed_bounded	(	FACE_sequence *	this_obj,
		size_t	sizeof_T,
		FACE_unsigned_long	bound
	)

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

(see FACE_string_init_managed_bounded)

If allocation is successful, FACE_sequence_buffer() will return NULL.

Parameters:

this_obj	the FACE_sequence to be initialized
sizeof_T	the size of each element in `this_obj`
bound	the specified bound for `this_obj` to be initialized with

FACE_sequence_return FACE_sequence_init_managed_copy	(	FACE_sequence *	this_obj,
		FACE_sequence *	src
	)

Managed copy initialization.

(see FACE_string_init_managed_copy)

FACE_sequence_return FACE_sequence_init_managed_data	(	FACE_sequence *	this_obj,
		const void *	arr,
		size_t	sizeof_T,
		FACE_unsigned_long	length
	)

Managed array initialization.

After initialization, this FACE_sequence manages its own data, which is a copy of the length elements of size sizeof_T in the array pointed to by arr, and the bound of this_obj is equal to length.

Preconditions:

arr != NULL
arr is not empty
sizeof_T != 0
length != 0 When calling this function, if any of these preconditions are false,
FACE_SEQUENCE_NULL_PARAM will be returned (if arr is NULL) or FACE_SEQUENCE_PRECONDITION_VIOLATED will be returned (if any other precondition is violated)
this_obj is put into the invalid state

If no preconditions are violated and memory allocation fails:

FACE_SEQUENCE_INSUFFICIENT_MEMORY will be returned
this_obj is put into the invalid state

The caller must ensure length * sizeof_T is not greater than the size of the memory allocated at arr. If this condition is violated, the result is implementation-defined behavior and may result in an attempt to access restricted memory.

Parameters:

this_obj	the FACE_sequence to be initialized
arr	a pointer to the array
sizeof_T	the size of each element in the array
length	the number of elements in the array

Return values:

FACE_SEQUENCE_NULL_THIS	if `this_obj` is null
FACE_SEQUENCE_PRECONDITION_VIOLATED	if `this_obj` is already initialized or any other preconditions are false
FACE_SEQUENCE_NULL_PARAM	if `arr` is null
FACE_SEQUENCE_INSUFFICIENT_MEMORY	if memory allocation fails
FACE_SEQUENCE_NO_ERROR	otherwise.

FACE_sequence_return FACE_sequence_init_unmanaged	(	FACE_sequence *	this_obj,
		void *	src,
		size_t	sizeof_T,
		FACE_unsigned_long	length,
		FACE_unsigned_long	bound
	)

Unmanaged initialization.

(see FACE_string_init_unmanaged)

The caller must ensure bound * sizeof_T 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.

Preconditions:

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

Parameters:

this_obj	a pointer to the FACE_sequence to be initialized
src	pointer to externally managed memory
length	the number of elements in the memory pointed to by `src`
sizeof_T	the size of each element in the memory pointed to by `src`
bound	the number of elements the externally managed memory can hold. Also serves as a capacity.

FACE_sequence_return FACE_sequence_free ( FACE_sequence * this_obj )

Frees any data managed by this_obj.

(see FACE_string_free)

FACE_sequence_return FACE_sequence_clear ( FACE_sequence * this_obj )

Clears this_obj's data.

(see FACE_string_clear)

FACE_sequence_return FACE_sequence_append	(	FACE_sequence *	this_obj,
		const FACE_sequence *	src
	)

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

(see FACE_string_append)

FACE_sequence_return FACE_sequence_append_elem	(	FACE_sequence *	this_obj,
		void *	src,
		size_t	sizeof_T
	)

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

(see FACE_string_append_elem)

Preconditions:

src != NULL
sizeof_T != 0 When calling this function, if any of these preconditions are false,
FACE_SEQUENCE_NULL_PARAM will be returned (if src is NULL) or
FACE_SEQUENCE_PRECONDITION_VIOLATED will be returned (if any other preconditions are violated)
this_obj is put into the invalid state

Parameters:

this_obj	a pointer to the FACE_sequence to be initialized
src	pointer to externally managed memory
sizeof_T	the size of the element in memory pointed to by `src`

FACE_sequence_return FACE_sequence_reserve	(	FACE_sequence *	this_obj,
		FACE_unsigned_long	capacity
	)

Reserve storage for capacity elements.

(see FACE_string_reserve)

const void* FACE_sequence_at	(	const FACE_sequence *	this_obj,
		FACE_unsigned_long	index
	)

Gets the element at a given index.

(see FACE_sequence_at)

Return values:

NULL	if `this_obj` is null, not initialized, or if index is out of range
a	const pointer to the element at the given index otherwise.

const void* FACE_sequence_buffer ( const FACE_sequence * this_obj )

Returns pointer to this_obj's underlying data.

To avoid accessing restricted memory, the caller should avoid dereferencing memory beyond buffer + length*(the size of each element).

Return values:

NULL	if `this_obj` is null or not initialized
a	pointer to contiguous memory for `this_obj's` data otherwise

FACE_sequence_return FACE_sequence_length	(	const FACE_sequence *	this_obj,
		FACE_unsigned_long *	length
	)

Gets the length of this_obj.

(see FACE_string_length)

FACE_sequence_return FACE_sequence_capacity	(	const FACE_sequence *	this_obj,
		FACE_unsigned_long *	capacity
	)

Gets the capacity of this_obj.

(see FACE_string_capacity)

FACE_sequence_return FACE_sequence_bound	(	const FACE_sequence *	this_obj,
		FACE_unsigned_long *	bound
	)

Gets the bound of this_obj.

(see FACE_string_bound)

FACE_sequence_return FACE_sequence_is_managed	(	const FACE_sequence *	this_obj,
		FACE_boolean *	is_managed
	)

Gets whether or not this_obj is managed.

(see FACE_string_is_managed)

FACE_sequence_return FACE_sequence_is_bounded	(	const FACE_sequence *	this_obj,
		FACE_boolean *	is_bounded
	)

Gets whether or not this_obj is bounded.

(see FACE_string_is_bounded)

FACE_sequence_return FACE_sequence_is_valid	(	const FACE_sequence *	this_obj,
		FACE_boolean *	is_valid
	)

Gets whether or not this_obj is in the invalid state.

(see FACE_string_is_valid)

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation