Atom Vec Interface

Functions for working with vectors (lists) of atoms. More...

Classes
struct	atom_vec_t
	Contains a vector (list) of Atoms. More...

Typedefs
typedef void(*	c_atom_vec_callback_t) (const struct atom_vec_t *vec, void *context)
	Function signature for a callback providing access to an atom_vec_t

Functions
struct atom_vec_t	atom_vec_new (void)
	Creates a new empty atom_vec_t
struct atom_vec_t	atom_vec_clone (const struct atom_vec_t *vec)
	Creates a new atom_vec_t by cloning an existing atom_vec_t
struct atom_vec_t	atom_vec_from_array (atom_t *atoms, uintptr_t size)
	Creates a new atom_vec_t from a C-style array.
void	atom_vec_free (struct atom_vec_t vec)
	Frees a atom_vec_t
uintptr_t	atom_vec_len (const struct atom_vec_t *vec)
	Returns the number of elements in a vec.
atom_t	atom_vec_pop (struct atom_vec_t *vec)
	Removes the last element from a vec, and returns it.
void	atom_vec_push (struct atom_vec_t *vec, atom_t atom)
	Push the atom onto the end of the vec.
atom_ref_t	atom_vec_get (const struct atom_vec_t *vec, uintptr_t idx)
	Access an atom at a specified index in a vec.

Detailed Description

Functions for working with vectors (lists) of atoms.

These functions are used to create, access, modify, and free atom vectors.

Typedef Documentation

c_atom_vec_callback_t

typedef void(* c_atom_vec_callback_t) (const struct atom_vec_t *vec, void *context)

Function signature for a callback providing access to an atom_vec_t

Parameters

[in]	vec	The atom_vec_t being provided. This vec should not be modified or freed by the callback.
[in]	context	The context state pointer initially passed to the upstream function initiating the callback.

Function Documentation

atom_vec_clone()

struct atom_vec_t atom_vec_clone

(

const struct atom_vec_t *

vec

)

Creates a new atom_vec_t by cloning an existing atom_vec_t

Parameters

[in]

vec

A pointer to an existing atom_vec_t to clone

Returns

A newly created atom_vec_t

Note

The caller must take ownership responsibility for the returned atom_vec_t

atom_vec_free()

void atom_vec_free

(

struct atom_vec_t

vec

)

Frees a atom_vec_t

Parameters

[in]

vec

The vec to free

atom_vec_from_array()

struct atom_vec_t atom_vec_from_array	(	atom_t *	atoms,
		uintptr_t	size )

Creates a new atom_vec_t from a C-style array.

Parameters

[in]	atoms	A packed buffer of atom_t *, representing the atoms to put into the vec.
[in]	size	The number of elements in atoms

Returns

The newly created atom_vec_t

Note

The caller must take ownership responsibility for the returned atom_vec_t

Warning

This function takes ownership of all atoms, so they must not be subsequently accessed or freed

atom_vec_get()

atom_ref_t atom_vec_get	(	const struct atom_vec_t *	vec,
		uintptr_t	idx )

Access an atom at a specified index in a vec.

Parameters

[in]	vec	The vec in which to access the atom
[in]	idx	The index of the element to access

Returns

A reference to the atom at the specified index

Note

In the event that no atom exists at the specified idx, a null atom_ref_t will be returned

Warning

The atom referenced by the return value from this function remains owned by the atom_vec_t. It must not be accessed after the vec has been modified or freed.

atom_vec_len()

uintptr_t atom_vec_len

(

const struct atom_vec_t *

vec

)

Returns the number of elements in a vec.

Parameters

[in]

vec

The vec to be inspected

Returns

The count of the number of elements contained within the vec

atom_vec_new()

struct atom_vec_t atom_vec_new

(

void

)

Creates a new empty atom_vec_t

Returns

The newly created atom_vec_t

Note

The caller must take ownership responsibility for the returned atom_vec_t

atom_vec_pop()

atom_t atom_vec_pop

(

struct atom_vec_t *

vec

)

Removes the last element from a vec, and returns it.

Parameters

[in]

vec

The vec from which to pop the atom

Returns

The last atom_t contained in the vec

Note

The caller must take ownership responsibility for the returned atom_t

In the event that the vec is empty, a null atom_t will be returned

atom_vec_push()

void atom_vec_push	(	struct atom_vec_t *	vec,
		atom_t	atom )

Push the atom onto the end of the vec.

Parameters

[in]	vec	a pointer to an atom_vec_t to push the atom onto
[in]	atom	the atom to push onto the vec

Warning

This function takes ownership of the supplied atom_t, and it must not be subsequently accessed of freed.