[][src]Module fast_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
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(),
    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
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());

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();



A Builder consumes a json::Parser to create a generic Json structure.


A structure to decode JSON to values in rust.


A structure for implementing serialization to JSON.


A streaming JSON parser implemented as an iterator of JsonEvent, consuming an iterator of char.


Another encoder for JSON, but prints out human-readable JSON instead of compact data


A Stack represents the current position of the parser in the logical structure of the JSON stream. For example foo.bar[3].x



The errors that can arise while parsing a JSON stream.


Represents a json value


The output of the streaming parser.


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



A trait for converting values to JSON



Creates an AsJson wrapper which can be used to print a value as JSON on-the-fly via write!


Creates an AsPrettyJson wrapper which can be used to print a value as JSON on-the-fly via write!


Shortcut function to decode a JSON &str into an object


Shortcut function to encode a T into a JSON String


Returns a readable error string for a given error code.


Decodes a json value from an &mut io::Read


Decodes a json value from a string

Type Definitions