Module rustc_ap_serialize::json

JSON parsing and serialization

What is JSON?

JSON (JavaScript Object Notation) is a way to write data in Javascript. Like XML, it allows to encode structured data in a text format that can be easily read by humans Its simple syntax and native compatibility with JavaScript have made it a widely used format.

Data types that can be encoded are JavaScript types (see the Json enum for more details):

• Boolean: equivalent to rust's bool
• Number: equivalent to rust's f64
• String: equivalent to rust's String
• Array: equivalent to rust's Vec<T>, but also allowing objects of different types in the same array
• Object: equivalent to rust's BTreeMap<String, json::Json>
• Null

An object is a series of string keys mapping to values, in "key": value format. Arrays are enclosed in square brackets ([ ... ]) and objects in curly brackets ({ ... }). A simple JSON document encoding a person, their age, address and phone numbers could look like

{
    "FirstName": "John",
    "LastName": "Doe",
    "Age": 43,
    "Address": {
        "Street": "Downing Street 10",
        "City": "London",
        "Country": "Great Britain"
    },
    "PhoneNumbers": [
        "+44 1234567",
        "+44 2345678"
    ]
}

Rust Type-based Encoding and Decoding

Rust provides a mechanism for low boilerplate encoding & decoding of values to and from JSON via the serialization API. To be able to encode a piece of data, it must implement the serialize::RustcEncodable trait. To be able to decode a piece of data, it must implement the serialize::RustcDecodable trait. The Rust compiler provides an annotation to automatically generate the code for these traits: #[derive(RustcDecodable, RustcEncodable)]

The JSON API provides an enum json::Json and a trait ToJson to encode objects. The ToJson trait provides a to_json method to convert an object into a json::Json value. A json::Json value can be encoded as a string or buffer using the functions described above. You can also use the json::Encoder object, which implements the Encoder trait.

When using ToJson the RustcEncodable trait implementation is not mandatory.

Examples of use

Using Autoserialization

Create a struct called TestStruct and serialize and deserialize it to and from JSON using the serialization API, using the derived serialization code.

extern crate serialize as rustc_serialize; // for the deriving below
use rustc_serialize::json;

// Automatically generate `Decodable` and `Encodable` trait implementations
#[derive(RustcDecodable, RustcEncodable)]
pub struct TestStruct  {
    data_int: u8,
    data_str: String,
    data_vector: Vec<u8>,
}

fn main() {
    let object = TestStruct {
        data_int: 1,
        data_str: "homura".to_string(),
        data_vector: vec![2,3,4,5],
    };

    // Serialize using `json::encode`
    let encoded = json::encode(&object).unwrap();

    // Deserialize using `json::decode`
    let decoded: TestStruct = json::decode(&encoded[..]).unwrap();
}

Using the ToJson trait

The examples above use the ToJson trait to generate the JSON string, which is required for custom mappings.

Simple example of ToJson usage

extern crate serialize as rustc_serialize;
use rustc_serialize::json::{self, ToJson, Json};

// A custom data structure
struct ComplexNum {
    a: f64,
    b: f64,
}

// JSON value representation
impl ToJson for ComplexNum {
    fn to_json(&self) -> Json {
        Json::String(format!("{}+{}i", self.a, self.b))
    }
}

// Only generate `RustcEncodable` trait implementation
#[derive(RustcEncodable)]
pub struct ComplexNumRecord {
    uid: u8,
    dsc: String,
    val: Json,
}

fn main() {
    let num = ComplexNum { a: 0.0001, b: 12.539 };
    let data: String = json::encode(&ComplexNumRecord{
        uid: 1,
        dsc: "test".to_string(),
        val: num.to_json(),
    }).unwrap();
    println!("data: {}", data);
    // data: {"uid":1,"dsc":"test","val":"0.0001+12.539i"};
}

Verbose example of ToJson usage

extern crate serialize as rustc_serialize;
use std::collections::BTreeMap;
use rustc_serialize::json::{self, Json, ToJson};

// Only generate `RustcDecodable` trait implementation
#[derive(RustcDecodable)]
pub struct TestStruct {
    data_int: u8,
    data_str: String,
    data_vector: Vec<u8>,
}

// Specify encoding method manually
impl ToJson for TestStruct {
    fn to_json(&self) -> Json {
        let mut d = BTreeMap::new();
        // All standard types implement `to_json()`, so use it
        d.insert("data_int".to_string(), self.data_int.to_json());
        d.insert("data_str".to_string(), self.data_str.to_json());
        d.insert("data_vector".to_string(), self.data_vector.to_json());
        Json::Object(d)
    }
}

fn main() {
    // Serialize using `ToJson`
    let input_data = TestStruct {
        data_int: 1,
        data_str: "madoka".to_string(),
        data_vector: vec![2,3,4,5],
    };
    let json_obj: Json = input_data.to_json();
    let json_str: String = json_obj.to_string();

    // Deserialize like before
    let decoded: TestStruct = json::decode(&json_str).unwrap();
}

Structs

AsJson
AsPrettyJson
Builder	A Builder consumes a json::Parser to create a generic Json structure.
Decoder	A structure to decode JSON to values in rust.
Encoder	A structure for implementing serialization to JSON.
Parser	A streaming JSON parser implemented as an iterator of JsonEvent, consuming an iterator of char.
PrettyEncoder	Another encoder for JSON, but prints out human-readable JSON instead of compact data
PrettyJson
Stack	A Stack represents the current position of the parser in the logical structure of the JSON stream. For example foo.bar[3].x

Enums

DecoderError
EncoderError
ErrorCode	The errors that can arise while parsing a JSON stream.
Json	Represents a json value
JsonEvent	The output of the streaming parser.
ParserError
StackElement	StackElements compose a Stack. For example, StackElement::Key("foo"), StackElement::Key("bar"), StackElement::Index(3) and StackElement::Key("x") are the StackElements compositing the stack that represents foo.bar[3].x

Traits

ToJson

A trait for converting values to JSON

Functions

as_json	Creates an AsJson wrapper which can be used to print a value as JSON on-the-fly via write!
as_pretty_json	Creates an AsPrettyJson wrapper which can be used to print a value as JSON on-the-fly via write!
decode	Shortcut function to decode a JSON &str into an object
encode	Shortcut function to encode a T into a JSON String
error_str	Returns a readable error string for a given error code.
from_reader	Decodes a json value from an &mut io::Read
from_str	Decodes a json value from a string

Type Definitions

Array
BuilderError
DecodeResult
EncodeResult
Object