Re: [PATCH] doc: Add doc for array integrators

[Jose E. Marchesi]

Hi Mohammad.
OK for master.
Thanks!

> 2022-01-22  Mohammad-Reza Nabipoor  <mnabipoor@gnu.org>
>
>       * doc/poke.texi (Casting Arrays): Add documentation for
>       array integrators.
> ---
>  ChangeLog     |  5 +++++
>  doc/poke.texi | 43 ++++++++++++++++++++++++++++++++++++++++---
>  2 files changed, 45 insertions(+), 3 deletions(-)
>
> diff --git a/ChangeLog b/ChangeLog
> index 218b299d..8e0f0727 100644
> --- a/ChangeLog
> +++ b/ChangeLog
> @@ -1,3 +1,8 @@
> +2022-01-22  Mohammad-Reza Nabipoor  <mnabipoor@gnu.org>
> +
> +     * doc/poke.texi (Casting Arrays): Add documentation for
> +     array integrators.
> +
>  2022-01-22  Mohammad-Reza Nabipoor  <mnabipoor@gnu.org>
>  
>       * libpoke/pkl-trans.c (pkl_trans2_ps_op_attr): New phase for
> diff --git a/doc/poke.texi b/doc/poke.texi
> index 74b4981d..50d06d55 100644
> --- a/doc/poke.texi
> +++ b/doc/poke.texi
> @@ -10033,10 +10033,16 @@ Poke part of its feel and magic.
>  
>  @node Casting Arrays
>  @subsection Casting Arrays
> -@cindex casting, arrays
> +@cindex casting, integration, integrate, arrays
>  
> -Poke allows to cast array values to array types that may have a
> -different bounding.
> +There are two kinds of casts for array values:
> +
> +@itemize @bullet
> +@item
> +Cast to array types that may have a different bounding.
> +@item
> +Cast of array of integers or integral structs to an integral type.
> +@end itemize
>  
>  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
> @@ -10071,6 +10077,37 @@ And this will result in a run-time error:
>  unhandled conversion error exception
>  @end example
>  
> +Now let's see how Poke reinterprets integral arrays as integers:
> +
> +@example
> +(poke) [0xdeUB,0xadUB] as uint16
> +0xdeadUH
> +(poke) [0xdeUB,0xadUB,0UB] as int
> +0xdead00
> +@end example
> +
> +Trying to cast an array with a size larger than 64-bit will result
> +in an error:
> +
> +@example
> +(poke) [1,2,3] as int
> +unhandled conversion error exception
> +arrays bigger than 64-bit cannot be casted to integral types
> +@end example
> +
> +It also works for nested arrays and arrays of integral structs
> +(@xref{Integral Structs}):
> +
> +@example
> +(poke) type Foo = struct uint @{ int16 hi; int16 lo; @};
> +(poke) [[Foo@{ hi=0xdeadH, lo=0xbeefH@}],[Foo@{@}]] as ulong
> +0xdeadbeef00000000UL
> +@end example
> +
> +The way it works is like putting all array elements in an
> +@code{uint<64>} number and then casting that number to the
> +destination integral type.
> +
>  @node Array Constructors
>  @subsection Array Constructors
>  @cindex constructing, arrays