List

API related to the bj_list object. More...

Collaboration diagram for List:

Detailed Description

bj_list is a container that supports constant time insertion and removal from anywhere in the container. It is implemented as a singly linked list.

Data Structures
struct	bj_list_iterator_t
	Structure representing a list iterator. More...

Macros
#define	bj_list_new_t(T)
	Creates a new bj_list with type inference for elements.

Typedefs
typedef struct bj_list_t	bj_list
	Typedef for the BList_t struct.
typedef struct bj_list_iterator_t	bj_list_iterator
	Typedef for the bj_list_iterator_t structure.

Functions
bj_list *	bj_list_alloc (void)
	Allocate a new bj_list object in memory.
bj_list *	bj_list_new (size_t bytes_payload)
	Creates a new bj_list with the specified payload size.
void	bj_list_del (bj_list *p_list)
	Deletes a bj_list object and releases associated memory.
bj_list *	bj_list_init (bj_list *p_list, size_t bytes_payload)
	Initializes the given list.
void	bj_list_clear (bj_list *list)
	Clears all data in the list.
void	bj_list_reset (bj_list *p_list)
	Reset the given list.
size_t	bj_list_len (bj_list *list)
	Returns the number of elements in the given list.
void *	bj_list_insert (bj_list *list, size_t index, void *p_data)
	Inserts a new element at the specified index and returns a pointer to it.
void *	bj_list_prepend (bj_list *list, void *p_data)
	Inserts a new element at position 0 and returns a pointer to it.
void *	bj_list_at (bj_list *list, size_t index)
	Returns the value of the element at the specified index.
void *	bj_list_head (bj_list *list)
	Returns the value of the first element in the list.
bj_list_iterator *	bj_list_iterator_new (bj_list *list)
	Creates a forward-only iterator for the given list.
void	bj_list_iterator_del (bj_list_iterator *iterator)
	Destroys the given list iterator.
void	bj_list_iterator_init (bj_list *p_list, bj_list_iterator *p_iterator)
	Initializes a list iterator.
void	bj_list_iterator_reset (bj_list_iterator *p_iterator)
	Resets a list iterator.
bj_bool	bj_list_iterator_has_next (bj_list_iterator *iterator)
	Returns BJ_TRUE if the iterator has more elements.
void *	bj_list_iterator_next (bj_list_iterator *iterator)
	Returns the next element in the iteration.

---

Data Structure Documentation

bj_list_iterator_t

struct bj_list_iterator_t

Data Fields
bj_list *	list
void **	p_current

Macro Definition Documentation

bj_list_new_t

#define bj_list_new_t

(

T

)

Value:

bj_list_new(sizeof(T))

Parameters

T	Type of elements.

Returns

A pointer to the newly created bj_list object.

Examples

list.c.

Function Documentation

bj_list_alloc()

bj_list * bj_list_alloc

(

void

)

Returns

A new bj_list object

Memory Management

The object pointed by the returned pointer must be freed using bj_free.

bj_list_at()

void * bj_list_at	(	bj_list *	list,
		size_t	index )

Parameters

list	The list object.
index	The position of the element to get.

Returns

A pointer to the element.

Examples

list.c.

bj_list_clear()

void bj_list_clear

(

bj_list *

list

)

Parameters

list	The list object.

If the list is already empty, this function does nothing.

Examples

list.c.

bj_list_del()

void bj_list_del

(

bj_list *

p_list

)

Parameters

p_list

Pointer to the bj_list object to delete.

Examples

list.c.

bj_list_head()

void * bj_list_head

(

bj_list *

list

)

Parameters

list	The list object.

Returns

A pointer to the first element.

This function effectively calls bj_list_at with index 0.

bj_list_init()

bj_list * bj_list_init	(	bj_list *	p_list,
		size_t	bytes_payload )

Parameters

p_list	the list to initialize.
bytes_payload	Size of each element's payload in bytes.

Returns

p_list

bj_list_insert()

void * bj_list_insert	(	bj_list *	list,
		size_t	index,
		void *	p_data )

Parameters

list	The list object.
index	The position of the new element in the list.
p_data	A pointer to the memory of the data to insert.

Returns

A pointer to the inserted value.

The newly inserted element is located at index. All elements previously located at any position starting from index have their positions shifted by 1.

Weak/Strong ownership

In weak ownership, the return value is equal to p_data.

In strong ownership, the return value points to a newly allocated block. If p_data != 0, the allocated block is initialized with the content pointed by p_data (using bj_memcpy). Otherwise, the block is left uninitialized.

Examples

list.c.

bj_list_iterator_del()

void bj_list_iterator_del

(

bj_list_iterator *

iterator

)

Parameters

iterator

The iterator object.

Memory Management

This function uses the allocator set in the given iterator to destroy the iterator.

Examples

list.c.

bj_list_iterator_has_next()

bj_bool bj_list_iterator_has_next

(

bj_list_iterator *

iterator

)

Parameters

iterator

The iterator object.

Returns

BJ_TRUE if the iterator has more elements.

Examples

list.c.

bj_list_iterator_init()

void bj_list_iterator_init	(	bj_list *	p_list,
		bj_list_iterator *	p_iterator )

Parameters

p_list	The list to iterate.
p_iterator	The iterator object.

bj_list_iterator_new()

bj_list_iterator * bj_list_iterator_new

(

bj_list *

list

)

Parameters

list	The list object.

Returns

A new iterator object.

Memory Management

This function uses the allocator set in the given list for any memory operations performed by this iterator.

Examples

list.c.

bj_list_iterator_next()

void * bj_list_iterator_next

(

bj_list_iterator *

iterator

)

Parameters

iterator

The iterator object.

Returns

A pointer to the next element in the iteration or 0 if no new element.

Examples

list.c.

bj_list_iterator_reset()

void bj_list_iterator_reset

(

bj_list_iterator *

p_iterator

)

Parameters

p_iterator

The iterator object.

bj_list_len()

size_t bj_list_len

(

bj_list *

list

)

Parameters

list	The list object.

Returns

An integer indicating the number of elements in the list.

Examples

list.c.

bj_list_new()

bj_list * bj_list_new

(

size_t

bytes_payload

)

Parameters

bytes_payload

Size of each element's payload in bytes.

Returns

A pointer to the newly created bj_list object.

bj_list_prepend()

void * bj_list_prepend	(	bj_list *	list,
		void *	p_data )

Parameters

list	The list object.
p_data	A pointer to the memory of the data to insert.

Returns

A pointer to the inserted value.

The newly inserted element is located at index 0. All elements previously located at any position starting from 0 have their positions shifted by 1.

Weak/Strong ownership

In weak ownership, the return value is equal to p_data.

In strong ownership, the return value points to a newly allocated block. If p_data != 0, the allocated block is initialized with the content pointed by p_data (using bj_memcpy). Otherwise, the block is left uninitialized.

bj_list_reset()

void bj_list_reset

(

bj_list *

p_list

)

Parameters

p_list

The list to reset