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

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.
+final class LCRNG: RandomNumberGenerator {
+  private var state: UInt64
+  
+  init(seed: Int) {
+    state = UInt64(truncatingIfNeeded: seed)
+    for _ in 0..<10 { _ = next() }
+  }
+  
+  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) {
+  let 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.
+final class LCRNG: RandomNumberGenerator {
+  private var state: UInt64
+  
+  init(seed: Int) {
+    state = UInt64(truncatingIfNeeded: seed)
+    for _ in 0..<10 { _ = next() }
+  }
+  
+  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
+    let 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
+    let 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/Collection.swift

@@ -790,24 +790,21 @@ public protocol Collection: Sequence where SubSequence: Collection {
   ///   `endIndex`.
   func formIndex(after i: inout Index)
 
-  /// 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
+  /// `random(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.random(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`.
   func random<T: RandomNumberGenerator>(using generator: T) -> Element?
 
   @available(*, deprecated, message: "all index distances are now of type Int")
@@ -1023,24 +1020,21 @@ extension Collection {
     return count
   }
 
-  /// Returns a random element from this 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:
+  /// Returns a random element of the collection, using the given generator as
+  /// a source for randomness.
   ///
-  ///     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
+  /// `random(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.random(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
@@ -1054,26 +1048,21 @@ extension Collection {
     return self[index]
   }
 
-  /// Returns a random element from this 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:
+  /// Returns a random element of the collection.
   ///
-  ///     let greetings = ["hi", "hey", "hello", "hola"]
-  ///     let randomGreeting = greetings.random()
+  /// For example, call `random()` 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.random()!
+  ///     // 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.random()` above is equivalent to calling
+  /// `names.random(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)

stdlib/public/core/CollectionAlgorithms.swift

@@ -265,11 +265,23 @@ 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
@@ -281,22 +293,44 @@ extension Sequence {
 
   /// 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)
   }
 }
 
 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
@@ -317,10 +351,18 @@ 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)