gimbal_array_map.h File Reference

Go to the source code of this file.

Data Structures
struct	GblArrayMapEntry
struct	GblArrayMap

Macros
#define	GBL_ARRAY_MAP_NPOS
#define	GBL_ARRAY_MAP_SIZE(elements)
#define	GBL_ARRAY_MAP_BINARY_SEARCH_CUTOFF_SIZE
#define	GBL_PSELF
#define	GBL_PCSELF

Typedefs
typedef GBL_RESULT(*	GblArrayMapDtorFn) (const GblArrayMap *, uintptr_t key, void *pEntry)
typedef int(*	GblArrayMapCmpFn) (const GblArrayMap *, uintptr_t key1, uintptr_t key2)

Functions
GblArrayMap *	GblArrayMap_create (GblArrayMapCmpFn pFnComp, GblBool binarySearch, GblContext *pCtx)
GBL_RESULT	GblArrayMap_destroy (GblArrayMap **ppSelf)
size_t	GblArrayMap_size (GblArrayMap *const *ppSelf)
GblContext *	GblArrayMap_context (GblArrayMap *const *ppSelf)
GblBool	GblArrayMap_empty (GblArrayMap *const *ppSelf)
GblBool	GblArrayMap_binarySearches (GblArrayMap *const *ppSelf)
GblBool	GblArrayMap_contains (GblArrayMap *const *ppSelf, uintptr_t key)
GblBool	GblArrayMap_containsUserdata (GblArrayMap *const *ppSelf, uintptr_t key)
GblBool	GblArrayMap_containsVariant (GblArrayMap *const *ppSelf, uintptr_t key)
uintptr_t	GblArrayMap_getValue (GblArrayMap *const *ppSelf, uintptr_t key)
GblVariant *	GblArrayMap_getVariant (GblArrayMap *const *ppSelf, uintptr_t key)
uintptr_t	GblArrayMap_atValue (GblArrayMap *const *ppSelf, uintptr_t key)
GblVariant *	GblArrayMap_atVariant (GblArrayMap *const *ppSelf, uintptr_t key)
GBL_RESULT	GblArrayMap_setUserdata (GblArrayMap **ppSelf, uintptr_t key, uintptr_t value, GblArrayMapDtorFn pDtor)
GBL_RESULT	GblArrayMap_setVariant (GblArrayMap **ppSelf, uintptr_t key, GblVariant *pVariant)
size_t	GblArrayMap_insertUserdata (GblArrayMap **ppSelf, uintptr_t key, uintptr_t value, GblArrayMapDtorFn pDtor)
size_t	GblArrayMap_insertVariant (GblArrayMap **ppSelf, uintptr_t key, GblVariant *pVariant)
GblBool	GblArrayMap_erase (GblArrayMap **ppSelf, uintptr_t key)
GblBool	GblArrayMap_extractVariant (GblArrayMap **ppSelf, uintptr_t key, GblVariant *pVariant)
GblBool	GblArrayMap_extractValue (GblArrayMap **ppSelf, uintptr_t key, uintptr_t *pValue)
void	GblArrayMap_clear (GblArrayMap **ppSelf)
size_t	GblArrayMap_find (GblArrayMap *const *ppSelf, uintptr_t key)
uintptr_t	GblArrayMap_probeKey (GblArrayMap *const *ppSelf, size_t index)
uintptr_t	GblArrayMap_probeValue (GblArrayMap *const *ppSelf, size_t index)
GblVariant *	GblArrayMap_probeVariant (GblArrayMap *const *ppSelf, size_t index)

Detailed Description

GblArrayMap container and related functions

Dynamic array-based [K,V] pair associative container.

Contiguous array-based associative container with [K,V] pairs. GblArrayMap is essentially a flat map structure with a few specific properties:

• Value types can either be uinptr_t userdata or typed GblVariants
• Userdata types can have per-entry custom destructors
• For non-trivial key types, a custom comparator can be specified
• insertion and searching can either be done sorted in a binary search or unsorted linearly

Note

GblArrayMap is a lazily-allocated structure, meaning it isn't actually allocated until it's needed. This is why the majority of the API takes a pointer to a pointer, so a NULL pointer value is a valid empty map. You can optionally preconstruct the structure with GblArrayMap_create.

See also

GblArrayMapEntry

Bug

• Extracting the last item will still invoke its destructor!

Author

Falco Girgis

Definition in file gimbal_array_map.h.

Macro Definition Documentation

GBL_ARRAY_MAP_NPOS

#define GBL_ARRAY_MAP_NPOS

Invalid index identifier returned when an entry couldn't be found.

Definition at line 19 of file gimbal_array_map.h.

GBL_ARRAY_MAP_SIZE

#define GBL_ARRAY_MAP_SIZE

(

elements

)

Calculates total size of the GblArrayMap structure with elements.

Definition at line 20 of file gimbal_array_map.h.

GBL_ARRAY_MAP_BINARY_SEARCH_CUTOFF_SIZE

#define GBL_ARRAY_MAP_BINARY_SEARCH_CUTOFF_SIZE

Magical break-even point for when binary searches out-perform linear searches, based on profiling.

Definition at line 21 of file gimbal_array_map.h.

GBL_PSELF

#define GBL_PSELF

Definition at line 23 of file gimbal_array_map.h.

GBL_PCSELF

#define GBL_PCSELF

Definition at line 24 of file gimbal_array_map.h.

Typedef Documentation

GblArrayMapDtorFn

typedef GBL_RESULT(* GblArrayMapDtorFn) (const GblArrayMap *, uintptr_t key, void *pEntry)

Custom destructor type for userdata values.

Definition at line 31 of file gimbal_array_map.h.

GblArrayMapCmpFn

typedef int(* GblArrayMapCmpFn) (const GblArrayMap *, uintptr_t key1, uintptr_t key2)

Custom comparator for nontrivial key types.

Definition at line 32 of file gimbal_array_map.h.

Function Documentation

GblArrayMap_create()

GblArrayMap * GblArrayMap_create	(	GblArrayMapCmpFn	pFnComparator,
		GblBool	binarySearches,
		GblContext *	pCtx )

Pre-creates a GblArrayMap with the given comparator, binary search config, and context.

Parameters

pFnComparator
binarySearches
pCtx

Returns

pointer to a new GblArrayMap

GblArrayMap_destroy()

GBL_RESULT GblArrayMap_destroy

(

GblArrayMap **

ppSelf

)

Destroys a GblArrayMap.

Parameters

ppSelf

Returns

GBL_RESULT_SUCCESS or error code upon failure

GblArrayMap_size()

size_t GblArrayMap_size

(

GblArrayMap *const *

ppSelf

)

Returns the number of entries within the given map.

GblArrayMap_context()

GblContext * GblArrayMap_context

(

GblArrayMap *const *

ppSelf

)

Returns the context associated with the given map.

GblArrayMap_empty()

GblBool GblArrayMap_empty

(

GblArrayMap *const *

ppSelf

)

Returns whether the given map is empty.

GblArrayMap_binarySearches()

GblBool GblArrayMap_binarySearches

(

GblArrayMap *const *

ppSelf

)

Returns whether the given map is sorted and uses binary searches.

GblArrayMap_contains()

GblBool GblArrayMap_contains	(	GblArrayMap *const *	ppSelf,
		uintptr_t	key )

Returns true if the given map contains the given key.

GblArrayMap_containsUserdata()

GblBool GblArrayMap_containsUserdata	(	GblArrayMap *const *	ppSelf,
		uintptr_t	key )

Returns true if the given map contains the given key, associated with a userdata value.

GblArrayMap_containsVariant()

GblBool GblArrayMap_containsVariant	(	GblArrayMap *const *	ppSelf,
		uintptr_t	key )

Returns true if the given map contains the given key, associated with a GblVariant value.

GblArrayMap_getValue()

uintptr_t GblArrayMap_getValue	(	GblArrayMap *const *	ppSelf,
		uintptr_t	key )

Returns the GblVariant or userdata value associated with the given key as a uintptr_t.

GblArrayMap_getVariant()

GblVariant * GblArrayMap_getVariant	(	GblArrayMap *const *	ppSelf,
		uintptr_t	key )

Returns the GblVariant associated with the given key.

GblArrayMap_atValue()

uintptr_t GblArrayMap_atValue	(	GblArrayMap *const *	ppSelf,
		uintptr_t	key )

Returns the GblVariant or userdata value associated with the given key, erroring if not found.

GblArrayMap_atVariant()

GblVariant * GblArrayMap_atVariant	(	GblArrayMap *const *	ppSelf,
		uintptr_t	key )

Returns the GblVariant associated with the given key, erroring if not found.

GblArrayMap_setUserdata()

GBL_RESULT GblArrayMap_setUserdata	(	GblArrayMap **	ppSelf,
		uintptr_t	key,
		uintptr_t	value,
		GblArrayMapDtorFn	pDtor )

Inserts or replaces the entry with the given key with a userdata value and optional destructor.

GblArrayMap_setVariant()

GBL_RESULT GblArrayMap_setVariant	(	GblArrayMap **	ppSelf,
		uintptr_t	key,
		GblVariant *	pVariant )

Inserts or replaces the entry with the given key with a GblVariant.

GblArrayMap_insertUserdata()

size_t GblArrayMap_insertUserdata	(	GblArrayMap **	ppSelf,
		uintptr_t	key,
		uintptr_t	value,
		GblArrayMapDtorFn	pDtor )

Attempts to insert a new entry with the given key and userdata, returning the insertion index.

GblArrayMap_insertVariant()

size_t GblArrayMap_insertVariant	(	GblArrayMap **	ppSelf,
		uintptr_t	key,
		GblVariant *	pVariant )

Attempts to insert a new entry with the given key and GblVariant value, returning insertion index.

GblArrayMap_erase()

GblBool GblArrayMap_erase	(	GblArrayMap **	ppSelf,
		uintptr_t	key )

Attempts to erase the value with the given key, returning GBL_FALSE if not found.

Parameters

ppSelf
key

Returns

GBL_TRUE if the entry with the given key was removed.

GblArrayMap_extractVariant()

GblBool GblArrayMap_extractVariant	(	GblArrayMap **	ppSelf,
		uintptr_t	key,
		GblVariant *	pVariant )

Attempts to remove the GblVariant with the given key, moving it into the given pointer if found.

Parameters

ppSelf
key
pVariant

Returns

GBL_TRUE if the given variant was extracted

GblArrayMap_extractValue()

GblBool GblArrayMap_extractValue	(	GblArrayMap **	ppSelf,
		uintptr_t	key,
		uintptr_t *	pValue )

Attempts to remove the value with the given key, moving it into the given pointer if found.

Parameters

ppSelf
key
pValue

Returns

GBL_TRUE if the given value was successfully extracted

GblArrayMap_clear()

void GblArrayMap_clear

(

GblArrayMap **

ppSelf

)

Clears all entries within the given map.

Parameters

ppSelf

GblArrayMap_find()

size_t GblArrayMap_find	(	GblArrayMap *const *	ppSelf,
		uintptr_t	key )

Returns the index of the entry with the given key.

GblArrayMap_probeKey()

uintptr_t GblArrayMap_probeKey	(	GblArrayMap *const *	ppSelf,
		size_t	index )

Returns the key for the entry at the given index.

GblArrayMap_probeValue()

uintptr_t GblArrayMap_probeValue	(	GblArrayMap *const *	ppSelf,
		size_t	index )

Returns the value for the entry at the given index.

GblArrayMap_probeVariant()

GblVariant * GblArrayMap_probeVariant	(	GblArrayMap *const *	ppSelf,
		size_t	index )

Returns the GblVariant for the entry at the given index.