Skip to content

map.h#

Map object interface.

Authors#

TheSilvered

Macros#

_Nst_MAP_MIN_SIZE#

Description:

The minimum size of a map, must be a power of two.

Functions#

Nst_map_new#

Synopsis:

Nst_ObjRef *Nst_map_new(void)

Description:

Create a new map object.

Returns:

The new object or NULL on failure. The error is set.

Nst_map_copy#

Synopsis:

Nst_ObjRef *Nst_map_copy(Nst_Obj *map)

Description:

Create a shallow copy of a map object.

Parameters:

  • map: the map to copy

Returns:

The copied map or NULL on failure. The error is set.

_Nst_map_traverse#

Synopsis:

void _Nst_map_traverse(Nst_Obj *map)

Description:

Nst_ObjTrav function for Map objects.

Nst_map_len#

Synopsis:

usize Nst_map_len(Nst_Obj *map)

Returns:

The number of key-value pairs in a map.

Nst_map_cap#

Synopsis:

usize Nst_map_cap(Nst_Obj *map)

Returns:

The current capacity of a map.

Nst_map_set#

Synopsis:

bool Nst_map_set(Nst_Obj *map, Nst_Obj *key, Nst_Obj *value)

Description:

Insert or modify a value in the map. Adds a reference to both the key and the value.

Parameters:

  • map: the map to update
  • key: the key to insert or modify
  • value: the value to associate with the key

Returns:

true on success and false on failure. The error is set.

Nst_map_get#

Synopsis:

Nst_ObjRef *Nst_map_get(Nst_Obj *map, Nst_Obj *key)

Description:

Get the value associated with a key.

Parameters:

  • map: the map to get the value from
  • key: the key to get

Returns:

The object associated with the key on success or NULL if the key is not hashable or is not inside the map. No error is set.

Nst_map_drop#

Synopsis:

Nst_ObjRef *Nst_map_drop(Nst_Obj *map, Nst_Obj *key)

Description:

Drop a key from a map and returns its value.

Parameters:

  • map: the map to drop the key from
  • key: the key to drop

Returns:

The object associated with the removed key on success or NULL if the key is not hashable or is not inside the map. No error is set.

Nst_map_set_str#

Synopsis:

bool Nst_map_set_str(Nst_Obj *map, const char *key, Nst_Obj *value)

Description:

Insert or modifies a value in the map using a C string as the key.

Parameters:

  • map: the map to update
  • key: the key to insert or modify as a C string
  • value: the value to associate with the key

Returns:

true on success and false on failure. The error is set.

Nst_map_get_str#

Synopsis:

Nst_ObjRef *Nst_map_get_str(Nst_Obj *map, const char *key)

Description:

Get the value associated with a key using a C string as the key.

Parameters:

  • map: the map to get the value from
  • key: the key to get as a C string

Returns:

The object associated with the key on success or NULL if the key is not hashable or is not inside the map. No error is set.

Nst_map_drop_str#

Synopsis:

Nst_ObjRef *Nst_map_drop_str(Nst_Obj *map, const char *key)

Description:

Drops a key from a map and returns its value using a C string as the key.

Parameters:

  • map: the map to drop the key from
  • key: the key to drop as a C string

Returns:

The object associated with the removed key on success or NULL if the key is not hashable or is not inside the map. No error is set.

Nst_map_next#

Synopsis:

isize Nst_map_next(isize idx, Nst_Obj *map, Nst_Obj **out_key,
                   Nst_Obj **out_val)

Description:

Get the next key-value pair in the map given an index.

To get the first item pass -1 to idx and to continue looping pass the previously returned value as idx. The function returns -1 when there are no more items.

Parameters:

  • idx: the previous returned index or -1 for the first item
  • map: the map to iterate over
  • out_key: pointer set to the key, can be NULL, no reference is added to the key
  • out_val: pointer set to the value, can be NULL, no reference is added to the value

Returns:

The index of the current pair or -1 if the map contains no more pairs. If the return value is -1, out_key and out_val are set to NULL.

Nst_map_prev#

Synopsis:

isize Nst_map_prev(isize idx, Nst_Obj *map, Nst_Obj **out_key,
                   Nst_Obj **out_val)

Description:

Get the previous key-value pair in the map given an index.

To get the last item pass -1 to idx and to continue looping pass the previously returned value as idx. The function returns -1 when there are no more items.

Parameters:

  • idx: the previous returned index or -1 for the first item
  • map: the map to iterate over
  • out_key: pointer set to the key, can be NULL, no reference is added to the key
  • out_val: pointer set to the value, can be NULL, no reference is added to the value

Returns:

The index of the current pair or -1 if the map contains no more pairs. If the return value is -1, out_key and out_val are set to NULL.