Re: [PATCH 0/1] zsh/random module

[Clinton Bunch <cdb_zsh@xxxxxxxxxxx>]

On 3/24/2024 21:34, Bart Schaefer wrote:
> On Sun, Mar 24, 2024 at 7:11 AM Clinton Bunch <cdb_zsh@xxxxxxxxxxx> wrote:
> > zrand_int takes 0-3 arguments, an exclusive upper bound, a lower bound,
> > a flag to make the upper bound inclusive.
> Documentation remarks:
>
> +optional.  If none are specified it is equivilent to
>
> Typo: "equivalent'
>
> +tt(inclusive) is a flag to determine whether the result can ever equal
> +tt(upper).  By default it can not. If this argument is set to a non-zero value
> +then it can.
>
> Something about the use of "can" in those sentences strikes me as odd.
>    a flag that controls whether the result is ever equal to
>    by default it is not
>    then it may be
> ??
>
> +possible return values 0-15, in order to use it as an array index which goes
> +from 1-16 you need to add one.  Since it can return zero, you don't want it
> +to return 16.
>
> It took me a few re-readings to figure out that "16" is meant as an
> example result of $#a from the previous two expressions.  The switch
> to addressing the reader as in "you need" / "you don't want" threw me
> off.  Perhaps adding:
>    For example, if $#a is 16,
> and then end sentence and start again:
>    values 0-15.  Thus in order
> I might also change "Since" to "Because".
Does this work better:

tt(inclusive) is a flag that controls whether the result is ever equal to
tt(upper).  By default it is not. If this argument is set to a non-zero 
value
then it may be.

This is to facilitate a construct like tt($a[zrand_int($#a)+1]) rather
than tt($a[zrand_int+LPAR()$#a-1+RPAR()+1]).
For example, if $#a is 16, you would use tt(zrand_int+LPAR()16RPAR()) 
which has
16 possible return values 0-15, in order to use it as an array index 
which goes
from 1-16 you need to add one.  Because the function can return zero, it 
would
be an array index range error for it to also potentially return 16 
($#a). You
could, however, use the construct tt(zrand_int+LPAR()16,1,1+RPAR()) 
instead of
adding 1 to achieve the same result, but it is more verbose.

Most statistics algorithms seem to also expect 0 to tt(upper)-1, so this was
deemed the most commonly desired case and chosen as the default.