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.