Update README

Author: kornelski

.github/workflows/ci.yml

@@ -1,4 +1,4 @@
-name: Continuous Integration
+name: Build
 on:
     push:
     pull_request:

README.md

@@ -1,61 +1,56 @@
 # RMP - Rust MessagePack
 
-RMP is a pure Rust [MessagePack](http://msgpack.org) implementation.
+RMP is a complete pure-Rust [MessagePack](http://msgpack.org) implementation. MessagePack a compact self-describing binary serialization format.
 
-[![Build Status](https://travis-ci.org/3Hren/msgpack-rust.svg?branch=master)](https://travis-ci.org/3Hren/msgpack-rust)
-[![Coverage Status][coveralls-img]][coveralls-url]
+This project consists of three crates:
 
-This repository consists of three separate crates: the RMP core and two implementations to ease serializing and
-deserializing Rust structs.
-
- crates.rs                                 | API Documentation               |
--------------------------------------------|---------------------------------|
- [![rmp][crates-rmp-img]][crates-rmp-url]     | [RMP][rmp-docs-url]             |
- [![rmps][crates-rmps-img]][crates-rmps-url]   | [RMP Serde][rmps-docs-url]      |
- [![rmpv][crates-rmpv-img]][crates-rmpv-url]   | [RMP Value][rmpv-docs-url]      |
+* [RMP-Serde][crates-rmps-url] ([Documentation][rmps-docs-url]) — easy serializing/deserializing via [Serde](https://serde.rs).
+* [RMP-Value][crates-rmpv-url] ([Documentation][rmpv-docs-url]) — a universal `Value` enum that can hold any MessagePack type. Allows deserializing arbitrary messages without a known schema.
+* [RMP][crates-rmp-url] ([Documentation][rmp-docs-url]) — low-level functions for reading/writing encoded data.
 
 ## Features
 
-- **Convenient API**
+- **Convenient and powerful APIs**
 
-  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.
+  RMP is designed to be lightweight and straightforward. There is a high-level API with support for Serde,
+  which provides you convenient interface for encode/decode Rust's data structures using `derive` attribute.
+  There are also low-level APIs, which give you full control over data encoding/decoding process,
+  with no-std support and without heap allocations.
 
 - **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 as long as the buffer lives.
-
-- **Clear error handling**
-
-  RMP's error system guarantees that you never receive an error enum with unreachable variant.
+  RMP allows to decode bytes from a buffer in a zero-copy manner. Parsing is implemented in safe Rust.
 
-- **Robust and tested**
+- **Robust, stable and tested**
 
   This project is developed using TDD and CI, so any found bugs will be fixed without breaking
   existing functionality.
 
+## Why MessagePack?
+
+Smaller and simpler to parse than JSON. Supports the same types as JSON, plus binary data, all float values, and 64-bit numbers.
+Encoded data is self-describing and extensible, without requiring a schema definition.
+
 ## Requirements
 
-- Rust 1.53.0 or later
+- Rust 1.56.0 or later
 
 [rustc-serialize]: https://github.com/rust-lang-nursery/rustc-serialize
 [serde]: https://github.com/serde-rs/serde
 
+[ci-img]: https://github.com/3Hren/msgpack-rust/actions/workflows/ci.yml/badge.svg
+[ci-url]: https://github.com/3Hren/msgpack-rust/actions/workflows/ci.yml
+
 [coveralls-img]: https://coveralls.io/repos/3Hren/msgpack-rust/badge.svg?branch=master&service=github
 [coveralls-url]: https://coveralls.io/github/3Hren/msgpack-rust?branch=master
 
 [rmp-docs-url]: https://docs.rs/rmp
 [rmps-docs-url]: https://docs.rs/rmp-serde
 [rmpv-docs-url]: https://docs.rs/rmpv
 
-[crates-rmp-img]: https://img.shields.io/crates/v/rmp.svg
 [crates-rmp-url]: https://lib.rs/crates/rmp
-
-[crates-rmps-img]: https://img.shields.io/crates/v/rmp-serde.svg
 [crates-rmps-url]: https://lib.rs/crates/rmp-serde
-
-[crates-rmpv-img]: https://img.shields.io/crates/v/rmpv.svg
 [crates-rmpv-url]: https://lib.rs/crates/rmpv
+
+
+[![Build][ci-img]][ci-url] [![Coverage Status][coveralls-img]][coveralls-url]

rmp-serde/README.md

@@ -0,0 +1,60 @@
+# MessagePack + Serde
+
+This crate connects Rust MessagePack library with [`serde`][serde] providing an ability to
+easily serialize and deserialize both Rust built-in types, the standard library and custom data
+structures.
+
+## Motivating example
+
+```rust
+let buf = rmp_serde::to_vec(&(42, "the Answer")).unwrap();
+
+assert_eq!(
+    vec![0x92, 0x2a, 0xaa, 0x74, 0x68, 0x65, 0x20, 0x41, 0x6e, 0x73, 0x77, 0x65, 0x72],
+    buf
+);
+
+assert_eq!((42, "the Answer"), rmp_serde::from_slice(&buf).unwrap());
+```
+
+## Type-based Serialization and Deserialization
+
+Serde provides a mechanism for low boilerplate serialization & deserialization of values to and
+from MessagePack via the serialization API.
+
+To be able to serialize a piece of data, it must implement the `serde::Serialize` trait. To be
+able to deserialize a piece of data, it must implement the `serde::Deserialize` trait. Serde
+provides an annotation to automatically generate the code for these
+traits: `#[derive(Serialize, Deserialize)]`.
+
+## Examples
+
+```rust
+use std::collections::HashMap;
+use serde::{Deserialize, Serialize};
+use rmp_serde::{Deserializer, Serializer};
+
+#[derive(Debug, PartialEq, Deserialize, Serialize)]
+struct Human {
+    age: u32,
+    name: String,
+}
+
+fn main() {
+    let mut buf = Vec::new();
+    let val = Human {
+        age: 42,
+        name: "John".into(),
+    };
+
+    val.serialize(&mut Serializer::new(&mut buf)).unwrap();
+}
+```
+
+## Efficient storage of `&[u8]` types
+
+MessagePack can efficiently store binary data. However, Serde's standard derived implementations *do not* use binary representations by default. Serde prefers to represent types like `&[u8; N]` or `Vec<u8>` as arrays of objects of arbitrary/unknown type, and not as slices of bytes. This creates about a 50% overhead in storage size.
+
+Wrap your data in [`serde_bytes`](https://lib.rs/crates/serde_bytes) to store blobs quickly and efficiently. Alternatively, [configure an override in `rmp_serde` to force use of byte slices](https://docs.rs/rmp-serde/latest/rmp_serde/encode/struct.Serializer.html#method.with_bytes).
+
+[serde]: https://serde.rs/

rmp-serde/README.md

@@ -268,6 +268,14 @@ impl<W: Write, C> Serializer<W, C> {
     /// This reduces overhead of binary data, but it may break
     /// decodnig of some Serde types that happen to contain `[u8]`s,
     /// but don't implement Serde's `visit_bytes`.
+    ///
+    /// ```rust
+    /// use serde::ser::Serialize;
+    /// let mut msgpack_data = Vec::new();
+    /// let mut serializer = rmp_serde::Serializer::new(&mut msgpack_data)
+    ///     .with_bytes(rmp_serde::config::BytesMode::ForceAll);
+    /// vec![255u8; 100].serialize(&mut serializer).unwrap();
+    /// ```
     #[inline]
     pub fn with_bytes(mut self, mode: BytesMode) -> Serializer<W, C> {
         self.config.bytes = mode;

rmp-serde/src/encode.rs

@@ -1,55 +1,4 @@
-//! This crate connects Rust MessagePack library with [`serde`][serde] providing an ability to
-//! easily serialize and deserialize both Rust built-in types, the standard library and custom data
-//! structures.
-//!
-//! ## Motivating example
-//!
-//! ```
-//! let buf = rmp_serde::to_vec(&(42, "the Answer")).unwrap();
-//!
-//! assert_eq!(
-//!     vec![0x92, 0x2a, 0xaa, 0x74, 0x68, 0x65, 0x20, 0x41, 0x6e, 0x73, 0x77, 0x65, 0x72],
-//!     buf
-//! );
-//!
-//! assert_eq!((42, "the Answer"), rmp_serde::from_slice(&buf).unwrap());
-//! ```
-//!
-//! # Type-based Serialization and Deserialization
-//!
-//! Serde provides a mechanism for low boilerplate serialization & deserialization of values to and
-//! from MessagePack via the serialization API.
-//!
-//! To be able to serialize a piece of data, it must implement the `serde::Serialize` trait. To be
-//! able to deserialize a piece of data, it must implement the `serde::Deserialize` trait. Serde
-//! provides an annotation to automatically generate the code for these
-//! traits: `#[derive(Serialize, Deserialize)]`.
-//!
-//! # Examples
-//!
-//! ```
-//! use std::collections::HashMap;
-//! use serde::{Deserialize, Serialize};
-//! use rmp_serde::{Deserializer, Serializer};
-//!
-//! #[derive(Debug, PartialEq, Deserialize, Serialize)]
-//! struct Human {
-//!     age: u32,
-//!     name: String,
-//! }
-//!
-//! fn main() {
-//!     let mut buf = Vec::new();
-//!     let val = Human {
-//!         age: 42,
-//!         name: "John".into(),
-//!     };
-//!
-//!     val.serialize(&mut Serializer::new(&mut buf)).unwrap();
-//! }
-//! ```
-//!
-//! [serde]: https://serde.rs/
+#![doc = include_str!("../README.md")]
 #![forbid(unsafe_code)]
 #![warn(missing_debug_implementations, missing_docs)]
 

rmp-serde/src/lib.rs

@@ -4,31 +4,31 @@ RMP is a pure Rust [MessagePack](http://msgpack.org) implementation of an effici
 serialization format. This crate provides low-level core functionality, writers and readers for
 primitive values with direct mapping between binary MessagePack format.
 
-**Warning** this library is still in rapid development and everything may change until 1.0
-comes.
+[Looking for Serde support](https://lib.rs/crates/rmp-serde)?
+
+This crate represents the very basic functionality needed to work with MessagePack format.
+Ideologically it is developed as a basis for building high-level abstractions.
 
 ### Usage
 
 To use `rmp`, first add this to your `Cargo.toml`:
 
 ```toml
 [dependencies.rmp]
-rmp = "^0.8"
+rmp = "0.8"
 ```
 
 ### Features
 
-- **Convenient API**
+- **Low-level 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.
+  RMP is designed to be lightweight and straightforward. There are low-level APIs, which give you
+  full control over the encoding/decoding process. `no-std` environments are supported.
 
 - **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.
+  RMP allows to decode bytes from a buffer in a zero-copy manner, without any heap allocations.
+  easily and blazingly fast. Rust static checks guarantee that the data will be valid until buffer lives.
 
 - **Clear error handling**
 
@@ -41,9 +41,6 @@ rmp = "^0.8"
 
 ### Detailed
 
-This crate represents the very basic functionality needed to work with MessagePack format.
-Ideologically it is developed as a basis for building high-level abstractions.
-
 Currently there are two large modules: encode and decode. More detail you can find in the
 corresponding sections.
 
@@ -140,6 +137,6 @@ assert_eq!([0xcb, 0x40, 0x9, 0x21, 0xfb, 0x54, 0x44, 0x2d, 0x18], buf[..]);
 assert_eq!(pi, rmp::decode::read_f64(&mut &buf[..]).unwrap());
 ```
 
-[read_int]: decode/fn.read_int.html
-
 License: MIT
+
+[read_int]: https://docs.rs/rmp/latest/rmp/decode/fn.read_int.html