serde_beve/lib.rs
1//! # Serde BEVE
2//!
3//! A Serde data format for [BEVE](https://github.com/beve-org/beve).
4//!
5//! ## 16-bit floats
6//!
7//! BEVE supports both [`f16`](half::f16)s and [brain floats](https://en.wikipedia.org/wiki/Bfloat16_floating-point_format). This crate supports the deserialization of both, converting them into [`f32`]s. However, similar to [extension types](https://github.com/beve-org/beve/blob/main/extensions.md), Serde provides no means of serializing these types, and as such **their deserialization is gated by the `half` feature**, which enables the use of the [`half`] crate for working with them.
8//!
9//! ## Notes
10//!
11//! Since BEVE is a binary format, this crate doesn't provide any tools for serializing to or deserializing from strings.
12//!
13//! BEVE collections (arrays, object, and strings) store their lengths as compressed integers[^1]. The compression method uses the first two bits to indicate the number of bytes in the integer, and as such, the maximum size is 62 bits[^2]. If, for some reason, you have a string with more than that many bytes, an array with more than that many items, or (heaven forbid) a struct or map with more than that many fields, serialization will fail.
14//!
15//! BEVE is a little-endian format, and for the sake of simplicity, this crate assumes it is being used on a little-endian system.
16//!
17//! [^1]: <https://github.com/beve-org/beve?tab=readme-ov-file#compressed-unsigned-integer>
18//!
19//! [^2]: (2^62) - 1 = 4611686018427387904
20
21/// Deserialization logic.
22pub mod de;
23/// Errors that can occur during serialization or deserialization.
24pub mod error;
25/// Serialization logic.
26pub mod ser;
27/// Intermediate representation of values used during serialization.
28pub mod value;
29
30mod headers;
31
32pub use de::{Deserializer, from_bytes, from_reader};
33pub use error::{Error, Result};
34pub use headers::{ArrayKind, ObjectKind};
35pub use ser::{Serializer, to_bytes, to_writer};
36pub use value::Value;