• Stars
    star
    373
  • Rank 114,600 (Top 3 %)
  • Language
    Rust
  • License
    Apache License 2.0
  • Created almost 7 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A fast binary serialization framework

A fast binary serialization framework

Documentation

The goal of this crate is to provide fast, simple and easy binary serialization.

Benchmarks

See rust_serialization_benchmark for benchmarks.

Example

use std::borrow::Cow;
use speedy::{Readable, Writable, Endianness};

#[derive(PartialEq, Debug, Readable, Writable)]
enum Enum {
    A,
    B,
    C,
}

#[derive(PartialEq, Debug, Readable, Writable)]
struct Struct< 'a > {
    number: u64,
    string: String,
    vector: Vec< u8 >,
    cow: Cow< 'a, [i64] >,
    float: f32,
    enumeration: Enum
}

fn main() {
    let original = Struct {
        number: 0x12345678ABCDEF00,
        string: "A totally pointless string".to_owned(),
        vector: vec![ 1, 2, 3 ],
        cow: Cow::Borrowed( &[ 4, 5, 6 ] ),
        float: 3.1415,
        enumeration: Enum::C
    };

    let bytes = original.write_to_vec().unwrap();
    let deserialized: Struct =
        Struct::read_from_buffer( &bytes ).unwrap();

    assert_eq!( original, deserialized );
}

Supported types

Out-of-box the following types are supported:

Type Serialized as
u8 as-is
u16 as-is
u32 as-is
u64 as-is
usize u64
i8 as-is
i16 as-is
i32 as-is
i64 as-is
f32 as-is
f64 as-is
bool u8, either 0 or 1
char u32
String {length: u32, bytes: [u8]}
Cow<'a, str> {length: u32, bytes: [u8]}
Vec<T> {length: u32, values: [T]}
Cow<'a, [T]> {length: u32, values: [T]}
HashMap<K, V> {length: u32, values: [K, V]}
BTreeMap<K, V> {length: u32, values: [K, V]}
HashSet<T> {length: u32, values: [T]}
BTreeSet<T> {length: u32, values: [T]}
Range<T> (T, T)
RangeInclusive<T> (T, T)
Option<T> (1_u8, T) or 0_u8
Result<T, E> (1_u8, T) or (0_u8, E)
() nothing
(T) as-is
(T, T) as-is
(T, .., T) as-is
enums {tag: u32, variant: T}
AtomicU8 u8
AtomicI8 i8
AtomicU16 u16
AtomicI16 i16
AtomicU32 u32
AtomicI32 i32
AtomicU64 u64
AtomicI64 i64
NonZeroU32 u32
std::net::Ipv4Addr u32
std::net::Ipv6Addr u128
std::net::IpAddr {is_ipv4: u8, value: {u32 or u128}}
std::time::Duration {secs: u64, subsec_nanos: u32}
std::time::SystemTime std::time::Duration since UNIX_EPOCH
uuid::Uuid [u8; 16]

These are stable and will not change in the future.

Field attributes

#[speedy(length = $expr)]

Can be used on most standard containers to specify the field's length. Can refer to any of the previous fields.

For example:

use speedy::{Readable, Writable};

#[derive(Readable, Writable)]
struct Struct {
    byte_count: u8,
    #[speedy(length = byte_count / 4)]
    data: Vec< u32 >
}

Before serializing you need to make sure that whatever is set as length is equal to the .len() of the field; if it's not then you will get an error when trying to serialize it.

Setting this attribute changes the serialization format as follows:

Type Serialized as
Vec<T> [T]
Cow<'a, [T]> [T]
String [u8]
Cow<'a, str> [u8]
HashMap<K, V> [K, V]
BTreeMap<K, V> [K, V]
HashSet<T> [T]
BTreeSet<T> [T]

#[speedy(length_type = $ty)]

Can be used to specify the exact size of the implicit length field of a container as it is read or written.

Possible values:

  • u7 (same as u8, but restricted to 7 bits for u64_varint compatibility)
  • u8
  • u16
  • u32 (default)
  • u64_varint

#[speedy(varint)]

Can be used only on u64 fields. Forces the field to be serialized as a varint.

#[speedy(skip)]

Skips a given field when reading and writing.

#[speedy(default_on_eof)]

If an EOF is encountered when reading this field its value will be set to the default value for its type and the EOF will be ignored.

#[speedy(constant_prefix = $expr)]

Specifies a static string of bytes which will be written or has to be present when reading before a given field.

Enum attributes

#[speedy(tag_type = $ty)]

Can be used to specify the exact size of the enum's tag as it is read or written.

Possible values:

  • u7 (same as u8, but restricted to 7 bits for u64_varint compatibility)
  • u8
  • u16
  • u32 (default)
  • u64_varint

#[speedy(peek_tag)]

An enum marked with this attribute will not consume its tag value when reading from a stream, nor will it write its own tag when writing.

Enum variant attributes

#[speedy(tag = $expr)]

Specifies a preset tag value to be used for a given enum variant.

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

More Repositories

1

bytehound

A memory profiler for Linux.
C
4,446
star
2

stdweb

A standard library for the client-side Web
Rust
3,441
star
3

cargo-web

A Cargo subcommand for the client-side Web
Rust
1,106
star
4

not-perf

A sampling CPU profiler for Linux
Rust
870
star
5

pinky

An NES emulator written in Rust
Rust
771
star
6

polkavm

A fast and secure RISC-V based virtual machine
Rust
239
star
7

schnellru

A fast and flexible LRU map.
Rust
170
star
8

parcel-plugin-cargo-web

JavaScript
48
star
9

libretro-backend

Libretro API bindings for Rust
Rust
46
star
10

sarek

A work-in-progress, experimental neural network library for Rust
Rust
44
star
11

polkadot-starship

Ruby
24
star
12

polkavm-experiment

An experimental RISC-V recompiler
Rust
18
star
13

hooky

A convenient LD_PRELOAD hooker
Rust
12
star
14

rustc-rv32e

Rust toolchain for RV32E
Shell
10
star
15

rwkv_tokenizer

Python
7
star
16

polkadoom

Yet another DOOM port
C++
7
star
17

libretro-sys

Raw FFI bindings to the libretro API
Rust
6
star
18

static_test

Attribute macro for writing tests which check that a given condition ALWAYS holds true or that a given code path is ALWAYS unreachable
Rust
6
star
19

serde-bench

A simple benchmark of various Rust serialization frameworks
Rust
6
star
20

nsctrld

Nintendo Switch Pro Controller userspace driver
Rust
4
star
21

linux-input

Rust
4
star
22

memory-pool

A global, thread-safe memory pool.
Rust
4
star
23

dspr

A DSP plugin server
C++
3
star
24

unsafe_target_feature

A more convenient `#[target_feature]` replacement
Rust
3
star
25

chromium-build

Shell
2
star
26

softfloat

Rust
2
star
27

cargo-shim

A helper library for Cargo subcommands
Rust
2
star
28

mmalloc

A simple mmap-based allocator
Rust
2
star
29

chrf

Rust
2
star
30

koute.github.io

JavaScript
1
star
31

inputd

Rust
1
star
32

linux-elf-loading-bug

Rust
1
star