Update API to match mailing list discussion, add tests

Added pick(_:) to collection
Added random(in:using:) to Randomizable
Added tests

Fix typo in Randomizable documentation

Rename pick to sampling

Move sampling below random

Author: Azoy

stdlib/public/core/CMakeLists.txt

@@ -98,7 +98,7 @@ set(SWIFTLIB_ESSENTIAL
   Policy.swift
   PrefixWhile.swift.gyb
   Print.swift
-  Random.swift
+  Random.swift.gyb
   RandomAccessCollection.swift
   Range.swift.gyb
   RangeReplaceableCollection.swift.gyb

stdlib/public/core/Collection.swift

@@ -783,6 +783,7 @@ public protocol Collection : Sequence
 
   /// Returns a random element from this collection.
   ///
+  /// This uses the default random number generator provided by the standard library.
   /// A good example of this is getting a random number from 1 to 10:
   ///
   ///     let randomToTen = (1 ... 10).random
@@ -1048,7 +1049,7 @@ extension Collection {
   ///
   /// - Parameter generator: The random number generator to use when getting
   ///   a random element.
-  /// - Returns: A random element this collection.
+  /// - Returns: A random element from this collection.
   ///
   /// A good example of this is getting a random number from 1 to 10:
   ///
@@ -1064,7 +1065,7 @@ extension Collection {
   @_inlineable
   public func random<T: RandomNumberGenerator>(using generator: T) -> Element? {
     guard !isEmpty else { return nil }
-    var random = generator.next(upperBound: UInt(self.count))
+    let random = generator.next(upperBound: UInt(self.count))
     let index = self.index(
       self.startIndex,
       offsetBy: IndexDistance(random),
@@ -1073,6 +1074,38 @@ extension Collection {
     return self[index!]
   }
 
+  /// Randomly samples n elements from the collection
+  ///
+  /// - Parameter n: Number of elements to randomly sample without replacement
+  ///   from this collection.
+  /// - Returns: An array of randomly sampled elements from this collection.
+  @_inlineable
+  public func sampling(_ n: Int) -> [Element] {
+    return self.sampling(n, using: Random.default)
+  }
+
+  /// Randomly samples n elements from the collection
+  ///
+  /// - Parameter n: Number of elements to randomly sample without replacement
+  ///   from this collection.
+  /// - Parameter generator: The random number generator to use when getting
+  ///   random elements.
+  /// - Returns: An array of randomly sampled elements from this collection.
+  @_inlineable
+  public func sampling<T: RandomNumberGenerator>(
+    _ n: Int,
+    using generator: T
+  ) -> [Element] {
+    guard n < count, n >= 0 else { return Array(self) }
+    var copySelf = Array(self)
+    copySelf.shuffle(using: generator)
+    var arr = [Element]()
+    for _ in 0 ..< n {
+      arr.append(copySelf.removeFirst())
+    }
+    return arr
+  }
+
   /// Do not use this method directly; call advanced(by: n) instead.
   @_inlineable
   @_versioned

stdlib/public/core/CollectionAlgorithms.swift.gyb

@@ -267,7 +267,7 @@ extension MutableCollection {
     guard count > 1 else { return }
     var amount = count
     while amount > 1 {
-      var random = generator.next(upperBound: UInt(count))
+      let random = generator.next(upperBound: UInt(count))
       guard amount != random else { continue }
       amount -= 1
       swapAt(

stdlib/public/core/Random.swift renamed to stdlib/public/core/Random.swift.gyb

@@ -1,4 +1,4 @@
-//===--- Random.swift -----------------------------------------------------===//
+//===--- Random.swift.gyb -------------------------------------*- swift -*-===//
 //
 // This source file is part of the Swift.org open source project
 //
@@ -19,8 +19,8 @@ import SwiftShims
 /// that implement their own pseudo-random or cryptographically secure
 /// pseudo-random number generation. Using the RandomNumberGenerator protocol
 /// allows these types to be used with types that conform to `Randomizable`,
-/// collections with .random, and collections/sequences with .shuffle() and
-/// .shuffled()
+/// collections with .random and .pick(_:), and collections/sequences with
+/// .shuffle() and .shuffled()
 ///
 /// Conforming to the RandomNumberGenerator protocol
 /// ==========================================
@@ -100,20 +100,20 @@ extension RandomNumberGenerator {
 /// Using those functions should be preferred over using this directly. An
 /// example of calling this directly:
 ///
-///     let random = Random.default.next(Int.self)
-///     let randomToTen = Random.default.next(Int.self, upperBound: 10)
+///     let random = Random.default.next(UInt8.self)
+///     let randomToTen = Random.default.next(UInt32.self, upperBound: 128)
 ///
 /// However, you should strive to use the random functions on the numeric types.
 /// Using the preferred way:
 ///
-///     let random = Int.random
-///     let randomToTen = (0 ... 10).random
+///     let random = UInt8.random
+///     let randomToTen = UInt32.random(in: 0 ... 128)
 ///
 /// - Note: The default implementation of randomness is cryptographically secure.
 ///   It utilizes arc4random on newer versions of macOS, iOS, etc. On older
-///   versions of these operating systems it uses /dev/urandom and SecRandomCopyBytes
-///   on iOS. For Linux, it tries to use the getrandom(2) system call on newer
-///   kernel versions. On older kernel versions, it uses /dev/urandom.
+///   versions of these operating systems it uses SecRandomCopyBytes. For Linux,
+///   it tries to use the getrandom(2) system call on newer kernel versions. On
+///   older kernel versions, it reads from /dev/urandom.
 public struct Random : RandomNumberGenerator {
   /// This random number generator generates the machine's bit width unsigned integer
   public typealias GeneratedNumber = UInt
@@ -150,37 +150,26 @@ public struct Random : RandomNumberGenerator {
 /// =======================================
 ///
 /// In order to conform to the Randomizable protocol, all one must implement is
-/// the random(using:) function. As an example, below is a custom Date structure:
+/// the random(using:) function. As an example, below is a custom Color structure:
 ///
-///     struct Date {
-///         let year: Int
-///         let month: Int
-///         let day: Int
+///     struct Color {
+///         let value: UInt32
 ///     }
 ///
-/// In order for `Date` to conform to `Randomizable`, it must declare conformance
+/// In order for `Color` to conform to `Randomizable`, it must declare conformance
 /// and implement the random(using:) function.
 ///
-///     extension Date : Randomizable {
+///     extension Color : Randomizable {
 ///         static func random<T: RandomNumberGenerator>(using generator: T) -> Self {
-///             let randomYear = (0 ... 3000).random(using: generator)
-///             let randomMonth = (1 ... 12).random(using: generator)
-///             let randomDay = (1 ... 31).random(using: generator)
-///             // This could produce a date with day 31 on months without 31 days
-///             // Ideally, you should check for this
-///             return Date(year: randomYear, month: randomMonth, day: randomDay)
+///             let value = UInt32.random(in: 0x0 ... 0xFFFFFF, using: generator)
+///             return Color(value: value)
 ///         }
 ///     }
 ///
-/// Note how the ranges use the random(using:) function that is defined for them.
+/// Note how the function .random(in:using:) is using custom generator argument.
 /// Make sure to do this for custom types as it allows developers the ability
 /// to use their own random number generators on custom types.
 public protocol Randomizable {
-  /// The random representation of this type.
-  ///
-  /// Shorthand for using the random(using:) function. This uses the default
-  /// random implementation defined in the standard library.
-  static var random: Self { get }
 
   /// Returns a random representation of this type.
   ///
@@ -191,7 +180,7 @@ public protocol Randomizable {
 }
 
 extension Randomizable {
-  /// The random representation of this type.
+  /// Returns a random representation of this type.
   ///
   /// Shorthand for using the random(using:) function. This uses the default
   /// random implementation defined in the standard library.
@@ -200,3 +189,63 @@ extension Randomizable {
     return self.random(using: Random.default)
   }
 }
+
+% for Range in ['Range', 'ClosedRange']:
+
+extension Randomizable where Self: BinaryFloatingPoint {
+  /// Returns a random representation of this type within the range
+  ///
+  /// - Parameter range: The range to select a random value from.
+  /// - Returns: A random representation of this type within the range.
+  ///
+  /// Shorthand for using the random(in:using:) function. This uses the default
+  /// random implementation defined in the standard library.
+  public static func random(in range: ${Range}<Self>) -> Self {
+    return range.random!
+  }
+
+  /// Returns a random representation of this type within the range
+  ///
+  /// - Parameter range: The range to select a random value from.
+  /// - Parameter generator: The random number generator to use when getting
+  ///   a random value from the range.
+  /// - Returns: A random representation of this type within the range.
+  public static func random<T: RandomNumberGenerator>(
+    in range: ${Range}<Self>,
+    using generator: T
+  ) -> Self {
+    return range.random(using: generator)!
+  }
+}
+
+% end
+
+% for Range in ['CountableRange', 'CountableClosedRange']:
+
+extension Randomizable where Self: Strideable, Self.Stride: SignedInteger {
+  /// Returns a random representation of this type within the range
+  ///
+  /// - Parameter range: The range to select a random value from.
+  /// - Returns: A random representation of this type within the range.
+  ///
+  /// Shorthand for using the random(in:using:) function. This uses the default
+  /// random implementation defined in the standard library.
+  public static func random(in range: ${Range}<Self>) -> Self {
+    return range.random!
+  }
+
+  /// Returns a random representation of this type within the range
+  ///
+  /// - Parameter range: The range to select a random value from.
+  /// - Parameter generator: The random number generator to use when getting
+  ///   a random value from the range.
+  /// - Returns: A random representation of this type within the range.
+  public static func random<T: RandomNumberGenerator>(
+    in range: ${Range}<Self>,
+    using generator: T
+  ) -> Self {
+    return range.random(using: generator)!
+  }
+}
+
+% end

test/stdlib/Random.swift

@@ -0,0 +1,98 @@
+// RUN: %target-run-simple-swift
+// REQUIRES: executable_test
+
+import StdlibUnittest
+
+let RandomTests = TestSuite("Random")
+
+RandomTests.test("random numbers") {
+  let randomNumber1 = Int.random
+  let randomNumber2 = Int.random
+  expectTrue(randomNumber1 != randomNumber2)
+
+  let randomDouble1 = Double.random
+  expectTrue(randomDouble1 < 1 && randomDouble1 > 0)
+  let randomDouble2 = Double.random
+  expectTrue(randomDouble1 < 1 && randomDouble2 > 0)
+  expectTrue(randomDouble1 != randomDouble2)
+}
+
+RandomTests.test("random numbers from range") {
+  let range1 = 0 ..< 20
+  for _ in range1 {
+    let randomNumber = Int.random(in: range1)
+    expectTrue(range1.contains(randomNumber))
+  }
+
+  let range2 = 0 ... 20
+  for _ in range1 {
+    let randomNumber = Int.random(in: range2)
+    expectTrue(range2.contains(randomNumber))
+  }
+
+  let range3 = 3.0 ..< 10.0
+  for _ in range1 {
+    let randomNumber = Double.random(in: range3)
+    expectTrue(range3.contains(randomNumber))
+  }
+
+  let range4 = 3.0 ... 10.0
+  for _ in range1 {
+    let randomNumber = Double.random(in: range4)
+    expectTrue(range4.contains(randomNumber))
+  }
+}
+
+RandomTests.test("random elements") {
+  let greetings = ["hello", "hi", "hey", "hola", "what's up"]
+  for _ in 0 ..< 20 {
+    let randomGreeting = greetings.random
+    expectNotNil(randomGreeting)
+    expectTrue(greetings.contains(randomGreeting!))
+  }
+}
+
+RandomTests.test("sampling from an array") {
+  let range = 0 ..< 20
+  let array = Array(range)
+  for i in range {
+    let chosen = array.sampling(i)
+    expectTrue(chosen.count == i)
+    for choice in chosen {
+      expectTrue(array.contains(choice))
+    }
+  }
+
+  // If we pick more elements than the array contains, check if count == array.count
+  expectTrue(array.sampling(100).count == array.count)
+}
+
+func chi2Test(_ samples: [Double]) -> Bool {
+  let upperBound = 50
+  let numberOfTrials = 500_000
+  let expected = Double(numberOfTrials / upperBound)
+  let cvLow = 28.9 // 1% with a degree of freedom of (50 - 1)
+  let cvHigh = 74.9 // 99% with a degree of freedom of (50 - 1)
+  let chi2 = samples.map {
+    (($0 - expected) * ($0 - expected)) / expected
+  }.reduce(0, +)
+
+  if chi2 < cvLow || chi2 > cvHigh {
+    return false
+  }else {
+    return true
+  }
+}
+
+RandomTests.test("uniform distribution") {
+  let upperBound = 50
+  let numberOfTrials = 500_000
+  var array = [Double](repeating: 0.0, count: upperBound)
+  for _ in 0 ..< numberOfTrials {
+    let randomIndex = Int.random(in: 0 ..< upperBound)
+    array[randomIndex] += 1.0
+  }
+  expectTrue(chi2Test(array))
+}
+
+runAllTests()