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
115
116
117
118
119
120
121

//! # The Rust MessagePack Library
//!
//! RMP is a pure Rust [MessagePack](http://msgpack.org) 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`:
//!
//! ```toml
//! [dependencies.rmp]
//! rmp = "^0.7"
//! ```
//!
//! Then, add this to your crate root:
//!
//! ```rust
//! 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 гарантирует, что будет возвращен только тот вариант, в котором все ошибки
//! могут произойти.

// #### Encode
// Модуль encode следует использовать, если вы хотите осуществить сериализацию примитивных типов.
// Они все принимают Write в качестве первого параметра и желаемое значение в качестве второго.
// В процессе своей работы они не осуществляют аллокаций на куче, если такое не предусмотрено в методе
// write. Все они могут вернуть любую I/O ошибку, а также некоторые другие, которые сответствуют своей
// сигнатуре.
//
// Например, вот так можно задекодировать целое число известного размера: (ПРИМЕР).
//
// #### Decode
//
// TODO:
// ### Low level functions (with a pair of examples).
// ### Value variant and its associated functions (with examples).
// ### ValueRef variant, why it's here and its associated functions (with examples).

extern crate byteorder;

pub mod encode;
pub mod decode;

mod init;

pub mod value;

pub const MSGPACK_VERSION : u32 = 5;

pub use init::Marker;

pub use value::{Value, ValueRef};