Revise documentation, add benchmarks (#3)

* [stdlib] Revise documentation for new random APIs

* [stdlib] Fix constraints on random integer generation

* [test] Isolate failing Random test

* [benchmark] Add benchmarks for new random APIs

Fix Float80 test

Value type generators

random -> randomElement

Fix some docs

One more doc fix

Doc fixes & bool fix

Use computed over explicit

(cherry picked from commit f146d17)

Author: natecook1000

benchmark/CMakeLists.txt

@@ -122,6 +122,8 @@ set(SWIFT_BENCH_MODULES
     single-source/Queue
     single-source/RC4
     single-source/RGBHistogram
+    single-source/RandomShuffle
+    single-source/RandomValues
     single-source/RangeAssignment
     single-source/RangeIteration
     single-source/RangeReplaceableCollectionPlusDefault

benchmark/single-source/RandomShuffle.swift

@@ -0,0 +1,64 @@
+//===--- RandomShuffle.swift ----------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2018 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+import TestsUtils
+
+//
+// Benchmark that shuffles arrays of integers. Measures the performance of
+// shuffling large arrays.
+//
+
+public let RandomShuffle = [
+  BenchmarkInfo(name: "RandomShuffleDef", runFunction: run_RandomShuffleDef,
+    tags: [.api], setUpFunction: setup_RandomShuffle),
+  BenchmarkInfo(name: "RandomShuffleLCG", runFunction: run_RandomShuffleLCG,
+    tags: [.api], setUpFunction: setup_RandomShuffle),
+]
+
+/// A linear congruential PRNG.
+struct LCRNG: RandomNumberGenerator {
+  private var state: UInt64
+  
+  init(seed: Int) {
+    state = UInt64(truncatingIfNeeded: seed)
+    for _ in 0..<10 { _ = next() }
+  }
+  
+  mutating func next() -> UInt64 {
+    state = 2862933555777941757 &* state &+ 3037000493
+    return state
+  }
+}
+
+var numbers = Array(0...3_000_000)
+
+@inline(never)
+func setup_RandomShuffle() {
+  _ = numbers.count
+}
+
+@inline(never)
+public func run_RandomShuffleDef(_ N: Int) {
+  for _ in 0 ..< N {
+    numbers.shuffle()
+    blackHole(numbers.first!)
+  }
+}
+
+@inline(never)
+public func run_RandomShuffleLCG(_ N: Int) {
+  var generator = LCRNG(seed: 0)
+  for _ in 0 ..< N {
+    numbers.shuffle(using: &generator)
+    blackHole(numbers.first!)
+  }
+}

benchmark/single-source/RandomValues.swift

@@ -0,0 +1,87 @@
+//===--- RandomValues.swift -----------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2018 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+import TestsUtils
+
+//
+// Benchmark generating lots of random values. Measures the performance of
+// the default random generator and the algorithms for generating integers
+// and floating-point values.
+//
+
+public let RandomValues = [
+  BenchmarkInfo(name: "RandomIntegersDef", runFunction: run_RandomIntegersDef, tags: [.api]),
+  BenchmarkInfo(name: "RandomIntegersLCG", runFunction: run_RandomIntegersLCG, tags: [.api]),
+  BenchmarkInfo(name: "RandomDoubleDef", runFunction: run_RandomDoubleDef, tags: [.api]),
+  BenchmarkInfo(name: "RandomDoubleLCG", runFunction: run_RandomDoubleLCG, tags: [.api]),
+]
+
+/// A linear congruential PRNG.
+struct LCRNG: RandomNumberGenerator {
+  private var state: UInt64
+  
+  init(seed: Int) {
+    state = UInt64(truncatingIfNeeded: seed)
+    for _ in 0..<10 { _ = next() }
+  }
+  
+  mutating func next() -> UInt64 {
+    state = 2862933555777941757 &* state &+ 3037000493
+    return state
+  }
+}
+
+@inline(never)
+public func run_RandomIntegersDef(_ N: Int) {
+  for _ in 0 ..< N {
+    var x = 0
+    for _ in 0 ..< 100_000 {
+      x &+= Int.random(in: 0...10_000)
+    }
+    blackHole(x)
+  }
+}
+
+@inline(never)
+public func run_RandomIntegersLCG(_ N: Int) {
+  for _ in 0 ..< N {
+    var x = 0
+    var generator = LCRNG(seed: 0)
+    for _ in 0 ..< 100_000 {
+      x &+= Int.random(in: 0...10_000, using: &generator)
+    }
+    CheckResults(x == 498214315)
+  }
+}
+
+@inline(never)
+public func run_RandomDoubleDef(_ N: Int) {
+  for _ in 0 ..< N {
+    var x = 0.0
+    for _ in 0 ..< 100_000 {
+      x += Double.random(in: -1000...1000)
+    }
+    blackHole(x)
+  }
+}
+
+@inline(never)
+public func run_RandomDoubleLCG(_ N: Int) {
+  for _ in 0 ..< N {
+    var x = 0.0
+    var generator = LCRNG(seed: 0)
+    for _ in 0 ..< 100_000 {
+      x += Double.random(in: -1000...1000, using: &generator)
+    }
+    blackHole(x)
+  }
+}

benchmark/utils/main.swift

@@ -110,6 +110,8 @@ import ProtocolDispatch2
 import Queue
 import RC4
 import RGBHistogram
+import RandomShuffle
+import RandomValues
 import RangeAssignment
 import RangeIteration
 import RangeReplaceableCollectionPlusDefault
@@ -264,6 +266,8 @@ registerBenchmark(QueueGeneric)
 registerBenchmark(QueueConcrete)
 registerBenchmark(RC4Test)
 registerBenchmark(RGBHistogram)
+registerBenchmark(RandomShuffle)
+registerBenchmark(RandomValues)
 registerBenchmark(RangeAssignment)
 registerBenchmark(RangeIteration)
 registerBenchmark(RangeReplaceableCollectionPlusDefault)

stdlib/public/core/Bool.swift

@@ -94,9 +94,9 @@ public struct Bool {
   /// - Returns: A random Boolean.
   @inlinable
   public static func random<T: RandomNumberGenerator>(
-    using generator: T
+    using generator: inout T
   ) -> Bool {
-    return generator.next() % 2 == 0
+    return (generator.next() >> 17) & 1 == 0
   }
 
   /// Returns a random Boolean
@@ -108,7 +108,7 @@ public struct Bool {
   /// This uses the standard library's default random number generator.
   @inlinable
   public static func random() -> Bool {
-    return Bool.random(using: Random.default)
+    return Bool.random(using: &Random.default)
   }
 }
 

stdlib/public/core/Collection.swift

@@ -1016,27 +1016,24 @@ extension Collection {
     return count
   }
 
-  /// Returns a random element from this collection.
+  /// Returns a random element of the collection, using the given generator as
+  /// a source for randomness.
   ///
-  /// - Parameter generator: The random number generator to use when getting
-  ///   a random element.
-  /// - Returns: A random element from this collection.
-  ///
-  /// A good example of this is getting a random greeting from an array:
-  ///
-  ///     let greetings = ["hi", "hey", "hello", "hola"]
-  ///     let randomGreeting = greetings.random()
+  /// You use this method to select a random element from a collection when you
+  /// are using a custom random number generator. For example, call
+  /// `randomElement(using:)` to select a random element from an array of names.
   ///
-  /// If the collection is empty, the value of this function is `nil`.
+  ///     let names = ["Zoey", "Chloe", "Amani", "Amaia"]
+  ///     let randomName = names.randomElement(using: &myGenerator)!
+  ///     // randomName == "Amani" (maybe)
   ///
-  ///     let numbers = [10, 20, 30, 40, 50]
-  ///     if let randomNumber = numbers.random() {
-  ///         print(randomNumber)
-  ///     }
-  ///     // Could print "20", perhaps
+  /// - Parameter generator: The random number generator to use when choosing
+  ///   a random element.
+  /// - Returns: A random element from the collection. If the collection is
+  ///   empty, the method returns `nil`.
   @inlinable
-  public func random<T: RandomNumberGenerator>(
-    using generator: T
+  public func randomElement<T: RandomNumberGenerator>(
+    using generator: inout T
   ) -> Element? {
     guard !isEmpty else { return nil }
     let random = generator.next(upperBound: UInt(count))
@@ -1048,29 +1045,24 @@ extension Collection {
     return self[index]
   }
 
-  /// Returns a random element from this collection.
+  /// Returns a random element of the collection.
   ///
-  /// - Parameter generator: The random number generator to use when getting
-  ///   a random element.
-  /// - Returns: A random element from this collection.
-  ///
-  /// A good example of this is getting a random greeting from an array:
-  ///
-  ///     let greetings = ["hi", "hey", "hello", "hola"]
-  ///     let randomGreeting = greetings.random()
+  /// For example, call `randomElement()` to select a random element from an
+  /// array of names.
   ///
-  /// If the collection is empty, the value of this function is `nil`.
+  ///     let names = ["Zoey", "Chloe", "Amani", "Amaia"]
+  ///     let randomName = names.randomElement()!
+  ///     // randomName == "Amani" (perhaps)
   ///
-  ///     let numbers = [10, 20, 30, 40, 50]
-  ///     if let randomNumber = numbers.random() {
-  ///         print(randomNumber)
-  ///     }
-  ///     // Could print "20", perhaps
+  /// This method uses the default random generator, `Random.default`. The call
+  /// to `names.randomElement()` above is equivalent to calling
+  /// `names.randomElement(using: &Random.default)`.
   ///
-  /// This uses the standard library's default random number generator.
+  /// - Returns: A random element from the collection. If the collection is
+  ///   empty, the method returns `nil`.
   @inlinable
-  public func random() -> Element? {
-    return random(using: Random.default)
+  public func randomElement() -> Element? {
+    return randomElement(using: &Random.default)
   }
 
   /// Do not use this method directly; call advanced(by: n) instead.

stdlib/public/core/CollectionAlgorithms.swift

@@ -372,41 +372,75 @@ extension MutableCollection where Self : BidirectionalCollection {
 //===----------------------------------------------------------------------===//
 
 extension Sequence {
-  /// Returns the elements of the sequence, shuffled.
+  /// Returns the elements of the sequence, shuffled using the given generator
+  /// as a source for randomness.
+  ///
+  /// You use this method to randomize the elements of a sequence when you
+  /// are using a custom random number generator. For example, you can shuffle
+  /// the numbers between `0` and `9` by calling the `shuffled(using:)` method
+  /// on that range:
+  ///
+  ///     let numbers = 0...9
+  ///     let shuffledNumbers = numbers.shuffled(using: &myGenerator)
+  ///     // shuffledNumbers == [8, 9, 4, 3, 2, 6, 7, 0, 5, 1]
   ///
   /// - Parameter generator: The random number generator to use when shuffling
   ///   the sequence.
-  /// - Returns: A shuffled array of this sequence's elements.
+  /// - Returns: An array of this sequence's elements in a shuffled order.
+  ///
+  /// - Complexity: O(*n*)
   @inlinable
   public func shuffled<T: RandomNumberGenerator>(
-    using generator: T
+    using generator: inout T
   ) -> [Element] {
     var result = ContiguousArray(self)
-    result.shuffle(using: generator)
+    result.shuffle(using: &generator)
     return Array(result)
   }
 
   /// Returns the elements of the sequence, shuffled.
   ///
+  /// For example, you can shuffle the numbers between `0` and `9` by calling
+  /// the `shuffled()` method on that range:
+  ///
+  ///     let numbers = 0...9
+  ///     let shuffledNumbers = numbers.shuffled()
+  ///     // shuffledNumbers == [1, 7, 6, 2, 8, 9, 4, 3, 5, 0]
+  ///
+  /// This method uses the default random generator, `Random.default`. The call
+  /// to `numbers.shuffled()` above is equivalent to calling
+  /// `numbers.shuffled(using: &Random.default)`.
+  ///
   /// - Parameter generator: The random number generator to use when shuffling
   ///   the sequence.
   /// - Returns: A shuffled array of this sequence's elements.
   ///
-  /// This uses the standard library's default random number generator.
+  /// - Complexity: O(*n*)
   @inlinable
   public func shuffled() -> [Element] {
-    return shuffled(using: Random.default)
+    return shuffled(using: &Random.default)
   }
 }
 
 extension MutableCollection {
-  /// Shuffles the collection in place.
+  /// Shuffles the collection in place, using the given generator as a source
+  /// for randomness.
+  ///
+  /// You use this method to randomize the elements of a collection when you
+  /// are using a custom random number generator. For example, you can use the
+  /// `shuffle(using:)` method to randomly reorder the elements of an array.
+  ///
+  ///     var names = ["Alejandro", "Camila", "Diego", "Luciana", "Luis", "Sofía"]
+  ///     names.shuffle(using: &myGenerator)
+  ///     // names == ["Sofía", "Alejandro", "Camila", "Luis", "Diego", "Luciana"]
   ///
   /// - Parameter generator: The random number generator to use when shuffling
   ///   the collection.
+  ///
+  /// - Complexity: O(*n*)
   @inlinable
   public mutating func shuffle<T: RandomNumberGenerator>(
-    using generator: T
+    using generator: inout T
   ) {
     guard count > 1 else { return }
     var amount = count
@@ -424,13 +458,21 @@ extension MutableCollection {
 
   /// Shuffles the collection in place.
   ///
-  /// - Parameter generator: The random number generator to use when shuffling
-  ///   the collection.
+  /// Use the `shuffle()` method to randomly reorder the elements of an
+  /// array.
+  ///
+  ///     var names = ["Alejandro", "Camila", "Diego", "Luciana", "Luis", "Sofía"]
+  ///     names.shuffle(using: myGenerator)
+  ///     // names == ["Luis", "Camila", "Luciana", "Sofía", "Alejandro", "Diego"]
   ///
-  /// This uses the standard library's default random number generator.
+  /// This method uses the default random generator, `Random.default`. The call
+  /// to `names.shuffle()` above is equivalent to calling
+  /// `names.shuffle(using: &Random.default)`.
+  ///
+  /// - Complexity: O(*n*)
   @inlinable
   public mutating func shuffle() {
-    shuffle(using: Random.default)
+    shuffle(using: &Random.default)
   }
 }