diff --git a/src/Iter.mli b/src/Iter.mli index 28be7a6..e833fff 100644 --- a/src/Iter.mli +++ b/src/Iter.mli @@ -707,6 +707,8 @@ end (** {1 Random iterators} *) +(** {2 Generating} *) + val random_int : int -> int t (** Infinite iterator of random integers between 0 and the given higher bound (see Random.int) *) @@ -745,6 +747,26 @@ val sample : int -> 'a t -> 'a array It returns an array of size [min (length seq) n]. @since 0.7 *) +(** {2 Seeding} + + Random iterators use [Random.int], [Random.float], [Random.bool], + etc., under the hood, so they will respect seeding of the random + generator in the usual way. I.e., if you do not initialize the + random generator with one of [Random.init], [Random.full_init], or + [Random.self_init] before calling these functions, they will yield + the same values across seperate invocations of your program. + + Example: + + {[ + (* Ensure a fresh random seed each time the program is executed. *) + let () = Random.self_init () + + (* Generate random values. *) + let l = Iter.random_int 1000 |> Iter.take 3 |> Iter.to_list + ]} + *) + (** {1 Infix functions} *) module Infix : sig diff --git a/src/IterLabels.mli b/src/IterLabels.mli index 65a566b..4d06a9a 100644 --- a/src/IterLabels.mli +++ b/src/IterLabels.mli @@ -676,6 +676,8 @@ end (** {2 Random iterators} *) +(** {3 Generating} *) + val random_int : int -> int t (** Infinite iterator of random integers between 0 and the given higher bound (see Random.int) *) @@ -714,6 +716,26 @@ val sample : n:int -> 'a t -> 'a array It returns an array of size [min (length seq) n]. @since 0.7 *) +(** {3 Seeding} + + Random iterators use [Random.int], [Random.float], [Random.bool], + etc., under the hood, so they will respect seeding of the random + generator in the usual way. I.e., if you do not initialize the + random generator with one of [Random.init], [Random.full_init], or + [Random.self_init] before calling these functions, they will yield + the same values across seperate invocations of your program. + + Example: + + {[ + (* Ensure a fresh random seed each time the program is executed. *) + let () = Random.self_init () + + (* Generate random values. *) + let l = Iter.random_int 1000 |> Iter.take 3 |> Iter.to_list + ]} + *) + (** {2 Infix functions} *) module Infix : sig