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
/*!
Yet another encoding/decoding library for bencode.
I believe [`deserializer`](crate::Deserializer) don't allocate memory. [`Serializer`](crate::Serializer) allocates
only when `sort_dictionary` feature enabled. I think this crate is fast enough.
## Examples
For `.torrent` parsing example see [`examples directory`](https://github.com/knightpp/serde_bencoded/tree/master/examples)
# Caveats
`serde` treats `[u8; N]`, `Vec<u8>`, `&[u8]` like any other
sequence, that is it will be encoded as list of bytes(not a byte string).
Solution - use [`serde_bytes`](https://github.com/serde-rs/bytes).
### Serializing map with `Option` values
You will need to write a custom ser/de helper. For inspiration see
[https://github.com/serde-rs/serde/issues/550#issuecomment-246746639](https://github.com/serde-rs/serde/issues/550#issuecomment-246746639)
### Serializing `Option`
Use `#[serde(skip_serializing_if = "Option::is_none")]` annotation or see
[`serde_with::skip_serializing_none`](https://docs.rs/serde_with/1.6.1/serde_with/attr.skip_serializing_none.html)
## Behaviour
This crate does sort dictionary by keys if `sort_dictionary` feature is
enabled (enabled by default). Otherwise order of elements can vary
(depends on [`Serialize`](serde::Serialize) trait implementation).
### Mapping of rust types to bencode
- [`bool`](bool) is [`integer`](#integers) either `i1e` or `i0e`.
- `all primitive integer types` is [`integer`](#integers).
- [`char`](char) is [`byte string`](#byte-strings) with length at most 4 bytes.
- [`String`](String) is [`byte string`](#byte-strings).
- `[u8]` is [`list`](#lists) see [`Caveats`](#caveats).
- [`Option`](Option), Serializing is not allowed but can be achieved. See [`Serializing Option`](#serializing-option).
- `()` (unit) is `0:`, empty [`byte string`](#byte-strings).
- `struct UnitStruct;` is `10:UnitStruct`, [`byte string`](#byte-strings) containing name
of the unit struct.
- `enum E { A, B }`
- `E::A` is `d1:E1:Ae`, [`dictionary`](#dictionaries) with one entry. Key is name of
the `enum` and value is the variant.
- `tuple`s and `array`s is [`lists`](#lists), tuples can be heterogeneous.
- `struct Rgb(u8, u8, u8)` (tuple struct) is [`list`](#lists) of tuple values.
- [`HashMap`](std::collections::HashMap) is [`dictionary`](#dictionaries).
- `struct`s is [`dictionary`](#dictionaries). Keys are field names, values are
field values.
- [`f32`](f32), [`f64`](f64) is not supported.
## Alternatives
Arbitrary order. Search more on [`crates.io`](https://crates.io/search?q=bencode) or
[`lib.rs`](https://lib.rs/search?q=bencode).
- [`bendy`](https://lib.rs/crates/bendy)
- [`bencode`](https://lib.rs/crates/bencode)
- [`serde_bencode`](https://lib.rs/crates/serde_bencode)
- [`bt_bencode`](https://lib.rs/crates/bt_bencode)
- [`bip_bencode`](https://lib.rs/crates/bip_bencode)
## Bencoding
### Supported data types
- [`Byte Strings`](#byte-strings)
- [`Integers`](#integers)
- [`Lists`](#lists)
- [`Dictionaries`](#dictionaries)
#### Byte Strings
`<base ten ASCII>:<string bytes>`
Examples:
- `4:abcd`
- `0:`
#### Integers
`i<base ten ASCII, optional minus sign>e`
The maximum number is not specified. This crate
handles integers as [`u64`](u64) or [`i64`](i64).
Examples:
- `i123456e`
- `i-5e`
Malformed:
- `i03e`, anything that starts with 0, except `i0e`
- `i-0e`
#### Lists
`l<bencode type values>e`
Examples:
- `li0ei1ei2ee` == `[1,2,3]`
- `le` == `[]`
#### Dictionaries
`d<bencoded string><bencoded element>e`
Keys must be sorted as __raw__ strings. [`string`](#byte-strings)'s should be
compared using a __binary comparison__.
Examples:
- `de` == `{}`
- `d4:rustl2:is7:awesomeee` == `{"rust" => ["is", "awesome"]}`
## Crate features
### sort_dictionary
Enables sort by keys when serializing to bencode dictionary.
*/
mod de;
mod error;
mod ser;
pub use de::{from_bytes, from_bytes_auto, from_str, from_str_auto, Deserializer};
pub use error::{DeError, DeResult, SerError, SerResult};
pub use ser::{to_string, to_vec, to_writer, Serializer};