# Module jsone #
* [Description](#description)
* [Data Types](#types)
* [Function Index](#index)
* [Function Details](#functions)

JSON decoding/encoding module.

<a name="types"></a>

## Data Types ##




### <a name="type-decode_option">decode_option()</a> ###


<pre><code>
decode_option() = {object_format, tuple | proplist | map}
</code></pre>

 object_format: <br />
- Decoded JSON object format <br />
- `tuple`: An object is decoded as `{[]}` if it is empty, otherwise `{[{Key, Value}]}`. <br />
- `proplist`: An object is decoded as `[{}]` if it is empty, otherwise `[{Key, Value}]`. <br />
- `map`: An object is decoded as `#{}` if it is empty, otherwise `#{Key => Value}`. <br />
- default: `map` <br />



### <a name="type-encode_option">encode_option()</a> ###


<pre><code>
encode_option() = native_utf8 | {float_format, [<a href="#type-float_format_option">float_format_option()</a>]} | {object_key_type, string | scalar | value} | {space, non_neg_integer()} | {indent, non_neg_integer()}
</code></pre>

`native_utf8`: <br />
- Encodes UTF-8 characters as a human-readable(non-escaped) string <br />

`{float_format, Optoins}`:
- Encodes a `float()` value in the format which specified by `Options` <br />
- default: `[{scientific, 20}]` <br />

`object_key_type`:
- Allowable object key type <br />
- `string`: Only string values are allowed (i.e. `json_string()` type) <br />
- `scalar`: In addition to `string`, following values are allowed: nulls, booleans, numerics (i.e. `json_scalar()` type) <br />
- `value`: Any json compatible values are allowed (i.e. `json_value()` type) <br />
- default: `string` <br />
- NOTE: If `scalar` or `value` option is specified, non `json_string()` key will be automatically converted to a `binary()` value (e.g. `1` => `<<"1">>`, `#{}` => `<<"{}">>`) <br />

`{space, N}`: <br />
- Inserts `N` spaces after every commna and colon <br />
- default: `0` <br />

`{indent, N}`: <br />
- Inserts a newline and `N` spaces for each level of indentation <br />
- default: `0` <br />



### <a name="type-float_format_option">float_format_option()</a> ###


<pre><code>
float_format_option() = {scientific, Decimals::0..249} | {decimals, Decimals::0..253} | compact
</code></pre>

`scientific`: <br />
- The float will be formatted using scientific notation with `Decimals` digits of precision. <br />

`decimals`: <br />
- The encoded string will contain at most `Decimals` number of digits past the decimal point. <br />
- If `compact` is provided the trailing zeros at the end of the string are truncated. <br />

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">>
```



### <a name="type-json_array">json_array()</a> ###


<pre><code>
json_array() = [<a href="#type-json_value">json_value()</a>]
</code></pre>




### <a name="type-json_boolean">json_boolean()</a> ###


<pre><code>
json_boolean() = boolean()
</code></pre>




### <a name="type-json_number">json_number()</a> ###


<pre><code>
json_number() = number()
</code></pre>




### <a name="type-json_object">json_object()</a> ###


<pre><code>
json_object() = <a href="#type-json_object_format_tuple">json_object_format_tuple()</a> | <a href="#type-json_object_format_proplist">json_object_format_proplist()</a> | <a href="#type-json_object_format_map">json_object_format_map()</a>
</code></pre>




### <a name="type-json_object_format_map">json_object_format_map()</a> ###


<pre><code>
json_object_format_map() = #{}
</code></pre>




### <a name="type-json_object_format_proplist">json_object_format_proplist()</a> ###


<pre><code>
json_object_format_proplist() = [{}] | <a href="#type-json_object_members">json_object_members()</a>
</code></pre>




### <a name="type-json_object_format_tuple">json_object_format_tuple()</a> ###


<pre><code>
json_object_format_tuple() = {<a href="#type-json_object_members">json_object_members()</a>}
</code></pre>




### <a name="type-json_object_members">json_object_members()</a> ###


<pre><code>
json_object_members() = [{<a href="#type-json_string">json_string()</a>, <a href="#type-json_value">json_value()</a>}]
</code></pre>




### <a name="type-json_scalar">json_scalar()</a> ###


<pre><code>
json_scalar() = <a href="#type-json_boolean">json_boolean()</a> | <a href="#type-json_number">json_number()</a> | <a href="#type-json_string">json_string()</a>
</code></pre>




### <a name="type-json_string">json_string()</a> ###


<pre><code>
json_string() = binary() | atom()
</code></pre>

NOTE: `decode/1` always returns `binary()` value



### <a name="type-json_value">json_value()</a> ###


<pre><code>
json_value() = <a href="#type-json_number">json_number()</a> | <a href="#type-json_string">json_string()</a> | <a href="#type-json_array">json_array()</a> | <a href="#type-json_object">json_object()</a> | <a href="#type-json_boolean">json_boolean()</a> | null
</code></pre>

<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#decode-1">decode/1</a></td><td>Equivalent to <a href="#decode-2"><tt>decode(Json, [])</tt></a>.</td></tr><tr><td valign="top"><a href="#decode-2">decode/2</a></td><td>Decodes an erlang term from json text (a utf8 encoded binary).</td></tr><tr><td valign="top"><a href="#encode-1">encode/1</a></td><td>Equivalent to <a href="#encode-2"><tt>encode(JsonValue, [])</tt></a>.</td></tr><tr><td valign="top"><a href="#encode-2">encode/2</a></td><td>Encodes an erlang term into json text (a utf8 encoded binary).</td></tr><tr><td valign="top"><a href="#try_decode-1">try_decode/1</a></td><td>Equivalent to <a href="#try_decode-2"><tt>try_decode(Json, [])</tt></a>.</td></tr><tr><td valign="top"><a href="#try_decode-2">try_decode/2</a></td><td>Decodes an erlang term from json text (a utf8 encoded binary).</td></tr><tr><td valign="top"><a href="#try_encode-1">try_encode/1</a></td><td>Equivalent to <a href="#try_encode-2"><tt>try_encode(JsonValue, [])</tt></a>.</td></tr><tr><td valign="top"><a href="#try_encode-2">try_encode/2</a></td><td>Encodes an erlang term into json text (a utf8 encoded binary).</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="decode-1"></a>

### decode/1 ###

<pre><code>
decode(Json::binary()) -&gt; <a href="#type-json_value">json_value()</a>
</code></pre>
<br />

Equivalent to [`decode(Json, [])`](#decode-2).

<a name="decode-2"></a>

### decode/2 ###

<pre><code>
decode(Json::binary(), Options::[<a href="#type-decode_option">decode_option()</a>]) -&gt; <a href="#type-json_value">json_value()</a>
</code></pre>
<br />

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)
```

<a name="encode-1"></a>

### encode/1 ###

<pre><code>
encode(JsonValue::<a href="#type-json_value">json_value()</a>) -&gt; binary()
</code></pre>
<br />

Equivalent to [`encode(JsonValue, [])`](#encode-2).

<a name="encode-2"></a>

### encode/2 ###

<pre><code>
encode(JsonValue::<a href="#type-json_value">json_value()</a>, Options::[<a href="#type-encode_option">encode_option()</a>]) -&gt; binary()
</code></pre>
<br />

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)
```

<a name="try_decode-1"></a>

### try_decode/1 ###

<pre><code>
try_decode(Json::binary()) -&gt; {ok, <a href="#type-json_value">json_value()</a>, Remainings::binary()} | {error, {Reason::term(), [<a href="erlang.md#type-stack_item">erlang:stack_item()</a>]}}
</code></pre>
<br />

Equivalent to [`try_decode(Json, [])`](#try_decode-2).

<a name="try_decode-2"></a>

### try_decode/2 ###

<pre><code>
try_decode(Json::binary(), Options::[<a href="#type-decode_option">decode_option()</a>]) -&gt; {ok, <a href="#type-json_value">json_value()</a>, Remainings::binary()} | {error, {Reason::term(), [<a href="erlang.md#type-stack_item">erlang:stack_item()</a>]}}
</code></pre>
<br />

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}]}]}}
```

<a name="try_encode-1"></a>

### try_encode/1 ###

<pre><code>
try_encode(JsonValue::<a href="#type-json_value">json_value()</a>) -&gt; {ok, binary()} | {error, {Reason::term(), [<a href="erlang.md#type-stack_item">erlang:stack_item()</a>]}}
</code></pre>
<br />

Equivalent to [`try_encode(JsonValue, [])`](#try_encode-2).

<a name="try_encode-2"></a>

### try_encode/2 ###

<pre><code>
try_encode(JsonValue::<a href="#type-json_value">json_value()</a>, Options::[<a href="#type-encode_option">encode_option()</a>]) -&gt; {ok, binary()} | {error, {Reason::term(), [<a href="erlang.md#type-stack_item">erlang:stack_item()</a>]}}
</code></pre>
<br />

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}]}]}}
```