Report a bug
If you spot a problem with this page, click here to create a Bugzilla issue.
Improve this page
Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using a local clone.

std.json

JavaScript Object Notation

Synopsis:

    //parse a file or string of json into a usable structure
    string s = "{ \"language\": \"D\", \"rating\": 3.14, \"code\": \"42\" }";
    JSONValue j = parseJSON(s);
    writeln("Language: ", j["language"].str(),
            " Rating: ", j["rating"].floating()
    );

    // j and j["language"] return JSONValue,
    // j["language"].str returns a string

    //check a type
    long x;
    if (const(JSONValue)* code = "code" in j)
    {
        if (code.type() == JSON_TYPE.INTEGER)
            x = code.integer;
        else
            x = to!int(code.str);
    }

    // create a json struct
    JSONValue jj = [ "language": "D" ];
    // rating doesnt exist yet, so use .object to assign
    jj.object["rating"] = JSONValue(3.14);
    // create an array to assign to list
    jj.object["list"] = JSONValue( ["a", "b", "c"] );
    // list already exists, so .object optional
    jj["list"].array ~= JSONValue("D");

    s = j.toString();
    writeln(s);

Authors:
Jeremie Pelletier, David Herberth

References: http://json.org/

Source: std/json.d

enum JSONFloatLiteral: string;
String literals used to represent special float values within JSON strings.
nan
string representation of floating-point NaN
inf
string representation of floating-point Infinity
negativeInf
string representation of floating-point negative Infinity
enum JSONOptions: int;
Flags that control how json is encoded and parsed.
none
standard parsing
specialFloatLiterals
encode NaN and Inf float values as strings
enum JSON_TYPE: byte;
JSON type enumeration
NULL

STRING

INTEGER

UINTEGER

FLOAT

OBJECT

ARRAY

TRUE

FALSE
Indicates the type of a JSONValue.
struct JSONValue;
JSON value node
const pure nothrow @nogc @property @safe JSON_TYPE type();
Returns the JSON_TYPE of the value stored in this structure.
Examples:
string s = "{ \"language\": \"D\" }";
JSONValue j = parseJSON(s);
assert(j.type == JSON_TYPE.OBJECT);
assert(j["language"].type == JSON_TYPE.STRING);
inout pure @property inout(string) str();

pure nothrow @nogc @property string str(string v);
Value getter/setter for JSON_TYPE.STRING.
Throws:
JSONException for read access if type is not
JSON_TYPE.STRING.
Examples:
JSONValue j = [ "language": "D" ];

// get value
assert(j["language"].str == "D");

// change existing key to new string
j["language"].str = "Perl";
assert(j["language"].str == "Perl");
inout pure @property @safe inout(long) integer();

pure nothrow @nogc @property @safe long integer(long v);
Value getter/setter for JSON_TYPE.INTEGER.
Throws:
JSONException for read access if type is not
JSON_TYPE.INTEGER.
inout pure @property @safe inout(ulong) uinteger();

pure nothrow @nogc @property @safe ulong uinteger(ulong v);
Value getter/setter for JSON_TYPE.UINTEGER.
Throws:
JSONException for read access if type is not
JSON_TYPE.UINTEGER.
inout pure @property @safe inout(double) floating();

pure nothrow @nogc @property @safe double floating(double v);
Value getter/setter for JSON_TYPE.FLOAT.
Throws:
JSONException for read access if type is not
JSON_TYPE.FLOAT.
inout pure @property ref inout(JSONValue[string]) object();

pure nothrow @nogc @property JSONValue[string] object(JSONValue[string] v);
Value getter/setter for JSON_TYPE.OBJECT.
Throws:
JSONException for read access if type is not
JSON_TYPE.OBJECT.
inout pure @property ref inout(JSONValue[]) array();

pure nothrow @nogc @property JSONValue[] array(JSONValue[] v);
Value getter/setter for JSON_TYPE.ARRAY.
Throws:
JSONException for read access if type is not
JSON_TYPE.ARRAY.
const pure nothrow @nogc @property @safe bool isNull();
Test whether the type is JSON_TYPE.NULL
this(T)(T arg)
if (!isStaticArray!T);

this(T)(ref T arg)
if (isStaticArray!T);

inout this(T : JSONValue)(inout T arg);
Constructor for JSONValue. If arg is a JSONValue its value and type will be copied to the new JSONValue. Note that this is a shallow copy: if type is JSON_TYPE.OBJECT or JSON_TYPE.ARRAY then only the reference to the data will be copied. Otherwise, arg must be implicitly convertible to one of the following types: typeof(null), string, ulong, long, double, an associative array V[K] for any V and K i.e. a JSON object, any array or bool. The type will be set accordingly.
Examples:
JSONValue j = JSONValue( "a string" );
j = JSONValue(42);

j = JSONValue( [1, 2, 3] );
assert(j.type == JSON_TYPE.ARRAY);

j = JSONValue( ["language": "D"] );
assert(j.type == JSON_TYPE.OBJECT);
inout pure ref inout(JSONValue) opIndex(size_t i);
Array syntax for json arrays.
Throws:
JSONException if type is not JSON_TYPE.ARRAY.
Examples:
JSONValue j = JSONValue( [42, 43, 44] );
assert( j[0].integer == 42 );
assert( j[1].integer == 43 );
inout pure ref inout(JSONValue) opIndex(string k);
Hash syntax for json objects.
Throws:
JSONException if type is not JSON_TYPE.OBJECT.
Examples:
JSONValue j = JSONValue( ["language": "D"] );
assert( j["language"].str == "D" );
pure void opIndexAssign(T)(auto ref T value, string key);
Operator sets value for element of JSON object by key.
If JSON value is null, then operator initializes it with object and then
sets value for it.
Throws:
JSONException if type is not JSON_TYPE.OBJECT
or JSON_TYPE.NULL.
Examples:
JSONValue j = JSONValue( ["language": "D"] );
j["language"].str = "Perl";
assert( j["language"].str == "Perl" );
const auto opBinaryRight(string op : "in")(string k);
Support for the in operator.
Tests wether a key can be found in an object.
Returns:
when found, the const(JSONValue)* that matches to the key, otherwise null.
Throws:
JSONException if the right hand side argument JSON_TYPE is not OBJECT.
Examples:
JSONValue j = [ "language": "D", "author": "walter" ];
string a = ("author" in j).str;
int opApply(int delegate(size_t index, ref JSONValue) dg);
Implements the foreach opApply interface for json arrays.
int opApply(int delegate(string key, ref JSONValue) dg);
Implements the foreach opApply interface for json objects.
const string toString(in JSONOptions options = JSONOptions.none);
Implicitly calls toJSON on this JSONValue.
options can be used to tweak the conversion behavior.
const string toPrettyString(in JSONOptions options = JSONOptions.none);
Implicitly calls toJSON on this JSONValue, like toString, but
also passes true as pretty argument.
options can be used to tweak the conversion behavior
JSONValue parseJSON(T)(T json, int maxDepth = -1, JSONOptions options = JSONOptions.none)
if (isInputRange!T);
Parses a serialized string and returns a tree of JSON values.
Throws:
std.json.JSONException if the depth exceeds the max depth.
Parameters:
T json json-formatted string to parse
int maxDepth maximum depth of nesting allowed, -1 disables depth checking
JSONOptions options enable decoding string representations of NaN/Inf as float values
JSONValue parseJSON(T)(T json, JSONOptions options)
if (isInputRange!T);
Parses a serialized string and returns a tree of JSON values.
Throws:
std.json.JSONException if the depth exceeds the max depth.
Parameters:
T json json-formatted string to parse
JSONOptions options enable decoding string representations of NaN/Inf as float values
string toJSON(in JSONValue* root, in bool pretty = false, in JSONOptions options = JSONOptions.none);
Takes a tree of JSON values and returns the serialized string.
Any Object types will be serialized in a key-sorted order.
If pretty is false no whitespaces are generated. If pretty is true serialized string is formatted to be human-readable. Set the flag is set in options to encode NaN/Infinity as strings.
class JSONException: object.Exception;
Exception thrown on JSON errors