am_map_insert()

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

Details

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

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 specified map object.

key

Pointer to the key for the entry.

---

Note –

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

---

value

Pointer to the [new] value to be associated with the key.

replace

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

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS

If the entry was successfully inserted into the map object.

AM_NO_MEMORY

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

AM_INVALID_ARGUMENT

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