NumericAnnex Reference (100% documented)

View on GitHub

Install in Dash

PRNG

public protocol PRNG : class, IteratorProtocol, Sequence
where Element : FixedWidthInteger & UnsignedInteger,
  SubSequence : Sequence,
  Element == SubSequence.Element

A pseudo-random number generator (PRNG).

Reference types that conform to PRNG are infinite sequences of pseudo-random elements. Protocol extension methods iterate over such a sequence as necessary to generate pseudo-random values from the desired distribution.

Considerations for Conforming Types

For clarity to end users, custom PRNGs may be implemented in an extension to Random. For instance, the xoroshiro128+ algorithm is implemented in a final class named Random.Xoroshiro.

The static methods _entropy(_:) and _entropy(_:count:) return cryptographically secure random bytes that may be useful for seeding your custom PRNG. However, these methods may return nil if the requested number of random bytes is not available, and they are not recommended as a routine source of random data.

Adding Other Probability Distributions

Many built-in protocol extension methods make use of the primitive, overloaded method _random(_:bitCount:). You may wish to use the same method in new protocol extension methods that return pseudo-random values from other probability distributions.

The method _random(_:bitCount:) generates uniformly distributed binary floating-point values in the half-open range [0, 1) with a precision of either bitCount or the significand bit count of the floating-point type, whichever is less. Additionally, this method generates uniformly distributed unsigned integers in the half-open range [0, 2 ** x), where ** is the exponentiation operator and x is the lesser of bitCount and the bit width of the integer type.

For end users, however, the recommended spelling for a uniformly distributed numeric value is uniform(); that method is overloaded to permit custom minimum and maximum values for the uniform distribution.

Topics

  • State

    A type that can represent the internal state of the pseudo-random number generator.

    Declaration

    Swift

    associatedtype State

  • state

    The internal state of the pseudo-random number generator.

    Declaration

    Swift

    var state: State

  • init(state:)

    Creates a pseudo-random number generator with the given internal state.

    Declaration

    Swift

    init(state: State)
    Parameters
    state

    The value to be used as the generator’s internal state.

  • init()

    Creates a pseudo-random number generator with an internal state seeded using cryptographically secure random bytes.

    If cryptographically secure random bytes are unavailable, the result is nil.

    Declaration

    Swift

    init?()

  • max Default implementation

    The maximum value that may be generated by the pseudo-random number generator.

    Declaration

    Swift

    static var max: Element

  • min Default implementation

    The minimum value that may be generated by the pseudo-random number generator.

    Declaration

    Swift

    static var min: Element

  • _randomBitWidth Extension method

    The number of pseudo-random bits available from a value generated by the pseudo-random number generator.

    Declaration

    Swift

    public static var _randomBitWidth: Int

  • _entropy(_:) Extension method

    Returns a value filled with data from a source of cryptographically secure random bytes, or nil if a sufficient number of cryptographically secure random bytes is unavailable.

    Declaration

    Swift

    public static func _entropy<
    T : FixedWidthInteger & UnsignedInteger
  >(_: T.Type = T.self) -> T?

  • _entropy(_:count:) Extension method

    Returns an array of count values filled with data from a source of cryptographically secure random bytes, or nil if a sufficient number of cryptographically secure random bytes is unavailable.

    Declaration

    Swift

    public static func _entropy<
    T : FixedWidthInteger & UnsignedInteger
  >(_: T.Type = T.self, count: Int) -> [T]?

  • _random(_:bitCount:) Extension method

    Generates a pseudo-random unsigned integer of type T in the range from 0 to 2 ** min(bitCount, T.bitWidth) (exclusive), where ** is the exponentiation operator.

    Declaration

    Swift

    public func _random<T : FixedWidthInteger & UnsignedInteger>(
    _: T.Type = T.self, bitCount: Int = T.bitWidth
  ) -> T

  • uniform(_:a:b:) Extension method

    Generates a pseudo-random unsigned integer of type T in the range from a through b (inclusive) from the discrete uniform distribution.

    Declaration

    Swift

    public func uniform<T : FixedWidthInteger & UnsignedInteger>(
    _: T.Type = T.self, a: T, b: T
  ) -> T

  • uniform(_:) Extension method

    Generates a pseudo-random unsigned integer of type T in the range from T.min through T.max (inclusive) from the discrete uniform distribution.

    Declaration

    Swift

    public func uniform<T : FixedWidthInteger & UnsignedInteger>(
    _: T.Type = T.self
  ) -> T

  • uniform(_:a:b:count:) Extension method

    Generates a sequence of count pseudo-random unsigned integers of type T in the range from a through b (inclusive) from the discrete uniform distribution.

    Declaration

    Swift

    public func uniform<T : FixedWidthInteger & UnsignedInteger>(
    _: T.Type = T.self, a: T, b: T, count: Int
  ) -> UnfoldSequence<T, Int>

  • uniform(_:count:) Extension method

    Generates a sequence of count pseudo-random unsigned integers of type T in the range from T.min through T.max (inclusive) from the discrete uniform distribution.

    Declaration

    Swift

    public func uniform<T : FixedWidthInteger & UnsignedInteger>(
    _: T.Type = T.self, count: Int
  ) -> UnfoldSequence<T, Int>

  • uniform(_:a:b:) Extension method

    Generates a pseudo-random signed integer of type T in the range from a through b (inclusive) from the discrete uniform distribution.

    Declaration

    Swift

    public func uniform<T : FixedWidthInteger & SignedInteger>(
    _: T.Type = T.self, a: T, b: T
  ) -> T where T.Magnitude : FixedWidthInteger & UnsignedInteger

  • uniform(_:) Extension method

    Generates a pseudo-random signed integer of type T in the range from T.min through T.max (inclusive) from the discrete uniform distribution.

    Declaration

    Swift

    public func uniform<T : FixedWidthInteger & SignedInteger>(
    _: T.Type = T.self
  ) -> T where T.Magnitude : FixedWidthInteger & UnsignedInteger

  • uniform(_:a:b:count:) Extension method

    Generates a sequence of count pseudo-random signed integers of type T in the range from a through b (inclusive) from the discrete uniform distribution.

    Declaration

    Swift

    public func uniform<T : FixedWidthInteger & SignedInteger>(
    _: T.Type = T.self, a: T, b: T, count: Int
  ) -> UnfoldSequence<T, Int>
  where T.Magnitude : FixedWidthInteger & UnsignedInteger

  • uniform(_:count:) Extension method

    Generates a sequence of count pseudo-random signed integers of type T in the range from T.min through T.max (inclusive) from the discrete uniform distribution.

    Declaration

    Swift

    public func uniform<T : FixedWidthInteger & SignedInteger>(
    _: T.Type = T.self, count: Int
  ) -> UnfoldSequence<T, Int>
  where T.Magnitude : FixedWidthInteger & UnsignedInteger

  • _random(_:bitCount:) Extension method

    Generates a pseudo-random binary floating-point value of type T in the range from 0 to 1 (exclusive) with min(bitCount, T.significandBitCount) bits of precision.

    Declaration

    Swift

    public func _random<T : BinaryFloatingPoint>(
    _: T.Type = T.self, bitCount: Int = T.significandBitCount
  ) -> T

  • uniform(_:a:b:) Extension method

    Generates a pseudo-random binary floating-point value of type T in the range from a to b (exclusive) from the uniform distribution.

    Declaration

    Swift

    public func uniform<T : BinaryFloatingPoint>(
    _: T.Type = T.self, a: T, b: T
  ) -> T

  • uniform(_:) Extension method

    Generates a pseudo-random binary floating-point value of type T in the range from 0 to 1 (exclusive) from the uniform distribution.

    Declaration

    Swift

    public func uniform<T : BinaryFloatingPoint>(_: T.Type = T.self) -> T

  • uniform(_:a:b:count:) Extension method

    Generates a sequence of count pseudo-random binary floating-point values of type T in the range from a to b (exclusive) from the uniform distribution.

    Declaration

    Swift

    public func uniform<T : BinaryFloatingPoint>(
    _: T.Type = T.self, a: T, b: T, count: Int
  ) -> UnfoldSequence<T, Int>

  • uniform(_:count:) Extension method

    Generates a sequence of count pseudo-random binary floating-point values of type T in the range from 0 to 1 (exclusive) from the uniform distribution.

    Declaration

    Swift

    public func uniform<T : BinaryFloatingPoint>(
    _: T.Type = T.self, count: Int
  ) -> UnfoldSequence<T, Int>