New standard function stoca

[Jose E. Marchesi]

FYI.

I just added a new function to the standard library: stoca.
Salud!

commit 79aafbddb498bca92006e952436a9e57320b8582
Author: Jose E. Marchesi <address@hidden>
Date:   Sun May 3 11:36:29 2020 +0200

    std: new function stoca
    
    2020-05-03  Jose E. Marchesi  <address@hidden>
    
            * libpoke/std.pk (stoca): Define.
            * testsuite/poke.std/stoca-1.pk: New test.
            * testsuite/poke.std/stoca-2.pk: Likewise.
            * testsuite/poke.std/stoca-3.pk: Likewise.
            * testsuite/poke.std/stoca-4.pk: Likewise.
            * doc/poke.texi (stoca): New section.

diff --git a/ChangeLog b/ChangeLog
index 7687c004..fe444e7d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2020-05-03  Jose E. Marchesi  <address@hidden>
+
+       * libpoke/std.pk (stoca): Define.
+       * testsuite/poke.std/stoca-1.pk: New test.
+       * testsuite/poke.std/stoca-2.pk: Likewise.
+       * testsuite/poke.std/stoca-3.pk: Likewise.
+       * testsuite/poke.std/stoca-4.pk: Likewise.
+       * doc/poke.texi (stoca): New section.
+
 2020-05-03  Jose E. Marchesi  <address@hidden>
 
        * doc/poke.texi (Writing Pickles): New chapter.
diff --git a/doc/poke.texi b/doc/poke.texi
index 60fc9379..0c5eaf51 100644
--- a/doc/poke.texi
+++ b/doc/poke.texi
@@ -8783,6 +8783,7 @@ useful conversions.
 
 @menu
 * catos::              converting characters arrays into string.
+* stoca::              filling character arrays from strings.
 * atoi::               converting strings to integers.
 @end menu
 
@@ -8815,6 +8816,23 @@ Note that if the passed array contains a @code{NULL} 
character
 "foo"
 @end example
 
+@node stoca
+@subsection @code{stoca}
+@cindex @code{stoca}
+@cindex converting, strings to arrays
+Sometimes we want to store strings in character arrays.  The standard
+function @code{stoca} provides the following interface:
+
+@example
+defun stoca = (string s, char[] ca, char fill = 0) void: @{ @dots{} @}
+@end example
+
+It fills the given array @var{ca} with the contents of the string
+@var{s}.  If the string doesn't fit in the array, then
+@code{E_out_of_bounds} is raised.  If the length of the string is less
+than the length of the array, the extra characters are set to the
+@var{fill} character, which defaults to @code{\0}.
+
 @node atoi
 @subsection @code{atoi}
 @cindex @code{atoi}
diff --git a/libpoke/std.pk b/libpoke/std.pk
index 1b2e0eca..a9db4237 100644
--- a/libpoke/std.pk
+++ b/libpoke/std.pk
@@ -80,6 +80,19 @@ defun catos = (char[] chars) string:
    return s;
   }
 
+defun stoca = (string s, char[] ca, char fill = 0) void:
+  {
+    if (s'length > ca'length)
+      raise E_out_of_bounds;
+
+    defvar i = 0;
+    while (i < ca'length)
+      {
+        ca[i] = i < s'length ? s[i] : fill;
+        i = i + 1;
+      }
+  }
+
 defun atoi = (string s, int b = 10) long:
   {
     defvar result = 0;
diff --git a/testsuite/poke.std/stoca-1.pk b/testsuite/poke.std/stoca-1.pk
new file mode 100644
index 00000000..72a32b5c
--- /dev/null
+++ b/testsuite/poke.std/stoca-1.pk
@@ -0,0 +1,7 @@
+/* { dg-do run } */
+
+defvar array = [1UB,2UB,3UB,4UB];
+
+/* { dg-command { stoca ("foo", array) } } */
+/* { dg-command { array } } */
+/* { dg-output "\\\[102UB,111UB,111UB,0UB\\\]" } */
diff --git a/testsuite/poke.std/stoca-2.pk b/testsuite/poke.std/stoca-2.pk
new file mode 100644
index 00000000..7f9ad2b5
--- /dev/null
+++ b/testsuite/poke.std/stoca-2.pk
@@ -0,0 +1,7 @@
+/* { dg-do run } */
+
+defvar array = [1UB,2UB,3UB,4UB];
+
+/* { dg-command { stoca ("", array) } } */
+/* { dg-command { array } } */
+/* { dg-output "\\\[0UB,0UB,0UB,0UB\\\]" } */
diff --git a/testsuite/poke.std/stoca-3.pk b/testsuite/poke.std/stoca-3.pk
new file mode 100644
index 00000000..7f2ed9a6
--- /dev/null
+++ b/testsuite/poke.std/stoca-3.pk
@@ -0,0 +1,7 @@
+/* { dg-do run } */
+
+defvar array = [1UB,2UB,3UB,4UB];
+
+/* { dg-command { stoca ("foo", array, 'x') } } */
+/* { dg-command { array } } */
+/* { dg-output "\\\[102UB,111UB,111UB,120UB\\\]" } */
diff --git a/testsuite/poke.std/stoca-4.pk b/testsuite/poke.std/stoca-4.pk
new file mode 100644
index 00000000..7b04bbf2
--- /dev/null
+++ b/testsuite/poke.std/stoca-4.pk
@@ -0,0 +1,6 @@
+/* { dg-do run } */
+
+defvar array = [1UB,2UB,3UB,4UB];
+
+/* { dg-command { try stoca ("foooo", array); catch if E_out_of_bounds { print 
"caught\n"; } } } */
+/* { dg-output "caught" } */