messagepack_async/lib.rs
1//! # MessagePack-Async
2//!
3//! `messagepack-async` is a simple, functional library for reading and writing
4//! MessagePack with `std::io::{Read, Write}` and `tokio::io::{AsyncRead, AsyncWrite}`.
5//!
6//! No features are enabled by default so you will either need to enable at least one of
7//! `sync` or `tokio` depending on what you're planning on reading/writing to.
8//!
9//! ```toml
10//! [dependencies]
11//! # Stdlib
12//! messagepack-async = { version = "0.2.3", features = [ "sync" ] }
13//! # Tokio
14//! messagepack-async = { version = "0.2.3", features = [ "tokio" ] }
15//! ```
16//!
17//! ## The Traits
18//!
19//! This crate provides four traits; [`sync::ReadFrom`], [`sync::WriteTo`],
20//! [`tokio::ReadFrom`], and [`tokio::WriteTo`]. These provide methods to read and
21//! write [`Value`]s to sources and sinks that implement the read/write traits from
22//! the stdlib or [tokio](https://docs.rs/tokio/latest/tokio/).
23//!
24//! Note that `write_to` will write **exactly** the value you supply. That means
25//! if you write a `Int::U64(0)` to a sink, it won't write the value as a U8 even
26//! though it could be represented as such.
27//!
28//! ```rust
29//! use messagepack_async::{Value, Int, sync::{ReadFrom, WriteTo}};
30//! let mut data = vec![];
31//! let value = Value::Int(Int::U64(0));
32//! value.write_to(&mut data).unwrap();
33//! let mut cursor = data.as_slice();
34//! let read_value = Value::read_from(&mut cursor).unwrap();
35//! assert_eq!(value, read_value);
36//! ```
37//!
38//! The implementation of [`std::cmp::PartialEq`] is derived so differentiates
39//! between different variants of [`Int`].
40//!
41//! If you need to minimise the size in bytes of the values you write, create your
42//! values with the [`Value::int`], [`Value::signed_int`], and
43//! [`Value::unsigned_int`] constructors for [`Value`].
44
45pub mod value;
46
47pub use value::{Ext, Float, Int, Value};
48
49#[cfg(feature = "tokio")]
50pub mod tokio;
51
52#[cfg(feature = "sync")]
53pub mod sync;