[COMMITTED] doc: document array casts in the manual

[Jose E. Marchesi]

2021-12-23  Jose E. Marchesi  <jemarch@gnu.org>

        * doc/poke.texi (Casting Arrays): New section.
        * etc/poke.rec (Document array casts in the manual): Removed as
        done.
---
 ChangeLog     |  6 ++++++
 doc/poke.texi | 41 +++++++++++++++++++++++++++++++++++++++++
 etc/poke.rec  |  6 ------
 3 files changed, 47 insertions(+), 6 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 01df1fef..2a13c980 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,11 @@
 2021-12-23  Jose E. Marchesi  <jemarch@gnu.org>
 
+       * doc/poke.texi (Casting Arrays): New section.
+       * etc/poke.rec (Document array casts in the manual): Removed as
+       done.
+
+2021-12-23  Jose E. Marchesi  <jemarch@gnu.org>
+
        * libpoke/pkl-typify.c (pkl_typify1_pr_func): Do not set location
        information in generated type.
        * libpoke/pkl-anal.c (pkl_anal1_pr_func): Fix checking for vararg
diff --git a/doc/poke.texi b/doc/poke.texi
index f787691c..9bf4b82b 100644
--- a/doc/poke.texi
+++ b/doc/poke.texi
@@ -9603,6 +9603,7 @@ Arrays are homogeneous collections of values.
 @menu
 * Array Literals::             Writing array values.
 * Array Types::                        Bounded and unbounded arrays.
+* Casting Arrays::              Converting arrays from one type to another.
 * Array Constructors::         Constructing array values.
 * Array Comparison::           Comparing array values.
 * Array Indexing::             Accessing values stored in arrays.
@@ -9803,6 +9804,46 @@ allows data structures to adjust to the particular data 
they contain,
 so usual in binary formats.  This is an important feature, that gives
 Poke part of its feel and magic.
 
+@node Casting Arrays
+@subsection Casting Arrays
+@cindex casting, arrays
+
+Poke allows to cast array values to array types that may have a
+different bounding.
+
+For example, we have seen that the type of an array literal is always
+bounded by a constant number of elements.  Thus the type of
+@code{[1,2,3]} is @code{int[3]}.
+
+We could cast the value above to an unbounded array type by doing:
+
+@example
+[1,2,3] as int[]
+@end example
+
+@noindent
+Or to an array bounded by size:
+
+@example
+[1,2,3] as int[12#B]
+@end example
+
+Of course trying to cast an array value to a type for which the
+bounding restrictions will fail.  This will give you a compile-time
+error:
+
+@example
+[1,2,3] as int[4]
+@end example
+
+@noindent
+And this will result in a run-time error:
+
+@example
+(poke) [1,2,3] as int[13#B]
+unhandled conversion error exception
+@end example
+
 @node Array Constructors
 @subsection Array Constructors
 @cindex constructing, arrays
diff --git a/etc/poke.rec b/etc/poke.rec
index 05967e03..e1902fb8 100644
--- a/etc/poke.rec
+++ b/etc/poke.rec
@@ -1517,12 +1517,6 @@ Kind: ENH
 Priority: 2
 Target: 1.1
 
-Summary: Document array casts in the manual
-Component: Documentation
-Kind: ENH
-Priority: 2
-Target: 1.1
-
 Summary: Document poke CSS classes in the manual
 Component: Documentation
 Kind: ENH
-- 
2.11.0