{"size": 4980, "ext": "scrbl", "max_stars_repo_path": "scribblings/irandom.scrbl", "max_stars_repo_name": "hkrish/irandom", "max_stars_repo_stars_event_min_datetime": null, "max_stars_repo_stars_event_max_datetime": null, "max_issues_repo_path": "scribblings/irandom.scrbl", "max_issues_repo_name": "hkrish/irandom", "max_issues_repo_issues_event_min_datetime": null, "max_issues_repo_issues_event_max_datetime": null, "max_forks_repo_path": "scribblings/irandom.scrbl", "max_forks_repo_name": "hkrish/irandom", "max_forks_repo_forks_event_min_datetime": null, "max_forks_repo_forks_event_max_datetime": null}
{"max_stars_count": null, "max_issues_count": null, "max_forks_count": null, "avg_line_length": 37.1641791045, "max_line_length": 98, "alphanum_fraction": 0.7022088353}
#lang scribble/manual
@require[@for-label[irandom
                    racket/base
                    racket/flonum
                    racket/fixnum
                    ffi/vector
                    racket/random]]

@title{irandom}
@author{hkrish}

@defmodule[irandom]

Racket implementation of Bob Jenkins' ISAAC pseudo-random number generator.

@margin-note{At the moment, this module requires racket
 @tech["CS" #:doc '(lib "scribblings/reference/reference.scrbl")]
 variant running on a 64-bit platform.}

@nested[#:style 'inset]{
 @bold{ISAAC: a fast cryptographic random number generator}

 "ISAAC (Indirection, Shift, Accumulate, Add, and Count) generates 32-bit random numbers. ...
 Cycles are guaranteed to be at least 2@superscript["40"] values long, and they
 are 2@superscript["8295"] values long on average. The results are uniformly distributed,
 unbiased, and unpredictable unless you know the seed."

 --- @url["http://burtleburtle.net/bob/rand/isaacafa.html"]}

Output of this implementation has been tested with output of the original source for conformity
and correctness, as well as the
@link["https://webhome.phy.duke.edu/~rgb/General/dieharder.php"]{dieharder} random number
generator test suit and passes all the tests ---see the results in the @filepath{test/data}
directory.

@table-of-contents[]


@;---------------------------------------------------------

@section[#:tag "random"]{Random Numbers}

@defproc[(irandom-context? [v any/c]) boolean]{
 Returns @racket[#t] if @racket[v] is an irandom-context, @racket[#f] otherwise.
}

@defproc[(make-irandom-context) irandom-context]{
 Returns a new irandom-context. The irandom-context is used by all functions in this module
 via the parameter @racket[current-irandom-context] for generating random numbers. The new
 irandom-context is seeded with bytes from @racket[crypto-random-bytes].
}

@defparam[current-irandom-context context irandom-context?]{
 A @tech["parameter" #:doc '(lib "scribblings/reference/reference.scrbl")] that determines
 the irandom-context used by all functions in this module.
}

@defproc[(irandom) (and/c flonum? (>=/c 0) (</c 1))]{
 Returns a random @tech["flonum" #:doc '(lib "scribblings/reference/reference.scrbl")] between 0
 (inclusive) and 1 (exclusive).
}

@defproc[(irandom-fixnum) fixnum?]{
 Returns a random @tech["fixnum" #:doc '(lib "scribblings/reference/reference.scrbl")].
}

@defproc[(irandom-32) fixnum?]{
 Returns a random @tech["fixnum" #:doc '(lib "scribblings/reference/reference.scrbl")] that is
 32-bits in size. On 64-bit platforms, the leading bits are 0.
}

@defproc[(irandom-bytes [n (and/c fixnum? (>=/c 0))]) bytes?]{
 Generates @racket[n] random bytes.
}

@defproc[(irandom-list-32 [n (and/c fixnum? (>=/c 0))]) list?]{
 Returns a list containing @racket[n] 32-bit random numbers.
}

@defproc[(irandom-fxvector [n (and/c fixnum? (>=/c 0))]) fxvector?]{
 Returns a @tech["fxvector" #:doc '(lib "scribblings/reference/reference.scrbl")]
 containing @racket[n] random numbers.
}

@defproc[(irandom-fxvector-32 [n (and/c fixnum? (>=/c 0))]) fxvector?]{
 Returns a @tech["fxvector" #:doc '(lib "scribblings/reference/reference.scrbl")]
 containing @racket[n] 32-bit random numbers.
}

@defproc[(irandom-flvector [n (and/c fixnum? (>=/c 0))]) flvector?]{
 Returns a @tech["flvector" #:doc '(lib "scribblings/reference/reference.scrbl")]
 containing @racket[n] random floating point numbers, each between 0 (inclusive) and
 1 (exclusive).
}

@defproc[(irandom-u32vector [n (and/c fixnum? (>=/c 0))]) u32vector?]{
 Returns a @racket[u32vector] containing @racket[n] random 32-bit integers.
}

@defproc[(irandom-u64vector [n (and/c fixnum? (>=/c 0))]) u64vector?]{
 Returns a @racket[u64vector] containing @racket[n] random 64-bit integers.
}

@defproc[(irandom-f64vector [n (and/c fixnum? (>=/c 0))]) f64vector?]{
 Returns a @racket[f64vector] containing @racket[n] random double-precision floating
 point numbers, each between 0 (inclusive) and 1 (exclusive).
}


@;---------------------------------------------------------

@section[#:tag "uuid"]{Random UUID Generation}
@defmodule[irandom/uuid]

Following bindings are exported by both @racketmodname[irandom], and @racketmodname[irandom/uuid].

@defproc[(uuid-string) (and/c string? immutable?)]{
 Generates an immutable
 @link["https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)"]{
  version-4 random UUID} string using random bytes generated by @racket[irandom-bytes].
}

@defproc[(uuid-bytes) (and/c bytes? immutable?)]{
 Generates an immutable
 @link["https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)"]{
  version-4 random UUID} bytestring using random bytes generated by @racket[irandom-bytes].
}

@defproc[(uuid-string? [v any/c]) boolean?]{
 Checks if the input is a string or bytestring and conforms to the
 @link["https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)"]{
  version-4 random UUID} format.
}
