The doubly linked list. More...

Data Structures
struct	LinkedList
	The implementation for doubly linked list. More...

Typedefs
typedef struct _LinkedListData	LinkedListData
	LinkedListData is the data type for the container private information. More...

Functions
int32_t	LinkedListInit (LinkedList **ppObj)
	The constructor for LinkedList. More...

void	LinkedListDeinit (LinkedList **ppObj)
	The destructor for LinkedList. More...

int32_t	LinkedListPushFront (LinkedList *self, Item item)
	Push an item to the head of the list. More...

int32_t	LinkedListPushBack (LinkedList *self, Item item)
	Push an item to the tail of the list. More...

int32_t	LinkedListInsert (LinkedList *self, Item item, int32_t iIdx)
	Insert an item to the designated index of the list. More...

int32_t	LinkedListPopFront (LinkedList *self)
	Pop an item from the head of the list. More...

int32_t	LinkedListPopBack (LinkedList *self)
	Pop an item from the tail of the list. More...

int32_t	LinkedListDelete (LinkedList *self, int32_t iIdx)
	Remove an item from the designated index of the list. More...

int32_t	LinkedListSetFront (LinkedList *self, Item item)
	Replace an item at the head of the list. More...

int32_t	LinkedListSetBack (LinkedList *self, Item item)
	Replace an item at the tail of the list. More...

int32_t	LinkedListSetAt (LinkedList *self, Item item, int32_t iIdx)
	Replace an item at the designated index of the list. More...

int32_t	LinkedListGetFront (LinkedList self, Item pItem)
	Get an item from the head of the list. More...

int32_t	LinkedListGetBack (LinkedList self, Item pItem)
	Get an item from the tail of the list. More...

int32_t	LinkedListGetAt (LinkedList self, Item pItem, int32_t iIdx)
	Get an item from the designated index of the list. More...

int32_t	LinkedListSize (LinkedList *self)
	Return the number of stored items. More...

int32_t	LinkedListReverse (LinkedList *self)
	Reverse the list. More...

int32_t	LinkedListIterate (LinkedList self, bool bReset, Item pItem)
	Iterate through the list till the tail end. More...

int32_t	LinkedListReverseIterate (LinkedList self, bool bReset, Item pItem)
	Reversely iterate through the list till the head end. More...

int32_t	LinkedListReplace (LinkedList *self, Item item)
	Immediately replace the item at a specific iteration. More...

int32_t	LinkedListSetDestroy (LinkedList self, void(pFunc)(Item))
	Set the custom item resource clean method. More...

Detailed Description

The doubly linked list.

Definition in file linked_list.h.

Typedef Documentation

typedef struct _LinkedListData LinkedListData

LinkedListData is the data type for the container private information.

Definition at line 11 of file linked_list.h.

Function Documentation

int32_t LinkedListInit ( LinkedList ** ppObj )

The constructor for LinkedList.

Parameters

ppObj The double pointer to the to be constructed list

Return values

SUCC
ERR_NOMEM	Insufficient memory for list construction

void LinkedListDeinit ( LinkedList ** ppObj )

The destructor for LinkedList.

If the custom resource clean method is set, it also runs the resource clean method for all the items.

Parameters

ppObj The double pointer to the to be destructed list

int32_t LinkedListPushFront	(	LinkedList *	self,
		Item	item
	)

Push an item to the head of the list.

Parameters

self	The pointer to the LinkedList structure
item	The designated item

Return values

SUCC
ERR_NOINIT	Uninitialized container
ERR_NOMEM	Insufficient memory for list extension

int32_t LinkedListPushBack	(	LinkedList *	self,
		Item	item
	)

Push an item to the tail of the list.

Parameters

self	The pointer to the LinkedList structure
item	The designated item

Return values

SUCC
ERR_NOINIT	Uninitialized container
ERR_NOMEM	Insufficient memory for list extension

int32_t LinkedListInsert	(	LinkedList *	self,
		Item	item,
		int32_t	iIdx
	)

Insert an item to the designated index of the list.

This function inserts an item to the designated index of the list and shifts the trailing items one position to the tail. The index can be positive or negative, but its absolute value should be smaller than or equal to the list size. The operation supports both forward and backward indexing. For the former one, the list is traversed from the head to the tail. And for the later one, the direction is reversed. To illustrate the behavior, let N denote the list size. Thus for forward indexing , index (0) and index (N-1) point to the head and tail. And for backward indexing, index (-1) and index (-N) point to the list tail and head. But no matter which indexing method is applied, the list always grows from the head to the tail.

Parameters

self	The pointer to the LinkedList structure
item	The designated item
iIdx	The designated index

Return values

SUCC
ERR_NOINIT	Uninitialized container
ERR_NOMEM	Insufficient memory for list extension
ERR_IDX	Out of range indexing

Note: The absolute value of the index should be smaller than or equal to the list size.

int32_t LinkedListPopFront ( LinkedList * self )

Pop an item from the head of the list.

This function removes an item from the head of the list. If the custom resource clean method is set, it also runs the resource clean method for the removed item.

Parameters

self	The pointer to the LinkedList structure

Return values

SUCC
ERR_NOINIT	Uninitialized container
ERR_IDX	Empty list

int32_t LinkedListPopBack ( LinkedList * self )

Pop an item from the tail of the list.

This function removes an item from the tail of the list. If the custom resource clean method is set, it also runs the resource clean method for the removed item.

Parameters

self	The pointer to the LinkedList structure

Return values

SUCC
ERR_NOINIT	Uninitialized container
ERR_IDX	Empty list

int32_t LinkedListDelete	(	LinkedList *	self,
		int32_t	iIdx
	)

Remove an item from the designated index of the list.

This function removes an item from the designated index of the list and shifts the trailing items one position to the head. If the custom resource clean method is set, it also runs the resource clean method for the removed item. The operation supports both forward and backward indexing. Let N denote the list size and i denote the index. For forward indexing, inequality 0 <= i < N must be fitted. For backward indexing, inequality 0 < i <= -N must be fitted.

Parameters

self	The pointer to the LinkedList structure
iIdx	The designated index

Return values

SUCC
ERR_NOINIT	Uninitialized container
ERR_IDX	Out of range indexing

int32_t LinkedListSetFront	(	LinkedList *	self,
		Item	item
	)

Replace an item at the head of the list.

This function replaces the head item with the designated one. If the custom resource clean method is set, it also runs the resource clean method for the replaced item.

Parameters

self	The pointer to the LinkedList structure
item	The designated item

Return values

SUCC
ERR_NOINIT	Uninitialized container
ERR_IDX	Empty list

int32_t LinkedListSetBack	(	LinkedList *	self,
		Item	item
	)

Replace an item at the tail of the list.

This function replaces the tail item with the designated one. If the custom resource clean method is set, it also runs the resource clean method for the replaced item.

Parameters

self	The pointer to the LinkedList structure
item	The designated item

Return values

SUCC
ERR_NOINIT	Uninitialized container
ERR_IDX	Empty list

int32_t LinkedListSetAt	(	LinkedList *	self,
		Item	item,
		int32_t	iIdx
	)

Replace an item at the designated index of the list.

This function replaces the item at the designated index with the designated one. If the custom resource clean method is set, it also runs the resource clean method for the replaced item. The operation supports both forward and backward indexing. Let N denote the list size and i denote the index. For forward indexing, inequality 0 <= i < N must be fitted. For backward indexing, inequality 0 < i <= -N must be fitted.

Parameters

self	The pointer to the LinkedList structure
item	The designated item
iIdx	The designated index

Return values

SUCC
ERR_NOINIT	Uninitialized container
ERR_IDX	Out of range index

int32_t LinkedListGetFront	(	LinkedList *	self,
		Item *	pItem
	)

Get an item from the head of the list.

Parameters

self	The pointer to the LinkedList structure
pItem	The pointer to the returned item

Return values

SUCC
ERR_NOINIT	Uninitialized container
ERR_IDX	Empty list
ERR_GET	Invalid parameter to store returned item

Note: If the exception occurs, the second parameter will be updated with NULL.

int32_t LinkedListGetBack	(	LinkedList *	self,
		Item *	pItem
	)

Get an item from the tail of the list.

Parameters

self	The pointer to the LinkedList structure
pItem	The pointer to the returned item

Return values

SUCC
ERR_NOINIT	Uninitialized container
ERR_IDX	Empty list
ERR_GET	Invalid parameter to store returned item

Note: If the exception occurs, the second parameter will be updated with NULL.

int32_t LinkedListGetAt	(	LinkedList *	self,
		Item *	pItem,
		int32_t	iIdx
	)

Get an item from the designated index of the list.

The operation supports both forward and backward indexing. Let N denote the list size and i denote the index. For forward indexing, inequality 0 <= i < N must be fitted. For backward indexing, inequality 0 < i <= -N must be fitted.

Parameters

self	The pointer to the LinkedList structure
pItem	The pointer to the returned item
iIdx	The designated index

Return values

SUCC
ERR_NOINIT	Uninitialized container
ERR_IDX	Out of range index
ERR_GET	Invalid parameter to store returned item

Note: If the exception occurs, the second parameter will be updated with NULL.

int32_t LinkedListSize ( LinkedList * self )

Return the number of stored items.

Parameters

self	The pointer to the LinkedList structure

Returns: The number of stored item

Return values

ERR_NOINIT Uninitialized container

int32_t LinkedListReverse ( LinkedList * self )

Reverse the list.

Parameters

self	The pointer to the LinkedList structure

Return values

SUCC
ERR_NOINIT	Uninitialized container

int32_t LinkedListIterate	(	LinkedList *	self,
		bool	bReset,
		Item *	pItem
	)

Iterate through the list till the tail end.

Before iterating through the list, it is necessary to pass bReset := true and pItem := NULL for iterator initialization. After initialization, you can pass bReset := false and pItem := the relevant pointer to get the returned item at each iteration.

Parameters

self	The pointer to the LinkedList structure
bReset	The knob to reset the iteration
pItem	The pointer to the returned item

Return values

SUCC
END	Beyond the tail end
ERR_NOINIT	Uninitialized container
ERR_GET	Invalid parameter to store returned item

int32_t LinkedListReverseIterate	(	LinkedList *	self,
		bool	bReset,
		Item *	pItem
	)

Reversely iterate through the list till the head end.

Before reversely iterating through the list, it is necessary to pass bReset := true and pItem := NULL for iterator initialization. After initialization, you can pass bReset := false and pItem := the relevant pointer to get the returned item at each iteration.

Parameters

self	The pointer to the LinkedList structure
bReset	The knob to reset the iteration
pItem	The pointer to the returned item

Return values

SUCC
END	Beyond the head end
ERR_NOINIT	Uninitialized container
ERR_GET	Invalid parameter to store returned item

int32_t LinkedListReplace	(	LinkedList *	self,
		Item	item
	)

Immediately replace the item at a specific iteration.

This operator should be applied within the scope of iterate() or reverse_iterate() iterators. If the custom resource clean method is set, it also runs the resource clean method for the replaced item

Parameters

self	The pointer to the LinkedList structure
item	The item which intends to take position

Return values

SUCC
ERR_NOINIT	Uninitialized container
ERR_IDX	Out of range indexing

Note: If you intend to use the operator outside of the iterators, the behavior is undefined. Which is, the operator may successfully replace the item or it may return an error code.

int32_t LinkedListSetDestroy	(	LinkedList *	self,
		void(*)(Item)	pFunc
	)

Set the custom item resource clean method.

Parameters

self	The pointer to the LinkedList structure
pFunc	The function pointer to the custom method

Return values

SUCC
ERR_NOINIT	Uninitialized container

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation