Update API to reflect mailing list discussions

Remove unnecessary import

Make sure not to return upperBound on Range

Use SecRandomCopyBytes on older macOS

Author: Azoy

stdlib/public/SwiftShims/LibcShims.h

@@ -96,7 +96,7 @@ _swift_stdlib_cxx11_mt19937_uniform(__swift_uint32_t upper_bound);
 SWIFT_RUNTIME_STDLIB_INTERFACE
 void _swift_stdlib_random(void *buf,
                           __swift_ssize_t nbytes,
-                          __swift_uint32_t debugFlags);
+                          __swift_uint32_t debug_flags);
 
 // Math library functions
 static inline SWIFT_ALWAYS_INLINE

stdlib/public/core/Bool.swift

@@ -88,9 +88,14 @@ public struct Bool : Randomizable {
     self = value
   }
 
+  /// Returns a random Boolean
+  ///
+  /// - Parameter generator: The random number generator to use when getting a
+  ///   random Boolean.
+  /// - Returns: A random Boolean.
   @_inlineable
-  public static func random(using generator: RandomGenerator) -> Bool {
-    let random = generator.next(Int8.self, upperBound: 2)
+  public static func random<T: RandomNumberGenerator>(using generator: T) -> Bool {
+    let random = Int8.random(using: generator)
     return self.init(Builtin.trunc_Int8_Int1(random._value))
   }
 }

stdlib/public/core/Collection.swift

@@ -781,14 +781,39 @@ public protocol Collection : Sequence
   ///   `endIndex`.
   func formIndex(after i: inout Index)
 
-  /// Returns a shuffled version of this collection.
+  /// Returns a random element from this collection.
   ///
-  /// - Parameter generator: The random number generator to use when shuffling
-  ///   the collection. This parameter is not needed as the default implementation
-  ///   of `Collection` uses the default random source in the standard library.
-  /// - Returns: A new array containing a shuffled version of this collection's
-  ///   elements.
-  func shuffled(using generator: RandomGenerator) -> [Element]
+  /// A good example of this is getting a random number from 1 to 10:
+  ///
+  ///     let randomToTen = (1 ... 10).random
+  ///
+  /// If the collection is empty, the value of this function is `nil`.
+  ///
+  ///     let numbers = [10, 20, 30, 40, 50]
+  ///     if let randomNumber = numbers.random {
+  ///         print(randomNumber)
+  ///     }
+  ///     // Could print "20"
+  var random: Element? { get }
+
+  /// 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 number from 1 to 10:
+  ///
+  ///     let randomToTen = (1 ... 10).random
+  ///
+  /// If the collection is empty, the value of this function is `nil`.
+  ///
+  ///     let numbers = [10, 20, 30, 40, 50]
+  ///     if let randomNumber = numbers.random {
+  ///         print(randomNumber)
+  ///     }
+  ///     // Could print "20"
+  func random<T: RandomNumberGenerator>(using generator: T) -> Element?
 }
 
 /// Default implementation for forward collections.
@@ -1000,20 +1025,52 @@ extension Collection {
     return count
   }
 
-  /// Returns a shuffled version of this collection.
+  /// Returns a random element from this collection.
   ///
-  /// - Parameter generator: The random number generator to use when shuffling
-  ///   the collection. This parameter is not needed as the default implementation
-  ///   of `Collection` uses the default random source in the standard library.
-  /// - Returns: A new array containing a shuffled version of this collection's
-  ///   elements.
+  /// 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
+  ///
+  /// If the collection is empty, the value of this function is `nil`.
+  ///
+  ///     let numbers = [10, 20, 30, 40, 50]
+  ///     if let randomNumber = numbers.random {
+  ///         print(randomNumber)
+  ///     }
+  ///     // Could print "20"
   @_inlineable
-  public func shuffled(
-    using generator: RandomGenerator = Random.default
-  ) -> [Element] {
-    var arr = Array(self)
-    arr.shuffle(using: generator)
-    return arr
+  public var random: Element? {
+    return self.random(using: Random.default)
+  }
+
+  /// Returns a random element from this collection.
+  ///
+  /// - Parameter generator: The random number generator to use when getting
+  ///   a random element.
+  /// - Returns: A random element this collection.
+  ///
+  /// A good example of this is getting a random number from 1 to 10:
+  ///
+  ///     let randomToTen = (1 ... 10).random
+  ///
+  /// If the collection is empty, the value of this function is `nil`.
+  ///
+  ///     let numbers = [10, 20, 30, 40, 50]
+  ///     if let randomNumber = numbers.random {
+  ///         print(randomNumber)
+  ///     }
+  ///     // Could print "20"
+  @_inlineable
+  public func random<T: RandomNumberGenerator>(using generator: T) -> Element? {
+    guard !isEmpty else { return nil }
+    var random = generator.next(upperBound: UInt(self.count))
+    let index = self.index(
+      self.startIndex,
+      offsetBy: IndexDistance(random),
+      limitedBy: self.endIndex
+    )
+    return self[index!]
   }
 
   /// Do not use this method directly; call advanced(by: n) instead.

stdlib/public/core/CollectionAlgorithms.swift.gyb

@@ -211,6 +211,81 @@ extension MutableCollection where Self : BidirectionalCollection {
   }
 }
 
+//===----------------------------------------------------------------------===//
+// shuffled()
+//===----------------------------------------------------------------------===//
+
+% for Self in ['Sequence', 'MutableCollection']:
+
+% sequenceKind = 'sequence' if 'Sequence' in Self else 'collection'
+
+extension ${Self} {
+  /// Returns the elements of the ${sequenceKind}, shuffled.
+  ///
+  /// - Returns: A shuffled array of this ${sequenceKind}'s elements.
+  ///
+  /// This uses the default random number generator provided by the standard library.
+  @_inlineable
+  public func shuffled() -> [Element] {
+    return self.shuffled(using: Random.default)
+  }
+
+  /// Returns the elements of the ${sequenceKind}, shuffled.
+  ///
+  /// - Parameter generator: The random number generator to use when shuffling
+  ///   the ${sequenceKind}.
+  /// - Returns: A shuffled array of this ${sequenceKind}'s elements.
+  @_inlineable
+  public func shuffled<T: RandomNumberGenerator>(
+    using generator: T
+  ) -> [Element] {
+    var result = ContiguousArray(self)
+    result.shuffle(using: generator)
+    return Array(result)
+  }
+}
+
+% end
+
+extension MutableCollection {
+  /// Shuffles the collection in place.
+  ///
+  /// This uses the default random number generator provided by the standard library.
+  @_inlineable
+  public mutating func shuffle() {
+    self.shuffle(using: Random.default)
+  }
+
+  /// Shuffles the collection in place.
+  ///
+  /// - Parameter generator: The random number generator to use when shuffling
+  ///   the collection.
+  @_inlineable
+  public mutating func shuffle<T: RandomNumberGenerator>(
+    using generator: T
+  ) {
+    guard count > 1 else { return }
+    var amount = count
+    while amount > 1 {
+      var random = generator.next(upperBound: UInt(count))
+      guard amount != random else { continue }
+      amount -= 1
+      swapAt(
+        index(
+          startIndex,
+          offsetBy: IndexDistance(amount),
+          limitedBy: endIndex
+        )!,
+        index(
+          startIndex,
+          offsetBy: IndexDistance(random),
+          limitedBy: endIndex
+        )!
+      )
+    }
+  }
+}
+
 //===----------------------------------------------------------------------===//
 // sorted()
 //===----------------------------------------------------------------------===//

stdlib/public/core/FloatingPoint.swift.gyb

@@ -2108,7 +2108,7 @@ extension BinaryFloatingPoint {
   ///
   /// The range of this random floating point is from 0 to 1 inclusive
   @_inlineable
-  public static func random(using generator: RandomGenerator) -> Self {
+  public static func random<T: RandomNumberGenerator>(using generator: T) -> Self {
     let random = generator.next(UInt64.self)
     return Self(random) / Self(UInt64.max)
   }

stdlib/public/core/Integers.swift.gyb

@@ -2606,7 +2606,33 @@ extension FixedWidthInteger {
   /// The range of this random integer is from the integer's min to the integer's
   /// max.
   @_inlineable
-  public static func random(using generator: RandomGenerator) -> Self {
+  public static func random<T: RandomNumberGenerator>(using generator: T) -> Self {
+    switch bitWidth {
+    case 8:
+      return Self.init(truncatingIfNeeded: generator.next(UInt8.self))
+    case 16:
+      return Self.init(truncatingIfNeeded: generator.next(UInt16.self))
+    case 32:
+      return Self.init(truncatingIfNeeded: generator.next(UInt32.self))
+    case 64:
+      return Self.init(truncatingIfNeeded: generator.next(UInt64.self))
+    default:
+      return Self.init(truncatingIfNeeded: generator.next())
+    }
+  }
+}
+
+extension FixedWidthInteger where Self: UnsignedInteger {
+  /// Returns a random representation of this integer.
+  ///
+  /// - Parameter generator: The random number generator to use when getting
+  ///   the random integer
+  /// - Returns: A random representation of this integer conforming to `Randomizable`
+  ///
+  /// The range of this random integer is from the integer's min to the integer's
+  /// max.
+  @_inlineable
+  public static func random<T: RandomNumberGenerator>(using generator: T) -> Self {
     return generator.next(Self.self)
   }
 }

stdlib/public/core/MutableCollection.swift

@@ -159,13 +159,6 @@ public protocol MutableCollection : Collection
     by belongsInSecondPartition: (Element) throws -> Bool
   ) rethrows -> Index
 
-  /// Shuffles the current collection
-  ///
-  /// - Parameter generator: The random number generator to use when shuffling
-  ///   the collection. This parameter is not needed as the default implementation
-  ///   of `Collection` uses the default random source in the standard library.
-  mutating func shuffle(using generator: RandomGenerator)
-
   /// Exchanges the values at the specified indices of the collection.
   ///
   /// Both parameters must be valid indices of the collection and not
@@ -234,37 +227,6 @@ extension MutableCollection {
     }
   }
 
-  /// Shuffles the current collection
-  ///
-  /// - Parameter generator: The random number generator to use when shuffling
-  ///   the collection. This parameter is not needed as the default implementation
-  ///   of `Collection` uses the default random source in the standard library.
-  @_inlineable
-  public mutating func shuffle(
-    using generator: RandomGenerator = Random.default
-  ) {
-    guard count > 1 else { return }
-    var amount = count
-    while amount > 1 {
-      var random = generator.next(Int.self, upperBound: Int(count))
-      if random < 0 { random *= -1 }
-      guard amount != random else { continue }
-      amount -= 1
-      swapAt(
-        index(
-          startIndex,
-          offsetBy: IndexDistance(amount),
-          limitedBy: endIndex
-        )!,
-        index(
-          startIndex,
-          offsetBy: IndexDistance(random),
-          limitedBy: endIndex
-        )!
-      )
-    }
-  }
-
   /// Exchanges the values at the specified indices of the collection.
   ///
   /// Both parameters must be valid indices of the collection that are not