Add shims for stdlib random

Initial random api

Use C syscall for I/O

1. Fixed an issue where integers would would result in an infinite loop if they were unsigned, or signed integers always returning negative numbers.
2. Fixed an issue with Bool initialization

Add shuffle functions

Add documentation to Random API

Fix a few typos within the documentation

Fixes more typos

Also states that the range for floating points is from 0 to 1 inclusive

Update API to reflect mailing list discussions

Remove unnecessary import

Make sure not to return upperBound on Range

Use SecRandomCopyBytes on older macOS

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

Update docs

Use new Libc naming

Fix Random.swift with new Libc naming

Remove sampling

gybify signed integer creation

Make FloatingPoint.random exclusive

Refactor {Closed}Range.random

Fix FloatingPoint initialization

Precondition getting a random number from range

Fix some doc typos

Make .random a function

Update API to reflect discussion

Make .random a function
Remove .random() in favor of .random(in:) for all numeric types

Fix compile errors

Clean up _stdlib_random

Cleanup around API

Remove `.random()` requirement from `Collection`

Use generators

Optimize shuffle()

Thread safety for /dev/urandom

Remove {Closed}Range<BinaryFloatingPoint>.random()

Add Collection random requirement

Refactor _stdlib_random

Remove whitespace changes

Clean linux shim

Add shuffle and more tests

Provide finishing tests and suggestions

Remove refs to Countable ranges

Revert to checking if T is > UInt64

Author: Azoy

stdlib/public/SwiftShims/LibcShims.h

@@ -149,6 +149,10 @@ __swift_uint32_t _stdlib_cxx11_mt19937(void);
 SWIFT_RUNTIME_STDLIB_INTERNAL
 __swift_uint32_t _stdlib_cxx11_mt19937_uniform(__swift_uint32_t upper_bound);
 
+// Random number for stdlib
+SWIFT_RUNTIME_STDLIB_INTERNAL
+void _stdlib_random(void *buf, __swift_size_t nbytes);
+
 // Math library functions
 static inline SWIFT_ALWAYS_INLINE
 float _stdlib_remainderf(float _self, float _other) {

stdlib/public/core/Bool.swift

@@ -86,6 +86,18 @@ public struct Bool {
   public init(_ value: Bool) {
     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: RandomNumberGenerator = Random.default
+  ) -> Bool {
+    return generator.next() % 2 == 0
+  }
 }
 
 extension Bool : _ExpressibleByBuiltinBooleanLiteral, ExpressibleByBooleanLiteral {

stdlib/public/core/CMakeLists.txt

@@ -97,6 +97,7 @@ set(SWIFTLIB_ESSENTIAL
   Policy.swift
   PrefixWhile.swift
   Print.swift
+  Random.swift
   RandomAccessCollection.swift
   Range.swift
   RangeReplaceableCollection.swift
@@ -193,6 +194,7 @@ if(CMAKE_SYSTEM_NAME STREQUAL "Darwin")
   list(APPEND swift_core_link_flags "-all_load")
   list(APPEND swift_core_framework_depends Foundation)
   list(APPEND swift_core_framework_depends CoreFoundation)
+  list(APPEND swift_core_framework_depends Security)
   list(APPEND swift_core_private_link_libraries icucore)
 else()
   # With the GNU linker the equivalent of -all_load is to tell the linker

stdlib/public/core/ClosedRange.swift

@@ -480,6 +480,57 @@ extension ClosedRange where Bound: Strideable, Bound.Stride : SignedInteger {
   }
 }
 
+extension ClosedRange
+where Bound : FixedWidthInteger,
+      Bound.Magnitude : UnsignedInteger {
+
+  /// 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:
+  ///
+  ///     let greetings = ["hi", "hey", "hello", "hola"]
+  ///     let randomGreeting = greetings.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", perhaps
+  @_inlineable
+  public func random(
+    using generator: RandomNumberGenerator = Random.default
+  ) -> Element? {
+    let isLowerNegative = Bound.isSigned && lowerBound < 0
+    let sameSign = !Bound.isSigned || isLowerNegative == (upperBound < 0)
+    var delta: Bound.Magnitude
+    if isLowerNegative {
+      delta = sameSign
+        ? lowerBound.magnitude - upperBound.magnitude
+        : lowerBound.magnitude + upperBound.magnitude
+    } else {
+      delta = upperBound.magnitude - lowerBound.magnitude
+    }
+    if delta == Bound.Magnitude.max {
+      return Bound(truncatingIfNeeded: generator.next() as Bound.Magnitude)
+    }
+    delta += 1
+    let randomMagnitude = generator.next(upperBound: delta)
+    if sameSign {
+      return lowerBound + Bound(randomMagnitude)
+    } else {
+      return Bound.isSigned && randomMagnitude <= upperBound.magnitude
+        ? Bound(randomMagnitude)
+        : 0 - Bound(randomMagnitude - upperBound.magnitude)
+    }
+  }
+}
+
 extension ClosedRange {
   @inlinable
   public func overlaps(_ other: ClosedRange<Bound>) -> Bool {

stdlib/public/core/Collection.swift

@@ -1016,6 +1016,38 @@ 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:
+  ///
+  ///     let greetings = ["hi", "hey", "hello", "hola"]
+  ///     let randomGreeting = greetings.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", perhaps
+  @_inlineable
+  public func random(
+    using generator: RandomNumberGenerator = Random.default
+  ) -> Element? {
+    guard !isEmpty else { return nil }
+    let 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.
   @inlinable
   @inline(__always)

stdlib/public/core/CollectionAlgorithms.swift

@@ -367,6 +367,50 @@ extension MutableCollection where Self : BidirectionalCollection {
   }
 }
 
+//===----------------------------------------------------------------------===//
+// shuffled()
+//===----------------------------------------------------------------------===//
+
+extension Sequence {
+  /// Returns the elements of the sequence, shuffled.
+  ///
+  /// - Parameter generator: The random number generator to use when shuffling
+  ///   the sequence.
+  /// - Returns: A shuffled array of this sequence's elements.
+  @_inlineable
+  public func shuffled(
+    using generator: RandomNumberGenerator = Random.default
+  ) -> [Element] {
+    var result = ContiguousArray(self)
+    result.shuffle(using: generator)
+    return Array(result)
+  }
+}
+
+extension MutableCollection {
+  /// Shuffles the collection in place.
+  ///
+  /// - Parameter generator: The random number generator to use when shuffling
+  ///   the collection.
+  @_inlineable
+  public mutating func shuffle(
+    using generator: RandomNumberGenerator = Random.default
+  ) {
+    guard count > 1 else { return }
+    var amount = count
+    var currentIndex = startIndex
+    while amount > 1 {
+      let random = generator.next(upperBound: UInt(amount))
+      amount -= 1
+      swapAt(
+        currentIndex,
+        index(currentIndex, offsetBy: numericCast(random))
+      )
+      formIndex(after: &currentIndex)
+    }
+  }
+}
+
 //===----------------------------------------------------------------------===//
 // sorted()/sort()
 //===----------------------------------------------------------------------===//

stdlib/public/core/FloatingPoint.swift.gyb

@@ -2399,6 +2399,53 @@ extension BinaryFloatingPoint {
   */
 }
 
+% for Range in ['Range', 'ClosedRange']:
+
+extension BinaryFloatingPoint
+where Self.RawSignificand : FixedWidthInteger,
+      Self.RawSignificand.Stride : SignedInteger & FixedWidthInteger,
+      Self.RawSignificand.Magnitude : UnsignedInteger {
+
+  /// Returns a random representation of this floating point within the range.
+  ///
+  /// - Parameter range: A ${Range} to determine the bounds to get a random value
+  ///   from.
+  /// - Parameter generator: The random number generator to use when getting
+  ///   the random floating point.
+  /// - Returns: A random representation of this floating point.
+  @_inlineable
+  public static func random(
+    in range: ${Range}<Self>,
+    using generator: RandomNumberGenerator = Random.default
+  ) -> Self {
+%   if 'Closed' not in Range:
+    _precondition(
+      range.lowerBound != range.upperBound,
+      "Can't get random value with lowerBound == upperBound"
+    )
+%   end
+    let delta = range.upperBound - range.lowerBound
+    let maxSignificand: Self.RawSignificand = 1 << Self.significandBitCount
+%   if 'Closed' not in Range:
+    let rand: Self.RawSignificand = generator.next(upperBound: maxSignificand)
+%   else:
+    let rand: Self.RawSignificand = generator.next(upperBound: maxSignificand + 1)
+    if rand == maxSignificand {
+      return range.upperBound
+    }
+%   end
+    let unitRandom = Self.init(
+      sign: .plus,
+      exponentBitPattern: (1 as Self).exponentBitPattern,
+      significandBitPattern: rand
+    ) - 1
+    return delta * unitRandom + range.lowerBound
+  }
+
+}
+
+% end
+
 /// Returns the absolute value of `x`.
 @inlinable // FIXME(sil-serialize-all)
 @_transparent

stdlib/public/core/GroupInfo.json

@@ -176,6 +176,7 @@
     "Policy.swift",
     "Print.swift",
     "REPL.swift",
+    "Random.swift",
     "Runtime.swift",
     "RuntimeFunctionCounters.swift",
     "Shims.swift",

stdlib/public/core/Integers.swift.gyb

@@ -2530,6 +2530,36 @@ ${assignmentOperatorComment(x.operator, False)}
   % end
 }
 
+% for Range in ['Range', 'ClosedRange']:
+
+extension FixedWidthInteger
+where Self.Stride : SignedInteger,
+      Self.Magnitude : UnsignedInteger {
+
+  /// Returns a random representation of this integer within the range.
+  ///
+  /// - Parameter range: A ${Range} to determine the bounds to get a random value
+  ///   from.
+  /// - Parameter generator: The random number generator to use when getting
+  ///   the random integer.
+  /// - Returns: A random representation of this integer.
+  @_inlineable
+  public static func random(
+    in range: ${Range}<Self>,
+    using generator: RandomNumberGenerator = Random.default
+  ) -> 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)!
+  }
+}
+
+% end
+
 //===----------------------------------------------------------------------===//
 //===--- Operators on FixedWidthInteger -----------------------------------===//
 //===----------------------------------------------------------------------===//