S2OPC OPCUA Toolkit: /builds/systerel/S2OPC/src/Common/helpers/sopc_singly_linked

A singly linked list based on elements with unique identifiers and dynamically allocated. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Typedefs
typedef struct SOPC_SLinkedList	SOPC_SLinkedList
	Singly linked list structure. More...

typedef struct SOPC_SLinkedList_Elt	SOPC_SLinkedList_Elt

typedef SOPC_SLinkedList_Elt *	SOPC_SLinkedListIterator

Functions
SOPC_SLinkedList *	SOPC_SLinkedList_Create (size_t sizeMax)
	Create and allocate a new singly linked list containing 0 elements with a size limit of the given size. More...

uintptr_t	SOPC_SLinkedList_Prepend (SOPC_SLinkedList *list, uint32_t id, uintptr_t value)
	Add a new element (and allocate new list element) before head of the given linked list. More...

uintptr_t	SOPC_SLinkedList_Append (SOPC_SLinkedList *list, uint32_t id, uintptr_t value)
	Add a new element (and allocate new list element) to the tail of the given linked list. More...

uintptr_t	SOPC_SLinkedList_SortedInsert (SOPC_SLinkedList list, uint32_t id, uintptr_t value, int8_t(pCompFn)(uintptr_t left, uintptr_t right))
	Insert element in sorted list in correct index regarding compare function. More...

uintptr_t	SOPC_SLinkedList_PopHead (SOPC_SLinkedList *list)
	Get and remove the head element of the list. More...

uintptr_t	SOPC_SLinkedList_PopLast (SOPC_SLinkedList *list)
	Get and remove the last element of the list. More...

uintptr_t	SOPC_SLinkedList_GetHead (SOPC_SLinkedList *list)
	Get the head element of the list without removing it. Note: it shall not be freed. More...

uintptr_t	SOPC_SLinkedList_GetLast (SOPC_SLinkedList *list)
	Get the tail element of the list without removing it. Note: it shall not be freed. More...

uintptr_t	SOPC_SLinkedList_FindFromId (SOPC_SLinkedList *list, uint32_t id)
	Find the first value associated to the given id in the linked list (iterate from head to tail) More...

void	SOPC_SLinkedList_Apply (SOPC_SLinkedList list, void(pFn)(uint32_t id, uintptr_t val))
	Apply a function to the value of each element of the list. More...

uintptr_t	SOPC_SLinkedList_RemoveFromId (SOPC_SLinkedList *list, uint32_t id)
	Find and remove the first value associated to the given id in the linked list (iterate from head to tail) More...

uintptr_t	SOPC_SLinkedList_RemoveFromValuePtr (SOPC_SLinkedList *list, uintptr_t value)
	Find and remove the first value pointer equal in the linked list (iterate from head to tail) More...

void	SOPC_SLinkedList_Clear (SOPC_SLinkedList *list)
	Delete all elements of the given linked list. More...

void	SOPC_SLinkedList_Delete (SOPC_SLinkedList *list)
	Delete and deallocate the given linked list. More...

void	SOPC_SLinkedList_EltGenericFree (uint32_t id, uintptr_t val)
	Frees the value of an element of the SOPC_SLinkedList. More...

SOPC_SLinkedListIterator	SOPC_SLinkedList_GetIterator (SOPC_SLinkedList *list)
	Get an iterator on a linked list to iterate on elements from head to tail. More...

bool	SOPC_SLinkedList_HasNext (const SOPC_SLinkedListIterator *it)
	Return true if iterator has a non NULL value to provide on next iteration (iterate from head to tail) More...

uintptr_t	SOPC_SLinkedList_Next (SOPC_SLinkedListIterator *it)
	Return the next element pointed by iterator in the linked list (iterate from head to tail) More...

uintptr_t	SOPC_SLinkedList_NextWithId (SOPC_SLinkedListIterator it, uint32_t pId)
	Return the next element pointed by iterator in the linked list (iterate from head to tail) More...

uint32_t	SOPC_SLinkedList_GetLength (SOPC_SLinkedList *list)
	Get the number of elements in the linked list. More...

uint32_t	SOPC_SLinkedList_GetCapacity (SOPC_SLinkedList *list)
	Get the maximum number of elements that can be contained in the linked list. More...

bool	SOPC_SLinkedList_SetCapacity (SOPC_SLinkedList *list, size_t sizeMax)
	Set the maximum number of elements that can be contained in the linked list. It might be used to modify the value provided on SOPC_SLinkedList_Create. Call to this function will fail if the current length is greater than provided value. More...

Detailed Description

A singly linked list based on elements with unique identifiers and dynamically allocated.

Typedef Documentation

◆ SOPC_SLinkedList

typedef struct SOPC_SLinkedList SOPC_SLinkedList

Singly linked list structure.

◆ SOPC_SLinkedList_Elt

typedef struct SOPC_SLinkedList_Elt SOPC_SLinkedList_Elt

◆ SOPC_SLinkedListIterator

typedef SOPC_SLinkedList_Elt* SOPC_SLinkedListIterator

Function Documentation

◆ SOPC_SLinkedList_Create()

SOPC_SLinkedList* SOPC_SLinkedList_Create ( size_t sizeMax )

Create and allocate a new singly linked list containing 0 elements with a size limit of the given size.

Parameters

sizeMax The maximum number of elements allowed in the new linked list or 0 if no limit defined

Returns: Pointer to the newly allocated singly linked list

◆ SOPC_SLinkedList_Prepend()

uintptr_t SOPC_SLinkedList_Prepend	(	SOPC_SLinkedList *	list,
		uint32_t	id,
		uintptr_t	value
	)

Add a new element (and allocate new list element) before head of the given linked list.

Parameters

list	Pointer on the linked list in which new element must be added
id	Unique identifier to associate with the element (if not unique Prepend has LIFO behavior for Find and Remove)
value	Pointer to the value or unsigned integer value of the element to prepend. Value 0 is considered invalid.

Returns: Pointer to the value or unsigned integer value prepended, provided as parameter, if succeeded, 0 (NULL) otherwise

◆ SOPC_SLinkedList_Append()

uintptr_t SOPC_SLinkedList_Append	(	SOPC_SLinkedList *	list,
		uint32_t	id,
		uintptr_t	value
	)

Add a new element (and allocate new list element) to the tail of the given linked list.

Parameters

list	Pointer on the linked list in which new element must be added
id	Unique identifier to associate with the element (if not unique Append has FIFO behavior for Find and Remove)
value	Pointer to the value or unsigned integer value of the element to append Value 0 is considered invalid.

Returns: Pointer to the value or unsigned integer value appended, provided as parameter, if succeeded, 0 (NULL) otherwise

◆ SOPC_SLinkedList_SortedInsert()

uintptr_t SOPC_SLinkedList_SortedInsert	(	SOPC_SLinkedList *	list,
		uint32_t	id,
		uintptr_t	value,
		int8_t(*)(uintptr_t left, uintptr_t right)	pCompFn
	)

Insert element in sorted list in correct index regarding compare function.

The element will be inserted before the element for which the compare function return that new element is < to the existing element (compare returns -1 when new element is left operand and < to right operand).

Note: Important: the provided list shall be sorted regarding the same compare function.

Parameters

list	Pointer to the linked list
id	Identifier of the given value
value	Value to insert in the sorted list. Value 0 is considered invalid.
pCompFn	Compare function pointer returning a int8_t equals to -1 if left value < right value, 0 if left value == right value and 1 if left value > right value

Returns: Pointer to the value or unsigned integer value inserted, provided as parameter, if succeeded, 0 (NULL) otherwise

◆ SOPC_SLinkedList_PopHead()

uintptr_t SOPC_SLinkedList_PopHead ( SOPC_SLinkedList * list )

Get and remove the head element of the list.

Parameters

list	Pointer on the linked list from which head element must be returned and removed

Returns: Pointer to the head element value of the list or 0 (NULL) if list is empty

◆ SOPC_SLinkedList_PopLast()

uintptr_t SOPC_SLinkedList_PopLast ( SOPC_SLinkedList * list )

Get and remove the last element of the list.

Note: This function iterate on the whole list to remove the last element

Parameters

list	Pointer on the linked list from which head element must be returned and removed

Returns: Pointer to the last element value of the list or 0 (NULL) if list is empty

◆ SOPC_SLinkedList_GetHead()

uintptr_t SOPC_SLinkedList_GetHead ( SOPC_SLinkedList * list )

Get the head element of the list without removing it. Note: it shall not be freed.

Parameters

list	Pointer on the linked list from which head element must be returned

Returns: Pointer to the head element value of the list or 0 (NULL) if list is empty

◆ SOPC_SLinkedList_GetLast()

uintptr_t SOPC_SLinkedList_GetLast ( SOPC_SLinkedList * list )

Get the tail element of the list without removing it. Note: it shall not be freed.

Parameters

list	Pointer on the linked list from which tail element must be returned

Returns: Pointer to the tail element value of the list or 0 (NULL) if list is empty

◆ SOPC_SLinkedList_FindFromId()

uintptr_t SOPC_SLinkedList_FindFromId	(	SOPC_SLinkedList *	list,
		uint32_t	id
	)

Find the first value associated to the given id in the linked list (iterate from head to tail)

Parameters

list	Pointer on the linked list in which element must be found
id	Unique identifier associated with the element to find

Returns: Pointer to the value or unsigned integer value found if succeeded, 0 (NULL) otherwise

◆ SOPC_SLinkedList_Apply()

void SOPC_SLinkedList_Apply	(	SOPC_SLinkedList *	list,
		void(*)(uint32_t id, uintptr_t val)	pFn
	)

Apply a function to the value of each element of the list.

An example is the SOPC_SLinkedList_EltGenericFree() function which frees the value of each element of the list.

Parameters

list	Pointer to the linked list
pFn	Function pointer which takes the id and the value of each element

◆ SOPC_SLinkedList_RemoveFromId()

uintptr_t SOPC_SLinkedList_RemoveFromId	(	SOPC_SLinkedList *	list,
		uint32_t	id
	)

Find and remove the first value associated to the given id in the linked list (iterate from head to tail)

Parameters

list	Pointer on the linked list in which element must be found
id	Unique identifier associated with the element to remove

Returns: Pointer to the value or unsigned integer value removed if succeeded, 0 (NULL) otherwise

◆ SOPC_SLinkedList_RemoveFromValuePtr()

uintptr_t SOPC_SLinkedList_RemoveFromValuePtr	(	SOPC_SLinkedList *	list,
		uintptr_t	value
	)

Find and remove the first value pointer equal in the linked list (iterate from head to tail)

Parameters

list	Pointer on the linked list in which element must be found
value	Pointer to the value or unsigned integer value of the element to remove. Value 0 is considered invalid.

Returns: Pointer to the value or unsigned integer value removed if succeeded, 0 (NULL) otherwise

◆ SOPC_SLinkedList_Clear()

void SOPC_SLinkedList_Clear ( SOPC_SLinkedList * list )

Delete all elements of the given linked list.

Parameters

list	Pointer to the list of elements to be deleted

◆ SOPC_SLinkedList_Delete()

void SOPC_SLinkedList_Delete ( SOPC_SLinkedList * list )

Delete and deallocate the given linked list.

Parameters

list	Pointer to the list to deallocate (pointer must not be used anymore after operation)

◆ SOPC_SLinkedList_EltGenericFree()

void SOPC_SLinkedList_EltGenericFree	(	uint32_t	id,
		uintptr_t	val
	)

Frees the value of an element of the SOPC_SLinkedList.

Parameters

id	Unique identifier associated with the element
val	Element to be freed

◆ SOPC_SLinkedList_GetIterator()

SOPC_SLinkedListIterator SOPC_SLinkedList_GetIterator ( SOPC_SLinkedList * list )

Get an iterator on a linked list to iterate on elements from head to tail.

Parameters

list	Pointer to the list for which an iterator is requested

Returns: An iterator on the given linked list

◆ SOPC_SLinkedList_HasNext()

bool SOPC_SLinkedList_HasNext ( const SOPC_SLinkedListIterator * it )

Return true if iterator has a non NULL value to provide on next iteration (iterate from head to tail)

Parameters

it	An iterator on a linked list

Returns: true if iterator has a non NULL value to provide on next iteration, false otherwise

◆ SOPC_SLinkedList_Next()

uintptr_t SOPC_SLinkedList_Next ( SOPC_SLinkedListIterator * it )

Return the next element pointed by iterator in the linked list (iterate from head to tail)

Parameters

it	An iterator on a linked list

Returns: Pointer to the value or unsigned integer value of the next element of the linked list

◆ SOPC_SLinkedList_NextWithId()

uintptr_t SOPC_SLinkedList_NextWithId	(	SOPC_SLinkedListIterator *	it,
		uint32_t *	pId
	)

Return the next element pointed by iterator in the linked list (iterate from head to tail)

Parameters

it	An iterator on a linked list
pId	Pointer in which the next element id of the linked list is set

Returns: Pointer to the value or unsigned integer value of the next element of the linked list

◆ SOPC_SLinkedList_GetLength()

uint32_t SOPC_SLinkedList_GetLength ( SOPC_SLinkedList * list )

Get the number of elements in the linked list.

Parameters

list	Pointer to the list

Returns: The number of elements in the list

◆ SOPC_SLinkedList_GetCapacity()

uint32_t SOPC_SLinkedList_GetCapacity ( SOPC_SLinkedList * list )

Get the maximum number of elements that can be contained in the linked list.

Parameters

list	Pointer to the list

Returns: The capacity of the list

◆ SOPC_SLinkedList_SetCapacity()

bool SOPC_SLinkedList_SetCapacity	(	SOPC_SLinkedList *	list,
		size_t	sizeMax
	)

Set the maximum number of elements that can be contained in the linked list. It might be used to modify the value provided on SOPC_SLinkedList_Create. Call to this function will fail if the current length is greater than provided value.

Parameters

list	Pointer to the list
sizeMax	The maximum number of elements allowed in the new linked list or 0 if no limit defined. If the current list length is greater than the provided value, call will fail.

Returns: true if the list capacity has been set, false otherwise

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ SOPC_SLinkedList

◆ SOPC_SLinkedList_Elt

◆ SOPC_SLinkedListIterator

Function Documentation

◆ SOPC_SLinkedList_Create()

◆ SOPC_SLinkedList_Prepend()

◆ SOPC_SLinkedList_Append()

◆ SOPC_SLinkedList_SortedInsert()

◆ SOPC_SLinkedList_PopHead()

◆ SOPC_SLinkedList_PopLast()

◆ SOPC_SLinkedList_GetHead()

◆ SOPC_SLinkedList_GetLast()

◆ SOPC_SLinkedList_FindFromId()

◆ SOPC_SLinkedList_Apply()

◆ SOPC_SLinkedList_RemoveFromId()

◆ SOPC_SLinkedList_RemoveFromValuePtr()

◆ SOPC_SLinkedList_Clear()

◆ SOPC_SLinkedList_Delete()

◆ SOPC_SLinkedList_EltGenericFree()

◆ SOPC_SLinkedList_GetIterator()

◆ SOPC_SLinkedList_HasNext()

◆ SOPC_SLinkedList_Next()

◆ SOPC_SLinkedList_NextWithId()

◆ SOPC_SLinkedList_GetLength()

◆ SOPC_SLinkedList_GetCapacity()

◆ SOPC_SLinkedList_SetCapacity()