%--------------------------------------------------%
% vim: ft=mercury ts=4 sts=4 sw=4 et
%--------------------------------------------------%
% Copyright (C) 2019, 2020, 2022 The Mercury team.
% This file is distributed under the terms specified in COPYING.LIB.
%--------------------------------------------------%
%
% File: random.sfc32.m
% Main author: Mark Brown
%
% 32-bit Small Fast Counting generator, by Chris Doty-Humphrey.
%
% http://pracrand.sourceforge.net/
%
% From the above:
% "[A] good small chaotic RNG driven by a bad smaller linear RNG. The
% combination gives it the strengths of each - good chaotic behavior,
% but enough structure to avoid short cycles."
%
%--------------------------------------------------%
%--------------------------------------------------%

:- module random.sfc32.
:- interface.

%--------------------------------------------------%

    % A fast, 32-bit SFC generator with unique state. This may achieve
    % better performance on 32-bit architectures, but generally does not
    % have the quality of the 64-bit generator or the low heap usage of
    % the 16-bit generator.
    %
:- type params.
:- type ustate.

:- instance urandom(params, ustate).
:- instance urandom_dup(ustate).

    % Initialise a 32-bit SFC generator with the default seed. The
    % resulting generator produces the same sequence every time.
    %
:- pred init(params::out, ustate::uo) is det.

    % Initialise a 32-bit SFC generator with the given seed.
    %
:- pred seed(uint32::in, uint32::in, uint32::in, params::out, ustate::uo)
    is det.

    % Generate a uniformly distributed pseudo-random unsigned integer
    % of 8, 16, 32 or 64 bits, respectively.
    %
:- pred generate_uint8(params::in, uint8::out,
    ustate::di, ustate::uo) is det.
:- pred generate_uint16(params::in, uint16::out,
    ustate::di, ustate::uo) is det.
:- pred generate_uint32(params::in, uint32::out,
    ustate::di, ustate::uo) is det.
:- pred generate_uint64(params::in, uint64::out,
    ustate::di, ustate::uo) is det.

    % Duplicate a 32-bit SFC state.
    %
:- pred urandom_dup(ustate::di, ustate::uo, ustate::uo) is det.

%--------------------------------------------------%

    % Generate a uniformly distributed pseudo-random unsigned integer
    % of 8, 16, 32 or 64 bits, respectively.
    %
    % As above, but does not require the params argument (which is a dummy
    % type only needed to satisfy the typeclass interface).
    %
:- pred generate_uint8(uint8::out, ustate::di, ustate::uo) is det.
:- pred generate_uint16(uint16::out, ustate::di, ustate::uo) is det.
:- pred generate_uint32(uint32::out, ustate::di, ustate::uo) is det.
:- pred generate_uint64(uint64::out, ustate::di, ustate::uo) is det.

%--------------------------------------------------%
%--------------------------------------------------%