# `Forex.Support`
[🔗](https://github.com/greven/forex/blob/1.1.2/lib/forex/support.ex#L1)

The `Forex.Support` module provides helper functions, for example, for
formatting the exchange rates values.

# `atomize_code`

```elixir
@spec atomize_code(atom() | String.t()) :: atom()
```

Conver the binary currency code to an existing atom representation.

## Examples

      iex> Forex.Support.atomize_code("usd")
      :usd

      iex> Forex.Support.atomize_code(:usd)
      :usd

      iex> Forex.Support.atomize_code("USD")
      :usd

      iex> Forex.Support.atomize_code(:USD)
      :usd

      iex> Forex.Support.atomize_code("uSD")
      :usd

      iex> Forex.Support.atomize_code(1)
      ** (FunctionClauseError) no function clause matching in Forex.Support.atomize_code/1

# `format_value`

```elixir
@spec format_value(number() | binary() | Decimal.t(), :string | :decimal) ::
  formatted_value :: binary() | Decimal.t()
```

Format the rate value based on the `format` option

## Examples

    iex> Forex.Support.format_value("1.2345", :string)
    "1.2345"

    iex> Forex.Support.format_value("1.2345", :decimal)
    Decimal.new("1.2345")

    iex> Forex.Support.format_value("1.2345", :decimal)
    Decimal.new("1.2345")

    iex> Forex.Support.format_value("1.2345", :string)
    "1.2345"

    iex> Forex.Support.format_value(1.2345, :decimal)
    Decimal.new("1.2345")

    iex> Forex.Support.format_value(1.2345, :string)
    "1.2345"

    iex> Forex.Support.format_value(Decimal.new("1.2345"), :decimal)
    Decimal.new("1.2345")

    iex> Forex.Support.format_value(Decimal.new("1.2345"), :string)
    "1.2345"

    iex> Forex.Support.format_value(1.2345, :number)
    ** (Forex.FormatError) Invalid format value: number

# `map_date`

```elixir
@spec map_date(parsable_date()) :: Date.t() | nil
```

Map the date to a `Date` struct
or `nil` if the date cannot be parsed.

## Examples

    iex> Forex.Support.map_date("2020-01-01")
    ~D[2020-01-01]

    iex> Forex.Support.map_date("2020-01-01T00:00:00Z")
    ~D[2020-01-01]

    iex> Forex.Support.map_date({1982, 2, 25})
    ~D[1982-02-25]

    iex> Forex.Support.map_date(~D[2020-01-01])
    ~D[2020-01-01]

    iex> Forex.Support.map_date(~U[2020-01-01T00:00:00Z])
    ~D[2020-01-01]

    iex> Forex.Support.map_date("2020-01-01T00:00:00")
    nil

    iex> Forex.Support.map_date("1982-02-31T00:00:00Z")
    nil

    iex> Forex.Support.map_date(1982)
    nil

# `parse_date`

```elixir
@spec parse_date(parsable_date()) :: {:ok, Date.t()} | {:error, :invalid_date}
```

Attempt to parse a date from a binary string in ISO 8601 format

## Examples

    iex> Forex.Support.parse_date("2020-01-01")
    {:ok, ~D[2020-01-01]}

    iex> Forex.Support.parse_date("2020-01-01T00:00:00Z")
    {:ok, ~D[2020-01-01]}

    iex> Forex.Support.parse_date({1982, 2, 25})
    {:ok, ~D[1982-02-25]}

    iex> Forex.Support.parse_date(~D[2020-01-01])
    {:ok, ~D[2020-01-01]}

    iex> Forex.Support.parse_date(~U[2020-01-01T00:00:00Z])
    {:ok, ~D[2020-01-01]}

    iex> Forex.Support.parse_date("2020-01-01T00:00:00")
    {:error, :invalid_date}

    iex> Forex.Support.parse_date("1982-02-31T00:00:00Z")
    {:error, :invalid_date}

    iex> Forex.Support.parse_date(1982)
    {:error, :invalid_date}

# `round_value`

```elixir
@spec round_value(any(), integer() | nil) :: any()
```

Round the rate value based on the `round` option

## Examples

      iex> Forex.Support.round_value(1.2345, 2)
      1.23

      iex> Forex.Support.round_value(1.2345, 4)
      1.2345

      iex> Forex.Support.round_value(1.2345, 0)
      1.0

      iex> Forex.Support.round_value(1.2345, 15)
      1.2345

      iex> Forex.Support.round_value(Decimal.new("1.2345"), 2)
      Decimal.new("1.23")

      iex> Forex.Support.round_value(Decimal.new("1.2345"), 4)
      Decimal.new("1.2345")

      iex> Forex.Support.round_value(Decimal.new("1.2345"), 0)
      Decimal.new("1")

      iex> Forex.Support.round_value("1.2345", 2)
      "1.23"

      iex> Forex.Support.round_value("1.2345", 4)
      "1.2345"

      iex> Forex.Support.round_value("1.2345", nil)
      "1.2345"

      iex> Forex.Support.round_value(nil, 2)
      nil

      iex> Forex.Support.round_value(1.2345, 16)
      ** (FunctionClauseError) no function clause matching in Forex.Support.round_value/2

# `stringify_code`

```elixir
@spec stringify_code(atom() | String.t()) :: String.t()
```

Convert the currency code to a default string representation (uppercase string).

## Examples

    iex> Forex.Support.stringify_code(:usd)
    "USD"

    iex> Forex.Support.stringify_code("usd")
    "USD"

    iex> Forex.Support.stringify_code("USD")
    "USD"

    iex> Forex.Support.stringify_code(:USD)
    "USD"

    iex> Forex.Support.stringify_code(:usd)
    "USD"

    iex> Forex.Support.stringify_code("usd")
    "USD"

    iex> Forex.Support.stringify_code("USD")
    "USD"

    iex> Forex.Support.stringify_code(:USD)
    "USD"

    iex> Forex.Support.stringify_code(1)
    ** (FunctionClauseError) no function clause matching in Forex.Support.stringify_code/1

---

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