2 files changed, 71 insertions, 3 deletions
diff --git a/cppawk-cons.1 b/cppawk-cons.1
index d400d89..d554da7 100644
--- a/cppawk-cons.1
+++ b/cppawk-cons.1
@@ -100,10 +100,10 @@ cons \- Lisp-like data representation and control flow macros
   mapcar(\fIf\fP, \fIx\fP)      \fI// map list through function f\fP
   mappend(\fIf\fP, \fIx\fP)     \fI// map list through f, append results\fP
 
-  \fI// array -> list conversion\fP
+  \fI// Array/list conversion\fP
 
-  values(\fIx\fP)         \fI// convert values of Awk array a to list\fP
-  keys(\fIx\fP)           \fI// return list of keys of Awk array x\fP
+  values(\fIa\fP)         \fI// convert values of Awk array a to list\fP
+  keys(\fIa\fP)           \fI// return list of keys of Awk array x\fP
 
   \fI// field <-> list conversion\fP
 
@@ -1893,6 +1893,61 @@ on GNU Awk before version 5.2.
   }
 .ft R
 
+.SH ARRAY/LIST CONVERSION
+
+.SS Functions \fIvalues\fP and \fIkeys\fP
+.bk
+Syntax:
+
+.ft B
+  values(\fIa\fP)
+  keys(\fIa\fP)
+.ft R
+
+The
+.B values
+function returns a list of all the values currently stored in the the
+associative array
+.IR a .
+
+The
+.B values
+function returns a list of all the indices of associative array
+.IR a .
+
+Associative arrays are not ordered; therefore the lists returned by
+.B keys
+and
+.B values
+are not in any required order.
+
+However, if the
+.B keys
+and
+.B values
+are applied to the same array object
+.I a
+without any intervening changes to
+.IR a ,
+then the contents of the two lists correspond to each other by position: the
+.IR n -th
+value in the value list corresponds to the
+.IR n -th
+key in the key list.
+
+The keys or values aren't subject to any conversion; they may be boxed
+or unboxed objects.
+
+.B Examples:
+
+.ft B
+  // assuming a is prepared like this:
+  split("a:b:c", a, /:/)
+
+  values(a) -> ("c" "a" "b")
+  keys(a) -> (3 1 2)
+.ft R
+
 .SH "SEE ALSO"
 
 cppawk(1), cppawk-fun(1)
diff --git a/testcases-cons b/testcases-cons
index 7b66766..10d827b 100644
--- a/testcases-cons
+++ b/testcases-cons
@@ -741,3 +741,16 @@ BEGIN {
 }'
 :
 ERR
+--
+39:
+$cppawk '
+#include <cons.h>
+
+BEGIN {
+  split("a:b:c", a, /:/)
+  print sexp(values(a))
+  print sexp(keys(a))
+}'
+:
+("a" "b" "c")
+(1 2 3)