# High-level Protobuf conversion library for Exonum

[![Travis Build Status](https://img.shields.io/travis/exonum/exonum/master.svg?label=Linux%20Build)](https://travis-ci.com/exonum/exonum)
[![License: Apache-2.0](https://img.shields.io/github/license/exonum/exonum.svg)](https://github.com/exonum/exonum/blob/master/LICENSE)
![rust 1.42.0+ required](https://img.shields.io/badge/rust-1.42.0+-blue.svg?label=Required%20Rust)

`exonum-proto` provides a high-level interface for interacting with code
generated by `protoc-rust` crate.

The central part of this crate is `ProtobufConvert` trait.

The main purpose of this trait is to allow users to create
a map between their types and the types generated from `.proto`
descriptions, while providing a mechanism for additional
validation of Protobuf data.

Most of the time you do not have to implement this trait because most
of the use cases are covered by `#[derive(ProtobufConvert)]`
from the `exonum-derive` crate.

A typical example of such mapping with validation is manual implementation
of this trait for `exonum_crypto::Hash`. `exonum_crypto::Hash` is a fixed
sized array of bytes but Protobuf does not allow us to express this
constraint since only dynamically sized arrays are supported.

If you would like to use `Hash` as a part of your Protobuf struct, you would
have to write a conversion function from Protobuf `proto::Hash`(which
is dynamically sized array of bytes) to`exonum_crypto::Hash` and call
it every time when you want to use `exonum_crypto::Hash` in your application.

The provided `ProtobufConvert` implementation for Hash allows you to embed
this field into your struct and generate `ProtobufConvert` for it using
`#[derive(ProtobufConvert)]`, which will validate your structure based on the
validation function for `Hash`.

Consult [the crate docs](https://docs.rs/exonum-proto) for more details.

## Examples

Sample Protobuf roundtrip:

```rust
use exonum_proto::ProtobufConvert;
use bit_vec::BitVec;

let bit_vector = BitVec::from_bytes(&[0b_1010_0000, 0b_0001_0010]);
let bit_vector_pb = bit_vector.to_pb();
let deserialized_bit_vector: BitVec = ProtobufConvert::from_pb(pb_bv).unwrap();
assert_eq!(bit_vector, deserialized_bit_vector);
```

## Usage

Include `exonum-proto` as a dependency in your `Cargo.toml`:

```toml
[dependencies]
exonum-proto = "1.0.0"
```

## License

`exonum-proto` is licensed under the Apache License (Version 2.0).
See [LICENSE](LICENSE) for details.