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

[Clinton Bunch <cdb_zsh@zentaur.org>]

On 3/26/2024 07:47, Clinton Bunch wrote:
> On 3/24/2024 21:34, Bart Schaefer wrote:
>> On Sun, Mar 24, 2024 at 7:11 AM Clinton Bunch <cdb_zsh@zentaur.org> 
>> 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.
>
>
Also added a statement that the default values of upper and lower are 
also their limits.

tt(upper) is the upper bound on the resultant number and defaults to
4,294,967,295.

tt(lower) is the lower bound and defaults to 0.

The defaults of these two arguments are also the maximum and minimum to 
which
either can be set.