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.

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

@spec clear() :: :ok

Clear CryptoRand process dictionary entries.

Link to this function

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 sourceis 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"
Link to this function

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"
Link to this function

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"
Link to this function

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
Link to this function

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.

Link to this function

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]