1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

//! CBOR and serialization.
//!
//! # What is CBOR?
//! [CBOR](http://cbor.io) is a way to encode data in a space-efficient and fast binary format.
//! CBORs data-model is a superset of the JSONs.
//!
//! A simple object describing a person in diagnostic notation (it is actually JSON plus some
//! annotations) looks like
//!
//! ```json
//! {
//!     "FirstName": "John",
//!     "LastName": "Doe",
//!     "Age": 43,
//!     "Address": {
//!         "Street": "Downing Street 10",
//!         "City": "London",
//!         "Country": "Great Britain"
//!     },
//!     "PhoneNumbers": [
//!         "+44 1234567",
//!         "+44 2345678"
//!     ]
//! }
//! ```
//!
//! The CBOR encoded object with comments in hexadecimal notation looks like
//!
//! ```cbor
//! a5                                      # map(5)
//!    69                                   # text(9)
//!       46697273744e616d65                # "FirstName"
//!    64                                   # text(4)
//!       4a6f686e                          # "John"
//!    68                                   # text(8)
//!       4c6173744e616d65                  # "LastName"
//!    63                                   # text(3)
//!       446f65                            # "Doe"
//!    63                                   # text(3)
//!       416765                            # "Age"
//!    18 2b                                # unsigned(43)
//!    67                                   # text(7)
//!       41646472657373                    # "Address"
//!    a3                                   # map(3)
//!       66                                # text(6)
//!          537472656574                   # "Street"
//!       71                                # text(17)
//!          446f776e696e6720537472656574203130 # "Downing Street 10"
//!       64                                # text(4)
//!          43697479                       # "City"
//!       66                                # text(6)
//!          4c6f6e646f6e                   # "London"
//!       67                                # text(7)
//!          436f756e747279                 # "Country"
//!       6d                                # text(13)
//!          4772656174204272697461696e     # "Great Britain"
//!    6c                                   # text(12)
//!       50686f6e654e756d62657273          # "PhoneNumbers"
//!    82                                   # array(2)
//!       6b                                # text(11)
//!          2b34342031323334353637         # "+44 1234567"
//!       6b                                # text(11)
//!          2b34342032333435363738         # "+44 2345678"
//! ```
//! While the JSON encoding is 174 bytes long the CBOR representation is only 141 bytes long.
//! This is 19% shorter! Sometimes compression will even better, but never CBOR will be longer
//! than the corresponding JSON. More importantly CBOR supports binary data, custom data tyes,
//! annotations for dates, times and expected encoding and is faster to serialize and deserialize.
//! It can even be used on embedded devices.
//!
//! # Type-based Serialization and Deserialization
//! Serde provides a mechanism for low boilerplate serialization & deserialization of values to and
//! from CBOR via the serialization API. To be able to serialize a piece of data, it must implement
//! the serde::Serialize trait. To be able to deserialize a piece of data, it must implement the
//! serde::Deserialize trait. Serde provides provides an annotation to automatically generate the
//! code for these traits: #[derive(Serialize, Deserialize)].
//!
//! The CBOR API also provides an enum serde_cbor::Value
//!
//! # Examples
//! Read a CBOR value that is known to be a map of string keys to string values and print it.
//!
//! ```rust
//! use std::collections::HashMap;
//! use serde_cbor::from_slice;
//!
//! let slice = b"\xa5aaaAabaBacaCadaDaeaE";
//! let value: HashMap<String, String> = from_slice(slice).unwrap();
//! println!("{:?}", value); // {"e": "E", "d": "D", "a": "A", "c": "C", "b": "B"}
//! ```
//!
//! Read a general CBOR value with an unknown content.
//!
//! ```rust
//! use serde_cbor::{from_slice, Value};
//!
//! let slice = b"\x82\x01\xa1aaab";
//! let value: Value = from_slice(slice).unwrap();
//! println!("{:?}", value); // Array([U64(1), Object({String("a"): String("b")})])
//! ```
//!
//! Serialize an object.
//!
//! ```rust
//! use std::collections::HashMap;
//! use serde_cbor::to_vec;
//!
//! let mut programming_languages = HashMap::new();
//! programming_languages.insert("rust", vec!["safe", "concurrent", "fast"]);
//! programming_languages.insert("python", vec!["powerful", "friendly", "open"]);
//! programming_languages.insert("js", vec!["lightweight", "interpreted", "object-oriented"]);
//! let encoded = to_vec(&programming_languages);
//! ```

#![deny(missing_docs)]

extern crate byteorder;
extern crate serde;

pub use de::{from_slice, from_reader};
pub use error::{Error, Result};
pub use ser::to_vec;
pub use value::{Value, ObjectKey};

pub mod de;
pub mod error;
pub mod ser;
pub mod value;