Value type generators

random -> randomElement

Fix some docs

One more doc fix

Doc fixes & bool fix

Use computed over explicit

Author: Azoy

benchmark/single-source/RandomShuffle.swift

@@ -25,15 +25,15 @@ public let RandomShuffle = [
 ]
 
 /// A linear congruential PRNG.
-final class LCRNG: RandomNumberGenerator {
+struct LCRNG: RandomNumberGenerator {
   private var state: UInt64
 
   init(seed: Int) {
     state = UInt64(truncatingIfNeeded: seed)
     for _ in 0..<10 { _ = next() }
   }
 
-  func next() -> UInt64 {
+  mutating func next() -> UInt64 {
     state = 2862933555777941757 &* state &+ 3037000493
     return state
   }
@@ -56,9 +56,9 @@ public func run_RandomShuffleDef(_ N: Int) {
 
 @inline(never)
 public func run_RandomShuffleLCG(_ N: Int) {
-  let generator = LCRNG(seed: 0)
+  var generator = LCRNG(seed: 0)
   for _ in 0 ..< N {
-    numbers.shuffle(using: generator)
+    numbers.shuffle(using: &generator)
     blackHole(numbers.first!)
   }
 }

benchmark/single-source/RandomValues.swift

@@ -26,15 +26,15 @@ public let RandomValues = [
 ]
 
 /// A linear congruential PRNG.
-final class LCRNG: RandomNumberGenerator {
+struct LCRNG: RandomNumberGenerator {
   private var state: UInt64
 
   init(seed: Int) {
     state = UInt64(truncatingIfNeeded: seed)
     for _ in 0..<10 { _ = next() }
   }
 
-  func next() -> UInt64 {
+  mutating func next() -> UInt64 {
     state = 2862933555777941757 &* state &+ 3037000493
     return state
   }
@@ -55,9 +55,9 @@ public func run_RandomIntegersDef(_ N: Int) {
 public func run_RandomIntegersLCG(_ N: Int) {
   for _ in 0 ..< N {
     var x = 0
-    let generator = LCRNG(seed: 0)
+    var generator = LCRNG(seed: 0)
     for _ in 0 ..< 100_000 {
-      x &+= Int.random(in: 0...10_000, using: generator)
+      x &+= Int.random(in: 0...10_000, using: &generator)
     }
     CheckResults(x == 498214315)
   }
@@ -78,9 +78,9 @@ public func run_RandomDoubleDef(_ N: Int) {
 public func run_RandomDoubleLCG(_ N: Int) {
   for _ in 0 ..< N {
     var x = 0.0
-    let generator = LCRNG(seed: 0)
+    var generator = LCRNG(seed: 0)
     for _ in 0 ..< 100_000 {
-      x += Double.random(in: -1000...1000, using: generator)
+      x += Double.random(in: -1000...1000, using: &generator)
     }
     blackHole(x)
   }

stdlib/public/core/Bool.swift

@@ -95,9 +95,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
@@ -109,7 +109,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

@@ -795,17 +795,19 @@ public protocol Collection: Sequence where SubSequence: Collection {
   ///
   /// 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.
+  /// `randomElement(using:)` to select a random element from an array of names.
   ///
   ///     let names = ["Zoey", "Chloe", "Amani", "Amaia"]
-  ///     let randomName = names.random(using: myGenerator)!
+  ///     let randomName = names.randomElement(using: &myGenerator)!
   ///     // randomName == "Amani" (maybe)
   ///
   /// - 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?
+  func randomElement<T: RandomNumberGenerator>(
+    using generator: inout T
+  ) -> Element?
 
   @available(*, deprecated, message: "all index distances are now of type Int")
   typealias IndexDistance = Int
@@ -1025,19 +1027,19 @@ extension Collection {
   ///
   /// 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.
+  /// `randomElement(using:)` to select a random element from an array of names.
   ///
   ///     let names = ["Zoey", "Chloe", "Amani", "Amaia"]
-  ///     let randomName = names.random(using: myGenerator)!
+  ///     let randomName = names.randomElement(using: &myGenerator)!
   ///     // randomName == "Amani" (maybe)
   ///
   /// - 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))
@@ -1050,22 +1052,22 @@ extension Collection {
 
   /// Returns a random element of the collection.
   ///
-  /// For example, call `random()` to select a random element from an
+  /// For example, call `randomElement()` to select a random element from an
   /// array of names.
   ///
   ///     let names = ["Zoey", "Chloe", "Amani", "Amaia"]
-  ///     let randomName = names.random()!
+  ///     let randomName = names.randomElement()!
   ///     // randomName == "Amani" (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)`.
+  /// to `names.randomElement()` above is equivalent to calling
+  /// `names.randomElement(using: &Random.default)`.
   ///
   /// - 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

@@ -274,7 +274,7 @@ extension Sequence {
   /// on that range:
   ///
   ///     let numbers = 0...9
-  ///     let shuffledNumbers = numbers.shuffled(using: myGenerator)
+  ///     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
@@ -284,10 +284,10 @@ extension Sequence {
   /// - 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)
   }
 
@@ -302,7 +302,7 @@ extension Sequence {
   ///
   /// This method uses the default random generator, `Random.default`. The call
   /// to `numbers.shuffled()` above is equivalent to calling
-  /// `numbers.shuffled(using: Random.default)`.
+  /// `numbers.shuffled(using: &Random.default)`.
   ///
   /// - Parameter generator: The random number generator to use when shuffling
   ///   the sequence.
@@ -311,7 +311,7 @@ extension Sequence {
   /// - Complexity: O(*n*)
   @inlinable
   public func shuffled() -> [Element] {
-    return shuffled(using: Random.default)
+    return shuffled(using: &Random.default)
   }
 }
 
@@ -324,7 +324,7 @@ extension MutableCollection {
   /// `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.shuffle(using: &myGenerator)
   ///     // names == ["Sofía", "Alejandro", "Camila", "Luis", "Diego", "Luciana"]
   ///
   /// - Parameter generator: The random number generator to use when shuffling
@@ -333,7 +333,7 @@ extension MutableCollection {
   /// - 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
@@ -360,12 +360,12 @@ extension MutableCollection {
   ///
   /// This method uses the default random generator, `Random.default`. The call
   /// to `names.shuffle()` above is equivalent to calling
-  /// `names.shuffle(using: Random.default)`.
+  /// `names.shuffle(using: &Random.default)`.
   ///
   /// - Complexity: O(*n*)
   @inlinable
   public mutating func shuffle() {
-    shuffle(using: Random.default)
+    shuffle(using: &Random.default)
   }
 }
 

stdlib/public/core/FloatingPoint.swift.gyb

@@ -2389,7 +2389,7 @@ where Self.RawSignificand : FixedWidthInteger,
   /// creates three new values in the range `${exampleRange}`.
   ///
   ///     for _ in 1...3 {
-  ///         print(Double.random(in: ${exampleRange}, using: myGenerator))
+  ///         print(Double.random(in: ${exampleRange}, using: &myGenerator))
   ///     }
   ///     // Prints "18.1900709259179"
   ///     // Prints "14.2286325689993"
@@ -2412,7 +2412,7 @@ where Self.RawSignificand : FixedWidthInteger,
   @inlinable
   public static func random<T: RandomNumberGenerator>(
     in range: ${Range}<Self>,
-    using generator: T
+    using generator: inout T
   ) -> Self {
 %   if 'Closed' not in Range:
     _precondition(
@@ -2466,7 +2466,7 @@ where Self.RawSignificand : FixedWidthInteger,
   ///
   /// This method uses the default random generator, `Random.default`. The call
   /// to `Double.random(in: ${exampleRange})` above is equivalent to calling
-  /// `Double.random(in: ${exampleRange}, using: Random.default)`.
+  /// `Double.random(in: ${exampleRange}, using: &Random.default)`.
   ///
   /// - Parameter range: The range in which to create a random value.
 %   if Range == 'Range':
@@ -2475,7 +2475,7 @@ where Self.RawSignificand : FixedWidthInteger,
   /// - Returns: A random value within the bounds of `range`.
   @inlinable
   public static func random(in range: ${Range}<Self>) -> Self {
-    return Self.random(in: range, using: Random.default)
+    return Self.random(in: range, using: &Random.default)
   }
 }
 

stdlib/public/core/Integers.swift.gyb

@@ -2510,8 +2510,8 @@ extension ${Range}
   ///   This method never returns `nil`.
 %   end
   @inlinable
-  public func random<T: RandomNumberGenerator>(
-    using generator: T
+  public func randomElement<T: RandomNumberGenerator>(
+    using generator: inout T
   ) -> Element? {
 %   if 'Closed' not in Range:
     guard lowerBound != upperBound else {
@@ -2565,8 +2565,8 @@ extension ${Range}
   /// value.
   ///
   /// This method uses the default random generator, `Random.default`. Calling
-  /// `(${exampleRange}).random()` is equivalent to calling
-  /// `(${exampleRange}).random(using: Random.default)`.
+  /// `(${exampleRange}).randomElement()` is equivalent to calling
+  /// `(${exampleRange}).randomElement(using: &Random.default)`.
   ///
   /// - Returns: A random element of the range.
 %   if 'Closed' not in Range:
@@ -2575,8 +2575,8 @@ extension ${Range}
   ///   This method never returns `nil`.
 %   end
   @inlinable
-  public func random() -> Element? {
-    return self.random(using: Random.default)
+  public func randomElement() -> Element? {
+    return randomElement(using: &Random.default)
   }
 }
 
@@ -2592,7 +2592,7 @@ where Self.Stride : SignedInteger,
   /// new values in the range `${exampleRange}`.
   ///
   ///     for _ in 1...3 {
-  ///         print(Int.random(in: ${exampleRange}, using: myGenerator))
+  ///         print(Int.random(in: ${exampleRange}, using: &myGenerator))
   ///     }
   ///     // Prints "7"
   ///     // Prints "44"
@@ -2609,15 +2609,15 @@ where Self.Stride : SignedInteger,
   @inlinable
   public static func random<T: RandomNumberGenerator>(
     in range: ${Range}<Self>,
-    using generator: T
+    using generator: inout T
   ) -> Self {
 %   if 'Closed' not in Range:
     _precondition(
       range.lowerBound != range.upperBound,
       "Can't get random value with lowerBound == upperBound"
     )
 %   end
-    return range.random(using: generator)!
+    return range.randomElement(using: &generator)!
   }
   
   /// Returns a random value within the specified range.
@@ -2634,7 +2634,7 @@ where Self.Stride : SignedInteger,
   ///
   /// This method uses the default random generator, `Random.default`. The call
   /// to `Int.random(in: ${exampleRange})` above is equivalent to calling
-  /// `Int.random(in: ${exampleRange}, using: Random.default)`.
+  /// `Int.random(in: ${exampleRange}, using: &Random.default)`.
   ///
   /// - Parameter range: The range in which to create a random value.
 %   if Range == 'Range':
@@ -2643,7 +2643,7 @@ where Self.Stride : SignedInteger,
   /// - Returns: A random value within the bounds of `range`.
   @inlinable
   public static func random(in range: ${Range}<Self>) -> Self {
-    return Self.random(in: range, using: Random.default)
+    return Self.random(in: range, using: &Random.default)
   }
 }