Merge pull request #390 from jmid/frequency-renaming

The Great Renaming, Chapter 16: `frequency` renaming

Author: jmid

README.adoc

@@ -183,7 +183,7 @@ let tree_gen = QCheck.Gen.(sized @@ fix
   (fun self n -> match n with
     | 0 -> map leaf nat
     | n ->
-      frequency
+      oneof_weighted
         [1, map leaf nat;
          2, map2 node (self (n/2)) (self (n/2))]
     ));;
@@ -221,7 +221,7 @@ generation of lists, arrays, and a choice function.
 Then, we define `arbitrary_tree`, a `tree QCheck.arbitrary` value, which
 contains everything needed for testing on trees:
 
-- a random generator (mandatory), weighted with `frequency` to
+- a random generator (mandatory), weighted with `oneof_weighted` to
   increase the chance of generating deep trees
 - a printer (optional), very useful for printing counterexamples
 - a *shrinker* (optional), very useful for trying to reduce big
@@ -313,7 +313,7 @@ let tree_gen = QCheck2.Gen.(sized @@ fix
   (fun self n -> match n with
     | 0 -> map leaf nat
     | n ->
-      frequency
+      oneof_weighted
         [1, map leaf nat;
          2, map2 node (self (n/2)) (self (n/2))]
     ));;

example/QCheck_runner_test.ml

@@ -157,7 +157,7 @@ let gen_tree = QCheck.Gen.(sized @@ fix
   (fun self n -> match n with
     | 0 -> map leaf nat
     | n ->
-      frequency
+      oneof_weighted
         [1, map leaf nat;
          2, map2 node (self (n/2)) (self (n/2))]
     ))

example/alcotest/QCheck_alcotest_test.ml

@@ -42,7 +42,7 @@ let gen_tree = QCheck.Gen.(sized @@ fix
   (fun self n -> match n with
     | 0 -> map leaf nat
     | n ->
-      frequency
+      oneof_weighted
         [1, map leaf nat;
          2, map2 node (self (n/2)) (self (n/2))]
     ))

example/ounit/QCheck_ounit_test.ml

@@ -45,7 +45,7 @@ let gen_tree = QCheck.Gen.(sized @@ fix
   (fun self n -> match n with
     | 0 -> map leaf nat
     | n ->
-      frequency
+      oneof_weighted
         [1, map leaf nat;
          2, map2 node (self (n/2)) (self (n/2))]
     ))

src/core/QCheck.ml

@@ -142,18 +142,24 @@ module Gen = struct
   let oneof_array xs st = Array.get xs (Random.State.int st (Array.length xs))
   let oneofa = oneof_array
 
-  let frequencyl l st =
+  let oneof_weighted_list l st =
     let sums = sum_int (List.map fst l) in
     let i = Random.State.int st sums in
     let rec aux acc = function
       | ((x,g)::xs) -> if i < acc+x then g else aux (acc+x) xs
-      | _ -> failwith "frequency"
+      | _ -> failwith "Gen.oneof_weighted_list"
     in
     aux 0 l
 
-  let frequencya a = frequencyl (Array.to_list a)
+  let frequencyl = oneof_weighted_list
 
-  let frequency l st = frequencyl l st st
+  let oneof_weighted_array a = oneof_weighted_list (Array.to_list a)
+
+  let frequencya = oneof_weighted_array
+
+  let oneof_weighted l st = oneof_weighted_list l st st
+
+  let frequency = oneof_weighted
 
   let int_pos_small st =
     let p = RS.float st 1. in
@@ -1873,19 +1879,26 @@ let always ?print x =
   make ?print gen
 
 (** like oneof, but with weights *)
-let frequency ?print ?small ?shrink ?collect l =
+let oneof_weighted ?print ?small ?shrink l =
   let first = snd (List.hd l) in
   let small = _opt_sum small first.small in
   let print = _opt_sum print first.print in
   let shrink = _opt_sum shrink first.shrink in
-  let collect = _opt_sum collect first.collect in
   let gens = List.map (fun (x,y) -> x, y.gen) l in
-  make ?print ?small ?shrink ?collect (Gen.frequency gens)
+  make ?print ?small ?shrink (Gen.oneof_weighted gens)
+
+let frequency ?print ?small ?shrink ?collect l =
+  let arb = oneof_weighted ?print ?small ?shrink l in
+  match collect with
+  | None -> arb
+  | Some c -> set_collect c arb
 
 (** Given list of [(frequency,value)] pairs, returns value with probability proportional
     to given frequency *)
-let frequencyl ?print ?small l = make ?print ?small (Gen.frequencyl l)
-let frequencya ?print ?small l = make ?print ?small (Gen.frequencya l)
+let oneof_weighted_list ?print ?small l = make ?print ?small (Gen.oneof_weighted_list l)
+let frequencyl = oneof_weighted_list
+let oneof_weighted_array ?print ?small a = make ?print ?small (Gen.oneof_weighted_array a)
+let frequencya = oneof_weighted_array
 
 let map_same_type f a =
   adapt_ a (fun st -> f (a.gen st))

src/core/QCheck.mli

@@ -69,7 +69,7 @@ all rights reserved.
                             (fun self n -> match n with
                                | 0 -> map leaf nat
                                | n ->
-                                 frequency
+                                 oneof_weighted
                                    [1, map leaf nat;
                                     2, map2 node (self (n/2)) (self (n/2))]
                             ))
@@ -224,17 +224,35 @@ module Gen : sig
       @raise Invalid_argument or Failure if list is empty
       @deprecated use {!oneof_array} instead. *)
 
+  val oneof_weighted : (int * 'a t) list -> 'a t
+  (** Constructs a generator that selects among a given list of generators.
+      Each of the given generators are chosen based on a positive integer weight.
+      @since NEXT_RELEASE *)
+
   val frequency : (int * 'a t) list -> 'a t
   (** Constructs a generator that selects among a given list of generators.
-      Each of the given generators are chosen based on a positive integer weight. *)
+      Each of the given generators are chosen based on a positive integer weight.
+      @deprecated use {!oneof_weighted} instead. *)
+
+  val oneof_weighted_list : (int * 'a) list -> 'a t
+  (** Constructs a generator that selects among a given list of values.
+      Each of the given values are chosen based on a positive integer weight.
+      @since NEXT_RELEASE *)
 
   val frequencyl : (int * 'a) list -> 'a t
   (** Constructs a generator that selects among a given list of values.
-      Each of the given values are chosen based on a positive integer weight. *)
+      Each of the given values are chosen based on a positive integer weight.
+      @deprecated use {!oneof_weighted_list} instead. *)
+
+  val oneof_weighted_array : (int * 'a) array -> 'a t
+  (** Constructs a generator that selects among a given array of values.
+      Each of the array entries are chosen based on a positive integer weight.
+      @since NEXT_RELEASE *)
 
   val frequencya : (int * 'a) array -> 'a t
   (** Constructs a generator that selects among a given array of values.
-      Each of the array entries are chosen based on a positive integer weight. *)
+      Each of the array entries are chosen based on a positive integer weight.
+      @deprecated use {!oneof_weighted_array} instead. *)
 
   val shuffle_array : 'a array -> 'a array t
   (** Creates a generator of shuffled arrays.
@@ -735,7 +753,7 @@ module Gen : sig
                               (fun self n -> match n with
                                  | 0 -> map leaf nat
                                  | n ->
-                                   frequency
+                                   oneof_weighted
                                      [1, map leaf nat;
                                       2, map2 node (self (n/2)) (self (n/2))]
                               ))
@@ -1782,19 +1800,38 @@ val oneof : 'a arbitrary list -> 'a arbitrary
 val always : ?print:'a Print.t -> 'a -> 'a arbitrary
 (** Always return the same element. *)
 
+val oneof_weighted : ?print:'a Print.t -> ?small:('a -> int) ->
+  ?shrink:'a Shrink.t -> (int * 'a arbitrary) list -> 'a arbitrary
+(** Similar to {!oneof} but with frequencies.
+    @since NEXT_RELEASE *)
+
 val frequency : ?print:'a Print.t -> ?small:('a -> int) ->
   ?shrink:'a Shrink.t -> ?collect:('a -> string) ->
   (int * 'a arbitrary) list -> 'a arbitrary
-(** Similar to {!oneof} but with frequencies. *)
+(** Similar to {!oneof} but with frequencies.
+    @deprecated use {!oneof_weighted} instead. *)
+
+val oneof_weighted_list : ?print:'a Print.t -> ?small:('a -> int) ->
+  (int * 'a) list -> 'a arbitrary
+(** Same as {!oneof_list}, but each element is paired with its frequency in
+    the probability distribution (the higher, the more likely).
+    @since NEXT_RELEASE *)
 
 val frequencyl : ?print:'a Print.t -> ?small:('a -> int) ->
   (int * 'a) list -> 'a arbitrary
 (** Same as {!oneof_list}, but each element is paired with its frequency in
-    the probability distribution (the higher, the more likely). *)
+    the probability distribution (the higher, the more likely).
+    @deprecated use {!oneof_weighted_list} instead. *)
+
+val oneof_weighted_array : ?print:'a Print.t -> ?small:('a -> int) ->
+  (int * 'a) array -> 'a arbitrary
+(** Same as {!oneof_frequency_list}, but with an array.
+    @since NEXT_RELEASE *)
 
 val frequencya : ?print:'a Print.t -> ?small:('a -> int) ->
   (int * 'a) array -> 'a arbitrary
-(** Same as {!frequencyl}, but with an array. *)
+(** Same as {!oneof_frequency_list}, but with an array.
+    @deprecated use {!oneof_weighted_array} instead. *)
 
 val map : ?rev:('b -> 'a) -> ('a -> 'b) -> 'a arbitrary -> 'b arbitrary
 (** [map f a] returns a new arbitrary instance that generates values using

src/core/QCheck2.ml

@@ -646,10 +646,10 @@ module Gen = struct
   let small_signed_int = int_small
 
   (** Shrink towards the first element of the list *)
-  let frequency (l : (int * 'a t) list) : 'a t =
-    if l = [] then failwith "QCheck2.frequency called with an empty list";
+  let oneof_weighted (l : (int * 'a t) list) : 'a t =
+    if l = [] then failwith "QCheck2.Gen.oneof_weighted called with an empty list";
     let sums = sum_int (List.map fst l) in
-    if sums < 1 then failwith "QCheck2.frequency called with weight sum < 1";
+    if sums < 1 then failwith "QCheck2.Gen.oneof_weighted called with weight sum < 1";
     int_bound (sums - 1)
     >>= fun i ->
     let rec aux acc = function
@@ -658,11 +658,17 @@ module Gen = struct
     in
     aux 0 l
 
-  let frequencyl (l : (int * 'a) list) : 'a t =
+  let frequency = oneof_weighted
+
+  let oneof_weighted_list (l : (int * 'a) list) : 'a t =
     List.map (fun (weight, value) -> (weight, pure value)) l
-    |> frequency
+    |> oneof_weighted
+
+  let frequencyl = oneof_weighted_list
+
+  let oneof_weighted_array a = oneof_weighted_list (Array.to_list a)
 
-  let frequencya a = frequencyl (Array.to_list a)
+  let frequencya = oneof_weighted_array
 
   let char_range ?(origin : char option) (a : char) (b : char) : char t =
     (int_range ~origin:(Char.code (Option.value ~default:a origin)) (Char.code a) (Char.code b)) >|= Char.chr

src/core/QCheck2.mli

@@ -82,7 +82,7 @@ content will appear. *)
                                     (fun self n -> match n with
                                        | 0 -> map leaf nat
                                        | n ->
-                                         frequency
+                                         oneof_weighted
                                            [1, map leaf nat;
                                             2, map2 node (self (n/2)) (self (n/2))]
                                     ));;
@@ -721,25 +721,52 @@ module Gen : sig
       @deprecated use {!oneof_array} instead.
   *)
 
+  val oneof_weighted : (int * 'a t) list -> 'a t
+  (** Constructs a generator that selects among a given list of generators.
+      Each of the given generators are chosen based on a positive integer weight.
+
+      Shrinks towards the first element of the list.
+      @since NEXT_RELEASE
+  *)
+
   val frequency : (int * 'a t) list -> 'a t
   (** Constructs a generator that selects among a given list of generators.
       Each of the given generators are chosen based on a positive integer weight.
 
       Shrinks towards the first element of the list.
+      @deprecated use {!oneof_weighted} instead.
+  *)
+
+  val oneof_weighted_list : (int * 'a) list -> 'a t
+  (** Constructs a generator that selects among a given list of values.
+      Each of the given values are chosen based on a positive integer weight.
+
+      Shrinks towards the first element of the list.
+      @since NEXT_RELEASE
   *)
 
   val frequencyl : (int * 'a) list -> 'a t
   (** Constructs a generator that selects among a given list of values.
       Each of the given values are chosen based on a positive integer weight.
 
       Shrinks towards the first element of the list.
+      @deprecated use {!oneof_weighted_list} instead.
+  *)
+
+  val oneof_weighted_array : (int * 'a) array -> 'a t
+  (** Constructs a generator that selects among a given array of values.
+      Each of the array entries are chosen based on a positive integer weight.
+
+      Shrinks towards the first element of the array.
+      @since NEXT_RELEASE
   *)
 
   val frequencya : (int * 'a) array -> 'a t
   (** Constructs a generator that selects among a given array of values.
       Each of the array entries are chosen based on a positive integer weight.
 
       Shrinks towards the first element of the array.
+      @deprecated use {!oneof_weighted_array} instead.
   *)
 
   (** {3 Shuffling elements} *)
@@ -1068,7 +1095,7 @@ module Gen : sig
                               (fun self n -> match n with
                                  | 0 -> map leaf nat
                                  | n ->
-                                   frequency
+                                   oneof_weighted
                                      [1, map leaf nat;
                                       2, map2 node (self (n/2)) (self (n/2))]
                               ))
@@ -1185,18 +1212,18 @@ module Gen : sig
             then int >|= Result.ok
             else string_printable >|= Result.error)
 
-        (* Another allternative syntax with OCaml 4.08+ binding operators *)
+        (* Another alternative syntax with OCaml 4.08+ binding operators *)
         let int_string_result : (int, string) result Gen.t = Gen.(
             let* n = int_range 0 9 in
             if n < 9
             then int >|= Result.ok
             else string_printable >|= Result.error)
       ]}
 
-      Note that this particular use case can be simplified by using [frequency]:
+      Note that this particular use case can be simplified by using [oneof_weighted]:
       {[
         let int_string_result : (int, string) result Gen.t = Gen.(
-            frequency [
+            oneof_weighted [
               (9, int >|= Result.ok);
               (1, string_printable >|= Result.error)
             ])

src/ppx_deriving_qcheck/QCheck_generators.ml

@@ -68,11 +68,11 @@ let pure ~loc ~version e =
   let gen = with_prefix_gen loc version "pure" in
   apply1 loc gen e
 
-let frequency ~loc ~version l =
+let oneof_weighted ~loc ~version l =
   match l with
   | [%expr [([%e? _], [%e? x])]] -> x
   | _ ->
-     let gen = with_prefix_gen loc version "frequency" in
+     let gen = with_prefix_gen loc version "oneof_weighted" in
      apply1 loc gen l
 
 let map ~loc ~version pat expr gen =
@@ -167,7 +167,7 @@ module Make (Version : sig val version : version end) = struct
   let list ~loc = list ~loc ~version
   let array ~loc = array ~loc ~version
   let pure ~loc x = pure ~loc ~version x
-  let frequency ~loc l = frequency ~loc ~version l
+  let oneof_weighted ~loc l = oneof_weighted ~loc ~version l
   let map ~loc pat expr gen = map ~loc ~version pat expr gen
   let pair ~loc a b = pair ~loc ~version a b
   let triple ~loc a b c = triple ~loc ~version a b c