Object List API

This API is useful for object value types including strings. More...

Macros
#define	ruIterNext(re, type)   (type) ruListNextData(&(re), NULL)
	Returns the data payload of the next list element casted to type. More...
#define	ruListIdx(rl, index, type, code)   (type)ruListIdxData(rl, index, code)
	Returns the data payload of the element at given 0 based index casted to type. More...

Functions
RUAPI ptr	ruListRemove (ruList rl, ruListElmt *rle, int32_t *code)
	Remove and return the current list element from list. More...
RUAPI ptr	ruListRemoveIdx (ruList rl, int32_t index, int32_t *code)
	Remove and return the list element at index position from list. More...
RUAPI ptr	ruListPop (ruList rl, int32_t *code)
	Return first element of the list. More...
RUAPI ptr	ruListTryPop (ruList rl, msec_t timeoutMs, int32_t *code)
	Tries to return first element of the list. More...
RUAPI ptr	ruListNextData (ruListElmt *re, int32_t *code)
	Returns the data payload of the next list element. More...
RUAPI ptr	ruListIdxData (ruList rl, int32_t index, int32_t *code)
	Returns the data payload of the element at given 0 based index. More...

Detailed Description

This API is useful for object value types including strings.

Example of non typed use:

ruList recipients = ruListNew(NULL);
// We are going to ignore some return codes for brevity.
int32_t ret = ruListAppend(recipients, "bob");
ret = ruListAppend(recipients, "alice");
ruIterator li = ruListIter(recipients);
for(char* recip = ruIterNext(li, char*);
        li; recip = ruIterNext(li, char*)) {
    printf("Recipient: %s", recip);
}
ruListFree(recipients);

Macro Definition Documentation

ruIterNext

#define ruIterNext	(		re,
			type
	)		(type) ruListNextData(&(re), NULL)

Returns the data payload of the next list element casted to type.

Parameters

re	Current list element to get the follower of.
type	Data type to cast the returned data payload to.

Returns

NULL if given element was the last or the data of the next element.

ruListIdx

#define ruListIdx	(		rl,
			index,
			type,
			code
	)		(type)ruListIdxData(rl, index, code)

Returns the data payload of the element at given 0 based index casted to type.

Parameters

rl	List from which to return the element data payload.
index	Index of the element in question. 0 is the first element.
type	Data type to cast the returned data payload to.
code	(Optional) Stores regify error code of this operation. RUE_OK on success RUE_USER_ABORT when a threaded list has quit else a regify error code.

Returns

Data of the given element including NULL or NULL if there was an error.

Function Documentation

ruListIdxData()

RUAPI ptr ruListIdxData	(	ruList	rl,
		int32_t	index,
		int32_t *	code
	)

Returns the data payload of the element at given 0 based index.

Parameters

rl	List from which to return the element data payload.
index	Index of the element in question. 0 is the first element. -1 is the last element.
code	(Optional) Stores regify error code of this operation. RUE_OK on success RUE_USER_ABORT when a threaded list has quit else a regify error code.

Returns

Data of the given element including NULL or NULL if there was an error.

ruListNextData()

RUAPI ptr ruListNextData	(	ruListElmt *	re,
		int32_t *	code
	)

Returns the data payload of the next list element.

Parameters

re	Address of current list element to be updated with the next one.
code	(Optional) Stores RUE_OK on success or regify error code.

Returns

NULL if error or given element was the last or the data of the next element.

ruListPop()

RUAPI ptr ruListPop	(	ruList	rl,
		int32_t *	code
	)

Return first element of the list.

Parameters

rl	List to pop object from.
code	(Optional) Stores regify error code of this operation. RUE_OK on success RUE_FILE_NOT_FOUND on empty list RUE_USER_ABORT when a threaded list has quit else a regify error code.

Returns

Object which was popped off of the list.

ruListRemove()

RUAPI ptr ruListRemove	(	ruList	rl,
		ruListElmt *	rle,
		int32_t *	code
	)

Remove and return the current list element from list.

Parameters

rl	List to remove object from.
rle	Pointer to element to remove, will be set to the previous element to allow for deletion during iteration.
code	(Optional) Stores regify error code of this operation. RUE_OK on success RUE_USER_ABORT when a threaded list has quit else a regify error code.

Returns

Object which was removed from list.

ruListRemoveIdx()

RUAPI ptr ruListRemoveIdx	(	ruList	rl,
		int32_t	index,
		int32_t *	code
	)

Remove and return the list element at index position from list.

Parameters

rl	List to remove object from.
index	0 based postion of the element to remove in the list.
code	(Optional) Stores regify error code of this operation. RUE_OK on success RUE_USER_ABORT when a threaded list has quit else a regify error code.

Returns

Object which was removed from list.

ruListTryPop()

RUAPI ptr ruListTryPop	(	ruList	rl,
		msec_t	timeoutMs,
		int32_t *	code
	)

Tries to return first element of the list.

Parameters

rl	List to pop object from.
timeoutMs	The number of milliseconds to wait for an entry before returning. Setting this to 0 will return after the first check.
code	(Optional) Stores regify error code of this operation. RUE_OK on success RUE_FILE_NOT_FOUND call timed out RUE_USER_ABORT when a threaded list has quit else a regify error code.

Returns

Object which was popped off of the list.