am_map_find()

Returns a value iterator that can sequence through all values associated with the specified key in the specified map object.

Syntax

#include "am_map.h"
AM_EXPORT am_status_t
am_map_find(am_map_t map, 
            const char *key,
            am_map_value_iter_t *value_iter_ptr);

Parameters

This function takes the following parameters:

map

The specified map object.

key

Pointer to a key.

value_iter_ptr

Pointer specifying the location of the returned value iterator.

---

Note –

If value_iter_ptr is not NULL, the location that it references will be set to NULL if an error is returned.

---

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 no error was detected.

AM_NO_MEMORY

If unable to allocate memory for the key iterator.

AM_INVALID_ARGUMENT

If the value_iter_ptr argument is NULL.

AM_NOT_FOUND

If the specified key is not found in the map.

Memory Concerns

After using value_iter_ptr, the caller must call am_map_value_iter_destroy().