# Module jsone #
* [Description](#description)
* [Data Types](#types)
* [Function Index](#index)
* [Function Details](#functions)
JSON decoding/encoding module.
## Data Types ##
### datetime_encode_format() ###
datetime_encode_format() = datetime_format() | {Format::datetime_format(), TimeZone::timezone()}
Datetime encoding format.
The default value of `TimeZone` is `utc`.
```
%
% Universal Time
%
> jsone:encode({{2000, 3, 10}, {10, 3, 58}}, [{datetime_format, iso8601}]).
<<"\"2000-03-10T10:03:58Z\"">>
%
% Local Time (JST)
%
> jsone:encode({{2000, 3, 10}, {10, 3, 58}}, [{datetime_format, {iso8601, local}}]).
<<"\"2000-03-10T10:03:58+09:00\"">>
%
% Explicit TimeZone Offset
%
> jsone:encode({{2000, 3, 10}, {10, 3, 58}}, [{datetime_format, {iso8601, -2*60*60}}]).
<<"\"2000-03-10T10:03:58-02:00\"">>
```
### datetime_format() ###
datetime_format() = iso8601
### decode_option() ###
decode_option() = {object_format, tuple | proplist | map} | {allow_ctrl_chars, boolean()}
`object_format`:
- Decoded JSON object format
- `tuple`: An object is decoded as `{[]}` if it is empty, otherwise `{[{Key, Value}]}`.
- `proplist`: An object is decoded as `[{}]` if it is empty, otherwise `[{Key, Value}]`.
- `map`: An object is decoded as `#{}` if it is empty, otherwise `#{Key => Value}`.
- default: `map` if OTP version is OTP-17 or more, `tuple` otherwise
`allow_ctrl_chars`:
- If the value is `true`, strings which contain ununescaped control characters will be regarded as a legal JSON string
- default: `false`
### encode_option() ###
encode_option() = native_utf8 | {float_format, [float_format_option()]} | {datetime_format, datetime_encode_format()} | {object_key_type, string | scalar | value} | {space, non_neg_integer()} | {indent, non_neg_integer()}
`native_utf8`:
- Encodes UTF-8 characters as a human-readable(non-escaped) string
`{float_format, Optoins}`:
- Encodes a `float()` value in the format which specified by `Options`
- default: `[{scientific, 20}]`
`{datetime_format, Format}`:
- Encodes a `calendar:datetime()` value in the format which specified by `Format`
- default: `{iso8601, utc}`
`object_key_type`:
- Allowable object key type
- `string`: Only string values are allowed (i.e. `json_string()` type)
- `scalar`: In addition to `string`, following values are allowed: nulls, booleans, numerics (i.e. `json_scalar()` type)
- `value`: Any json compatible values are allowed (i.e. `json_value()` type)
- default: `string`
- NOTE: If `scalar` or `value` option is specified, non `json_string()` key will be automatically converted to a `binary()` value (e.g. `1` => `<<"1">>`, `#{}` => `<<"{}">>`)
`{space, N}`:
- Inserts `N` spaces after every commna and colon
- default: `0`
`{indent, N}`:
- Inserts a newline and `N` spaces for each level of indentation
- default: `0`
### float_format_option() ###
float_format_option() = {scientific, Decimals::0..249} | {decimals, Decimals::0..253} | compact
`scientific`:
- The float will be formatted using scientific notation with `Decimals` digits of precision.
`decimals`:
- The encoded string will contain at most `Decimals` number of digits past the decimal point.
- If `compact` is provided the trailing zeros at the end of the string are truncated.
For more details, see [erlang:flaot_to_list/2](http://erlang.org/doc/man/erlang.md#float_to_list-2).
```
> jsone:encode(1.23).
<<"1.22999999999999998224e+00">>
> jsone:encode(1.23, [{float_format, [{scientific, 4}]}]).
<"1.2300e+00">>
> jsone:encode(1.23, [{float_format, [{scientific, 1}]}]).
<<"1.2e+00">>
> jsone:encode(1.23, [{float_format, [{decimals, 4}]}]).
<<"1.2300">>
> jsone:encode(1.23, [{float_format, [{decimals, 4}, compact]}]).
<<"1.23">>
```
### json_array() ###
json_array() = [json_value()]
### json_boolean() ###
json_boolean() = boolean()
### json_number() ###
json_number() = number()
### json_object() ###
json_object() = json_object_format_tuple() | json_object_format_proplist() | json_object_format_map()
### json_object_format_map() ###
json_object_format_map() = #{}
### json_object_format_proplist() ###
json_object_format_proplist() = [{}] | json_object_members()
### json_object_format_tuple() ###
json_object_format_tuple() = {json_object_members()}
### json_object_members() ###
json_object_members() = [{json_string(), json_value()}]
### json_scalar() ###
json_scalar() = json_boolean() | json_number() | json_string()
### json_string() ###
json_string() = binary() | atom() | calendar:datetime()
NOTE: `decode/1` always returns `binary()` value
### json_value() ###
json_value() = json_number() | json_string() | json_array() | json_object() | json_boolean() | null
### timezone() ###
timezone() = utc | local | utc_offset_seconds()
### utc_offset_seconds() ###
utc_offset_seconds() = -86399..86399
## Function Index ##
## Function Details ##
### decode/1 ###
decode(Json::binary()) -> json_value()
Equivalent to [`decode(Json, [])`](#decode-2).
### decode/2 ###
decode(Json::binary(), Options::[decode_option()]) -> json_value()
Decodes an erlang term from json text (a utf8 encoded binary)
Raises an error exception if input is not valid json
```
> jsone:decode(<<"1">>, []).
1
> jsone:decode(<<"wrong json">>, []).
** exception error: bad argument
in function jsone_decode:number_integer_part/4
called as jsone_decode:number_integer_part(<<"wrong json">>,1,[],<<>>)
in call from jsone:decode/1 (src/jsone.erl, line 71)
```
### encode/1 ###
encode(JsonValue::json_value()) -> binary()
Equivalent to [`encode(JsonValue, [])`](#encode-2).
### encode/2 ###
encode(JsonValue::json_value(), Options::[encode_option()]) -> binary()
Encodes an erlang term into json text (a utf8 encoded binary)
Raises an error exception if input is not an instance of type `json_value()`
```
> jsone:encode([1, null, 2]).
<<"[1,null,2]">>
> jsone:encode([1, hoge, 2]). % 'hoge' atom is not a json value
** exception error: bad argument
in function jsone_encode:value/3
called as jsone_encode:value(hoge,[{array_values,[2]}],<<"[1,">>)
in call from jsone:encode/1 (src/jsone.erl, line 97)
```
### try_decode/1 ###
try_decode(Json::binary()) -> {ok, json_value(), Remainings::binary()} | {error, {Reason::term(), [erlang:stack_item()]}}
Equivalent to [`try_decode(Json, [])`](#try_decode-2).
### try_decode/2 ###
try_decode(Json::binary(), Options::[decode_option()]) -> {ok, json_value(), Remainings::binary()} | {error, {Reason::term(), [erlang:stack_item()]}}
Decodes an erlang term from json text (a utf8 encoded binary)
```
> jsone:try_decode(<<"[1,2,3] \"next value\"">>, []).
{ok,[1,2,3],<<" \"next value\"">>}
> jsone:try_decode(<<"wrong json">>, []).
{error,{badarg,[{jsone_decode,number_integer_part,
[<<"wrong json">>,1,[],<<>>],
[{line,208}]}]}}
```
### try_encode/1 ###
try_encode(JsonValue::json_value()) -> {ok, binary()} | {error, {Reason::term(), [erlang:stack_item()]}}
Equivalent to [`try_encode(JsonValue, [])`](#try_encode-2).
### try_encode/2 ###
try_encode(JsonValue::json_value(), Options::[encode_option()]) -> {ok, binary()} | {error, {Reason::term(), [erlang:stack_item()]}}
Encodes an erlang term into json text (a utf8 encoded binary)
```
> jsone:try_encode([1, null, 2]).
{ok,<<"[1,null,2]">>}
> jsone:try_encode([1, hoge, 2]). % 'hoge' atom is not a json value
{error,{badarg,[{jsone_encode,value,
[hoge,[{array_values,[2]}],<<"[1,">>],
[{line,86}]}]}}
```