Module serialize::json [−] [src]

Unstable (rustc_private)
: deprecated in favor of rustc-serialize on crates.io

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

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

{
    "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.

#![feature(rustc_private)] 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(); }

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

#![feature(rustc_private)] extern crate serialize; use 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(Encodable)] 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"}; }

extern crate serialize;
use 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(Encodable)]
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

#![feature(rustc_private)] extern crate serialize; use std::collections::BTreeMap; use serialize::json::{self, Json, ToJson}; // Only generate `Decodable` trait implementation #[derive(Decodable)] 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(); }

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

// Only generate `Decodable` trait implementation
#[derive(Decodable)]
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	[Unstable]
AsPrettyJson	[Unstable]
Builder	[Unstable] A Builder consumes a json::Parser to create a generic Json structure.
Decoder	[Unstable] A structure to decode JSON to values in rust.
Encoder	[Unstable] A structure for implementing serialization to JSON.
Parser	[Unstable] A streaming JSON parser implemented as an iterator of JsonEvent, consuming an iterator of char.
PrettyEncoder	[Unstable] Another encoder for JSON, but prints out human-readable JSON instead of compact data
PrettyJson	[Unstable]
Stack	[Unstable] 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	[Unstable]
EncoderError	[Unstable]
ErrorCode	[Unstable] The errors that can arise while parsing a JSON stream.
Json	[Unstable] Represents a json value
JsonEvent	[Unstable] The output of the streaming parser.
ParserError	[Unstable]
StackElement	[Unstable] 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

[Unstable]

A trait for converting values to JSON

Functions

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

Type Definitions

Array	[Unstable]
BuilderError	[Unstable]
DecodeResult	[Unstable]
EncodeResult	[Unstable]
Object	[Unstable]