List Collection

This section contains a list implementation. More...

Modules
	Object List API
	This API is useful for object value types including strings.
	Typed List API
	This API is useful for scalar types such as int, long or bool.

Macros
#define	ruListAppend(rl, data)   ruListAppendPtr(rl, (perm_ptr)(data))
	Calls ruListAppendPtr but handles the void* cast.
#define	ruListPush(rl, data)   ruListAppendPtr(rl, (perm_ptr)(data))
	Stack usage synonym for ruListAppend.
#define	ruListIter(rl)   ruListHead(rl, NULL)
	Returns the first element in the given list to iterate over.

Typedefs
typedef void *	ruList
	Opaque pointer to list object. See List Collection.
typedef void *	ruListElmt
	Opaque pointer to list element object. See List Collection.
typedef void *	ruIterator
	Opaque pointer to list iterator object. See List Collection.

Functions
RUAPI ruList	ruListNew (ruType valueType)
	Creates a new list object. To be freed with ruListFree.
RUAPI ruList	ruListNewBound (ruType valueType, uint32_t maxSize, bool ordered)
	Creates a new bound list object. To be freed with ruListFree.
RUAPI int32_t	ruListBind (ruList rl, bool bound)
	Allows ignoring or obeying the ruListNewBound maxSize of a ruList.
RUAPI ruList	ruListFree (ruList rl)
	Frees the given list object.
RUAPI int32_t	ruListClear (ruList rl)
	Clears the given list.
RUAPI int32_t	ruListAppendPtr (ruList rl, perm_ptr data)
	Appends the given object to the list.
RUAPI int32_t	ruListInsertIdx (ruList rl, int32_t index, perm_ptr data)
	Inserts given object at indexed position in list in given list element.
RUAPI int32_t	ruListInsertBefore (ruList rl, ruListElmt rle, perm_ptr data)
	Inserts given object before given list element.
RUAPI int32_t	ruListInsertAfter (ruList rl, ruListElmt rle, perm_ptr data)
	Inserts given object after given list element.
RUAPI uint32_t	ruListSize (ruList rl, int32_t *code)
	Returns the number of elements in the list.
RUAPI alloc_chars	ruListJoin (ruList rl, trans_chars delim, int32_t *code)
	Joins a list of char* item with given delim.
RUAPI int32_t	ruListSort (ruList rl)
	Sorts the given list using the associated types comparator function.
RUAPI ruListElmt	ruListHead (ruList rl, int32_t *code)
	Returns the first element in the given list.
RUAPI ruListElmt	ruListTail (ruList rl, int32_t *code)
	Returns the last element in the given list.
RUAPI bool	ruListElmtIsHead (ruListElmt re, int32_t *code)
	Indicates whether given element is the first in the given list.
RUAPI bool	ruListElmtIsTail (ruListElmt re, int32_t *code)
	Indicates whether given element is the last in the given list.
RUAPI ruListElmt	ruListNextElmt (ruListElmt re, int32_t *code)
	Return the next element following the given element from list.

Detailed Description

This section contains a list implementation.

The list has typed and non typed variants and can also be used as a queue. The list is made thread safe by a mutex that is locked during read and write operations.

Macro Definition Documentation

ruListAppend

#define ruListAppend	(		rl,
			data
	)		ruListAppendPtr(rl, (perm_ptr)(data))

Calls ruListAppendPtr but handles the void* cast.

Parameters

rl	List to append object to.
data	Object to append.

Returns

RUE_OK on success RUE_USER_ABORT when a threaded list has quit else a regify error code.

ruListIter

#define ruListIter

(

rl

)

ruListHead(rl, NULL)

Returns the first element in the given list to iterate over.

Parameters

rl	List to return element of.

Returns

The first element of the list or NULL on failure.

ruListPush

#define ruListPush	(		rl,
			data
	)		ruListAppendPtr(rl, (perm_ptr)(data))

Stack usage synonym for ruListAppend.

Parameters

rl	List to append object to.
data	Object to append.

Returns

RUE_OK on success RUE_USER_ABORT when a threaded list has quit else a regify error code.

Typedef Documentation

ruIterator

typedef void* ruIterator

Opaque pointer to list iterator object. See List Collection.

ruList

typedef void* ruList

Opaque pointer to list object. See List Collection.

ruListElmt

typedef void* ruListElmt

Opaque pointer to list element object. See List Collection.

Function Documentation

ruListAppendPtr()

RUAPI int32_t ruListAppendPtr	(	ruList	rl,
		perm_ptr	data
	)

Appends the given object to the list.

Parameters

rl	List to append object to.
data	Object to append.

Returns

RUE_OK on success RUE_USER_ABORT when a threaded list has quit else a regify error code.

ruListBind()

RUAPI int32_t ruListBind	(	ruList	rl,
		bool	bound
	)

Allows ignoring or obeying the ruListNewBound maxSize of a ruList.

This is primarily used to unblock threads on termination.

Parameters

rl	list to alter.
bound	Whether to obey (true) or ignore (false) the given maxSize.

Returns

RUE_OK on success RUE_USER_ABORT when a threaded list has quit RUE_INVALID_STATE if the given ruList has no maxSize else a regify error code.

ruListClear()

RUAPI int32_t ruListClear

(

ruList

rl

)

Clears the given list.

Parameters

rl	list to clear

Returns

RUE_OK on success RUE_USER_ABORT when a threaded list has quit else a regify error code.

ruListElmtIsHead()

RUAPI bool ruListElmtIsHead	(	ruListElmt	re,
		int32_t *	code
	)

Indicates whether given element is the first in the given list.

Parameters

re	List element in question
code	(Optional) Stores RUE_OK on success or regify error code.

Returns

true if the element is the first in the list.

ruListElmtIsTail()

RUAPI bool ruListElmtIsTail	(	ruListElmt	re,
		int32_t *	code
	)

Indicates whether given element is the last in the given list.

Parameters

re	List element in question
code	(Optional) Stores RUE_OK on success or regify error code.

Returns

true if the element is the last in the list.

ruListFree()

RUAPI ruList ruListFree

(

ruList

rl

)

Frees the given list object.

Parameters

rl	list to free.

Returns

NULL

ruListHead()

RUAPI ruListElmt ruListHead	(	ruList	rl,
		int32_t *	code
	)

Returns the first element in the given list.

Parameters

rl	List to return element of.
code	(Optional) Stores RUE_OK on success or regify error code.

Returns

The first element of the list or NULL on failure.

ruListInsertAfter()

RUAPI int32_t ruListInsertAfter	(	ruList	rl,
		ruListElmt	rle,
		perm_ptr	data
	)

Inserts given object after given list element.

Parameters

rl	List in which to insert object.
rle	Element after which to insert object. NULL for first element.
data	Object to insert.

Returns

RUE_OK on success RUE_USER_ABORT when a threaded list has quit else a regify error code.

ruListInsertBefore()

RUAPI int32_t ruListInsertBefore	(	ruList	rl,
		ruListElmt	rle,
		perm_ptr	data
	)

Inserts given object before given list element.

Parameters

rl	List in which to insert object.
rle	Element before which to insert object. NULL for first element.
data	Object to insert.

Returns

RUE_OK on success RUE_USER_ABORT when a threaded list has quit else a regify error code.

ruListInsertIdx()

RUAPI int32_t ruListInsertIdx	(	ruList	rl,
		int32_t	index,
		perm_ptr	data
	)

Inserts given object at indexed position in list in given list element.

Parameters

rl	List in which to insert object.
index	Index at which to insert the object. 0(first)/-1(last) element. If index is > list size the item will be appended.
data	Object to insert.

Returns

RUE_OK on success RUE_USER_ABORT when a threaded list has quit else a regify error code.

ruListJoin()

RUAPI alloc_chars ruListJoin	(	ruList	rl,
		trans_chars	delim,
		int32_t *	code
	)

Joins a list of char* item with given delim.

This function should only be called with char* lists.

Parameters

rl	List to join
delim	Delimiter to join with or NULL for blank
code	(Optional) Stores RUE_OK on success or regify error code.

Returns

Joined string to be freed by the caller

ruListNew()

RUAPI ruList ruListNew

(

ruType

valueType

)

Creates a new list object. To be freed with ruListFree.

Parameters

valueType

A value specification. Will be freed by this call.

Returns

Guaranteed to return new list object, or process abort.

ruListNewBound()

RUAPI ruList ruListNewBound	(	ruType	valueType,
		uint32_t	maxSize,
		bool	ordered
	)

Creates a new bound list object. To be freed with ruListFree.

Parameters

valueType	A value specification. Will be freed by this call.
maxSize	A maximum entry size at which incoming additions will block. If 0 will return an unbound list like ruListNew.
ordered	If true guarantees unblocking in the same order in which blocking occurred.

Returns

Guaranteed to return new list object, or process abort.

ruListNextElmt()

RUAPI ruListElmt ruListNextElmt	(	ruListElmt	re,
		int32_t *	code
	)

Return the next element following the given element from list.

Parameters

re	List element to return follower of.
code	(Optional) Stores RUE_OK on success or regify error code.

Returns

Next element or NULL if given element was the last or an error occured.

ruListSize()

RUAPI uint32_t ruListSize	(	ruList	rl,
		int32_t *	code
	)

Returns the number of elements in the list.

Parameters

rl	List to return size of.
code	(Optional) Stores RUE_OK on success or regify error code.

Returns

Number of elements in list or 0 on error.

ruListSort()

RUAPI int32_t ruListSort

(

ruList

rl

)

Sorts the given list using the associated types comparator function.

Parameters

rl	List to sort

Returns

RUE_OK on success RUE_USER_ABORT when a threaded list has quit else a regify error code.

ruListTail()

RUAPI ruListElmt ruListTail	(	ruList	rl,
		int32_t *	code
	)

Returns the last element in the given list.

Parameters

rl	List to return element of.
code	(Optional) Stores RUE_OK on success or regify error code.

Returns

The last element of the list or NULL on failure.