Data Structures
struct	GblRingListClass

struct	GblRingList

Macros
#define	GBL_RING_LIST_NPOS

#define	GblRingList_foreach(...)

#define	GblRingList_create(...)

#define	GblRingList_copy(...)

#define	GblRingList_unref(...)

#define	GblRingList_pushBack(self, ...)

#define	GblRingList_pushFront(self, ...)

#define	GblRingList_insert(self, ...)

#define	GblRingList_insertSorted(...)

#define	GblRingList_splice(...)

#define	GblRingList_popBack(...)

#define	GblRingList_popFront(...)

#define	GblRingList_remove(...)

#define	GblRingList_sort(...)

#define	GblRingList_iterate(...)

#define	GblRingList_find(...)

Type System
Type UUID and cast macros
#define	GBL_RING_LIST_TYPE

#define	GBL_RING_LIST_CLASS(klass)

Typedefs
User-Operator Callbacks
Typedefs for applying various user-supplied functions over a ring list.
typedef GblBool(*	GblRingListIterFn) (void pValue, void pClosure)

typedef int(*	GblRingListCmpFn) (const void pVal1, const void pVal2, void *pClosure)

typedef void (	GblRingListCopyFn) (const void pValue, void pClosure)

typedef GBL_RESULT(*	GblRingListDtorFn) (void pValue, void pClosure)

Functions
GblType	GblRingList_type (void)

Lifetime
Methods for creating, acquring, and releasing a list.
GblRingList *	GblRingList_createEmpty (void)

GblRingList *	GblRingList_create (void *pData,...)

GblRefCount	GblRingList_unref (const GblRingList pSelf, GblRingListDtorFn pFnDtor, void pCl)

GblRingList *	GblRingList_ref (const GblRingList *pSelf)

GblRingList *	GblRingList_copy (const GblRingList pSelf, GblRingListCopyFn pFnCpy, void pCl)

Properties
Methods for querying the properties of a list.
GblRefCount	GblRingList_refCount (const GblRingList *pSelf)

size_t	GblRingList_size (const GblRingList *pSelf)

GblBool	GblRingList_empty (const GblRingList *pSelf)

Retrieval
Methods for retrieving entries within a list.
void *	GblRingList_front (const GblRingList *pSelf)

void *	GblRingList_back (const GblRingList *pSelf)

void *	GblRingList_at (const GblRingList *pSelf, intptr_t index)

size_t	GblRingList_find (const GblRingList pSelf, const void pVal, GblRingListCmpFn pFnCmp, void *pCl)

Insertion
Methods for adding entries into the list.
GBL_RESULT	GblRingList_pushBack (GblRingList *pSelf,...)

GBL_RESULT	GblRingList_pushBackVaList (GblRingList pSelf, va_list pList)

GBL_RESULT	GblRingList_pushFront (GblRingList *pSelf,...)

GBL_RESULT	GblRingList_pushFrontVaList (GblRingList pSelf, va_list plist)

GBL_RESULT	GblRingList_insert (GblRingList *pSelf, intptr_t index,...)

GBL_RESULT	GblRingList_insertVaList (GblRingList pSelf, intptr_t index, va_list pList)

GBL_RESULT	GblRingList_insertSorted (GblRingList pSelf, void pData, GblRingListCmpFn pFnCmp, void *pCl)

GblBool	GblRingList_splice (GblRingList pSelf, GblRingList pOther, int32_t index)

void *	GblRingList_replace (GblRingList pSelf, intptr_t index, void pData)

Removing
Methods for removing entries from a list.
void *	GblRingList_popBack (GblRingList *pSelf, size_t count)

void *	GblRingList_popFront (GblRingList *pSelf, size_t count)

void *	GblRingList_remove (GblRingList *pSelf, intptr_t index, size_t count)

void *	GblRingList_extract (GblRingList pSelf, GblRingList pNode)

GBL_RESULT	GblRingList_clear (GblRingList *pSelf)

Operations
Other operations which can be performed on a list.
void	GblRingList_sort (GblRingList pSelf, GblRingListCmpFn pFnCmp, void pCl)

void	GblRingList_rotate (GblRingList *pSelf, intptr_t n)

void	GblRingList_reverse (GblRingList *pSelf)

GblBool	GblRingList_iterate (GblRingList pSelf, GblRingListIterFn pFnIt, void pCl)

Detailed Description

GblRingList structure and related functions.

This file provides the GblRingList container structure and its public API for operating upon it.

Author: 2023, 2025 Falco Girgis; 2025 Agustín Bellagamba

Copyright: MIT License

Definition in file gimbal_ring_list.h.

Macro Definition Documentation

◆ GBL_RING_LIST_NPOS

#define GBL_RING_LIST_NPOS

size_t type denoting an invalid array index or position within a GblRingList

Definition at line 23 of file gimbal_ring_list.h.

◆ GBL_RING_LIST_TYPE

#define GBL_RING_LIST_TYPE

Type UUID for GblRingList.

Definition at line 29 of file gimbal_ring_list.h.

◆ GBL_RING_LIST_CLASS

#define GBL_RING_LIST_CLASS ( klass )

Casts a GblClass to a GblRingListClass.

Definition at line 30 of file gimbal_ring_list.h.

◆ GblRingList_foreach

#define GblRingList_foreach ( ... )

For-loop style iteration over a GblRingList.

Iterates over every entry within a GblRingList, setting the item variable to the current entry's value. Optionally takes in a type parameter to specify the type of the item variable, which defaults to void*.

Definition at line 38 of file gimbal_ring_list.h.

◆ GblRingList_create

#define GblRingList_create ( ... )

Definition at line 264 of file gimbal_ring_list.h.

◆ GblRingList_copy

#define GblRingList_copy ( ... )

Definition at line 265 of file gimbal_ring_list.h.

◆ GblRingList_unref

#define GblRingList_unref ( ... )

Definition at line 266 of file gimbal_ring_list.h.

◆ GblRingList_pushBack

#define GblRingList_pushBack	(		self,
			... )

Definition at line 267 of file gimbal_ring_list.h.

◆ GblRingList_pushFront

#define GblRingList_pushFront	(		self,
			... )

Definition at line 268 of file gimbal_ring_list.h.

◆ GblRingList_insert

#define GblRingList_insert	(		self,
			... )

Definition at line 269 of file gimbal_ring_list.h.

◆ GblRingList_insertSorted

#define GblRingList_insertSorted ( ... )

Definition at line 270 of file gimbal_ring_list.h.

◆ GblRingList_splice

#define GblRingList_splice ( ... )

Definition at line 271 of file gimbal_ring_list.h.

◆ GblRingList_popBack

#define GblRingList_popBack ( ... )

Definition at line 272 of file gimbal_ring_list.h.

◆ GblRingList_popFront

#define GblRingList_popFront ( ... )

Definition at line 273 of file gimbal_ring_list.h.

◆ GblRingList_remove

#define GblRingList_remove ( ... )

Definition at line 274 of file gimbal_ring_list.h.

◆ GblRingList_sort

#define GblRingList_sort ( ... )

Definition at line 275 of file gimbal_ring_list.h.

◆ GblRingList_iterate

#define GblRingList_iterate ( ... )

Definition at line 276 of file gimbal_ring_list.h.

◆ GblRingList_find

#define GblRingList_find ( ... )

Definition at line 277 of file gimbal_ring_list.h.

Typedef Documentation

◆ GblRingListIterFn

typedef GblBool(* GblRingListIterFn) (void *pValue, void *pClosure)

Iterator callback function which gets called over every entry within a GblRingList, being passed back its stored value and an arbitrary closure, returning true should iteration cease early.

Definition at line 64 of file gimbal_ring_list.h.

◆ GblRingListCmpFn

typedef int(* GblRingListCmpFn) (const void *pVal1, const void *pVal2, void *pClosure)

Comparator callback for comparing the values of two different entries within a GblRingList, also getting passed back the closure that was passed to the API call. 0 should be returned if equal.

Definition at line 66 of file gimbal_ring_list.h.

◆ GblRingListCopyFn

typedef void *(* GblRingListCopyFn) (const void *pValue, void *pClosure)

Returns a copy of the value of each entry within a GblRingList, also getting passed back the closure that was passed to the initial API call.

Definition at line 68 of file gimbal_ring_list.h.

◆ GblRingListDtorFn

typedef GBL_RESULT(* GblRingListDtorFn) (void *pValue, void *pClosure)

Destructs the value of each entry within a GblRingList, also getting passed back the closure that was passed to the iniital API call, and returning a GBL_RESULT for the status.

Definition at line 70 of file gimbal_ring_list.h.

Function Documentation

◆ GblRingList_type()

GblType GblRingList_type ( void )

Returns the GblType UUID associated with GblRingList.

◆ GblRingList_createEmpty()

GblRingList * GblRingList_createEmpty ( void )

Creates a new, empty GblRingList of size 0 and returns a reference to it.

◆ GblRingList_create()

GblRingList * GblRingList_create	(	void *	pData,
			... )

Creates a new GblRingList, given an initial value and an optional list of additional values, returning a reference to the list.

◆ GblRingList_unref()

GblRefCount GblRingList_unref	(	const GblRingList *	pSelf,
		GblRingListDtorFn	pFnDtor,
		void *	pCl )

Unreferences an existing GblRingList, destroying it if this was the last reference, using an optional, user-provided per-entry destructor which gets passed back the given optional closure data.

◆ GblRingList_ref()

GblRingList * GblRingList_ref ( const GblRingList * pSelf )

Returns a new reference to an existing GblRingList, incrementing its reference counter by 1.

◆ GblRingList_copy()

GblRingList * GblRingList_copy	(	const GblRingList *	pSelf,
		GblRingListCopyFn	pFnCpy,
		void *	pCl )

Creates a copy of the given GblRingList, optionally deep-copying each entry by using the user-provided copy function which optionally gets passed back a pointer to arbitrary closure data.

◆ GblRingList_refCount()

GblRefCount GblRingList_refCount ( const GblRingList * pSelf )

Returns the number of active references to the given GblRingList.

◆ GblRingList_size()

size_t GblRingList_size ( const GblRingList * pSelf )

Returns the number of entries held by the given GblRingList.

◆ GblRingList_empty()

GblBool GblRingList_empty ( const GblRingList * pSelf )

Returns true if the given GblRingList has no entries held within it.

◆ GblRingList_front()

void * GblRingList_front ( const GblRingList * pSelf )

Returns a pointer to the value held within the first entry of the list, or NULL if the list is empty.

◆ GblRingList_back()

void * GblRingList_back ( const GblRingList * pSelf )

Returns a pointer to the value held within the last entry of the list, or NULL if the list is empty.

◆ GblRingList_at()

void * GblRingList_at	(	const GblRingList *	pSelf,
		intptr_t	index )

Linearly traverses the list to the given index, returning a pointer to the value held within that entry, or NULL if the entry is invalid. NOTE that negative indices start at the last entry and enumerate backwards.

◆ GblRingList_find()

size_t GblRingList_find	(	const GblRingList *	pSelf,
		const void *	pVal,
		GblRingListCmpFn	pFnCmp,
		void *	pCl )

Searches the list for an entry with the given value, or for an entry which matches the value based on the optional comparison callback, which takes an optional closure pointer. The index of the matching entry or GBL_RING_LIST_NPOS is returned.

◆ GblRingList_pushBack()

GBL_RESULT GblRingList_pushBack	(	GblRingList *	pSelf,
			... )

Adds a comma-separated list of values to the end of the given GblRingList.

◆ GblRingList_pushBackVaList()

GBL_RESULT GblRingList_pushBackVaList	(	GblRingList *	pSelf,
		va_list *	pList )

Equivalent to GblRingList_pushBack(), except taking a va_list*, rather than a variadic argument list.

◆ GblRingList_pushFront()

GBL_RESULT GblRingList_pushFront	(	GblRingList *	pSelf,
			... )

Adds a comma-separated list of values to the front of the given GblRingList.

◆ GblRingList_pushFrontVaList()

GBL_RESULT GblRingList_pushFrontVaList	(	GblRingList *	pSelf,
		va_list *	plist )

Equivalent to GblRingList_pushFront(), except taking a va_list*, rather than a variadic argument list.

◆ GblRingList_insert()

GBL_RESULT GblRingList_insert	(	GblRingList *	pSelf,
		intptr_t	index,
			... )

Inserts the comma-separated list of values into the given GblRingList, so that the first value is at the position of the given index.

◆ GblRingList_insertVaList()

GBL_RESULT GblRingList_insertVaList	(	GblRingList *	pSelf,
		intptr_t	index,
		va_list *	pList )

Equivalent to GblRingList_insert(), except taking a va_list* rather than a variadic argument list.

◆ GblRingList_insertSorted()

GBL_RESULT GblRingList_insertSorted	(	GblRingList *	pSelf,
		void *	pData,
		GblRingListCmpFn	pFnCmp,
		void *	pCl )

Inserts a value into a sorted list, optionally taking a comparator for sort direction and an optional closure which gets passed back.

◆ GblRingList_splice()

GblBool GblRingList_splice	(	GblRingList *	pSelf,
		GblRingList *	pOther,
		int32_t	index )

Joins pOther into the given GblRingList such that its first entry is positioned at the given index, returning GBL_TRUE if it succeeded. Do NOT forget to still call GblRingList_unref() on the now empty pOther list.

◆ GblRingList_replace()

void * GblRingList_replace	(	GblRingList *	pSelf,
		intptr_t	index,
		void *	pData )

Replaces the entry within the given GblRingList located at pIndex with the pData value, returning its old value (or NULL upon failure).

◆ GblRingList_popBack()

void * GblRingList_popBack	(	GblRingList *	pSelf,
		size_t	count )

Removes the last entry from the given list, returning its previously held value, or NULL if the list was empty.

◆ GblRingList_popFront()

void * GblRingList_popFront	(	GblRingList *	pSelf,
		size_t	count )

Removes the first entry from the given list, returning its previously held value, or NULL if the list was empty.

◆ GblRingList_remove()

void * GblRingList_remove	(	GblRingList *	pSelf,
		intptr_t	index,
		size_t	count )

Removes count items from the given GblRingList, starting at the given index, returning the value previously held by the last item which was removed.

◆ GblRingList_extract()

void * GblRingList_extract	(	GblRingList *	pSelf,
		GblRingList *	pNode )

Returns the value which was held by the given GblRingList node within the given list, also removing it from the list.

◆ GblRingList_clear()

GBL_RESULT GblRingList_clear ( GblRingList * pSelf )

Erases all entries from the GblRingList, returning its size back to 0.

◆ GblRingList_sort()

void GblRingList_sort	(	GblRingList *	pSelf,
		GblRingListCmpFn	pFnCmp,
		void *	pCl )

Sorts the given GblRingList, optionally using a user-specified comparator which can optionally take an closure data pointer.

◆ GblRingList_rotate()

void GblRingList_rotate	(	GblRingList *	pSelf,
		intptr_t	n )

Rotates the positions of all entries within the given GblRingList, such that they ahve been offset by n, where positives rotate right and negatives rotate left.

◆ GblRingList_reverse()

void GblRingList_reverse ( GblRingList * pSelf )

Reverses the order of the entire GblRingList, such that the tail becomes the head entry, and all values are now in opposite order.

◆ GblRingList_iterate()

GblBool GblRingList_iterate	(	GblRingList *	pSelf,
		GblRingListIterFn	pFnIt,
		void *	pCl )

Iterates over every entry within the given GblRingList, passing their values to the given iterator function, wich may optionally take a closure data pointer. Iteration ends early when the iterator returns GBL_TRUE.

Data Structures

Macros

Typedefs

Functions