Map API

Data Structures
struct	JUNO_MAP_HASHABLE_POINTER_API_TAG
	Hashing and null-check operations for map keys/values. More...
struct	JUNO_MAP_API_TAG
	Map API vtable. More...

Functions
struct JUNO_MAP_ROOT_TAG	JUNO_MODULE_ROOT (JUNO_MAP_API_T, const JUNO_MAP_HASHABLE_POINTER_API_T *ptHashablePointerApi;const JUNO_VALUE_POINTER_API_T *ptValuePointerApi;JUNO_DS_ARRAY_ROOT_T *ptHashMap;)
	Map root instance and state.
static JUNO_STATUS_T	JunoDs_MapVerify (JUNO_MAP_ROOT_T *ptMap)
	Verify the map root, APIs, and backing array are valid.
JUNO_STATUS_T	JunoDs_MapInit (JUNO_MAP_ROOT_T *ptMapRoot, const JUNO_MAP_HASHABLE_POINTER_API_T *ptHashablePointerApi, const JUNO_VALUE_POINTER_API_T *ptValuePointerApi, JUNO_DS_ARRAY_ROOT_T *ptArray, JUNO_FAILURE_HANDLER_T pfcnFailureHandler, JUNO_USER_DATA_T *pvUserData)
	Initialize the map root with hashing/equality APIs and backing array.
JUNO_RESULT_POINTER_T	JunoDs_MapGet (JUNO_MAP_ROOT_T *ptJunoMap, JUNO_POINTER_T tItem)
	Retrieve an entry by key via linear probing.
JUNO_STATUS_T	JunoDs_MapSet (JUNO_MAP_ROOT_T *ptJunoMap, JUNO_POINTER_T tItem)
	Insert or update an entry (key/value) via linear probing.
JUNO_STATUS_T	JunoDs_MapRemove (JUNO_MAP_ROOT_T *ptJunoMap, JUNO_POINTER_T tKey)
	Remove an entry by key via linear probing.

Detailed Description

A lightweight associative container using linear probing over a user-supplied array as storage. Behavior is parameterized by:

• A hash function for keys.
• A value equality comparator for key comparison.
• A predicate to detect logically empty slots in the table.

Characteristics

• Deterministic and capacity-bound; no dynamic allocation.
• Average O(1) Set/Get/Remove with linear probing; worst-case O(n) under high load or clustered collisions.
• Non-thread-safe by default; guard externally if needed.

Invariants and requirements

• The backing array defines capacity (zCapacity) and provides element access operations via its API (see JunoDs_ArrayVerify).
• The hashable pointer API must supply Hash and IsValueNull.
• The value pointer API must supply Equals to compare a key against an entry.
• Slot pointer types must match the provided key/value pointer types; the implementation checks pointer API identity and returns JUNO_STATUS_INVALID_TYPE_ERROR on mismatch.

Function Documentation

JUNO_MODULE_ROOT()

struct JUNO_MAP_ROOT_TAG JUNO_MODULE_ROOT	(	JUNO_MAP_API_T	,
		const JUNO_MAP_HASHABLE_POINTER_API_T *ptHashablePointerApi;const JUNO_VALUE_POINTER_API_T *ptValuePointerApi;JUNO_DS_ARRAY_ROOT_T *ptHashMap;
	)

Map root instance and state.

JunoDs_MapGet()

JUNO_RESULT_POINTER_T JunoDs_MapGet	(	JUNO_MAP_ROOT_T *	ptJunoMap,
		JUNO_POINTER_T	tItem
	)

Retrieve an entry by key via linear probing.

Parameters

ptJunoMap	Map instance.
tItem	Pointer descriptor to a key-only or key/value entry used for lookup.

Returns

On success, a pointer result to the matching entry. Returns JUNO_STATUS_DNE_ERROR when probing encounters an empty slot (key not found). May return JUNO_STATUS_TABLE_FULL_ERROR if the table is full with no empty slots and no match. Propagates hashing/array/pointer errors.

JunoDs_MapInit()

JUNO_STATUS_T JunoDs_MapInit	(	JUNO_MAP_ROOT_T *	ptMapRoot,
		const JUNO_MAP_HASHABLE_POINTER_API_T *	ptHashablePointerApi,
		const JUNO_VALUE_POINTER_API_T *	ptValuePointerApi,
		JUNO_DS_ARRAY_ROOT_T *	ptArray,
		JUNO_FAILURE_HANDLER_T	pfcnFailureHandler,
		JUNO_USER_DATA_T *	pvUserData
	)

Initialize the map root with hashing/equality APIs and backing array.

Parameters

ptMapRoot	Map instance to initialize (output).
ptHashablePointerApi	Hash and null-check callbacks for entries.
ptValuePointerApi	Equality comparator for keys.
ptArray	Backing array providing capacity and element storage ops.
pfcnFailureHandler	Optional failure handler (can be NULL).
pvUserData	Optional user data for the failure handler (can be NULL).

Returns

Result of JunoDs_MapVerify on the configured map.

JunoDs_MapRemove()

JUNO_STATUS_T JunoDs_MapRemove	(	JUNO_MAP_ROOT_T *	ptJunoMap,
		JUNO_POINTER_T	tKey
	)

Remove an entry by key via linear probing.

Parameters

ptJunoMap	Map instance.
tKey	Pointer descriptor to a key-only or key/value entry identifying the key.

Returns

JUNO_STATUS_SUCCESS whether removed or not-present (no-op when empty encountered); or errors from hashing/pointer/array operations.

JunoDs_MapSet()

JUNO_STATUS_T JunoDs_MapSet	(	JUNO_MAP_ROOT_T *	ptJunoMap,
		JUNO_POINTER_T	tItem
	)

Insert or update an entry (key/value) via linear probing.

Parameters

ptJunoMap	Map instance.
tItem	Pointer descriptor to the entry to write into the table.

Returns

JUNO_STATUS_SUCCESS on success; JUNO_STATUS_TABLE_FULL_ERROR when no empty slot exists; or pointer/array errors.

JunoDs_MapVerify()

static JUNO_STATUS_T JunoDs_MapVerify ( JUNO_MAP_ROOT_T *  ptMap )

inlinestatic

Verify the map root, APIs, and backing array are valid.

Ensures all required function pointers are non-NULL and delegates to JunoDs_ArrayVerify for the backing array. Called by all operations.

Returns

JUNO_STATUS_SUCCESS on valid configuration; otherwise an error (e.g., NULLPTR or INVALID_TYPE from dependencies).