346 lines
No EOL
19 KiB
HTML
346 lines
No EOL
19 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<meta name="generator" content="rustdoc">
|
||
<meta name="description" content="API documentation for the Rust `serde_cbor` crate.">
|
||
<meta name="keywords" content="rust, rustlang, rust-lang, serde_cbor">
|
||
|
||
<title>serde_cbor - Rust</title>
|
||
|
||
<link rel="stylesheet" type="text/css" href="../normalize.css">
|
||
<link rel="stylesheet" type="text/css" href="../rustdoc.css" id="mainThemeStyle">
|
||
|
||
<link rel="stylesheet" type="text/css" href="../dark.css">
|
||
<link rel="stylesheet" type="text/css" href="../main.css" id="themeStyle">
|
||
<script src="../storage.js"></script>
|
||
|
||
|
||
|
||
|
||
</head>
|
||
<body class="rustdoc mod">
|
||
<!--[if lte IE 8]>
|
||
<div class="warning">
|
||
This old browser is unsupported and will most likely display funky
|
||
things.
|
||
</div>
|
||
<![endif]-->
|
||
|
||
|
||
|
||
<nav class="sidebar">
|
||
<div class="sidebar-menu">☰</div>
|
||
|
||
<p class='location'>Crate serde_cbor</p><div class="sidebar-elems"><div class="block items"><ul><li><a href="#modules">Modules</a></li><li><a href="#structs">Structs</a></li><li><a href="#enums">Enums</a></li><li><a href="#functions">Functions</a></li></ul></div><p class='location'></p><script>window.sidebarCurrent = {name: 'serde_cbor', ty: 'mod', relpath: '../'};</script></div>
|
||
</nav>
|
||
|
||
<div class="theme-picker">
|
||
<button id="theme-picker" aria-label="Pick another theme!">
|
||
<img src="../brush.svg" width="18" alt="Pick another theme!">
|
||
</button>
|
||
<div id="theme-choices"></div>
|
||
</div>
|
||
<script src="../theme.js"></script>
|
||
<nav class="sub">
|
||
<form class="search-form js-only">
|
||
<div class="search-container">
|
||
<input class="search-input" name="search"
|
||
autocomplete="off"
|
||
placeholder="Click or press ‘S’ to search, ‘?’ for more options…"
|
||
type="search">
|
||
</div>
|
||
</form>
|
||
</nav>
|
||
|
||
<section id='main' class="content">
|
||
<h1 class='fqn'><span class='in-band'>Crate <a class="mod" href=''>serde_cbor</a></span><span class='out-of-band'><span id='render-detail'>
|
||
<a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">
|
||
[<span class='inner'>−</span>]
|
||
</a>
|
||
</span><a class='srclink' href='../src/serde_cbor/lib.rs.html#1-147' title='goto source code'>[src]</a></span></h1>
|
||
<div class='docblock'><p>CBOR and serialization.</p>
|
||
<h1 id="what-is-cbor" class="section-header"><a href="#what-is-cbor">What is CBOR?</a></h1>
|
||
<p><a href="http://cbor.io">CBOR</a> is a way to encode data in a space-efficient and fast binary format.
|
||
CBORs data-model is a superset of the JSONs.</p>
|
||
<p>A simple object describing a person in diagnostic notation (it is actually JSON plus some
|
||
annotations) looks like</p>
|
||
<pre><code class="language-json">{
|
||
"FirstName": "John",
|
||
"LastName": "Doe",
|
||
"Age": 43,
|
||
"Address": {
|
||
"Street": "Downing Street 10",
|
||
"City": "London",
|
||
"Country": "Great Britain"
|
||
},
|
||
"PhoneNumbers": [
|
||
"+44 1234567",
|
||
"+44 2345678"
|
||
]
|
||
}
|
||
</code></pre>
|
||
<p>The CBOR encoded object with comments in hexadecimal notation looks like</p>
|
||
<pre><code class="language-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"
|
||
</code></pre>
|
||
<p>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.</p>
|
||
<h1 id="type-based-serialization-and-deserialization" class="section-header"><a href="#type-based-serialization-and-deserialization">Type-based Serialization and Deserialization</a></h1>
|
||
<p>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 <code>serde::Serialize</code> trait. To be able to deserialize a piece of data, it must implement the
|
||
<code>serde::Deserialize</code> trait. Serde provides an annotation to automatically generate the
|
||
code for these traits: <code>#[derive(Serialize, Deserialize)]</code>.</p>
|
||
<p>The CBOR API also provides an enum <code>serde_cbor::Value</code>.</p>
|
||
<h1 id="packed-encoding" class="section-header"><a href="#packed-encoding">Packed Encoding</a></h1>
|
||
<p>When serializing structs or enums in CBOR the keys or enum variant names will be serialized
|
||
as string keys to a map. Esspecially in embedded environments this can increase the file
|
||
size too much. In packed encoding the keys and variants will be serialized as variable sized
|
||
integers. The first 24 entries in any struct consume only a single byte!
|
||
To serialize a document in packed encoding use <code>ser::to_(vec|writer)_packed</code>, deserialization
|
||
works without any changes.</p>
|
||
<h1 id="self-describing-documents" class="section-header"><a href="#self-describing-documents">Self describing documents</a></h1>
|
||
<p>In some contexts different formats are used but there is no way to declare the format used
|
||
out of band. For this reason CBOR has a magic number that may be added before any document.
|
||
The <em><code>_sd</code> (for <em>s</em>elf</em>d*escribe) append the magic number before documents.</p>
|
||
<h1 id="examples" class="section-header"><a href="#examples">Examples</a></h1>
|
||
<p>Read a CBOR value that is known to be a map of string keys to string values and print it.</p>
|
||
|
||
<pre class="rust rust-example-rendered">
|
||
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">collections</span>::<span class="ident">BTreeMap</span>;
|
||
<span class="kw">use</span> <span class="ident">serde_cbor</span>::<span class="ident">from_slice</span>;
|
||
|
||
<span class="kw">let</span> <span class="ident">slice</span> <span class="op">=</span> <span class="string">b"\xa5aaaAabaBacaCadaDaeaE"</span>;
|
||
<span class="kw">let</span> <span class="ident">value</span>: <span class="ident">BTreeMap</span><span class="op"><</span><span class="ident">String</span>, <span class="ident">String</span><span class="op">></span> <span class="op">=</span> <span class="ident">from_slice</span>(<span class="ident">slice</span>).<span class="ident">unwrap</span>();
|
||
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"{:?}"</span>, <span class="ident">value</span>); <span class="comment">// {"e": "E", "d": "D", "a": "A", "c": "C", "b": "B"}</span></pre>
|
||
<p>Read a general CBOR value with an unknown content.</p>
|
||
|
||
<pre class="rust rust-example-rendered">
|
||
<span class="kw">use</span> <span class="ident">serde_cbor</span>::{<span class="ident">from_slice</span>, <span class="ident">Value</span>};
|
||
|
||
<span class="kw">let</span> <span class="ident">slice</span> <span class="op">=</span> <span class="string">b"\x82\x01\xa1aaab"</span>;
|
||
<span class="kw">let</span> <span class="ident">value</span>: <span class="ident">Value</span> <span class="op">=</span> <span class="ident">from_slice</span>(<span class="ident">slice</span>).<span class="ident">unwrap</span>();
|
||
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"{:?}"</span>, <span class="ident">value</span>); <span class="comment">// Array([U64(1), Object({String("a"): String("b")})])</span></pre>
|
||
<p>Serialize an object.</p>
|
||
|
||
<pre class="rust rust-example-rendered">
|
||
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">collections</span>::<span class="ident">BTreeMap</span>;
|
||
<span class="kw">use</span> <span class="ident">serde_cbor</span>::<span class="ident">to_vec</span>;
|
||
|
||
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">programming_languages</span> <span class="op">=</span> <span class="ident">BTreeMap</span>::<span class="ident">new</span>();
|
||
<span class="ident">programming_languages</span>.<span class="ident">insert</span>(<span class="string">"rust"</span>, <span class="macro">vec</span><span class="macro">!</span>[<span class="string">"safe"</span>, <span class="string">"concurrent"</span>, <span class="string">"fast"</span>]);
|
||
<span class="ident">programming_languages</span>.<span class="ident">insert</span>(<span class="string">"python"</span>, <span class="macro">vec</span><span class="macro">!</span>[<span class="string">"powerful"</span>, <span class="string">"friendly"</span>, <span class="string">"open"</span>]);
|
||
<span class="ident">programming_languages</span>.<span class="ident">insert</span>(<span class="string">"js"</span>, <span class="macro">vec</span><span class="macro">!</span>[<span class="string">"lightweight"</span>, <span class="string">"interpreted"</span>, <span class="string">"object-oriented"</span>]);
|
||
<span class="kw">let</span> <span class="ident">encoded</span> <span class="op">=</span> <span class="ident">to_vec</span>(<span class="kw-2">&</span><span class="ident">programming_languages</span>);
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">encoded</span>.<span class="ident">unwrap</span>().<span class="ident">len</span>(), <span class="number">103</span>);</pre>
|
||
</div><h2 id='modules' class='section-header'><a href="#modules">Modules</a></h2>
|
||
<table>
|
||
<tr class=' module-item'>
|
||
<td><a class="mod" href="de/index.html"
|
||
title='mod serde_cbor::de'>de</a></td>
|
||
<td class='docblock-short'>
|
||
<p>Deserialization.</p>
|
||
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="mod" href="error/index.html"
|
||
title='mod serde_cbor::error'>error</a></td>
|
||
<td class='docblock-short'>
|
||
<p>When serializing or deserializing CBOR goes wrong.</p>
|
||
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="mod" href="ser/index.html"
|
||
title='mod serde_cbor::ser'>ser</a></td>
|
||
<td class='docblock-short'>
|
||
<p>Serialize a Rust data structure to CBOR data.</p>
|
||
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="mod" href="value/index.html"
|
||
title='mod serde_cbor::value'>value</a></td>
|
||
<td class='docblock-short'>
|
||
<p>CBOR values, keys and serialization routines.</p>
|
||
|
||
</td>
|
||
</tr></table><h2 id='structs' class='section-header'><a href="#structs">Structs</a></h2>
|
||
<table>
|
||
<tr class=' module-item'>
|
||
<td><a class="struct" href="struct.Deserializer.html"
|
||
title='struct serde_cbor::Deserializer'>Deserializer</a></td>
|
||
<td class='docblock-short'>
|
||
<p>A Serde <code>Deserialize</code>r of CBOR data.</p>
|
||
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="struct" href="struct.Serializer.html"
|
||
title='struct serde_cbor::Serializer'>Serializer</a></td>
|
||
<td class='docblock-short'>
|
||
<p>A structure for serializing Rust values to CBOR.</p>
|
||
|
||
</td>
|
||
</tr></table><h2 id='enums' class='section-header'><a href="#enums">Enums</a></h2>
|
||
<table>
|
||
<tr class=' module-item'>
|
||
<td><a class="enum" href="enum.ObjectKey.html"
|
||
title='enum serde_cbor::ObjectKey'>ObjectKey</a></td>
|
||
<td class='docblock-short'>
|
||
<p>A simplified CBOR value containing only types useful for keys.</p>
|
||
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="enum" href="enum.Value.html"
|
||
title='enum serde_cbor::Value'>Value</a></td>
|
||
<td class='docblock-short'>
|
||
<p>An enum over all possible CBOR types.</p>
|
||
|
||
</td>
|
||
</tr></table><h2 id='functions' class='section-header'><a href="#functions">Functions</a></h2>
|
||
<table>
|
||
<tr class=' module-item'>
|
||
<td><a class="fn" href="fn.from_reader.html"
|
||
title='fn serde_cbor::from_reader'>from_reader</a></td>
|
||
<td class='docblock-short'>
|
||
<p>Decodes a value from CBOR data in a reader.</p>
|
||
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="fn" href="fn.from_slice.html"
|
||
title='fn serde_cbor::from_slice'>from_slice</a></td>
|
||
<td class='docblock-short'>
|
||
<p>Decodes a value from CBOR data in a slice.</p>
|
||
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="fn" href="fn.to_value.html"
|
||
title='fn serde_cbor::to_value'>to_value</a></td>
|
||
<td class='docblock-short'>
|
||
<p>Convert a <code>T</code> into <code>serde_cbor::Value</code> which is an enum that can represent
|
||
any valid CBOR data.</p>
|
||
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="fn" href="fn.to_vec.html"
|
||
title='fn serde_cbor::to_vec'>to_vec</a></td>
|
||
<td class='docblock-short'>
|
||
<p>Serializes a value to a vector.</p>
|
||
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="fn" href="fn.to_writer.html"
|
||
title='fn serde_cbor::to_writer'>to_writer</a></td>
|
||
<td class='docblock-short'>
|
||
<p>Serializes a value to a writer.</p>
|
||
|
||
</td>
|
||
</tr></table></section>
|
||
<section id='search' class="content hidden"></section>
|
||
|
||
<section class="footer"></section>
|
||
|
||
<aside id="help" class="hidden">
|
||
<div>
|
||
<h1 class="hidden">Help</h1>
|
||
|
||
<div class="shortcuts">
|
||
<h2>Keyboard Shortcuts</h2>
|
||
|
||
<dl>
|
||
<dt><kbd>?</kbd></dt>
|
||
<dd>Show this help dialog</dd>
|
||
<dt><kbd>S</kbd></dt>
|
||
<dd>Focus the search field</dd>
|
||
<dt><kbd>↑</kbd></dt>
|
||
<dd>Move up in search results</dd>
|
||
<dt><kbd>↓</kbd></dt>
|
||
<dd>Move down in search results</dd>
|
||
<dt><kbd>↹</kbd></dt>
|
||
<dd>Switch tab</dd>
|
||
<dt><kbd>⏎</kbd></dt>
|
||
<dd>Go to active search result</dd>
|
||
<dt><kbd>+</kbd></dt>
|
||
<dd>Expand all sections</dd>
|
||
<dt><kbd>-</kbd></dt>
|
||
<dd>Collapse all sections</dd>
|
||
</dl>
|
||
</div>
|
||
|
||
<div class="infos">
|
||
<h2>Search Tricks</h2>
|
||
|
||
<p>
|
||
Prefix searches with a type followed by a colon (e.g.
|
||
<code>fn:</code>) to restrict the search to a given type.
|
||
</p>
|
||
|
||
<p>
|
||
Accepted types are: <code>fn</code>, <code>mod</code>,
|
||
<code>struct</code>, <code>enum</code>,
|
||
<code>trait</code>, <code>type</code>, <code>macro</code>,
|
||
and <code>const</code>.
|
||
</p>
|
||
|
||
<p>
|
||
Search functions by type signature (e.g.
|
||
<code>vec -> usize</code> or <code>* -> vec</code>)
|
||
</p>
|
||
</div>
|
||
</div>
|
||
</aside>
|
||
|
||
|
||
|
||
<script>
|
||
window.rootPath = "../";
|
||
window.currentCrate = "serde_cbor";
|
||
</script>
|
||
<script src="../main.js"></script>
|
||
<script defer src="../search-index.js"></script>
|
||
</body>
|
||
</html> |