W3cubDocs

/Crystal

module Random

Overview

Random provides an interface for random values generation, using a pseudo random number generator (PRNG).

Random.rand    # => 0.167595
Random.rand(5) # => 2

The above methods delegate to a Random instance.

r = Random.new
r.rand      # => 0.0372991
r.next_bool # => true
r.next_int  # => 2223112

This module also defines a global method #rand, which Array#sample and Array#shuffle delegates.

rand     # => 0.293829
rand(10) # => 8

An instance of each class that includes Random is a random number generator with its own state. Usually such RNGs can be initialized with a seed, which defines their initial state. It is guaranteed that after initializing two different instances with the same seed, and then executing the same calls on both of them, you will get the same results. This allows exactly reproducing the same seemingly random events by just keeping the seed.

It is possible to make a custom RNG by including Random and implementing #next_u to return an unsigned number of a pre-determined type (usually UInt32). The numbers generated by your RNG must be uniformly distributed in the whole range of possible values for that type (e.g. 0u32..UInt32::MAX). This allows all other methods of Random to be based on this and still produce uniformly distributed results. Your Random class should also have a way to initialize it. For pseudo-random number generators that will usually be an integer seed, but there are no rigid requirements for the initialization.

The default PRNG is Random::PCG32 which has a good overall statistical distribution (low bias of generated numbers) and is fast for overall usages on different platforms, but isn't cryptographically secure. If a third party has access to some generated numbers, she may deduce incoming numbers, putting your application at risk.

It is recommended to use a secure source, such as Random::Secure, Random::ISAAC or ChaCha20 for anything that needs security, such as online games, identification tokens, salts, initializing a PRNG, ... These PRNG are slower but cryptographically secure, so a third party can't deduce incoming numbers.

Direct including types

Defined in:

big/big_int.cr
random.cr
random/secure.cr

Constant Summary

DEFAULT = PCG32.new

Constructors

Class Method Summary

Instance Method Summary

Constructor Detail

def self.new(seed, sequence = 0_u64)Source

Initializes an instance with the given seed and sequence.

def self.newSource

Initializes an instance seeded from a system source.

Class Method Detail

def self.rand(x)Source

See #rand(x).

def self.rand : Float64Source

See #rand.

Instance Method Detail

def base64(n : Int = 16) : StringSource

Generates n random bytes that are encoded into base64.

Check Base64#strict_encode for details.

Random::Secure.base64(4) # => "fK1eYg=="

It is recommended to use the secure Random::Secure as a source or another cryptographically quality PRNG such as Random::ISAAC or ChaCha20.

def hex(n : Int = 16) : StringSource

Generates a hexadecimal string based on n random bytes.

The bytes are encoded into a string of two-digit hexadecimal number (00-ff) per byte.

Random::Secure.hex    # => "05f100a1123f6bdbb427698ab664ff5f"
Random::Secure.hex(1) # => "1a"

It is recommended to use the secure Random::Secure as a source or another cryptographically quality PRNG such as Random::ISAAC or ChaCha20.

def next_bool : BoolSource

Generates a random Bool.

Random.new.next_bool # => true

def next_float : Float64Source

See #rand.

def next_int : Int32Source

Same as #rand(Int32::MIN..Int32::MAX).

abstract def next_uSource

Generates a random unsigned integer.

The integers must be uniformly distributed between 0 and the maximal value for the chosen type.

def rand(range : Range(Int, Int)) : IntSource

Returns a random integer in the given range.

The return type always matches the supplied argument.

Random.new.rand(10..20)                 # => 14
Random.new.rand(Int64::MIN..Int64::MAX) # => -5297435808626736140

def rand(max : Int) : IntSource

Generates a random integer which is greater than or equal to 0 and less than max.

The return type always matches the supplied argument.

Random.new.rand(10)   # => 5
Random.new.rand(5000) # => 2243

def rand : Float64Source

Generates a random Float64 between 0 and 1.

r = Random.new
r.rand # => 0.167595
r.rand # => 0.0372991

def rand(type : UInt64.class) : UInt64Source

Returns a random UInt64

rand(UInt64) # => 15004487597684511003

def rand(type : Int64.class) : Int64Source

Returns a random Int64

rand(Int64) # => 4438449217673515190

def rand(type : UInt32.class) : UInt32Source

Returns a random UInt32

rand(UInt32) # => 3147957137

def rand(type : Int32.class) : Int32Source

Returns a random Int32

rand(Int32) # => 1870830079

def rand(type : UInt16.class) : UInt16Source

Returns a random UInt16

rand(UInt16) # => 39546

def rand(type : Int16.class) : Int16Source

Returns a random Int16

rand(Int16) # => -32554

def rand(type : UInt8.class) : UInt8Source

Returns a random UInt8

rand(UInt8) # => 186

def rand(type : Int8.class) : Int8Source

Returns a random Int8

rand(Int8) # => 20

def rand(max : Float) : Float64Source

Returns a random Float64 which is greater than or equal to 0 and less than max.

Random.new.rand(3.5)    # => 2.88938
Random.new.rand(10.725) # => 7.70147

def rand(type : StaticArray(Int64, UNDERSCORE).class)Source

Returns a StaticArray filled with random Int64 values.

rand(StaticArray(Int64, 4)) # => StaticArray[4438449217673515190, 8514493061600538358, -4874671083204037318, -7825896160729246667]

def rand(type : StaticArray(UInt32, UNDERSCORE).class)Source

Returns a StaticArray filled with random UInt32 values.

rand(StaticArray(UInt32, 4)) # => StaticArray[3147957137, 4245108745, 2207809043, 3184391838]

def rand(type : StaticArray(Int32, UNDERSCORE).class)Source

Returns a StaticArray filled with random Int32 values.

rand(StaticArray(Int32, 4)) # => StaticArray[1870830079, -1043532158, -867180637, -1216773590]

def rand(type : StaticArray(UInt16, UNDERSCORE).class)Source

Returns a StaticArray filled with random UInt16 values.

rand(StaticArray(UInt16, 4)) # => StaticArray[39546, 44091, 2874, 17348]

def rand(type : StaticArray(Int16, UNDERSCORE).class)Source

Returns a StaticArray filled with random Int16 values.

rand(StaticArray(Int16, 4)) # => StaticArray[-32554, 32169, -20152, -7686]

def rand(type : StaticArray(UInt8, UNDERSCORE).class)Source

Returns a StaticArray filled with random UInt8 values.

rand(StaticArray(UInt8, 4)) # => StaticArray[186, 221, 127, 245]

def rand(type : StaticArray(Int8, UNDERSCORE).class)Source

Returns a StaticArray filled with random Int8 values.

rand(StaticArray(Int8, 4)) # => StaticArray[20, -66, 89, 19]

def rand(range : Range(Float, Float)) : FloatSource

Returns a random Float in the given range.

Random.new.rand(6.2..21.768) # => 15.2989

def rand(type : StaticArray(UInt64, UNDERSCORE).class)Source

Returns a StaticArray filled with random UInt64 values.

rand(StaticArray(UInt64, 4)) # => StaticArray[15004487597684511003, 12027825265648206103, 11303949506191212698, 6228566501671148658]

def random_bytes(n : Int = 16) : BytesSource

Generates a slice filled with n random bytes.

Random.new.random_bytes    # => [145, 255, 191, 133, 132, 139, 53, 136, 93, 238, 2, 37, 138, 244, 3, 216]
Random.new.random_bytes(4) # => [217, 118, 38, 196]

def random_bytes(buf : Bytes) : NilSource

Fills a given slice with random bytes.

slice = Bytes.new(4) # => [0, 0, 0, 0]
Random.new.random_bytes(slice)
slice # => [217, 118, 38, 196]

def urlsafe_base64(n : Int = 16, padding = false) : StringSource

URL-safe variant of #base64.

Check Base64#urlsafe_encode for details.

Random::Secure.urlsafe_base64                    # => "MAD2bw8QaBdvITCveBNCrw"
Random::Secure.urlsafe_base64(8, padding: true)  # => "vvP1kcs841I="
Random::Secure.urlsafe_base64(16, padding: true) # => "og2aJrELDZWSdJfVGkxNKw=="

It is recommended to use the secure Random::Secure as a source or another cryptographically quality PRNG such as Random::ISAAC or ChaCha20.

© 2012–2020 Manas Technology Solutions.
Licensed under the Apache License, Version 2.0.
https://crystal-lang.org/api/0.35.1/Random.html