List module interface file. More...

#include "mcl/mcl_common.h"

Include dependency graph for mcl_list.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	mcl_list_node_t

struct	mcl_list_t

Typedefs
typedef E_MCL_ERROR_CODE(*	mcl_list_compare_callback) (void reference_item, const void item_to_compare)

typedef void(*	mcl_list_item_destroy_callback) (void **item)

Functions
MCL_EXPORT E_MCL_ERROR_CODE	mcl_list_initialize (mcl_list_t **list)
	Initializes a list with zero items in it. More...

MCL_EXPORT E_MCL_ERROR_CODE	mcl_list_add (mcl_list_t list, void data)
	Adds a new item to list. More...

MCL_EXPORT E_MCL_ERROR_CODE	mcl_list_next (mcl_list_t list, mcl_list_node_t *node)
	Gets the next node from the list. More...

MCL_EXPORT E_MCL_ERROR_CODE	mcl_list_remove (mcl_list_t list, mcl_list_node_t node)
	Removes a node from the list. More...

MCL_EXPORT E_MCL_ERROR_CODE	mcl_list_remove_with_content (mcl_list_t list, mcl_list_node_t node, mcl_list_item_destroy_callback callback)
	Removes a node from the list and destroys the removed item with the provided callback function. More...

MCL_EXPORT E_MCL_ERROR_CODE	mcl_list_exist (mcl_list_t list, const void item_to_find, mcl_list_compare_callback compare_function, void **item)
	Searches `item_to_find` in the `list`. More...

MCL_EXPORT void	mcl_list_reset (mcl_list_t *list)
	Reset the current node to head node. More...

MCL_EXPORT void	mcl_list_destroy (mcl_list_t **list)
	Destroys the list. More...

MCL_EXPORT void	mcl_list_destroy_with_content (mcl_list_t **list, mcl_list_item_destroy_callback callback)
	Destroys the list and its items with a given callback function. More...

Detailed Description

List module interface file.

Copyright: Copyright (C) 2017 Siemens Aktiengesellschaft.
All rights reserved.

Date: Oct 30, 2017 The list interface provides mcl_list_t data structure for linked lists and functions for list operations.

Definition in file mcl_list.h.

Typedef Documentation

typedef E_MCL_ERROR_CODE(* mcl_list_compare_callback) (void *reference_item, const void *item_to_compare)

Callback function prototype to compare item_to_compare to the reference_item.

Parameters

[in]	reference_item	Reference item to compare to.
[in]	item_to_compare	Item to compare with the `reference_item`.

Returns

MCL_OK in case of match.
MCL_FAIL in case of mismatch.

Definition at line 59 of file mcl_list.h.

typedef void(* mcl_list_item_destroy_callback) (void **item)

Callback function prototype to destroy a list item.

Parameters

[in] item Address of pointer to the item.

Definition at line 66 of file mcl_list.h.

Function Documentation

MCL_EXPORT E_MCL_ERROR_CODE mcl_list_add	(	mcl_list_t *	list,
		void *	data
	)

Adds a new item to list.

A new list item pointed by data is added to the list. No new memory is allocated and no memory copy operations done. The lifetime of data should be handled by the caller of this function.

Parameters

[in]	list	The list to which the data is added.
[in]	data	The pointer to the list item to be added.

Returns

MCL_OK in case of success.
MCL_TRIGGERED_WITH_NULL in case any input parameter is NULL.
MCL_OUT_OF_MEMORY in case there is not enough memory in the system to proceed.
MCL_LIMIT_EXCEEDED in case list is full and data can not be added to list.

Definition at line 32 of file list.c.

References ASSERT_NOT_NULL, DEBUG_ENTRY, DEBUG_LEAVE, and list_add().

Here is the call graph for this function:

MCL_EXPORT void mcl_list_destroy ( mcl_list_t ** list )

Destroys the list.

For every node in the list, it frees the node but not the data it holds. After all nodes freed, it frees the list itself and sets it's value to NULL.

User needs to free all the data that the list is holding before destroying it!

Parameters

[in] list The address of the pointer of the list to be destroyed.

Definition at line 121 of file list.c.

References DEBUG_ENTRY, DEBUG_LEAVE, and list_destroy().

Here is the call graph for this function:

MCL_EXPORT void mcl_list_destroy_with_content	(	mcl_list_t **	list,
		mcl_list_item_destroy_callback	callback
	)

Destroys the list and its items with a given callback function.

For every node in the list, it frees the node. The data of the node can also freed by given callback function. After all nodes freed, it frees the list itself and sets it's value to NULL.

Parameters

[in]	list	The address of the pointer of the list to be destroyed.
[in]	callback	The callback function to destroy each node data within the list. If NULL no action will be performed.

Definition at line 130 of file list.c.

References DEBUG_ENTRY, DEBUG_LEAVE, and list_destroy_with_content().

Here is the call graph for this function:

MCL_EXPORT E_MCL_ERROR_CODE mcl_list_exist	(	mcl_list_t *	list,
		const void *	item_to_find,
		mcl_list_compare_callback	compare_function,
		void **	item
	)

Searches item_to_find in the list.

Parameters

[in]	list	The list to search in.
[in]	item_to_find	Item to search for.
[in]	compare_function	Callback function used to compare.
[out]	item	Pointer to the item found.

Returns

MCL_OK if item_to_find exists in the list.
MCL_TRIGGERED_WITH_NULL in case any input parameter is NULL.
MCL_FAIL if item_to_find doesn't exist in the list.

Definition at line 96 of file list.c.

References ASSERT_NOT_NULL, DEBUG_ENTRY, DEBUG_LEAVE, and list_exist().

Here is the call graph for this function:

MCL_EXPORT E_MCL_ERROR_CODE mcl_list_initialize ( mcl_list_t ** list )

Initializes a list with zero items in it.

Parameters

[out] list Initialized mcl_list_t instance.

Returns

MCL_OK in case of success.
MCL_TRIGGERED_WITH_NULL in case input parameter is NULL.
MCL_OUT_OF_MEMORY in case there is not enough memory in the system to proceed.

Definition at line 19 of file list.c.

References ASSERT_NOT_NULL, DEBUG_ENTRY, DEBUG_LEAVE, and list_initialize().

Here is the call graph for this function:

MCL_EXPORT E_MCL_ERROR_CODE mcl_list_next	(	mcl_list_t *	list,
		mcl_list_node_t **	node
	)

Gets the next node from the list.

Last returned node is kept in list. This function can be called consequently to loop over the list. If there is no node left to return or the list is empty, node will be NULL.

Parameters

[in]	list	The list.
[out]	node	Address of next node.

Returns

MCL_OK in case of success.
MCL_TRIGGERED_WITH_NULL in case any input parameter is NULL.
MCL_FAIL if there is no node in the list.

Definition at line 46 of file list.c.

References ASSERT_NOT_NULL, DEBUG_ENTRY, DEBUG_LEAVE, list_next(), MCL_FAIL, MCL_NULL, and MCL_OK.

Here is the call graph for this function:

MCL_EXPORT E_MCL_ERROR_CODE mcl_list_remove	(	mcl_list_t *	list,
		mcl_list_node_t *	node
	)

Removes a node from the list.

The list node is removed from the list and its handle of type mcl_list_node_t will be freed but the data that it holds will not. User needs to free the resource before it calls remove!

Parameters

[in]	list	The list from which the node is removed.
[in]	node	The node to be removed.

Returns

MCL_OK in case of success.
MCL_TRIGGERED_WITH_NULL in case any input parameter is NULL.
MCL_ARRAY_IS_EMPTY in case list is empty.

Definition at line 67 of file list.c.

References ASSERT_NOT_NULL, DEBUG_ENTRY, DEBUG_LEAVE, and list_remove().

Here is the call graph for this function:

MCL_EXPORT E_MCL_ERROR_CODE mcl_list_remove_with_content	(	mcl_list_t *	list,
		mcl_list_node_t *	node,
		mcl_list_item_destroy_callback	callback
	)

Removes a node from the list and destroys the removed item with the provided callback function.

The node (mcl_list_node_t) will be freed and the data that it holds is going to be destroyed by passing it to the provided callback function.

Parameters

[in]	list	The list from which the node is removed.
[in]	node	The node to be removed.
[in]	callback	The callback function to destroy the list item.

Returns

MCL_OK in case of success.
MCL_TRIGGERED_WITH_NULL in case any input parameter is NULL.
MCL_ARRAY_IS_EMPTY in case list is empty.

Definition at line 81 of file list.c.

References ASSERT_NOT_NULL, DEBUG_ENTRY, DEBUG_LEAVE, and list_remove_with_content().

Here is the call graph for this function:

MCL_EXPORT void mcl_list_reset ( mcl_list_t * list )

Reset the current node to head node.

The goal here is to be able to loop over the list from it's beginning.

Parameters

[in] list The list which is used to reset it's current node to it's head node.

Definition at line 112 of file list.c.

References DEBUG_ENTRY, DEBUG_LEAVE, and list_reset().

Here is the call graph for this function:

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation