Burger::LinkedListObjects Class Reference

Linked list object class. More...

Collaboration diagram for Burger::LinkedListObjects:

Classes
class	Object
	Instance of a linked list object that contains a pointer to arbitrary data. More...

Public Types
typedef uint32_t(*	ProcAction) (void *pData)
	Iterator callback pointer.

Public Member Functions
	LinkedListObjects () noexcept
	Initialize to default.
	~LinkedListObjects ()
	Dispose of all data.
void	shutdown (void) noexcept
	Dispose of all data.
uint32_t	get_count (void) const noexcept
	Return the number of Objects in the list.
Object *	get_first (void) const noexcept
	Return the pointer to the first object in the list.
Object *	get_last (void) const noexcept
	Return the pointer to the last object in the list.
void *	get_first_data (void) const noexcept
	Return the data pointer from the first object in the list.
void *	get_last_data (void) const noexcept
	Return the data pointer from the last object in the list.
void *	get_data (uint32_t uIndex) const noexcept
	Get the data from an indexed entry in the list.
Object *	get_object (uint32_t uIndex) const noexcept
	Get the data from an indexed entry in the list.
Object *	get_object (void *pData) const noexcept
	Traverse the linked list until an entry matches the supplied data.
Object *	get_string_object (const char *pString) const noexcept
	Traverse the linked list until an entry matches the supplied "C" string.
uint32_t	get_string_index (const char *pString) const noexcept
	Traverse the linked list until an entry matches the supplied "C" string.
void	destroy (Object *pObject) noexcept
	Remove an object from the list and dispose of it.
void	append (Object *pObject) noexcept
	Add a data object to the end of the list.
void	prepend (Object *pObject) noexcept
	Add a data object to the beginning of the list.
void	append (void *pData, Object::ProcDataDelete pDataDelete=Object::proc_free_object_and_data) noexcept
	Add a pointer of data to the end of the list.
void	prepend (void *pData, Object::ProcDataDelete pDataDelete=Object::proc_free_object_and_data) noexcept
	Add a pointer of data to the beginning of the list.
void	append (const char *pString) noexcept
	Add a copy of a string into the linked list.
void	prepend (const char *pString) noexcept
	Add a copy of a string into the linked list.
Object *	iterate_forward (ProcAction pProc) noexcept
	Forward iterate over the linked list.
Object *	iterate_reverse (ProcAction pProc) noexcept
	Reverse iterate over the linked list.

Static Public Attributes
static const uint32_t	kContinue = 0
	Don't do anything.
static const uint32_t	kAbort = 0x01
	Abort iteration.
static const uint32_t	kDeleteObject = 0x02
	Delete this object and continue iterating.

Private Member Functions
	LinkedListObjects (const LinkedListObjects &)=delete
LinkedListObjects &	operator= (const LinkedListObjects &)=delete
	LinkedListObjects (LinkedListObjects &&)=delete
LinkedListObjects &	operator= (LinkedListObjects &&)=delete

Private Attributes
Object *	m_pRoot
	Root linked list entry.
uint32_t	m_uCount
	Number of objects in the list.

Detailed Description

Linked list object class.

---

A LinkedListObjects is the root entry. It contains all the entries of the list and all calls use this root entry as a starting point.

The LinkedListObjects::Object are where the magic happens. It is a member of a circular doubly linked list. The root LinkedListObjects structure is where you can find the beginning and the ending of the entire list quickly.

Each LinkedListObjects::Object also has a pointer to the generic data that is contained and also a pointer to a function to discard the data once the entry itself is deleted. The function pointer could be nullptr meaning that the data can be deleted with a simple call to Burger::Free(). The data could also be pointing to the end of the base LinkedListObjects::Object structure if the LinkedListObjects::Object structure is part of a larger structure.

All Linked list manager calls are pointer based. There is no support of handles. However the Data field could be a handle and you can pass your own data destructor routine to discard the handle. There is a convenience routine to add data if the data is a handle. But you have to typecast the void * to a void ** manually when you access the data

Member Typedef Documentation

ProcAction

Burger::LinkedListObjects::ProcAction

Iterator callback pointer.

---

When iterate_forward(ProcAction) or iterate_reverse(ProcAction) is called, this function pointer is used to perform an action with every individual object data.

The function returns kContinue to continue iteration, kAbort to stop iteration and kDeleteObject to tell the iterator to call the disposal function at a safe time. kAbort and kDeleteObject can be or'd together to perform both actions.

Parameters

pData

Pointer to the data in the object

See also

Object::get_data(), iterate_forward(ProcAction), or iterate_reverse(ProcAction)

Constructor & Destructor Documentation

LinkedListObjects() [1/3]

Burger::LinkedListObjects::LinkedListObjects ( const LinkedListObjects & )

privatedelete

LinkedListObjects() [2/3]

Burger::LinkedListObjects::LinkedListObjects ( LinkedListObjects && )

privatedelete

LinkedListObjects() [3/3]

Burger::LinkedListObjects::LinkedListObjects ( )

inlinenoexcept

Initialize to default.

---

Creates an empty class.

See also

~LinkedListObjects() or shutdown()

~LinkedListObjects()

Burger::LinkedListObjects::~LinkedListObjects ( )

inline

Dispose of all data.

---

Calls shutdown() to dispose of all the linked list members

See also

LinkedListObjects() or shutdown()

Member Function Documentation

append() [1/3]

void Burger::LinkedListObjects::append ( const char * pString )

noexcept

Add a copy of a string into the linked list.

---

Make a copy of the input string and append the string to the end of the linked list

Parameters

pString

Pointer to the "C" to copy.

See also

prepend(const char*)

append() [2/3]

void Burger::LinkedListObjects::append ( Object * pObject )

noexcept

Add a data object to the end of the list.

---

Accept an Object entry and append it to the end of the linked list.

Parameters

pObject

Pointer to the Object to append

See also

append(void*, Object::ProcDataDelete), prepend(Object*)

append() [3/3]

void Burger::LinkedListObjects::append ( void * pData, Object::ProcDataDelete pDataDelete = Object::proc_free_object_and_data )

noexcept

Add a pointer of data to the end of the list.

---

Allocate a new Object entry and attach this data pointer to it.

Parameters

pData	Pointer to the data pointer
pDataDelete	The default data deletion procedure

See also

append(Object*), prepend(void*, Object::ProcDataDelete)

destroy()

void Burger::LinkedListObjects::destroy ( Object * pObject )

noexcept

Remove an object from the list and dispose of it.

---

If the input is not nullptr, detach the object from the list and then dispose of it. If the object was the head of the list, the next item will be made the new head. If this was the only item in the list, the list will be have the head set to nullptr

Parameters

pObject

Pointer to the Object to delete

See also

append(Object*)

get_count()

Burger::LinkedListObjects::get_count ( void ) const

inlinenoexcept

Return the number of Objects in the list.

---

Return 0 if the list is empty, the count of objects otherwise.

See also

get_last() or get_first()

get_data()

void * Burger::LinkedListObjects::get_data ( uint32_t uIndex ) const

noexcept

Get the data from an indexed entry in the list.

---

Iterate over the linked list "uIndex" times and return the data from that object.

If the index is out of bounds, return nullptr

Parameters

uIndex

0 for the first entry, 1 for the second and so on.

Returns

Data in the Object::get_data() field.

See also

Object::get_data()

get_first()

Burger::LinkedListObjects::Object * Burger::LinkedListObjects::get_first ( void ) const

inlinenoexcept

Return the pointer to the first object in the list.

---

If there are no entries in the list, return nullptr. Otherwise, return the pointer of the first item in the linked list.

Note

This function should not be used to determine if the list is empty. Use get_count() instead.

See also

get_last(), get_first_data() or get_count()

get_first_data()

void * Burger::LinkedListObjects::get_first_data ( void ) const

noexcept

Return the data pointer from the first object in the list.

---

If there are no entries in the list, return nullptr. Otherwise, return the data pointer of the first item in the linked list.

Note

This function should not be used to determine if the list is empty. Use get_count() instead.

See also

get_first(), get_last_data() or get_count()

get_last()

Burger::LinkedListObjects::Object * Burger::LinkedListObjects::get_last ( void ) const

noexcept

Return the pointer to the last object in the list.

---

If there are no entries in the list, return nullptr. Otherwise, return the pointer of the last item in the linked list.

Note

This function should not be used to determine if the list is empty. Use get_count() instead.

See also

get_last_data(), get_first() or get_count()

get_last_data()

void * Burger::LinkedListObjects::get_last_data ( void ) const

noexcept

Return the data pointer from the last object in the list.

---

If there are no entries in the list, return nullptr. Otherwise, return the data pointer of the last item in the linked list.

Note

This function should not be used to determine if the list is empty. Use get_count() instead.

See also

get_last(), get_first_data() or get_count()

get_object() [1/2]

Burger::LinkedListObjects::Object * Burger::LinkedListObjects::get_object ( uint32_t uIndex ) const

noexcept

Get the data from an indexed entry in the list.

---

Iterate over the linked list "uIndex" times and return the data from that object.

If the index is out of bounds, return nullptr

Parameters

uIndex

0 for the first entry, 1 for the second and so on.

Returns

Data in the Object::get_data() field.

See also

Object::get_data()

get_object() [2/2]

Burger::LinkedListObjects::Object * Burger::LinkedListObjects::get_object ( void * pData ) const

noexcept

Traverse the linked list until an entry matches the supplied data.

---

Returns nullptr if the data is not in the list

Parameters

pData

Data pointer to scan for

Returns

Pointer to the located Object or nullptr if a match was not found

get_string_index()

uint32_t Burger::LinkedListObjects::get_string_index ( const char * pString ) const

noexcept

Traverse the linked list until an entry matches the supplied "C" string.

---

Returns UINT32_MAX if the string is not in the list. The comparison is case insensitive

0 is the first object, 1 is the second object and so on...

Parameters

pString

A pointer to a "C" string to scan for

Returns

Numeric index in the list of the location of the string or -1 if not found

get_string_object()

Burger::LinkedListObjects::Object * Burger::LinkedListObjects::get_string_object ( const char * pString ) const

noexcept

Traverse the linked list until an entry matches the supplied "C" string.

---

Returns nullptr if the string is not in the list. The comparison is case insensitive

Parameters

pString

A pointer to a "C" string to scan for

Returns

Pointer to the located Object or nullptr if a match was not found

iterate_forward()

Burger::LinkedListObjects::Object * Burger::LinkedListObjects::iterate_forward ( ProcAction pProc )

noexcept

Forward iterate over the linked list.

---

Call a callback function on each and every entry in the list.

The function returns kContinue to continue iteration, kAbort to stop iteration and kDeleteObject to tell the iterator to call the disposal function at a safe time. kAbort and kDeleteObject can be or'd together to perform both actions.

Parameters

pProc

Function callback

Returns

nullptr if the list iterated to the end, or an Object pointer when kAbort was returned

See also

ProcAction or iterate_reverse(ProcAction)

iterate_reverse()

Burger::LinkedListObjects::Object * Burger::LinkedListObjects::iterate_reverse ( ProcAction pProc )

noexcept

Reverse iterate over the linked list.

---

Call a callback function on each and every entry in the list.

The function returns kContinue to continue iteration, kAbort to stop iteration and kDeleteObject to tell the iterator to call the disposal function at a safe time. kAbort and kDeleteObject can be or'd together to perform both actions.

Parameters

pProc

Function callback

Returns

nullptr if the list iterated to the end, or an Object pointer when kAbort was returned

See also

ProcAction or iterate_forward(ProcAction)

operator=() [1/2]

LinkedListObjects & Burger::LinkedListObjects::operator= ( const LinkedListObjects & )

privatedelete

operator=() [2/2]

LinkedListObjects & Burger::LinkedListObjects::operator= ( LinkedListObjects && )

privatedelete

prepend() [1/3]

void Burger::LinkedListObjects::prepend ( const char * pString )

noexcept

Add a copy of a string into the linked list.

---

Make a copy of the input string and append the string to the beginning of the linked list

Parameters

pString

Pointer to the "C" to copy.

See also

append(const char*)

prepend() [2/3]

void Burger::LinkedListObjects::prepend ( Object * pObject )

noexcept

Add a data object to the beginning of the list.

---

Accept an Object entry and insert it into the beginning of the linked list.

Parameters

pObject

Pointer to the Object to prepend

See also

prepend(void *,Object::ProcDataDelete), append(Object *)

prepend() [3/3]

void Burger::LinkedListObjects::prepend ( void * pData, Object::ProcDataDelete pDataDelete = Object::proc_free_object_and_data )

noexcept

Add a pointer of data to the beginning of the list.

---

Allocate a new Object entry and attach this data pointer to it. Insert the new Object at the beginning of the list.

Parameters

pData	Pointer to the data pointer
pDataDelete	The default data deletion procedure

See also

prepend(Object *), append(void *,Object::ProcDataDelete)

shutdown()

void Burger::LinkedListObjects::shutdown ( void )

noexcept

Dispose of all data.

---

Iterate though all of the linked list items and either use a default destructor or a custom destructor to dispose of the contents

See also

~LinkedListObjects() or destroy(Object*)

Member Data Documentation

kAbort

const uint32_t Burger::LinkedListObjects::kAbort = 0x01

static

Abort iteration.

kContinue

const uint32_t Burger::LinkedListObjects::kContinue = 0

static

Don't do anything.

kDeleteObject

const uint32_t Burger::LinkedListObjects::kDeleteObject = 0x02

static

Delete this object and continue iterating.

m_pRoot

Object* Burger::LinkedListObjects::m_pRoot

private

Root linked list entry.

m_uCount

uint32_t Burger::LinkedListObjects::m_uCount

private

Number of objects in the list.