[][src]Module 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();
}Run

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;
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"};
}Run

Verbose example of ToJson usage

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

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