Merge branch 'sverk/nif-map-docs'

* sverk/nif-map-docs:
  erts: Cleanup fsummary lines in erl_nif docs
  erts: Fix alphabetic order in erl_nif doc
  erts: Add docs for map functions in nif API
  erts: Rename ErlNifMapIteratorEntry enums

4 files changed, 167 insertions, 50 deletions

diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml
index 4bad8b253c..e915c3b693 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 <seealso marker="#enif_free_env">enif_free_env</seealso>
         or <c>enif_send</c>.</p>
-        <p>All elements of a list/tuple must belong to the same environment as the
-        list/tuple itself. Terms can be copied between environments with
+        <p>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
         <seealso marker="#enif_make_copy">enif_make_copy</seealso>.</p>
       </item>
     <tag><marker id="ErlNifFunc"/>ErlNifFunc</tag>
@@ -564,11 +565,11 @@ typedef enum {
 
   <funcs>
     <func><name><ret>void *</ret><nametext>enif_alloc(size_t size)</nametext></name>
-      <fsummary>Allocate dynamic memory.</fsummary>
+      <fsummary>Allocate dynamic memory</fsummary>
       <desc><p>Allocate memory of <c>size</c> bytes. Return NULL if allocation failed.</p></desc>
     </func>
     <func><name><ret>int</ret><nametext>enif_alloc_binary(size_t size, ErlNifBinary* bin)</nametext></name>
-      <fsummary>Create a new binary.</fsummary>
+      <fsummary>Create a new binary</fsummary>
       <desc><p>Allocate a new binary of size <c>size</c>
       bytes. Initialize the structure pointed to by <c>bin</c> to
       refer to the allocated binary. The binary must either be released by 
@@ -595,7 +596,7 @@ typedef enum {
       <desc><p>Allocate a memory managed resource object of type <c>type</c> and size <c>size</c> bytes.</p></desc>
     </func>
     <func><name><ret>void</ret><nametext>enif_clear_env(ErlNifEnv* env)</nametext></name>
-      <fsummary>Clear an environment for reuse.</fsummary>
+      <fsummary>Clear an environment for reuse</fsummary>
       <desc><p>Free all terms in an environment and clear it for reuse. The environment must
       have been allocated with <seealso marker="#enif_alloc_env">enif_alloc_env</seealso>.
       </p></desc>
@@ -683,14 +684,14 @@ typedef enum {
               <c>size-1</c>.</p></desc>
     </func>
     <func><name><ret>int</ret><nametext>enif_get_atom_length(ErlNifEnv* env, ERL_NIF_TERM term, unsigned* len, ErlNifCharEncoding encode)</nametext></name>
-      <fsummary>Get the length of atom <c>term</c>.</fsummary>
+      <fsummary>Get the length of atom <c>term</c></fsummary>
       <desc><p>Set <c>*len</c> to the length (number of bytes excluding
       terminating null character) of the atom <c>term</c> with encoding
       <c>encode</c>. Return true on success or false if <c>term</c> is not an
       atom.</p></desc>
     </func>
     <func><name><ret>int</ret><nametext>enif_get_double(ErlNifEnv* env, ERL_NIF_TERM term, double* dp)</nametext></name>
-      <fsummary>Read a floating-point number term.</fsummary>
+      <fsummary>Read a floating-point number term</fsummary>
       <desc><p>Set <c>*dp</c> to the floating point value of
       <c>term</c>. Return true on success or false if <c>term</c> is not a float.</p></desc>
     </func>
@@ -719,17 +720,28 @@ typedef enum {
       non-empty list.</p></desc>
     </func>
     <func><name><ret>int</ret><nametext>enif_get_list_length(ErlNifEnv* env, ERL_NIF_TERM term, unsigned* len)</nametext></name>
-      <fsummary>Get the length of list <c>term</c>.</fsummary>
+      <fsummary>Get the length of list <c>term</c></fsummary>
       <desc><p>Set <c>*len</c> to the length of list <c>term</c> and return true,
       or return false if <c>term</c> is not a list.</p></desc>
     </func>
     <func><name><ret>int</ret><nametext>enif_get_long(ErlNifEnv* env, ERL_NIF_TERM term, long int* ip)</nametext></name>
-      <fsummary>Read an long integer term.</fsummary>
+      <fsummary>Read an long integer term</fsummary>
       <desc><p>Set <c>*ip</c> to the long integer value of <c>term</c> and
       return true, or return false if <c>term</c> is not an integer or is
       outside the bounds of type <c>long int</c>.</p></desc>
     </func>
-    <func><name><ret>int</ret><nametext>enif_get_resource(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifResourceType* type, void** objp)</nametext></name>
+    <func><name><ret>int</ret><nametext>enif_get_map_size(ErlNifEnv* env, ERL_NIF_TERM term, size_t *size)</nametext></name>
+      <fsummary>Read the size of a map term</fsummary>
+      <desc><p>Set <c>*size</c> to the number of key-value pairs in the map <c>term</c> and
+      return true, or return false if <c>term</c> is not a map.</p></desc>
+    </func>
+    <func><name><ret>int</ret><nametext>enif_get_map_value(ErlNifEnv* env, ERL_NIF_TERM map, ERL_NIF_TERM key, ERL_NIF_TERM* value)</nametext></name>
+     <fsummary>Get the value of a key in a map</fsummary>
+      <desc><p>Set <c>*value</c> to the value associated with <c>key</c> in the
+      map <c>map</c> and return true. Return false if <c>map</c> is not a map
+      or if <c>map</c> does not contain <c>key</c>.</p></desc>
+    </func>
+   <func><name><ret>int</ret><nametext>enif_get_resource(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifResourceType* type, void** objp)</nametext></name>
       <fsummary>Get the pointer to a resource object</fsummary>
       <desc><p>Set <c>*objp</c> to point to the resource object referred to by <c>term</c>.</p>
       <p>Return true on success or false if <c>term</c> is not a handle to a resource object
@@ -738,7 +750,7 @@ typedef enum {
     <func><name><ret>int</ret><nametext>enif_get_string(ErlNifEnv* env, 
                                 ERL_NIF_TERM list, char* buf, unsigned size,
                                 ErlNifCharEncoding encode)</nametext></name>
-      <fsummary>Get a C-string from a list.</fsummary>
+      <fsummary>Get a C-string from a list</fsummary>
       <desc><p>Write a null-terminated string, in the buffer pointed to by
               <c>buf</c> with size <c>size</c>, consisting of the characters
               in the string <c>list</c>. The characters are written using encoding
@@ -751,7 +763,7 @@ typedef enum {
               <c>size</c> is less than 1.</p></desc>
     </func>
     <func><name><ret>int</ret><nametext>enif_get_tuple(ErlNifEnv* env, ERL_NIF_TERM term, int* arity, const ERL_NIF_TERM** array)</nametext></name>
-      <fsummary>Inspect the elements of a tuple.</fsummary>
+      <fsummary>Inspect the elements of a tuple</fsummary>
       <desc><p>If <c>term</c> is a tuple, set <c>*array</c> to point
       to an array containing the elements of the tuple and set
       <c>*arity</c> to the number of elements. Note that the array
@@ -761,25 +773,25 @@ typedef enum {
       tuple.</p></desc>
     </func>
     <func><name><ret>int</ret><nametext>enif_get_uint(ErlNifEnv* env, ERL_NIF_TERM term, unsigned int* ip)</nametext></name>
-      <fsummary>Read an unsigned integer term.</fsummary>
+      <fsummary>Read an unsigned integer term</fsummary>
       <desc><p>Set <c>*ip</c> to the unsigned integer value of <c>term</c> and
       return true, or return false if <c>term</c> is not an unsigned integer or
       is outside the bounds of type <c>unsigned int</c>.</p></desc>
     </func>
     <func><name><ret>int</ret><nametext>enif_get_uint64(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifUInt64* ip)</nametext></name>
-      <fsummary>Read an unsigned 64-bit integer term.</fsummary>
+      <fsummary>Read an unsigned 64-bit integer term</fsummary>
       <desc><p>Set <c>*ip</c> to the unsigned integer value of <c>term</c> and
       return true, or return false if <c>term</c> is not an unsigned integer or
       is outside the bounds of an unsigned 64-bit integer.</p></desc>
     </func>
     <func><name><ret>int</ret><nametext>enif_get_ulong(ErlNifEnv* env, ERL_NIF_TERM term, unsigned long* ip)</nametext></name>
-      <fsummary>Read an unsigned integer term.</fsummary>
+      <fsummary>Read an unsigned integer term</fsummary>
       <desc><p>Set <c>*ip</c> to the unsigned long integer value of <c>term</c>
       and return true, or return false if <c>term</c> is not an unsigned integer or is
       outside the bounds of type <c>unsigned long</c>.</p></desc>
     </func>
     <func><name><ret>int</ret><nametext>enif_has_pending_exception(ErlNifEnv* env)</nametext></name>
-      <fsummary>Check if an exception has been raised.</fsummary>
+      <fsummary>Check if an exception has been raised</fsummary>
       <desc><p>Return true if a pending exception is associated
       with the environment <c>env</c>. The only possible exception is currently
       <c>badarg</c> (see <seealso marker="#enif_make_badarg">enif_make_badarg</seealso>).</p></desc>
@@ -817,6 +829,10 @@ typedef enum {
       <fsummary>Determine if a term is an exception</fsummary>
       <desc><p>Return true if <c>term</c> is an exception.</p></desc>
     </func>
+    <func><name><ret>int</ret><nametext>enif_is_map(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name>
+      <fsummary>Determine if a term is a map</fsummary>
+      <desc><p>Return true if <c>term</c> is a map, false otherwise.</p></desc>
+    </func>
     <func><name><ret>int</ret><nametext>enif_is_number(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name>
       <fsummary>Determine if a term is a number (integer or float)</fsummary>
       <desc><p>Return true if <c>term</c> is a number.</p></desc>
@@ -890,7 +906,7 @@ typedef enum {
       </p></desc>
     </func>
     <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_badarg(ErlNifEnv* env)</nametext></name>
-      <fsummary>Make a badarg exception.</fsummary>
+      <fsummary>Make a badarg exception</fsummary>
       <desc><p>Make a badarg exception to be returned from a NIF, and associate
       it with the environment <c>env</c>. Once a NIF or any function
       it calls invokes <c>enif_make_badarg</c>, the runtime ensures that a
@@ -909,14 +925,14 @@ typedef enum {
       if <c>enif_make_badarg</c> has been invoked.</p></note></desc>
     </func>
     <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_binary(ErlNifEnv* env, ErlNifBinary* bin)</nametext></name>
-      <fsummary>Make a binary term.</fsummary>
+      <fsummary>Make a binary term</fsummary>
       <desc><p>Make a binary term from <c>bin</c>. Any ownership of 
               the binary data will be transferred to the created term and
               <c>bin</c> should be considered read-only for the rest of the NIF
               call and then as released.</p></desc>
     </func>
     <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_copy(ErlNifEnv* dst_env, ERL_NIF_TERM src_term)</nametext></name>
-      <fsummary>Make a copy of a term.</fsummary>
+      <fsummary>Make a copy of a term</fsummary>
       <desc><p>Make a copy of term <c>src_term</c>. The copy will be created in
       environment <c>dst_env</c>. The source term may be located in any
       environment.</p></desc>        
@@ -957,7 +973,7 @@ typedef enum {
       <desc><p>Create an integer term from a signed 64-bit integer.</p></desc>
     </func>
     <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list(ErlNifEnv* env, unsigned cnt, ...)</nametext></name>
-      <fsummary>Create a list term.</fsummary>
+      <fsummary>Create a list term</fsummary>
       <desc><p>Create an ordinary list term of length <c>cnt</c>. Expects
       <c>cnt</c> number of arguments (after <c>cnt</c>) of type ERL_NIF_TERM as the
       elements of the list. An empty list is returned if <c>cnt</c> is 0.</p></desc>
@@ -971,28 +987,21 @@ typedef enum {
     <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list7(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e7)</nametext></name>
     <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list8(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e8)</nametext></name>
     <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list9(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e9)</nametext></name>
-      <fsummary>Create a list term.</fsummary>
+      <fsummary>Create a list term</fsummary>
       <desc><p>Create an ordinary list term with length indicated by the
       function name. Prefer these functions (macros) over the variadic
       <c>enif_make_list</c>  to get a compile time error if the number of
       arguments does not match.</p></desc>
     </func>
     <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list_cell(ErlNifEnv* env, ERL_NIF_TERM head, ERL_NIF_TERM tail)</nametext></name>
-      <fsummary>Create a list cell.</fsummary>
+      <fsummary>Create a list cell</fsummary>
       <desc><p>Create a list cell <c>[head | tail]</c>.</p></desc>
     </func>
     <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list_from_array(ErlNifEnv* env, const ERL_NIF_TERM arr[], unsigned cnt)</nametext></name>
-      <fsummary>Create a list term from an array.</fsummary>
+      <fsummary>Create a list term from an array</fsummary>
       <desc><p>Create an ordinary list containing the elements of array <c>arr</c>
       of length <c>cnt</c>. An empty list is returned if <c>cnt</c> is 0.</p></desc>
     </func>
-    <func><name><ret>int</ret><nametext>enif_make_reverse_list(ErlNifEnv* env, ERL_NIF_TERM term, ERL_NIF_TERM *list)</nametext></name>
-      <fsummary>Create the reverse list of the list <c>term</c>.</fsummary>
-      <desc><p>Set <c>*list</c> to the reverse list of the list <c>term</c> and return true,
-      or return false if <c>term</c> 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.</p></desc>
-    </func>
     <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_long(ErlNifEnv* env, long int i)</nametext></name>
       <fsummary>Create an integer term from a long int</fsummary>
       <desc><p>Create an integer term from a <c>long int</c>.</p></desc>
@@ -1007,12 +1016,42 @@ typedef enum {
       reallocated.</p><p>Return a pointer to the raw binary data and set
       <c>*termp</c> to the binary term.</p></desc>
     </func>
+    <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_new_map(ErlNifEnv* env)</nametext></name>
+      <fsummary>Make an empty map term</fsummary>
+      <desc><p>Make an empty map term.</p></desc>
+    </func>
+    <func><name><ret>int</ret><nametext>enif_make_map_put(ErlNifEnv* env, ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM value, ERL_NIF_TERM* map_out)</nametext></name>
+      <fsummary>Insert key-value pair in map</fsummary>
+      <desc><p>Make a copy of map <c>map_in</c> and insert <c>key</c> with
+      <c>value</c>. If <c>key</c> already exists in <c>map_in</c>, the old
+      associated value is replaced by <c>value</c>. If successful set
+      <c>*map_out</c> to the new map and return true. Return false if
+      <c>map_in</c> is not a map.</p>
+      <p>The <c>map_in</c> term must belong to the environment <c>env</c>.</p></desc>
+    </func>
+    <func><name><ret>int</ret><nametext>enif_make_map_update(ErlNifEnv* env, ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM new_value, ERL_NIF_TERM* map_out)</nametext></name>
+      <fsummary>Replace value for key in map</fsummary>
+      <desc><p>Make a copy of map <c>map_in</c> and replace the old associated
+      value for <c>key</c> with <c>new_value</c>. If successful set
+      <c>*map_out</c> to the new map and return true. Return false if
+      <c>map_in</c> is not a map or if it does no contain <c>key</c>.</p>
+      <p>The <c>map_in</c> term must belong to the environment <c>env</c>.</p></desc>
+    </func>
+    <func><name><ret>int</ret><nametext>enif_make_map_remove(ErlNifEnv* env, ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM* map_out)</nametext></name>
+      <fsummary>Remove key from map</fsummary>
+      <desc><p>If map <c>map_in</c> contains <c>key</c>, make a copy of
+      <c>map_in</c> in <c>*map_out</c> and remove <c>key</c> and associated
+      value. If map <c>map_in</c> does not contain <c>key</c>, set
+      <c>*map_out</c> to <c>map_in</c>. Return true for success or false if
+      <c>map_in</c> is not a map.</p>
+      <p>The <c>map_in</c> term must belong to the environment <c>env</c>.</p></desc>
+    </func>
     <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_pid(ErlNifEnv* env, const ErlNifPid* pid)</nametext></name>
       <fsummary>Make a pid term</fsummary>
       <desc><p>Make a pid term from <c>*pid</c>.</p></desc>
     </func>
     <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_ref(ErlNifEnv* env)</nametext></name>
-      <fsummary>Create a reference.</fsummary>
+      <fsummary>Create a reference</fsummary>
       <desc><p>Create a reference like <seealso marker="erlang#make_ref-0">erlang:make_ref/0</seealso>.</p></desc>
     </func>
     <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_resource(ErlNifEnv* env, void* obj)</nametext></name>
@@ -1050,20 +1089,28 @@ typedef enum {
       <seealso marker="#enif_release_resource">enif_release_resource</seealso>.</p>
       </desc>
     </func>
+    <func><name><ret>int</ret><nametext>enif_make_reverse_list(ErlNifEnv* env, ERL_NIF_TERM list_in, ERL_NIF_TERM *list_out)</nametext></name>
+      <fsummary>Create the reverse of a list</fsummary>
+      <desc><p>Set <c>*list_out</c> to the reverse list of the list <c>list_in</c> and return true,
+      or return false if <c>list_in</c> 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.</p>
+      <p>The <c>list_in</c> term must belong to the environment <c>env</c>.</p></desc>
+    </func>
     <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_string(ErlNifEnv* env, const char* string, ErlNifCharEncoding encoding)</nametext></name>
-      <fsummary>Create a string.</fsummary>
+      <fsummary>Create a string</fsummary>
       <desc><p>Create a list containing the characters of the
       null-terminated string <c>string</c> with encoding <seealso marker="#ErlNifCharEncoding">encoding</seealso>.</p></desc>
     </func>
     <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_string_len(ErlNifEnv* env, const char* string, size_t len, ErlNifCharEncoding encoding)</nametext></name>
-      <fsummary>Create a string.</fsummary>
+      <fsummary>Create a string</fsummary>
       <desc><p>Create a list containing the characters of the string <c>string</c> with
       length <c>len</c> and encoding <seealso marker="#ErlNifCharEncoding">encoding</seealso>.
       Null-characters are treated as any other characters.</p></desc>
     </func>
     <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_sub_binary(ErlNifEnv* 
       env, ERL_NIF_TERM bin_term, size_t pos, size_t size)</nametext></name>
-      <fsummary>Make a subbinary term.</fsummary>
+      <fsummary>Make a subbinary term</fsummary>
       <desc><p>Make a subbinary of binary <c>bin_term</c>, starting at 
               zero-based position <c>pos</c> with a length of <c>size</c> bytes. 
               <c>bin_term</c> must be a binary or bitstring and
@@ -1071,7 +1118,7 @@ typedef enum {
               bytes in <c>bin_term</c>.</p></desc>
     </func>
     <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple(ErlNifEnv* env, unsigned cnt, ...)</nametext></name>
-      <fsummary>Create a tuple term.</fsummary>
+      <fsummary>Create a tuple term</fsummary>
       <desc><p>Create a tuple term of arity <c>cnt</c>. Expects
       <c>cnt</c> number of arguments (after <c>cnt</c>) of type ERL_NIF_TERM as the
       elements of the tuple.</p></desc>
@@ -1085,14 +1132,14 @@ typedef enum {
     <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple7(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e7)</nametext></name>
     <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple8(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e8)</nametext></name>
     <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple9(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e9)</nametext></name>
-      <fsummary>Create a tuple term.</fsummary>
+      <fsummary>Create a tuple term</fsummary>
       <desc><p>Create a tuple term with length indicated by the
       function name. Prefer these functions (macros) over the variadic
       <c>enif_make_tuple</c>  to get a compile time error if the number of
       arguments does not match.</p></desc>
     </func>
     <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple_from_array(ErlNifEnv* env, const ERL_NIF_TERM arr[], unsigned cnt)</nametext></name>
-      <fsummary>Create a tuple term from an array.</fsummary>
+      <fsummary>Create a tuple term from an array</fsummary>
       <desc><p>Create a tuple containing the elements of array <c>arr</c>
       of length <c>cnt</c>.</p></desc>
     </func>
@@ -1108,6 +1155,72 @@ typedef enum {
       <fsummary>Create an integer term from an unsigned long int</fsummary>
       <desc><p>Create an integer term from an <c>unsigned long int</c>.</p></desc>
     </func>
+    <func><name><ret>int</ret><nametext>enif_map_iterator_create(ErlNifEnv *env, ERL_NIF_TERM map, ErlNifMapIterator *iter, ErlNifMapIteratorEntry entry)</nametext></name>
+      <fsummary>Create a map iterator</fsummary>
+      <desc><p>Create an iterator for the map <c>map</c> by initializing the
+      structure pointed to by <c>iter</c>. The <c>entry</c> argument determines
+      the start position of the iterator: <c>ERL_NIF_MAP_ITERATOR_FIRST</c> or
+      <c>ERL_NIF_MAP_ITERATOR_LAST</c>. Return true on success or false if
+      <c>map</c> is not a map.</p>
+      <p>A map iterator is only useful during the lifetime of the environment
+      <c>env</c> that the <c>map</c> belongs to. The iterator must be destroyed by
+      calling <seealso marker="#enif_map_iterator_destroy">
+      enif_map_iterator_destroy</seealso>.</p>
+      <code type="none">
+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, &amp;iter, &amp;key, &amp;value)) {
+    do_something(key,value);
+    enif_map_iterator_next(env, &amp;iter);
+}
+enif_map_iterator_destroy(env, &amp;iter);
+      </code>
+     <note><p>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.</p>
+    </note>
+      </desc>
+    </func>
+    <func><name><ret>void</ret><nametext>enif_map_iterator_destroy(ErlNifEnv *env, ErlNifMapIterator *iter)</nametext></name>
+      <fsummary>Destroy a map iterator</fsummary>
+      <desc><p>Destroy a map iterator created by
+      <seealso marker="#enif_map_iterator_create">enif_map_iterator_create</seealso>.
+      </p></desc>
+    </func>
+    <func><name><ret>int</ret><nametext>enif_map_iterator_get_pair(ErlNifEnv *env, ErlNifMapIterator *iter, ERL_NIF_TERM *key, ERL_NIF_TERM *value)</nametext></name>
+      <fsummary>Get key and value at current map iterator position</fsummary>
+      <desc><p>Get key and value terms at current map iterator position.
+      On success set <c>*key</c> and <c>*value</c> and return true.
+      Return false if the iterator is positioned at head (before first entry)
+      or tail (beyond last entry).</p></desc>
+    </func>
+    <func><name><ret>int</ret><nametext>enif_map_iterator_is_head(ErlNifEnv *env, ErlNifMapIterator *iter)</nametext></name>
+      <fsummary>Check if map iterator is positioned before first</fsummary>
+      <desc><p>Return true if map iterator <c>iter</c> is positioned
+      before first entry.</p></desc>
+    </func>
+    <func><name><ret>int</ret><nametext>enif_map_iterator_is_tail(ErlNifEnv *env, ErlNifMapIterator *iter)</nametext></name>
+      <fsummary>Check if map iterator is positioned after last</fsummary>
+      <desc><p>Return true if map iterator <c>iter</c> is positioned
+      after last entry.</p></desc>
+    </func>
+    <func><name><ret>int</ret><nametext>enif_map_iterator_next(ErlNifEnv *env, ErlNifMapIterator *iter)</nametext></name>
+      <fsummary>Increment map iterator to point to next entry</fsummary>
+      <desc><p>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).</p></desc>
+    </func>
+    <func><name><ret>int</ret><nametext>enif_map_iterator_prev(ErlNifEnv *env, ErlNifMapIterator *iter)</nametext></name>
+      <fsummary>Decrement map iterator to point to previous entry</fsummary>
+      <desc><p>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).</p></desc>
+    </func>
     <func><name><ret>ErlNifMutex *</ret><nametext>enif_mutex_create(char *name)</nametext></name>
     <fsummary></fsummary>
     <desc><p>Same as <seealso marker="erl_driver#erl_drv_mutex_create">erl_drv_mutex_create</seealso>.
@@ -1169,18 +1282,18 @@ typedef enum {
       <p>Was previously named <c>enif_get_data</c>.</p></desc>
     </func>
     <func><name><ret>int</ret><nametext>enif_realloc_binary(ErlNifBinary* bin, size_t size)</nametext></name>
-      <fsummary>Change the size of a binary.</fsummary>
+      <fsummary>Change the size of a binary</fsummary>
       <desc><p>Change the size of a binary <c>bin</c>. The source binary
       may be read-only, in which case it will be left untouched and
       a mutable copy is allocated and assigned to <c>*bin</c>. Return true on success,
       false if memory allocation failed.</p></desc>
     </func>
     <func><name><ret>void</ret><nametext>enif_release_binary(ErlNifBinary* bin)</nametext></name>
-      <fsummary>Release a binary.</fsummary>
+      <fsummary>Release a binary</fsummary>
       <desc><p>Release a binary obtained from <c>enif_alloc_binary</c>.</p></desc>
     </func>
     <func><name><ret>void</ret><nametext>enif_release_resource(void* obj)</nametext></name>
-      <fsummary>Release a resource object.</fsummary>
+      <fsummary>Release a resource object</fsummary>
       <desc><p>Remove a reference to resource object <c>obj</c>obtained from
       <seealso marker="#enif_alloc_resource">enif_alloc_resource</seealso>.
       The resource object will be destructed when the last reference is removed.
@@ -1256,12 +1369,12 @@ typedef enum {
       </desc>
     </func>
     <func><name><ret>ErlNifPid *</ret><nametext>enif_self(ErlNifEnv* caller_env, ErlNifPid* pid)</nametext></name>
-      <fsummary>Get the pid of the calling process.</fsummary>
+      <fsummary>Get the pid of the calling process</fsummary>
       <desc><p>Initialize the pid variable <c>*pid</c> to represent the
       calling process. Return <c>pid</c>.</p></desc>
     </func>
     <func><name><ret>int</ret><nametext>enif_send(ErlNifEnv* env, ErlNifPid* to_pid, ErlNifEnv* msg_env, ERL_NIF_TERM msg)</nametext></name>
-      <fsummary>Send a message to a process.</fsummary>
+      <fsummary>Send a message to a process</fsummary>
       <desc><p>Send a message to a process.</p>
       <taglist>
         <tag><c>env</c></tag>
diff --git a/erts/emulator/beam/erl_nif.c b/erts/emulator/beam/erl_nif.c
index 426a00304e..4df34e4a06 100644
--- a/erts/emulator/beam/erl_nif.c
+++ b/erts/emulator/beam/erl_nif.c
@@ -2024,8 +2024,8 @@ int enif_map_iterator_create(ErlNifEnv *env,
 	size_t offset;
 
 	switch (entry) {
-	    case ERL_NIF_MAP_ITERATOR_HEAD: offset = 0; break;
-	    case ERL_NIF_MAP_ITERATOR_TAIL: offset = flatmap_get_size(mp) - 1; break;
+	    case ERL_NIF_MAP_ITERATOR_FIRST: offset = 0; break;
+	    case ERL_NIF_MAP_ITERATOR_LAST: offset = flatmap_get_size(mp) - 1; break;
 	    default: goto error;
 	}
 
@@ -2048,12 +2048,12 @@ int enif_map_iterator_create(ErlNifEnv *env,
         WSTACK_INIT(iter->u.hash.wstack, ERTS_ALC_T_NIF);
 
         switch (entry) {
-	    case ERL_NIF_MAP_ITERATOR_HEAD:
+	    case ERL_NIF_MAP_ITERATOR_FIRST:
                 iter->idx = 1;
                 hashmap_iterator_init(&iter->u.hash.wstack->ws, map, 0);
                 iter->u.hash.kv = hashmap_iterator_next(&iter->u.hash.wstack->ws);
                 break;
-	    case ERL_NIF_MAP_ITERATOR_TAIL:
+	    case ERL_NIF_MAP_ITERATOR_LAST:
                 iter->idx = hashmap_size(map);
                 hashmap_iterator_init(&iter->u.hash.wstack->ws, map, 1);
                 iter->u.hash.kv = hashmap_iterator_prev(&iter->u.hash.wstack->ws);
diff --git a/erts/emulator/beam/erl_nif.h b/erts/emulator/beam/erl_nif.h
index c4fdfd4187..af806736fd 100644
--- a/erts/emulator/beam/erl_nif.h
+++ b/erts/emulator/beam/erl_nif.h
@@ -218,8 +218,12 @@ typedef struct /* All fields all internal and may change */
 } ErlNifMapIterator;
 
 typedef enum {
-    ERL_NIF_MAP_ITERATOR_HEAD = 1,
-    ERL_NIF_MAP_ITERATOR_TAIL = 2
+    ERL_NIF_MAP_ITERATOR_FIRST = 1,
+    ERL_NIF_MAP_ITERATOR_LAST = 2,
+
+    /* deprecated synonyms (undocumented in 17 and 18-rc) */
+    ERL_NIF_MAP_ITERATOR_HEAD = ERL_NIF_MAP_ITERATOR_FIRST,
+    ERL_NIF_MAP_ITERATOR_TAIL = ERL_NIF_MAP_ITERATOR_LAST
 } ErlNifMapIteratorEntry;
 
 #if (defined(__WIN32__) || defined(_WIN32) || defined(_WIN32_))
diff --git a/erts/emulator/test/nif_SUITE_data/nif_SUITE.c b/erts/emulator/test/nif_SUITE_data/nif_SUITE.c
index 3cc9f51ef8..d964ae338e 100644
--- a/erts/emulator/test/nif_SUITE_data/nif_SUITE.c
+++ b/erts/emulator/test/nif_SUITE_data/nif_SUITE.c
@@ -1802,7 +1802,7 @@ static ERL_NIF_TERM sorted_list_from_maps_nif(ErlNifEnv* env, int argc, const ER
     if (argc != 1 && !enif_is_map(env, map))
 	return enif_make_int(env, __LINE__);
 
-    if(!enif_map_iterator_create(env, map, &iter_f, ERL_NIF_MAP_ITERATOR_HEAD))
+    if(!enif_map_iterator_create(env, map, &iter_f, ERL_NIF_MAP_ITERATOR_FIRST))
 	return enif_make_int(env, __LINE__);
 
     cnt = 0;
@@ -1817,7 +1817,7 @@ static ERL_NIF_TERM sorted_list_from_maps_nif(ErlNifEnv* env, int argc, const ER
     if (cnt && next_ret)
 	return enif_make_int(env, __LINE__);
 
-    if(!enif_map_iterator_create(env, map, &iter_b, ERL_NIF_MAP_ITERATOR_TAIL))
+    if(!enif_map_iterator_create(env, map, &iter_b, ERL_NIF_MAP_ITERATOR_LAST))
 	return enif_make_int(env, __LINE__);
 
     cnt = 0;