CryptoRand (crypto_rand v1.0.4)
CryptoRand
provides fast and efficient crytographically strong versions of several Enum
functions that rely on :rand
uniform for
underlying randomness. CryptoRand
functions also operate on String.t()
where appropriate.
Summary
Functions
Clear CryptoRand
process dictionary entries.
Returns a random element of source
.
Shuffles the elements of source
.
Takes count
random items from an enumerable source
or graphemes from a string source
.
Generate random uniform integer in the range 1 to max
.
Generate a random binary such that n
integers in the range 0 to max
-1 can be parsed by
processing the binary k bits at a time, where k is the number of bits required to
represent max
-1.
Generate n
random uniform integers in the range 1 to max
.
Functions
clear()
@spec clear() :: :ok
Clear CryptoRand
process dictionary entries.
random(source, rand_bytes \\ &:crypto.strong_rand_bytes/1)
@spec random(Enumerable.t() | String.t(), (non_neg_integer() -> binary())) :: any()
Returns a random element of source
.
Randomness is generated using rand_bytes/1
.
Raises Enum.EmptyError
if source
is empty.
This function uses bytes from the function rand_bytes
to generate a random integer in the range
[0, n-1], where n is the number of elements in the source
enumerable or graphemes in the
source
string. The element at the random integer index is returned.
Example
iex> CryptoRand.random(1..10)
7
iex> CryptoRand.random("aeiou")
"i"
shuffle(source, rand_bytes \\ &:crypto.strong_rand_bytes/1)
@spec shuffle(Enumerable.t() | String.t(), (non_neg_integer() -> binary())) :: list() | String.t()
Shuffles the elements of source
.
Randomness is generated using rand_bytes/1
.
Returns a list
with the elements of an enumerable source
shuffled or a String.t()
with the
graphemes of a string source
shuffled.
Example
iex> CryptoRand.shuffle([1,2,3,4,5])
[5, 2, 3, 4, 1]
iex> CryptoRand.shuffle(?a..?z)
'chivgpxldtrokyuqsnjmawzfeb'
iex> CryptoRand.shuffle("dingosky")
"ndsyigok"
take_random(source, count, rand_bytes \\ &:crypto.strong_rand_bytes/1)
@spec take_random( Enumerable.t() | String.t(), non_neg_integer(), (non_neg_integer() -> binary()) ) :: list() | String.t()
Takes count
random items from an enumerable source
or graphemes from a string source
.
Returns a list
for a source
enumerable and a String.t()
for a source
string.
Examples
iex> CryptoRand.take_random(?a..?z, 5)
'kwvhn'
iex> CryptoRand.take_random([?a,?e,?i,?o,?u], 3)
'eao'
iex> CryptoRand.take_random("dingosky", 3)
"dgi"
uniform(max, rand_bytes \\ &:crypto.strong_rand_bytes/1)
@spec uniform( pos_integer(), (non_neg_integer() -> binary()) ) :: non_neg_integer()
Generate random uniform integer in the range 1 to max
.
Randomness is generated using rand_bytes/1
.
Example
iex> CryptoRand.uniform(16)
13
uniform_bytes(max, n, rand_bytes \\ &:crypto.strong_rand_bytes/1)
@spec uniform_bytes( pos_integer(), non_neg_integer(), (non_neg_integer() -> binary()) ) :: binary()
Generate a random binary such that n
integers in the range 0 to max
-1 can be parsed by
processing the binary k bits at a time, where k is the number of bits required to
represent max
-1.
Randomness is generated using rand_bytes/1
.
This function provides bytes such that each k bits can be used to index into an enumerable
or String.t()
of length max
.
Example
iex> CryptoRand.uniform_bytes(12, 9) |> IO.inspect() |> binary_digits()
<<148, 137, 83, 155, 160>>
"10010100 10001001 01010011 10011011 10100000"
iex> k = max |> :math.log2() |> :math.ceil() |> round()
4
For the bytes returned above, 9 integers can be parsed 4 bits at a time with each integer value being less than 12. Note none of the 4-bit clusters starts with 11, which means each 4-bit integer will be less than 12, as desired.
The function binary_digits/1
is not shown.
uniform_list(max, n, rand_bytes \\ &:crypto.strong_rand_bytes/1)
@spec uniform_list( pos_integer(), non_neg_integer(), (non_neg_integer() -> binary()) ) :: list()
Generate n
random uniform integers in the range 1 to max
.
Randomness is generated using rand_bytes/1
.
Example
iex> CryptoRand.uniform_list(16, 8)
[6, 9, 16, 4, 12, 4, 4, 10]