# `Localize.Translate.JSON`
[🔗](https://github.com/elixir-localize/localize_translate/blob/v0.1.0/lib/localize/translate/json.ex#L1)

Adapter that exposes the Erlang `:json` module under the bang-suffixed API
(`encode!/1`, `decode!/1`, `encode_to_iodata!/1`) expected by Ecto and Postgrex.

Provides Elixir-native semantics on top of `:json`:

* `nil` encodes as JSON `null` (not the string `"nil"`).

* `true` and `false` encode as JSON booleans.

* Structs encode as maps (the `:__struct__` key is dropped).

* Other atoms encode as strings.

* JSON `null` decodes as `nil` (not the atom `:null`).

Configured by default in `config/config.exs`:

    config :ecto, json_library: Localize.Translate.JSON
    config :postgrex, json_library: Localize.Translate.JSON

# `decode!`

```elixir
@spec decode!(iodata()) :: term()
```

Decodes a JSON binary into an Elixir term.

### Arguments

* `value` is JSON-encoded iodata: a binary or a list of binaries.

### Returns

* The decoded Elixir term. Objects decode as maps with string keys, arrays as lists,
  JSON `null` as `nil`, and JSON booleans as `true` / `false`.

### Examples

    iex> Localize.Translate.JSON.decode!(~s({"name":"Ada"}))
    %{"name" => "Ada"}

    iex> Localize.Translate.JSON.decode!("[1,true,null]")
    [1, true, nil]

# `encode!`

```elixir
@spec encode!(term()) :: binary()
```

Encodes an Elixir term as a JSON binary.

### Arguments

* `value` is any term encodable as JSON: a map, list, struct, binary, number, boolean,
  `nil`, or atom.

### Returns

* A binary containing the JSON encoding of `value`.

### Examples

    iex> Localize.Translate.JSON.encode!(%{name: "Ada"})
    ~s({"name":"Ada"})

    iex> Localize.Translate.JSON.encode!([1, true, nil])
    "[1,true,null]"

    iex> Localize.Translate.JSON.encode!(nil)
    "null"

# `encode_to_iodata!`

```elixir
@spec encode_to_iodata!(term()) :: iodata()
```

Encodes an Elixir term as JSON iodata.

Identical to `encode!/1` but returns iodata for efficient writing to IO devices or
sockets without an intermediate binary.

### Arguments

* `value` is any term encodable as JSON.

### Returns

* An iodata value (a binary, a list of binaries, or a list of iodata) containing the JSON
  encoding of `value`.

### Examples

    iex> Localize.Translate.JSON.encode_to_iodata!(%{}) |> IO.iodata_to_binary()
    "{}"

---

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