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