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