[COMMITTED] std: add eoffset standard function

[Jose E. Marchesi]

2022-03-09  Jose E. Marchesi  <jemarch@gnu.org>

        * libpoke/std.pk (eoffset): New function.
        * doc/poke.texi (eoffset): New section.
        (Values Functions): Likewise.
---
 ChangeLog      |  6 ++++++
 doc/poke.texi  | 25 +++++++++++++++++++++++++
 libpoke/std.pk | 14 ++++++++++++++
 3 files changed, 45 insertions(+)

diff --git a/ChangeLog b/ChangeLog
index d9492dae..6049c58b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,11 @@
 2022-03-09  Jose E. Marchesi  <jemarch@gnu.org>
 
+       * libpoke/std.pk (eoffset): New function.
+       * doc/poke.texi (eoffset): New section.
+       (Values Functions): Likewise.
+
+2022-03-09  Jose E. Marchesi  <jemarch@gnu.org>
+
        * libpoke/pkl-tab.y: Define tokens APUSH and APOP, and add rules
        for the operators.
        * libpoke/pkl-lex.l: Rules for APUSH and APOP tokens.
diff --git a/doc/poke.texi b/doc/poke.texi
index d94cf3d9..589c37ec 100644
--- a/doc/poke.texi
+++ b/doc/poke.texi
@@ -243,6 +243,7 @@ The Standard Library
 * Conversion Functions::       catos, atoi, @i{etc}.
 * Array Functions::             Functions which deal with arrays.
 * String Functions::           Functions which deal with strings.
+* Values Functions::            Functions which deal with values in general.
 * Sorting Functions::          qsort.
 * CRC Functions::               Cyclic Redundancy Checksums.
 * Dates and Times::             Processing and displaying dates and times.
@@ -14266,6 +14267,7 @@ facilities provided by the library.
 * Conversion Functions::       catos, atoi, @i{etc}.
 * Array Functions::             Functions which deal with arrays.
 * String Functions::           Functions which deal with strings.
+* Values Functions::            Functions which deal with values in general.
 * Sorting Functions::          qsort.
 * CRC Functions::               Cyclic Redundancy Checksums.
 * Dates and Times::             Processing and displaying dates and times.
@@ -14569,6 +14571,29 @@ It returns the index of the first occurrence of the 
character @var{c}
 in the string @var{s}.  If the character is not found in the string,
 this function returns the length of the string.
 
+@node Values Functions
+@section Values Functions
+The Poke standard library provides the following functions to handle
+values in general:
+
+@menu
+* eoffset::            Offset of a value's element by name.
+@end menu
+
+@node eoffset
+@subsection @code{eoffset}
+
+The standard function @code{eoffset} provides the following interface:
+
+@example
+fun eoffset = (any val, string name) offset<uint<64>,b>
+@end example
+
+@noindent
+It returns the offset of the element having the given name in the
+given composite value.  If the value doesn't contain an element with
+the given name then the exception @code{E_inval} is raised.
+
 @node Sorting Functions
 @section Sorting Functions
 @cindex sorting
diff --git a/libpoke/std.pk b/libpoke/std.pk
index 61789ed0..589580ea 100644
--- a/libpoke/std.pk
+++ b/libpoke/std.pk
@@ -381,3 +381,17 @@ fun exit = (int<32> exit_code = 0) void:
   {
     raise Exception { code = EC_exit, name = "exit", exit_status = exit_code };
   }
+
+/* Return the offset of the element having the given name in the given
+   composite value.
+
+   If the value doesn't contain an element with the given name then
+   raise E_inval.  */
+
+fun eoffset = (any v, string n) offset<uint<64>,b>:
+  {
+    for (var i = 0UL; i < v'length; ++i)
+      if (n == v'ename (i))
+        return v'eoffset (i);
+    raise E_inval;
+  }
-- 
2.11.0