eljiffy v1.3.0 Eljiffy
Documentation for Eljiffy.
Eljiffy (Elixir Jiffy) is an Elixir wrapper around the erlang JSON nif library Jiffy. It also provides functions to convert json to maps directly rather than having to pass the option return_maps explicitly (https://github.com/davisp/jiffy) (decode!/1 and decode!/2)
The opts parameter for decode_proplist/2
is a list of terms:
:return_maps
- Tell Jiffy to return objects using the maps data type on VMs that support it. This raises an error on VMs that don't support maps.null_term:
term - Returns the specified Term instead of null when decoding JSON. This is for people that wish to use undefined instead of null.:use_nil
- Returns the atom nil instead of null when decoding JSON. This is a short hand for{:null_term, nil}
.:return_trailer
- If any non-whitespace is found after the first JSON term is decoded the return value ofdecode_proplist/2
becomes{:has_trailer, firstTerm, restData}
. This is useful to decode multiple terms in a single binary.:dedupe_keys
- If a key is repeated in a JSON object this flag will ensure that the parsed object only contains a single entry containing the last value seen. This mirrors the parsing beahvior of virtually every other JSON parser.:copy_strings
- Normaly when strings are decoded they are created as sub-binaries of the input data. With some workloads this can lead to an undeseriable bloating of memory when a few small strings in JSON keep a reference to the full JSON document alive. Setting this option will instead allocate new binaries for each string to avoid keeping the original JSON document around after garbage collection.bytes_per_red: n where n >= 0
- This controls the number of bytes that Jiffy will process as an equivalent to a reduction. Each 20 reductions we consume 1% of our allocated time slice for the current process. When the Erlang VM indicates we need to return from the NIF.bytes_per_iter: n where n >= 0
- Backwards compatible option that is converted into thebytes_per_red
value.
The opts parameter for encode!/2
is a list of terms:
:uescape
- Escapes UTF-8 sequences to produce a 7-bit clean output:pretty
- Produce JSON using two-space indentation:force_utf8
- Force strings to encode as UTF-8 by fixing broken surrogate pairs and/or using the replacement character to remove broken UTF-8 sequences in data.:use_nil
- Encode's the atom nil as null.:escape_forward_slashes
- Escapes the / character which can be useful when encoding URLs in some cases.bytes_per_red:
n - Refer to the decode optionsbytes_per_iter:
n - Refer to the decode options
Link to this section Summary
Functions
Transforms a json string into a map
Transforms a json string into a map
Transforms a json string into a map
Transforms a json string into a key/value list in EEP 18 format
Does the same thing as decode_proplist/1
, but accepts decode options (see opts)
Transforms a EEP 18 format key/value list or map into a json string
Transforms a EEP 18 format key/value list or map into a json string
Link to this section Functions
decode(data, opts \\ [])
Transforms a json string into a map
Accepts decode options (see opts)
Examples
iex> jsonData = ~s({"people": [{"name": "Joe"}, {"name": "Robert"}, {"name": "Mike"}]}) iex> Eljiffy.decode(jsonData) {:ok, %{"people" => [
%{"name" => "Joe"},
%{"name" => "Robert"},
%{"name" => "Mike"}
]}}
iex> jsonData = ~s(invalid_json) iex> Eljiffy.decode(jsonData) {:error, %ErlangError{original: {1, :invalid_json}}}
decode!(data, opts \\ [])
Transforms a json string into a map
Accepts decode options (see opts)
Examples
iex> jsonData = ~s({"people": [{"name": "Joe"}, {"name": "Robert"}, {"name": "Mike"}]}) iex> Eljiffy.decode!(jsonData) %{"people" => [
%{"name" => "Joe"},
%{"name" => "Robert"},
%{"name" => "Mike"}
]}
Transforms a json string into a map
Accepts decode options (see opts)
Examples
iex> jsonData = ~s({"people": [{"name": "Joe"}, {"name": "Robert"}, {"name": "Mike"}]}) iex> Eljiffy.decode_maps(jsonData) %{"people" => [
%{"name" => "Joe"},
%{"name" => "Robert"},
%{"name" => "Mike"}
]}
decode_proplist(data)
Transforms a json string into a key/value list in EEP 18 format
Examples
iex> jsonData = ~s({"people": [{"name": "Joe"}, {"name": "Robert"}, {"name": "Mike"}]}) iex> Eljiffy.decode_proplist(jsonData) {[
{"people", [
{[{"name", "Joe"}]},
{[{"name", "Robert"}]},
{[{"name", "Mike"}]}
]}
]}
decode_proplist(data, opts)
Does the same thing as decode_proplist/1
, but accepts decode options (see opts)
encode(data, opts \\ [])
Transforms a EEP 18 format key/value list or map into a json string
Accepts encode options (see opts)
Examples
iex> term = %{langs: [%{elixir: %{beam: :true}}, %{erlang: %{beam: :true}}, %{rust: %{beam: :false}}]} iex> Eljiffy.encode(term) {:ok, ~s({"langs":[{"elixir":{"beam":true}},{"erlang":{"beam":true}},{"rust":{"beam":false}}]})}
iex> term = <<255>> iex> Eljiffy.encode(term) {:error, %ErlangError{original: {:invalid_string, <<255>>}}}
encode!(data, opts \\ [])
Transforms a EEP 18 format key/value list or map into a json string
Accepts encode options (see opts)
Examples
iex> term = %{langs: [%{elixir: %{beam: :true}}, %{erlang: %{beam: :true}}, %{rust: %{beam: :false}}]} iex> Eljiffy.encode!(term) ~s({"langs":[{"elixir":{"beam":true}},{"erlang":{"beam":true}},{"rust":{"beam":false}}]})