Typed List API

This API is useful for scalar types such as int, long or bool. More...

Macros
#define	ruListRemoveTo(rl, rle, dest)   ruListRemoveDataTo(rl, &(rle), (ptr*)&(dest))
	Remove and return the current list element from list.
#define	ruListRemoveIdxTo(rl, index, dest)   ruListRemoveIdxDataTo(rl, index, (ptr*)&(dest))
	Remove and return the list element at index position from list.
#define	ruListPopTo(rl, dest)   ruListPopDataTo(rl, (ptr*)&(dest))
	Return first element of the list.
#define	ruListTryPopTo(rl, timeoutMs, dest)   ruListTryPopDataTo(rl, timeoutMs, (ptr*)&(dest))
	Tries to return first element of the list.
#define	ruIterTo(re, dest)   ruListNextDataTo(&(re), (ptr*)&(dest))
	Returns the next element data in the given list to iterate over.
#define	ruListIdxTo(rl, index, dest)   ruListIdxDataTo(rl, index, (ptr*)&(dest))
	Returns the data payload of the element at given 0 based index casted to type.

Functions
RUAPI int32_t	ruListRemoveDataTo (ruList rl, ruListElmt *rle, ptr *dest)
	Remove and return the current list element from list.
RUAPI int32_t	ruListRemoveIdxDataTo (ruList rl, int32_t index, ptr *dest)
	Remove and return the list element at index position from list.
RUAPI int32_t	ruListPopDataTo (ruList rl, ptr *dest)
	Return first element of the list.
RUAPI int32_t	ruListTryPopDataTo (ruList rl, msec_t timeoutMs, ptr *dest)
	Tries to return first element of the list.
RUAPI int32_t	ruListNextDataTo (ruListElmt *re, ptr *dest)
	Returns the data payload of the next list element.
RUAPI int32_t	ruListIdxDataTo (ruList rl, int32_t index, ptr *dest)
	Returns the data payload of the element at given 0 based index.

Detailed Description

This API is useful for scalar types such as int, long or bool.

Example of typed use:

// error checking left out for brevity
bool b1 = false;
bool b2 = true;
ruList rl = ruListNew(ruTypeBool());
ruListAppend(rl, &b1);
ruListAppend(rl, &b2);
 
ruIterator li = ruListIter(rl);
bool vbool;
for (ruIterTo(li, vbool); li; ruIterTo(li, vbool)) {
    printf("%d\n", vbool);
}
rl = ruListFree(rl);
 
rl = ruListNew(ruTypeStrDup());
ruListAppend(rl, "foo");
ruListAppend(rl, "bar");
 
li = ruListIter(rl);
perm_chars vstr;
for (ruIterTo(li, vstr); li; ruIterTo(li, vstr)) {
    printf("%s\n", vstr);
}
rl = ruListFree(rl);

Macro Definition Documentation

ruIterTo

#define ruIterTo	(		re,
			dest
	)		ruListNextDataTo(&(re), (ptr*)&(dest))

Returns the next element data in the given list to iterate over.

Parameters

re	Current list element to get the follower of.
dest	Where the returned object will be stored as its given type. (casts added).

Returns

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.

ruListIdxTo

#define ruListIdxTo	(		rl,
			index,
			dest
	)		ruListIdxDataTo(rl, index, (ptr*)&(dest))

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.
dest	Where the returned object will be stored as its given type (without casts).

Returns

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.

ruListPopTo

#define ruListPopTo	(		rl,
			dest
	)		ruListPopDataTo(rl, (ptr*)&(dest))

Return first element of the list.

Parameters

rl	List to pop object from.
dest	Optional. Where the returned object will be stored as its given type. (casts added)

Returns

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.

ruListRemoveIdxTo

#define ruListRemoveIdxTo	(		rl,
			index,
			dest
	)		ruListRemoveIdxDataTo(rl, index, (ptr*)&(dest))

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

Parameters

rl	List to remove object from.
index	0(first)/-1(last) position of the element to remove in the list.
dest	Optional. Where the returned object will be stored as its given type. (casts added)

Returns

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

ruListRemoveTo

#define ruListRemoveTo	(		rl,
			rle,
			dest
	)		ruListRemoveDataTo(rl, &(rle), (ptr*)&(dest))

Remove and return the current list element from list.

Parameters

rl	List to remove object from.
rle	Element to remove, will be set to the previous element to allow for deletion during iteration.
dest	Optional. Where the returned object will be stored as its given type. (casts added)

Returns

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

ruListTryPopTo

#define ruListTryPopTo	(		rl,
			timeoutMs,
			dest
	)		ruListTryPopDataTo(rl, timeoutMs, (ptr*)&(dest))

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.
dest	Optional. Where the returned object will be stored as its given type. (casts added)

Returns

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.

Function Documentation

ruListIdxDataTo()

RUAPI int32_t ruListIdxDataTo	(	ruList	rl,
		int32_t	index,
		ptr *	dest
	)

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.
dest	Where the returned object will be stored as its given type.

Returns

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.

ruListNextDataTo()

RUAPI int32_t ruListNextDataTo	(	ruListElmt *	re,
		ptr *	dest
	)

Returns the data payload of the next list element.

Parameters

re	Address of current list element to be updated with the next one.
dest	Optional. Where the returned object will be stored as its given type.

Returns

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.

ruListPopDataTo()

RUAPI int32_t ruListPopDataTo	(	ruList	rl,
		ptr *	dest
	)

Return first element of the list.

Parameters

rl	List to pop object from.
dest	Optional. Where the returned object will be stored as its given type.

Returns

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.

ruListRemoveDataTo()

RUAPI int32_t ruListRemoveDataTo	(	ruList	rl,
		ruListElmt *	rle,
		ptr *	dest
	)

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.
dest	Optional. Where the returned object will be stored as its given type. When not set object will be freed.

Returns

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

ruListRemoveIdxDataTo()

RUAPI int32_t ruListRemoveIdxDataTo	(	ruList	rl,
		int32_t	index,
		ptr *	dest
	)

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

Parameters

rl	List to remove object from.
index	0(first)/-1(last) position of the element to remove in the list.
dest	Optional. Where the returned object will be stored as its given type. When not set object will be freed.

Returns

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

ruListTryPopDataTo()

RUAPI int32_t ruListTryPopDataTo	(	ruList	rl,
		msec_t	timeoutMs,
		ptr *	dest
	)

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.
dest	Optional. Where the returned object will be stored as its given type.

Returns

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.