RandomKit is a Swift framework that makes random data generation simple and easy.

Build Status
Installation
Benchmark
Usage
Extra
- BigInt
License

Build Status

Installation

Compatibility

Platforms:
- macOS 10.9+
- iOS 8.0+
- watchOS 2.0+
- tvOS 9.0+
- Linux
Xcode 8.0+
Swift 3.0.2+ & 4.0

RandomKit is possibly also compatible with FreeBSD, Android, and Windows (under Cygwin) but has not been tested for those platforms.

Install Using Swift Package Manager

The Swift Package Manager is a decentralized dependency manager for Swift.

Add the project to your Package.swift.

import PackageDescription

let package = Package(
    name: "MyAwesomeProject",
    dependencies: [
        .Package(url: "https://github.com/nvzqz/RandomKit.git",
                 majorVersion: 5)
    ]
)

Import the RandomKit module.
```
import RandomKit
```

Install Using CocoaPods

CocoaPods is a centralized dependency manager for Objective-C and Swift. Go here to learn more.

Add the project to your Podfile.

use_frameworks!

pod 'RandomKit', '~> 5.2.3'

If you want to be on the bleeding edge, replace the last line with:

pod 'RandomKit', :git => 'https://github.com/nvzqz/RandomKit.git'

Run pod install and open the .xcworkspace file to launch Xcode.
Import the RandomKit framework.
```
import RandomKit
```

Install Using Carthage

Carthage is a decentralized dependency manager for Objective-C and Swift.

Add the project to your Cartfile.
```
github "nvzqz/RandomKit"
```
Run carthage update and follow the additional steps in order to add RandomKit to your project.
Import the RandomKit framework.
```
import RandomKit
```

Benchmark

Various components of RandomKit can be easily benchmarked by running benchmark.sh.

./benchmark.sh [FLAGS] [PROTOCOLS]

Use the --help flag for information regarding how to use it.

Note: The default count is 10000000, which is A LOT if using the --array flag. This can be changed by passing an argument into --count or -c.

Usage

Try it out for yourself! Download the repo and open 'RandomKit.playground'.

RandomGenerator

The RandomGenerator protocol defines basic methods for generating primitive values and randomizing a buffer.

All provided types that conform to RandomGenerator have a static default value that can be passed as an inout argument to generation functions.

let value = Int.random(using: &Xoroshiro.default)

Available Generators

ARC4Random
- Because the symbols for the arc4random family of functions aren't exported with Foundation on Linux and other platforms, they're dynamically loaded at runtime.
DeviceRandom
- Reads from "/dev/random" or "/dev/urandom" as its source.
MersenneTwister
Xoroshiro
Xorshift
XorshiftStar
ChaCha

SeedableRandomGenerator

SeedableRandomGenerator is for types that can be seeded with some associated Seed type.

RandomBytesGenerator

The RandomBytesGenerator protocol is for types that specialize in generating a specific type that fills up a number of bytes. For example, MersenneTwister specializes in generating UInt64 while Xorshift generates UInt32 values.

Thread Safety

For single-threaded programs, it is safe to use a global generator instance such as Xoroshiro.default as a source of randomness.

For multi-threaded programs, the thread-local instances should be used. This allows for different threads to use their own separate random generators without a shared mutable state.

In the following example, randomGenerator is unique to each thread.

let randomBytes = Xoroshiro.withThreadLocal { randomGenerator in
    return [UInt8](randomCount: 1000, using: &randomGenerator)
}

Thread-local generators are deallocated upon thread exit, so there's no need to worry about cleanup.

It's recommended to not call withThreadLocal(_:) or get the threadLocal pointer each individual time it's needed. Retrieving the thread-local instance incurs avoidable overhead.

// Bad
let value = Int.random(using: &Xoroshiro.threadLocal.pointee)
array.shuffle(using: &Xoroshiro.threadLocal.pointee)

// Good
let threadLocal = Xoroshiro.threadLocal
let value = Int.random(using: &threadLocal.pointee)
array.shuffle(using: &threadLocal.pointee)

// Better
Xoroshiro.withThreadLocal { randomGenerator in
    let value = Int.random(using: &randomGenerator)
    array.shuffle(using: &randomGenerator)
}

As a shortcut, you can even apply a function directly as a parameter.

let value = Xoroshiro.withThreadLocal(Int.random)

Prior to v4.4.0, thread safety could be achieved by instantiating a new seeded instance of a given RandomGenerator type. The problem with this is that unnecessary seeding occurs each time. With this, the generator is seeded once and can then be reused at later points.

Shortcuts to the reseeding version of a generator are also available:

Xoroshiro.withThreadLocalReseeding {
    ...
}

Which is way better than writing:

ReseedingRandomGenerator.withThreadLocal(createdWith: { Xoroshiro.reseeding }) {
    ...
}

Protocols

RandomKit is very protocol-oriented, which gives it the ability to be very flexible and modular.

Random

A protocol for types that can generate random values using a RandomGenerator.

RandomInRange

A protocol for types that can generate optional random values within a range using a RandomGenerator.

Int.random(in: 0 ..< 0, using: &randomGenerator) // nil

RandomInClosedRange

A protocol for types that can generate random values within a closed range using a RandomGenerator.

Int.random(in: -100 ... 100, using: &randomGenerator) // -79

RandomToValue

A protocol for types that can generate random values from a base value to another

RandomKit

Install / Use

README