# Puid.Entropy (puid v1.1.2)

Entropy related calculations

The implementation is based on mathematical approximations to the solution of what is often referred to as the Birthday Problem.

# Link to this section Summary

## Functions

Entropy bits for generating a `total` number of instances with the given `risk` of repeat

Entropy bits of a string of `len` generated from characters `charset`, where `charset` is either an pre-defined `Puid.CharSet` or a string of unique characters.

Same as `Puid.Entropy.bits_for_len/2` but either returns the integer bits or raises a `Puid.Error`

Entropy bits per character where `charset` is either an pre-defined `Puid.CharSet` or a string of unique characters.

Same as `bits_per_char/1` but either returns the `bits` or raises a `Puid.Error`

Length needed for a string generated from `charset` to have `bits` of entropy.

Same as `Puid.Entropy.len_for_bits/2` but either returns the integer len or raises a `Puid.Error`

# bits(total, risk)

## Specs

`bits(pos_integer(), pos_integer()) :: float()`

Entropy bits for generating a `total` number of instances with the given `risk` of repeat

The total size of the instance pool is 2<sup>bits</sup>.

## Example

``````iex> Puid.Entropy.bits(10.0e6, 1.0e12)
85.37013046707142``````

# bits_for_len(len, charset)

## Specs

```bits_for_len(non_neg_integer(), atom() | String.t()) ::
{:ok, non_neg_integer()} | {:error, Error.reason()}```

Entropy bits of a string of `len` generated from characters `charset`, where `charset` is either an pre-defined `Puid.CharSet` or a string of unique characters.

The character set must be comprised of unique symbols, and it is assumed each symbol in the character set has equal probability of occurrence (which maximizes entropy).

## Example

``````iex> Puid.Entropy.bits_for_len(14, :alphanum)
{:ok, 83}

iex> Puid.Entropy.bits_for_len(14, "dingosky")
{:ok, 42}``````

# bits_for_len!(len, charset)

## Specs

`bits_for_len!(non_neg_integer(), atom() | String.t()) :: non_neg_integer()`

Same as `Puid.Entropy.bits_for_len/2` but either returns the integer bits or raises a `Puid.Error`

## Example

``````iex> Puid.Entropy.bits_for_len!(14, :alphanum)
83

iex> Puid.Entropy.bits_for_len!(14, "dingosky")
42``````

# bits_for_length(len, charset)

This function is deprecated. Use Puid.Entropy.bits_for_len.

# bits_for_length!(len, charset)

This function is deprecated. Use Puid.Entropy.bits_for_len!.

# bits_per_char(charset)

## Specs

`bits_per_char(atom() | String.t()) :: {:ok, float()} | {:error, Error.reason()}`

Entropy bits per character where `charset` is either an pre-defined `Puid.CharSet` or a string of unique characters.

The character set must be comprised of unique symbols, and it is assumed each symbol in the character set has equal probability of occurrence (which maximizes entropy).

Returns `{:ok, bits}`; or `{:error, reason}` if `arg` is either an unrecognized pre-defined `Puid.CharSet` or a string of non-unique characters.

## Example

``````iex> Puid.Entropy.bits_per_char(:alphanum)
{:ok, 5.954196310386875}

iex> Puid.Entropy.bits_per_char("dingosky")
{:ok, 3.0}``````

# bits_per_char!(charset)

## Specs

`bits_per_char!(atom() | String.t()) :: float()`

Same as `bits_per_char/1` but either returns the `bits` or raises a `Puid.Error`

## Example

`````` iex> Puid.Entropy.bits_per_char!(:alphanum)
5.954196310386875

Puid.Entropy.bits_per_char!("dingosky")
3.0``````

# len_for_bits(bits, charset)

## Specs

```len_for_bits(non_neg_integer(), atom() | String.t()) ::
{:ok, non_neg_integer()} | {:error, Error.reason()}```

Length needed for a string generated from `charset` to have `bits` of entropy.

The character set must be comprised of unique symbols, and it is assumed each symbol in the character set has equal probability of occurrence (which maximizes entropy).

## Example

``````iex> Puid.Entropy.len_for_bits(128, :alphanum)
{:ok, 22}

iex> Puid.Entropy.len_for_bits(128, "dingosky")
{:ok, 43}``````

# len_for_bits!(bits, charset)

## Specs

`len_for_bits!(non_neg_integer(), atom() | String.t()) :: non_neg_integer()`

Same as `Puid.Entropy.len_for_bits/2` but either returns the integer len or raises a `Puid.Error`

## Example

``````iex> Puid.Entropy.len_for_bits!(128, :alphanum)
22

iex> Puid.Entropy.len_for_bits!(128, "dingosky")
43``````