Crate rmp [−] [src]
The Rust MessagePack Library
RMP is a pure Rust MessagePack implementation.
MessagePack is an efficient binary serialization format.
Warning this library is still in rapid development and everything may change until 1.0 comes.
Usage
To use rmp
, first add this to your Cargo.toml
:
[dependencies.rmp]
rmp = "^0.7"
Then, add this to your crate root:
extern crate rmp as msgpack; // Or just `rmp`.
Features
Convenient API
RMP is designed to be lightweight and straightforward. There are low-level API, which gives you full control on data encoding/decoding process and makes no heap allocations. On the other hand there are high-level API, which provides you convenient interface using Rust standard library and compiler reflection, allowing to encode/decode structures using
derive
attribute.Zero-copy value decoding
RMP allows to decode bytes from a buffer in a zero-copy manner easily and blazingly fast, while Rust static checks guarantees that the data will be valid until buffer lives.
Clear error handling
RMP's error system guarantees that you never receive an error enum with unreachable variant.
Robust and tested
This project is developed using TDD and CI, so any found bugs will be fixed without breaking existing functionality.
Detailed
Данный крейт предоставляет самую базовую функциональность, необходимую для работы с MessagePack.
Он идеологически задуман как фундамент для построение более высокоуровненных абстракций,
облегчающих рутинную работу (например, см. rmp-serde
crate).
Он состоит из трех больших модулей: encode, decode и value. Более детально о каждом из них написано в соответствующем разделе.
В двух словах MessagePack формат состоит из некого маркера, которая инкапсулирует тип данных и, собственно, значения. Иногда отдельного значения может не быть, в этом случае оно явно или неявно закодировано в самом маркере.
Также одно и то же значение может быть представлено в различном виде.
Например, значение true
декодируется как 0xc3
, а вот значение 42
может быть представлено
по-разному: [0x2a]
, [0xcc, 0x2a]
, [0xcd, 0x00, 0x2a]
и тд.
RMP гарантирует, что в случае сериализации будет выбран наиболее экономное представление. В то же время гарантируется, что в случае десериализации будет возможно получить исходное значение независимо от того, какую запись выбрал источник.
API
Практически все API представляют собой чистые функции. В качестве альтернативы можно было бы расширить трейты Write и Read, но это не было сделано специально, чтобы не захламлять пространство методов. Например, в одном и том же модуле могут использоваться энкодеры в json и msgpack, в таком случае наличие метода write_u8 выглядело бы странным, а наличие write_msgpack_u8 - уродливым.
Performance
Этот крейт предоставляет настолько низкий уровено абстракции, насколько это возможно, поэтому производительность является основной целью. Любое улучшение производительности тщательно анализируется при помощи бенчмарков, благо Rust предоставляет достаточно удобные инструменты для этого.
Однако на текущий момент специально не было проведено никаких оптимизаций, так что этот код может (и будет) работать быстрее. Не стесняйтесь - тестируйте и присылайте ваши оптимизации.
Error handling
Меня всегда расстраивал код, в котором приходится делать unreachable!()
в случае обработок
ошибок, поэтому RMP гарантирует, что будет возвращен только тот вариант, в котором все ошибки
могут произойти.
Reexports
pub use value::{Value, ValueRef}; |
Modules
decode |
Provides various functions and structs for MessagePack decoding. |
encode |
Provides various functions and structs for MessagePack encoding. |
value |
Contains Value and ValueRef structs and its conversion traits. |
Enums
Marker |
Constants
MSGPACK_VERSION |