# `Faker.Util`
[🔗](https://github.com/artkay/fakerer/blob/v1.0.0/lib/faker/util.ex#L1)

Collection of useful functions for your fake data. Functions aware of locale.

# `cycle`

```elixir
@spec cycle(pid()) :: any()
```

Cycle randomly through the given list with guarantee every element of the list is used once before
elements are being picked again. This is done by keeping a list of remaining elements that have
not been picked yet. The list of remaining element is returned, as well as the randomly picked
element.

# `cycle_start`

```elixir
@spec cycle_start([any()]) :: pid()
```

Start a cycle. See cycle/1

# `digit`

```elixir
@spec digit() :: binary()
```

Get a random digit as a string; one of 0-9

## Examples

    iex> Faker.Util.digit()
    "0"
    iex> Faker.Util.digit()
    "1"
    iex> Faker.Util.digit()
    "5"
    iex> Faker.Util.digit()
    "4"

# `format`

```elixir
@spec format(binary(), Keyword.t()) :: binary()
```

Format a string with randomly generated data. Format specifiers are replaced by random values. A
format specifier follows this prototype:

    %[length]specifier

The following specifier rules are present by default:

  - **d**: digits 0-9
  - **a**: lowercase letter a-z
  - **A**: uppercase letter A-Z
  - **b**: anycase letter a-z, A-Z

The specifier rules can be overridden using the second argument.

## Examples

    iex> Faker.Util.format("%2d-%3d %a%A %2d%%")
    "01-542 aS 61%"
    iex> Faker.Util.format("%8nBATMAN", n: fn() -> "nana " end)
    "nana nana nana nana nana nana nana nana BATMAN"

# `join`

```elixir
@spec join(integer(), binary(), (-> binary())) :: binary()
```

Execute fun n times with the index as first param and join the results with joiner

## Examples

    iex> Faker.Util.join(3, ", ", &Faker.Code.isbn13/0)
    "9781542646109, 9783297052358, 9790203032090"
    iex> Faker.Util.join(4, "-", fn -> Faker.format("####") end)
    "7337-6033-7459-8109"
    iex> Faker.Util.join(2, " vs ", &Faker.Superhero.name/0)
    "Falcon vs Green Blink Claw"
    iex> Faker.Util.join(2, " or ", &Faker.Color.name/0)
    "Purple or White"

# `letter`

```elixir
@spec letter() :: binary()
```

Get a random alphabet character as a string; one of a-z or A-Z

## Examples

    iex> Faker.Util.letter()
    "E"
    iex> Faker.Util.letter()
    "L"
    iex> Faker.Util.letter()
    "R"
    iex> Faker.Util.letter()
    "C"
    iex> Faker.Util.letter()
    "e"

# `list`

```elixir
@spec list(integer(), (integer() -> any())) :: [any()]
@spec list(integer(), (-> any())) :: [any()]
```

Execute fun n times with the index as first param and return the results as a list

## Examples

    iex> Faker.Util.list(3, &(&1))
    [0, 1, 2]
    iex> Faker.Util.list(3, &(&1 + 1))
    [1, 2, 3]
    iex> Faker.Util.list(5, &(&1 * &1))
    [0, 1, 4, 9, 16]
    iex> Faker.Util.list(3, &(to_string(&1)))
    ["0", "1", "2"]

# `lower_letter`

```elixir
@spec lower_letter() :: binary()
```

Get a random lowercase character as a string; one of a-z

## Examples

    iex> Faker.Util.lower_letter()
    "e"
    iex> Faker.Util.lower_letter()
    "l"
    iex> Faker.Util.lower_letter()
    "r"
    iex> Faker.Util.lower_letter()
    "c"

# `pick`

# `pick`

```elixir
@spec pick(Enum.t(), Enum.t()) :: any()
```

Pick a random element from an enumerable. Can also be provided a blacklist enumerable as a second argument.

## Examples

    iex> Faker.Util.pick(10..100)
    79
    iex> Faker.Util.pick([1, 3, 5, 7])
    3
    iex> Faker.Util.pick([true, false, nil])
    true
    iex> Faker.Util.pick(["a", "b", "c"], ["b"])
    "a"
    iex> Faker.Util.pick([1, "2", 3.0], 1..10)
    "2"

# `sample_uniq`

```elixir
@spec sample_uniq(pos_integer(), (-> any()), MapSet.t()) :: [any()]
```

Generate N unique elements

## Examples

    iex> Faker.Util.sample_uniq(2, &Faker.Internet.email/0)
    ["conor2058@schiller.com", "elizabeth2056@rolfson.net"]
    iex> Faker.Util.sample_uniq(10, fn -> Faker.String.base64(4) end)
    [
      "0CzJ",
      "3nuk",
      "D1Ip",
      "IqFG",
      "My3J",
      "W3yW",
      "e/kH",
      "gd75",
      "hVCK",
      "snJn"
    ]
    iex> Faker.Util.sample_uniq(1, &Faker.Phone.EnUs.area_code/0)
    ["508"]
    iex> Faker.Util.sample_uniq(0, &Faker.Internet.email/0)
    ** (FunctionClauseError) no function clause matching in Faker.Util.sample_uniq/3

# `to_sentence`

```elixir
@spec to_sentence([binary()]) :: binary()
```

Converts a list to a string, with "and" before the last item. Uses an Oxford comma.

## Examples

    iex> Faker.Util.to_sentence(["Black", "White"])
    "Black and White"
    iex> Faker.Util.to_sentence(["Jon Snow"])
    "Jon Snow"
    iex> Faker.Util.to_sentence(["Oceane", "Angeline", "Nicholas"])
    "Angeline, Nicholas, and Oceane"
    iex> Faker.Util.to_sentence(["One", "Two", "Three", "Four"])
    "Two, Three, Four, and One"

# `upper_letter`

```elixir
@spec upper_letter() :: binary()
```

Get a random uppercase character as a string; one of A-Z

## Examples

    iex> Faker.Util.upper_letter()
    "E"
    iex> Faker.Util.upper_letter()
    "L"
    iex> Faker.Util.upper_letter()
    "R"
    iex> Faker.Util.upper_letter()
    "C"

---

*Consult [api-reference.md](api-reference.md) for complete listing*