am_map_insert()

Inserts a new key-value pair into the specified map.

Syntax

#include "am_map.h"
AM_EXPORT am_status_t
am_map_insert(am_map_t map, const char *key, const char *value,
         int replace);

Parameters

This function takes the following parameters:

map

The handle for the map object to be modified.

key

The key for the entry.

value

The (new) value to be associated with the key.

replace

If non-zero, then the specified value replaces all of the existing values. Otherwise the specified value is added to the list of values associated with the specified key.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If the entry was successfully inserted into the map.

AM_INVALID_ARGUMENT

If either the map, key, or value argument is NULL.

AM_NO_MEMORY

If unable to allocate memory for value and if necessary the key.

Details

If an entry with the same key already exists, then the existing value is replaced by the new value.

NOTE: The map does not retain any references to the provided key or value parameters. It makes copies of any strings it needs to store.