.. zsh-module-meta::
   :name: zsh/random
   :summary: Some high-quality randomness parameters and functions.

The ``zsh/random`` module gets random data from the kernel random pool. If no
kernel random pool can be found, the module will not load.

Parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. index:: single: SRANDOM; Variable

``SRANDOM``
    
    A random positive 32-bit integer between 0 and 4,294,967,295.  This parameter
    is read-only. The name was chosen for compatibility with Bash and to
    distinguish it from ``RANDOM`` which has a documented repeatable behavior.
    

Math Functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``zrand_float()``
    
    Returns a random floating point number between 0 and 1 inclusive.
    

``zrand_int``\(:var:`upper`, :var:`lower`, :var:`inclusive`)
    
    Returns a random integer between :var:`lower` and :var:`upper`. All parameters
    are optional.  If none are specified it is equivalent to ``SRANDOM``. Note
    that this is equivalent to passing the default values except that it
    is inclusive.
    
    :var:`upper` is the upper bound on the resultant number and defaults to
    4,294,967,295. It is exclusive by default, unless :var:`inclusive` is passed.
    
    :var:`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.
    
    :var:`inclusive` is a flag that controls whether the :var:`upper` bound is
    exclusive or inclusive. Passing any non-zero value makes it inclusive,
    otherwise it is exclusive when the :var:`upper` bound is specified. The
    :var:`lower` bound is always inclusive.
    
    This is to facilitate a construct like ``$a[zrand_int($#a)+1]`` rather
    than ``$a[zrand_int($#a-1)+1]``.
    For example, if $#a is 16, you would use ``zrand_int(16)`` which has
    16 possible return values 0-15.  Because the function can return zero, in order
    to use it as an array index from 1-16 you need to add one.  It would
    be an array index range error for it to also potentially return 16 ($#a). You
    could, however, use the construct ``zrand_int(16,1,1)`` instead of
    adding 1 to achieve the same result, but it is more verbose.
    
    Most statistics algorithms seem to also expect 0 to :var:`upper`-1, so this was
    deemed the most commonly desired case and chosen as the default.
    

