1 // Copyright 2019 Google LLC
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // https://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 //! Flexbuffers is a high performance schemaless binary data format designed at Google.
16 //! It is complementary to the schema-ed format [Flatbuffers](http://docs.rs/flatbuffers/).
17 //! See [Flexbuffer Internals](https://google.github.io/flatbuffers/flatbuffers_internals.html)
18 //! for details on the binary format.
19 //!
20 //! See the examples for usage:
21 //! * [Example](https://github.com/google/flatbuffers/blob/master/samples/sample_flexbuffers.rs)
22 //! * [Serde Example](https://github.com/google/flatbuffers/blob/master/samples/sample_flexbuffers_serde.rs)
23 //!
24 //! This rust implementation is in progress and, until the 1.0 release, breaking API changes may
25 //! happen between minor versions.
26 // TODO(cneo): serde stuff are behind a default-on feature flag
27 // Reader to Json is behind a default-off feature flag
28 // Serializable structs are Pushable
29 // Serde with maps - field names and type names.
30
31 // Until flat/flexbuffers is on Rust v1.42, we cannot use the previously unstable matches! macro.
32 #![allow(clippy::unknown_clippy_lints)]
33 #![allow(clippy::match_like_matches_macro)]
34
35 #[macro_use]
36 extern crate bitflags;
37 extern crate byteorder;
38 #[macro_use]
39 extern crate serde_derive;
40 extern crate num_enum;
41 extern crate serde;
42
43 mod bitwidth;
44 mod builder;
45 mod flexbuffer_type;
46 mod reader;
47 mod buffer;
48
49 pub use bitwidth::BitWidth;
50 pub use builder::Error as SerializationError;
51 pub use builder::{
52 singleton, Builder, BuilderOptions, FlexbufferSerializer, MapBuilder, Pushable, VectorBuilder,
53 };
54 pub use flexbuffer_type::FlexBufferType;
55 pub use buffer::Buffer;
56 pub use reader::Error as ReaderError;
57 pub use reader::{DeserializationError, MapReader, Reader, ReaderIterator, VectorReader};
58 use serde::{Deserialize, Serialize};
59
60 mod private {
61 pub trait Sealed {}
62 }
63
64 /// Serialize as a flexbuffer into a vector.
to_vec<T: Serialize>(x: T) -> Result<Vec<u8>, SerializationError>65 pub fn to_vec<T: Serialize>(x: T) -> Result<Vec<u8>, SerializationError> {
66 let mut s = FlexbufferSerializer::new();
67 x.serialize(&mut s)?;
68 Ok(s.take_buffer())
69 }
70
71 /// Deserialize a type from a flexbuffer.
from_slice<'de, T: Deserialize<'de>>(buf: &'de [u8]) -> Result<T, DeserializationError>72 pub fn from_slice<'de, T: Deserialize<'de>>(buf: &'de [u8]) -> Result<T, DeserializationError> {
73 let r = Reader::get_root(buf)?;
74 T::deserialize(r)
75 }
76
77 /// Deserialize a type from a flexbuffer.
from_buffer<'de, T: Deserialize<'de>, B: Buffer>( buf: &'de B ) -> Result<T, DeserializationError>78 pub fn from_buffer<'de, T: Deserialize<'de>, B: Buffer>(
79 buf: &'de B
80 ) -> Result<T, DeserializationError> {
81 let r = Reader::get_root(buf as &'de [u8])?;
82 T::deserialize(r)
83 }
84
85 /// This struct, when pushed will be serialized as a `FlexBufferType::Blob`.
86 ///
87 /// A `Blob` is a variable width `length` followed by that many bytes of data.
88 #[derive(Debug, PartialEq, Eq)]
89 pub struct Blob<B>(pub B);
90
91 impl<B: Buffer> Clone for Blob<B> {
clone(&self) -> Self92 fn clone(&self) -> Self {
93 Blob(self.0.shallow_copy())
94 }
95 }
96
97 /// This struct, when pushed, will be serialized as a `FlexBufferType::IndirectUInt`.
98 ///
99 /// It is an unsigned integer stored by reference in the flexbuffer. This can reduce the
100 /// size of vectors and maps containing the `IndirectUInt`.
101 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
102 pub struct IndirectUInt(pub u64);
103
104 /// This struct, when pushed, will be serialized as a `FlexBufferType::IndirectInt`.
105 ///
106 /// It is a signed integer stored by reference in the flexbuffer. This can reduce the
107 /// size of vectors and maps containing the `IndirectInt`.
108 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
109 pub struct IndirectInt(pub i64);
110
111 /// This struct, when pushed, will be serialized as a `FlexBufferType::IndirectFloat`.
112 ///
113 /// It is a floating point stored by reference in the flexbuffer. This can reduce the
114 /// size of vectors and maps containing the `IndirectFloat`.
115 #[derive(Debug, Copy, Clone, PartialEq)]
116 pub struct IndirectFloat(pub f64);
117