From 264c4d037618a5ca8f55001855cb422d0bb5d136 Mon Sep 17 00:00:00 2001 From: Sverker Eriksson Date: Wed, 27 May 2015 17:55:08 +0200 Subject: erts: Add docs for map functions in nif API --- erts/doc/src/erl_nif.xml | 129 ++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 121 insertions(+), 8 deletions(-) (limited to 'erts') diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 4bad8b253c..2cc06de0e0 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -461,8 +461,9 @@ ok independent environment with all its terms is valid until you explicitly invalidates it with enif_free_env or enif_send.

-

All elements of a list/tuple must belong to the same environment as the - list/tuple itself. Terms can be copied between environments with +

All contained terms of a list/tuple/map must belong to the same + environment as the list/tuple/map itself. Terms can be copied between + environments with enif_make_copy.

ErlNifFunc @@ -729,7 +730,18 @@ typedef enum { return true, or return false if term is not an integer or is outside the bounds of type long int.

- intenif_get_resource(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifResourceType* type, void** objp) + intenif_get_map_size(ErlNifEnv* env, ERL_NIF_TERM term, size_t *size) + Read the size of a map term +

Set *size to the number of key-value pairs in the map term and + return true, or return false if term is not a map.

 + + intenif_get_map_value(ErlNifEnv* env, ERL_NIF_TERM map, ERL_NIF_TERM key, ERL_NIF_TERM* value) + Get the value of a key in a map +

Set *value to the value associated with key in the + map map and return true. Return false if map is not a map + or if map does not contain key.

 + + intenif_get_resource(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifResourceType* type, void** objp) Get the pointer to a resource object

Set *objp to point to the resource object referred to by term.

Return true on success or false if term is not a handle to a resource object @@ -817,6 +829,10 @@ typedef enum { Determine if a term is an exception

Return true if term is an exception.

 + intenif_is_map(ErlNifEnv* env, ERL_NIF_TERM term) + Determine if a term is a map +

Return true if term is a map, false otherwise.

 + intenif_is_number(ErlNifEnv* env, ERL_NIF_TERM term) Determine if a term is a number (integer or float)

Return true if term is a number.

 @@ -986,12 +1002,13 @@ typedef enum {

Create an ordinary list containing the elements of array arr of length cnt. An empty list is returned if cnt is 0.

 - intenif_make_reverse_list(ErlNifEnv* env, ERL_NIF_TERM term, ERL_NIF_TERM *list) - Create the reverse list of the list term. -

Set *list to the reverse list of the list term and return true, - or return false if term is not a list. This function should only be used on + intenif_make_reverse_list(ErlNifEnv* env, ERL_NIF_TERM list_in, ERL_NIF_TERM *list_out) + Create the reverse of a list +

Set *list_out to the reverse list of the list list_in and return true, + or return false if list_in is not a list. This function should only be used on short lists as a copy will be created of the list which will not be released until after the - nif returns.

 + nif returns.

+

The list_in term must belong to the environment env.

 ERL_NIF_TERMenif_make_long(ErlNifEnv* env, long int i) Create an integer term from a long int @@ -1007,6 +1024,36 @@ typedef enum { reallocated.

Return a pointer to the raw binary data and set *termp to the binary term.

 + ERL_NIF_TERMenif_make_new_map(ErlNifEnv* env) + Make an empty map term +

Make an empty map term.

 + + intenif_make_map_put(ErlNifEnv* env, ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM value, ERL_NIF_TERM* map_out) + Insert key-value pair in map +

Make a copy of map map_in and insert key with + value. If key already exists in map_in, the old + associated value is replaced by value. If successful set + *map_out to the new map and return true. Return false if + map_in is not a map.

+

The map_in term must belong to the environment env.

 + + intenif_make_map_update(ErlNifEnv* env, ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM new_value, ERL_NIF_TERM* map_out) + Replace value for key in map +

Make a copy of map map_in and replace the old associated + value for key with new_value. If successful set + *map_out to the new map and return true. Return false if + map_in is not a map or if it does no contain key.

+

The map_in term must belong to the environment env.

 + + intenif_make_map_remove(ErlNifEnv* env, ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM* map_out) + Remove key from map +

If map map_in contains key, make a copy of + map_in in *map_out and remove key and associated + value. If map map_in does not contain key, set + *map_out to map_in. Return true for success or false if + map_in is not a map.

+

The map_in term must belong to the environment env.

 + ERL_NIF_TERMenif_make_pid(ErlNifEnv* env, const ErlNifPid* pid) Make a pid term

Make a pid term from *pid.

 @@ -1108,6 +1155,72 @@ typedef enum { Create an integer term from an unsigned long int

Create an integer term from an unsigned long int.

 + intenif_map_iterator_create(ErlNifEnv *env, ERL_NIF_TERM map, ErlNifMapIterator *iter, ErlNifMapIteratorEntry entry) + Create a map iterator +

Create an iterator for the map map by initializing the + structure pointed to by iter. The entry argument determines + the start position of the iterator: ERL_NIF_MAP_ITERATOR_FIRST or + ERL_NIF_MAP_ITERATOR_LAST. Return true on success or false if + map is not a map.

+

A map iterator is only useful during the lifetime of the environment + env that the map belongs to. The iterator must be destroyed by + calling + enif_map_iterator_destroy.

+ +ERL_NIF_TERM key, value; +ErlNifMapIterator iter; +enif_map_iterator_create(env, my_map, ERL_NIF_MAP_ITERATOR_FIRST); + +while (enif_map_iterator_get_pair(env, &iter, &key, &value)) { + do_something(key,value); + enif_map_iterator_next(env, &iter); +} +enif_map_iterator_destroy(env, &iter); + +

The key-value pairs of a map have no defined iteration + order. The only guarantee is that the iteration order of a single map + instance is preserved during the lifetime of the environment that the map + belongs to.

+ + + + voidenif_map_iterator_destroy(ErlNifEnv *env, ErlNifMapIterator *iter) + Destroy a map iterator +

Destroy a map iterator created by + enif_map_iterator_create. +

+ + intenif_map_iterator_get_pair(ErlNifEnv *env, ErlNifMapIterator *iter, ERL_NIF_TERM *key, ERL_NIF_TERM *value) + Get key and value at current map iterator position +

Get key and value terms at current map iterator position. + On success set *key and *value and return true. + Return false if the iterator is positioned at head (before first entry) + or tail (beyond last entry).

 + + intenif_map_iterator_is_head(ErlNifEnv *env, ErlNifMapIterator *iter) + Check if map iterator is positioned before first +

Return true if map iterator iter is positioned + before first entry.

 + + intenif_map_iterator_is_tail(ErlNifEnv *env, ErlNifMapIterator *iter) + Check if map iterator is positioned after last +

Return true if map iterator iter is positioned + after last entry.

 + + intenif_map_iterator_next(ErlNifEnv *env, ErlNifMapIterator *iter) + Increment map iterator to point to next entry +

Increment map iterator to point to next key-value entry. + Return true if the iterator is now positioned at a valid key-value entry, + or false if the iterator is positioned at the tail (beyond the last + entry).

 + + intenif_map_iterator_prev(ErlNifEnv *env, ErlNifMapIterator *iter) + Decrement map iterator to point to previous entry +

Decrement map iterator to point to previous key-value entry. + Return true if the iterator is now positioned at a valid key-value entry, + or false if the iterator is positioned at the head (before the first + entry).

 + ErlNifMutex *enif_mutex_create(char *name)

Same as erl_drv_mutex_create. -- cgit v1.2.3