1# Serde CBOR
2[![Build Status](https://travis-ci.org/pyfisch/cbor.svg?branch=master)](https://travis-ci.org/pyfisch/cbor)
3[![Crates.io](https://img.shields.io/crates/v/serde_cbor.svg)](https://crates.io/crates/serde_cbor)
4[![Documentation](https://docs.rs/serde_cbor/badge.svg)](https://docs.rs/serde_cbor)
5
6## PROJECT IS ARCHIVED
7
8After almost 6 years it is time to retire this crate.
9This implementation of CBOR for serde is used in hundreds of projects with widely differing needs.
10Besides the standard features it contains code for no-std environments, a packed encoding and CBOR tags.
11However while these features are useful to many people they sometimes interact poorly with each others and with optional features of serde itself.
12Because I don't use the crate myself and because of the potential for new errors I have been reluctant to accept any changes or additional features for the crate.
13Since this situation is unlikely to change anytime soon and no one else stepped up to maintain this crate I am archiving the repository today.
14If the crate works for you there is no need to switch to another implementation.
15However if you encounter problems or for new projects I recommend you take a look at these crates:
16
17* [ciborium](https://crates.io/crates/ciborium)
18* [minicbor](https://crates.io/crates/minicbor)
19
20~~ Pyfisch, August 2021
21
22
23
24This crate implements the Concise Binary Object Representation from [RFC 7049].
25It builds on [Serde], the generic serialization framework for Rust.
26CBOR provides a binary encoding for a superset
27of the JSON data model that is small and very fast to parse.
28
29[RFC 7049]: https://tools.ietf.org/html/rfc7049
30[Serde]: https://github.com/serde-rs/serde
31
32## Usage
33
34Serde CBOR supports Rust 1.40 and up. Add this to your `Cargo.toml`:
35```toml
36[dependencies]
37serde_cbor = "0.11.2"
38```
39
40Storing and loading Rust types is easy and requires only
41minimal modifications to the program code.
42
43```rust
44use serde_derive::{Deserialize, Serialize};
45use std::error::Error;
46use std::fs::File;
47
48// Types annotated with `Serialize` can be stored as CBOR.
49// To be able to load them again add `Deserialize`.
50#[derive(Debug, Serialize, Deserialize)]
51struct Mascot {
52    name: String,
53    species: String,
54    year_of_birth: u32,
55}
56
57fn main() -> Result<(), Box<dyn Error>> {
58    let ferris = Mascot {
59        name: "Ferris".to_owned(),
60        species: "crab".to_owned(),
61        year_of_birth: 2015,
62    };
63
64    let ferris_file = File::create("examples/ferris.cbor")?;
65    // Write Ferris to the given file.
66    // Instead of a file you can use any type that implements `io::Write`
67    // like a HTTP body, database connection etc.
68    serde_cbor::to_writer(ferris_file, &ferris)?;
69
70    let tux_file = File::open("examples/tux.cbor")?;
71    // Load Tux from a file.
72    // Serde CBOR performs roundtrip serialization meaning that
73    // the data will not change in any way.
74    let tux: Mascot = serde_cbor::from_reader(tux_file)?;
75
76    println!("{:?}", tux);
77    // prints: Mascot { name: "Tux", species: "penguin", year_of_birth: 1996 }
78
79    Ok(())
80}
81```
82
83There are a lot of options available to customize the format.
84To operate on untyped CBOR values have a look at the `Value` type.
85
86## License
87Licensed under either of
88
89 * Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
90 * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
91
92at your option.
93
94### Contribution
95Unless you explicitly state otherwise, any contribution intentionally submitted
96for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any
97additional terms or conditions.
98