beve/
lib.rs

1//! BEVE - Binary Efficient Versatile Encoding
2//!
3//! High-performance, tagged binary format designed for scientific computing.
4//! This crate provides a robust, fast, and ergonomic implementation with serde support.
5//!
6//! - Little-endian encoding
7//! - Direct struct serialization via `serde::{Serialize, Deserialize}`
8//! - Typed arrays for numeric, boolean, and string sequences when possible
9//! - Object keys as strings or integer types
10//! - Enum support via BEVE type-tag extension
11//! - Validation helpers for checking BEVE payload integrity without deserialization
12//!
13//! Example
14//!
15//! ```rust
16//! use serde::{Serialize, Deserialize};
17//!
18//! #[derive(Serialize, Deserialize, Debug, PartialEq)]
19//! struct Point { x: f64, y: f64 }
20//!
21//! let p = Point { x: 1.0, y: -2.0 };
22//! let bytes = beve::to_vec(&p).unwrap();
23//! let p2: Point = beve::from_slice(&bytes).unwrap();
24//! assert_eq!(p, p2);
25//! ```
26//!
27//! Validate a payload without decoding it into a concrete Rust type:
28//!
29//! ```rust
30//! use std::io::Cursor;
31//!
32//! let bytes = beve::to_vec(&vec![1u32, 2, 3]).unwrap();
33//! beve::validate_slice(&bytes).unwrap();
34//! beve::validate_reader(Cursor::new(bytes)).unwrap();
35//! ```
36
37mod de;
38mod error;
39mod ext;
40pub mod fast;
41mod header;
42mod json;
43mod ser;
44mod size;
45mod value;
46
47pub use crate::de::{from_slice, validate_slice, Deserializer};
48pub use crate::error::{Error, Result};
49pub use crate::ext::{
50    decode_matrix_slice, Complex, ComplexSlice, DecodedMatrix, Matrix, MatrixDecodeMode,
51    MatrixLayout, MatrixOwned, RawMatrix,
52};
53pub use crate::fast::{
54    to_vec_bool_slice, to_vec_complex32, to_vec_complex32_slice, to_vec_complex64,
55    to_vec_complex64_slice, to_vec_str_slice, to_vec_string_slice, to_vec_typed_slice,
56    write_bool_slice, write_str_slice, write_string_slice, write_typed_slice, BeveTypedSlice,
57};
58pub use crate::json::{
59    beve_slice_to_json, beve_slice_to_json_string, json_slice_to_beve, json_str_to_beve,
60};
61pub use crate::ser::{
62    to_vec, to_vec_into, to_vec_into_with_options, to_vec_with_options, EnumEncoding, Serializer,
63    SerializerOptions,
64};
65pub use crate::value::{
66    from_value, from_value_ref, BigInt, BigIntKey, Key, Number, Object, Value, ValueError,
67};
68
69/// BEVE-specific utilities and helper types.
70pub mod util {
71    pub use crate::ext::MatrixLayout;
72}
73
74use std::io::{Read, Write};
75
76/// Serialize a value to any writer. For unknown-length containers, this uses an internal buffer.
77pub fn to_writer<W: Write, T: serde::Serialize>(mut writer: W, value: &T) -> Result<()> {
78    let bytes = to_vec(value)?;
79    writer
80        .write_all(&bytes)
81        .map_err(|e| Error::MessageOwned(e.to_string()))
82}
83
84/// Serialize a value to any writer with custom options.
85pub fn to_writer_with_options<W: Write, T: serde::Serialize>(
86    mut writer: W,
87    value: &T,
88    opts: SerializerOptions,
89) -> Result<()> {
90    let bytes = to_vec_with_options(value, opts)?;
91    writer
92        .write_all(&bytes)
93        .map_err(|e| Error::MessageOwned(e.to_string()))
94}
95
96/// Deserialize a value by reading all bytes from a reader into a buffer first.
97pub fn from_reader<R: Read, T: serde::de::DeserializeOwned>(mut reader: R) -> Result<T> {
98    let mut buf = Vec::new();
99    reader
100        .read_to_end(&mut buf)
101        .map_err(|e| Error::MessageOwned(e.to_string()))?;
102    from_slice(&buf)
103}
104
105/// Validate BEVE data from any reader without deserializing into a concrete type.
106///
107/// This enforces the same semantics as [`validate_slice`]: exactly one valid BEVE
108/// value and no trailing bytes.
109///
110/// # Example
111///
112/// ```rust
113/// use std::io::Cursor;
114///
115/// let bytes = beve::to_vec(&123u32).unwrap();
116/// beve::validate_reader(Cursor::new(bytes)).unwrap();
117/// ```
118pub fn validate_reader<R: Read>(mut reader: R) -> Result<()> {
119    let mut buf = Vec::new();
120    reader
121        .read_to_end(&mut buf)
122        .map_err(|e| Error::MessageOwned(e.to_string()))?;
123    validate_slice(&buf)
124}
beve/lib.rs

beve/
lib.rs
