SMap

SMap containers are data types composed of a paired collection of unique keys (strings) and values (SObject), where each key is associated with one value. There are currently two different implementations of the SMap container.

The iterator (SIterator) implementation returns an element (as SObject) of the map for the SIteratorObject() function call. When a key-value pair is unlinked from the map with SIteratorUnlink(), the key is freed, and the value is returned (as SObject). The SMap iterator implements the SIteratorKey() call and returns the key of a key-value pair.

Definitions

speect object SMap

A map object.

An abstract data type composed of a collection of unique string keys and a collection of values (of type SObject), where each key is associated with one value.

SMap Structure

speect object SMapClass

The map class structure.

It inherits from SContainer so that it supports different map implementations.

SMapClass Structure.

Functions

Accessing

sint32 SMapGetInt(const SMap *self, const char *key, s_erc *error)

Get the signed integer value of the named key.

Parameters:

• self –

  The key-value map.

• key –

  The string key of the value to get.

• error –

  Error code.

Note:

An S_ARGERROR error is set if the named key is not in the map.

See also:

SMapGetIntDef

Return:

The signed integer value of the named key.

float SMapGetFloat(const SMap *self, const char *key, s_erc *error)

Get the float value of the named key.

Parameters:

• self –

  The key-value map.

• key –

  The string key of the value to get.

• error –

  Error code.

Note:

An S_ARGERROR error is set if the named key is not in the map.

See also:

SMapGetFloatDef

Return:

The float value of the named key.

const char *SMapGetString(const SMap *self, const char *key, s_erc *error)

Get the string value of the named key.

Parameters:

• self –

  The key-value map.

• key –

  The string key of the value to get.

• error –

  Error code.

Note:

An S_ARGERROR error is set if the named key is not in the map.

See also:

SMapGetStringDef

Return:

Pointer to the string of the named key.

const SObject *SMapGetObject(const SMap *self, const char *key, s_erc *error)

Get the object of the named key.

Parameters:

• self –

  The key-value map.

• key –

  The string key of the object to get.

• error –

  Error code.

Note:

An S_ARGERROR error is set if the named key is not in the map.

See also:

SMapGetObjectDef

Return:

Pointer to the object of the named key.

SList *SMapGetKeys(const SMap *self, s_erc *error)

Get a list of the keys in the map container.

Parameters:

• self –

  The key-value map.

• error –

  Error code.

Return:

SList of keys in container, or NULL if the container is empty. The list objects (keys) are string objects and are accessed with SObjectGetString.

Note:

The caller is responsible for the memory of the returned SList object.

Accessing (with defaults)

sint32 SMapGetIntDef(const SMap *self, const char *key, sint32 def, s_erc *error)

Get the signed integer value of the named key.

If the named key is not found then use the given default.

Parameters:

• self –

  The key-value map.

• key –

  The string key of the value to get.

• def –

  Default value to return if named key is not found.

• error –

  Error code.

See also:

SMapGetInt

Return:

The signed integer value of the named key, or given default value.

float SMapGetFloatDef(const SMap *self, const char *key, float def, s_erc *error)

Get the float value of the named key.

If the named key is not found then use the given default.

Parameters:

• self –

  The key-value map.

• key –

  The string key of the value to get.

• def –

  Default value to return if named key is not found.

• error –

  Error code.

See also:

SMapGetFloat

Return:

The float value of the named key, or given default value.

const char *SMapGetStringDef(const SMap *self, const char *key, const char *def, s_erc *error)

Get the string value of the named key.

If the named key is not found then use the given default.

Parameters:

• self –

  The key-value map.

• key –

  The string key of the value to get.

• def –

  Default value to return if named key is not found.

• error –

  Error code.

See also:

SMapGetString

Return:

Pointer to the string of the named key, or given default value.

const SObject *SMapGetObjectDef(const SMap *self, const char *key, const SObject *def, s_erc *error)

Get the SObject of the named key.

If the named key is not found then use the given default.

Parameters:

• self –

  The key-value map.

• key –

  The string key of the object to get.

• def –

  Default value to return if named key is not found.

• error –

  Error code.

See also:

SMapGetObject

Return:

Pointer to the SObject of the named key, or given default value.

Setting

void SMapSetInt(SMap *self, const char *key, sint32 i, s_erc *error)

Set the value of the named key as a signed integer value.

If the named key already exists then it’s data will be replaced.

Parameters:

• self –

  The key-value map.

• key –

  The string key of the value to set.

• i –

  The signed integer value of the named key.

• error –

  Error code.

void SMapSetFloat(SMap *self, const char *key, float f, s_erc *error)

Set the value of the named key as a float value.

If the named key already exists then it’s data will be replaced.

Parameters:

• self –

  The key-value map.

• key –

  The string key of the value to set.

• f –

  The float value of the named key.

• error –

  Error code.

void SMapSetString(SMap *self, const char *key, const char *s, s_erc *error)

Set the value of the named key as a string value.

If the named key already exists then it’s data will be replaced.

Parameters:

• self –

  The key-value map.

• key –

  The string key of the value to set.

• s –

  Pointer to the string value of the named key.

• error –

  Error code.

void SMapSetObject(SMap *self, const char *key, const SObject *object, s_erc *error)

Set the value of the named key as an SObject.

If the named key already exists then it’s SObject will be deleted (if not referenced) and replaced.

Parameters:

• self –

  The key-value map.

• key –

  The string key of the object to set.

• object –

  Pointer to the SObject of the named key.

• error –

  Error code.

Note:

The map takes hold of the object, and therefore the object should not be deleted with a call to S_DELETE, see SMapObjectDelete and SMapObjectUnlink.

Delete/Unlink

void SMapObjectDelete(SMap *self, const char *key, s_erc *error)

Delete the named key-value pair from the map.

Key is removed from list and value deleted if it doesn’t have any references.

Parameters:

• self –

  The key-value map.

• key –

  The string key of the value to delete.

• error –

  Error code.

SObject *SMapObjectUnlink(SMap *self, const char *key, s_erc *error)

Remove named key-value pair from the map.

Key is removed (freed) from list and value object is returned.

Parameters:

• self –

  The key-value map.

• key –

  The string key of the value to unlink.

• error –

  Error code.

Return:

SObject of named key.

Query

s_bool SMapObjectPresent(const SMap *self, const char *key, s_erc *error)

Query the presence of a named key-value pair in the map.

Parameters:

• self –

  The key-value map.

• key –

  The string key of the object’s presence to query.

• error –

  Error code.

Return:

TRUE or FALSE.

size_t SMapSize(const SMap *self, s_erc *error)

Get the number of key-value pairs in the container.

Parameters:

• self –

  The key-value map.

• error –

  Error code.

Return:

The number of key-value pairs in the container.

Copy

SMap *SMapCopy(SMap *dst, const SMap *src, s_erc *error)

Copy (shallow) the key-value pairs from src to dst.

If dst does not exist a new one will be created.

Parameters:

• dst –

  Pointer to destination key-value map. If NULL then a new map will be created.

• src –

  Pointer to source key-value map.

• error –

  Error code.

Return:

Pointer to destination key-value map.

Note:

Values in dst with the same named keys as in src will be overwritten with the values in src.

Implementations

Two different implementations of the SMap container:

SMapHashTable

SMapHashTable is an implementation of SMap, where the underlying data structure is a hash table.

speect object SMapHashTable

The SMapHashTable structure.

Inherits and implements SMap as a hash table.

SMapHashTable Specific Functions

void SMapHashTableResize(SMapHashTable *self, sint32 size, s_erc *error)

Resize a SMapHashTable‘s hash table.

Resize the hash table to a specific size. When a new SMapHashTable is created with S_NEW(“SMapHashTable”), the hash table’s size is set to contain 128 elements. This function is useful if a rough estimate of the number of objects that will be contained in the map is known beforehand, as it can save some memory, and growing a table is an relatively expensive operation. Resizing before any objects are added is comparatively cheap.

The hash table can be resized to any size as long as it can still contain all the existing objects in it. There are a few outcomes based on the given size and the elements contained in the hash table:

• size = -1, the hash table is resized to the minimum possible size (power of 2) that will still contain all elements.
• size = 0, nothing is done and the function returns.
• size <= number_of_objects, nothing is done and the function returns.
• In all other cases the hash table is resized to closest power of 2 bigger than size.

Parameters:

• self –

  The SMapHashTable to resize.

• size –

  The new size of table.

• error –

  Error code.

SMapList

SMapList is an implementation of SMap, where the underlying data structure is a doubly-linked list.

speect object SMapList

The SMapList structure.

Inherits and implements SMap as a doubly linked list.