Menu

- Learn
- Documentation
  - Language Reference
  - Library Reference
  - Command-line Reference
  - Feature Overview
  - Articles
- Packages
- Community
  - Blog
  - Orgs using D
  - Twitter
  - Forums
  - IRC
  - Wiki
  - GitHub
  - Issues
- Resources
  - Books
  - Tutorials
  - Tools
  - Editors
  - IDEs
  - Visual D
  - Acknowledgments
  - D Style
  - Glossary
  - Sitemap

Search
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
License:
Boost License 1.0.
Authors:
Jeremie Pelletier, David Herberth

References: http://json.org/

Source: std/json.d

Examples:

    // parse a file or string of json into a usable structure
    string s = `{ "language": "D", "rating": 3.5, "code": "42" }`;
    JSONValue j = parseJSON(s);
    // j and j["language"] return JSONValue,
    // j["language"].str returns a string
    assert(j["language"].str == "D");
    assert(j["rating"].floating == 3.5);

    // 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.5);
    // 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");

    string jjStr = `{"language":"D","list":["a","b","c","D"],"rating":3.5}`;
    assert(jj.toString == jjStr);

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
  escapeNonAsciiChars
    encode non ascii characters with an unicode escape sequence
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);

  const pure @property @trusted string str();
  pure nothrow @nogc @property @safe 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. Note that despite
    the name, this is a 64-bit double, not a 32-bit float.
    Throws:
    JSONException for read access if type is not
    JSON_TYPE.FLOAT.
  inout pure @property ref @system inout(JSONValue[string]) object();
  pure nothrow @nogc @property @safe 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 @trusted inout(JSONValue[string]) objectNoRef();
    Value getter for JSON_TYPE.OBJECT.
    Unlike object, this retrieves the object by value and can be used in @safe code.
    A caveat is that, if the returned value is null, modifications will not be visible:

        JSONValue json;

        json.object = null;

        json.objectNoRef["hello"] = JSONValue("world");

        assert("hello" !in json.object);

    Throws:
    JSONException for read access if type is not
    JSON_TYPE.OBJECT.
  inout pure @property ref @system inout(JSONValue[]) array();
  pure nothrow @nogc @property @safe JSONValue[] array(JSONValue[] v);
    Value getter/setter for JSON_TYPE.ARRAY.
    Throws:
    JSONException for read access if type is not
    JSON_TYPE.ARRAY.
  inout pure @property @trusted inout(JSONValue[]) arrayNoRef();
    Value getter for JSON_TYPE.ARRAY.
    Unlike array, this retrieves the array by value and can be used in @safe code.
    A caveat is that, if you append to the returned array, the new values aren't visible in the

    JSONValue:

        JSONValue json;

        json.array = [JSONValue("hello")];

        json.arrayNoRef ~= JSONValue("world");

        assert(json.array.length == 1);

    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 @safe 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 @safe 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 @safe 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;

  @system int opApply(scope int delegate(size_t index, ref JSONValue) dg);
    Implements the foreach opApply interface for json arrays.
  @system int opApply(scope int delegate(string key, ref JSONValue) dg);
    Implements the foreach opApply interface for json objects.
  const @safe string toString(in JSONOptions options = JSONOptions.none);
    Implicitly calls toJSON on this JSONValue.
    options can be used to tweak the conversion behavior.
  const @safe 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:
  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

@safe string toJSON(ref const 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

Copyright Jeremie Pelletier 2008 - 2009. | Page generated by Ddoc on Wed Nov 30 12:04:51 2016