Crate serde_ubj 

serde-ubj

Universal Binary JSON data format for Rust with Serde (both std and no_std environments).

This project is in an early stage of development, and not production ready yet.
Use with caution!

This project does:

• implement the serde::Serializer trait for most of the Serde data model types,
• support optimized serialize_bytes (that you can enable via the serde_bytes crate),
• support both std (standard) and no_std environments (by replying upon the embedded-io project),
• pass enough unit tests covering at least 85% of its code base.

tl;dr

For the impatient.

serialization

With any Rust std writer of your choice (i.e., output console, memory buffer, file on disk, network socket, etc.), serialize any value for which you have either derived or provided a serde::Serialize implementation to Universal Binary JSON in a few instructions:

use sdt::{error, io};

fn main() -> Result<(), Box<dyn error::Error>> {

  let value = 123_i16;
  // let value = ... my model type ... 
  
  // With any IO writer, serialize the value
  let mut w: io::Write = io::stdout();
  serde_ubj::to_writer(&w, &value)?;
}

deserialization

Whit any Rust std buffered reader of your choice (i.e., input console, memory buffer, file on disk, network socket, etc.), deserialize any value for which you have either derived or provided serde::Deserialize implementation from Universal Binary JSON in a few instructions:

use sdt::{error,io}

fn main() -> Result<(), Box<dyn error::Error>> {
  // With any IO buffered reader,
  let mut r: io::BufRead = ...;
  
  // Deserialize the value of type `T`
  let value: T = serde_ubj::from_buf_reader(&mut r)?;
  Ok(())
}

exceptions

This implementation does not support the following Serde types:

• serialization

  • Serde byte array
  • Serde numeric u64 values greater than Rust i64::MAX
  • Serde numeric i128, u128
  • Serde string having length greater than Rust i64::MAX,
  • UBJ optimizations

• deserialization

  • all exceptions above, and
  • Serde u16, u32, u64
  • Serde &str

limitations

This implementation is made with the following limitations:

• strings
  their length must be not greater than i64::MAX

• maps
  keys must be Strings

no_std

This implementation can be adopted in no_std environments, as long as you disable the default features and, at the same time, enable the embedded-io feature, as per following Cargo.toml example:

[package]
name = "my_no_std_project"
version = "0.1.0"
edition = "2024"

[dependencies]
serde_ubj = { version = "0.2.0", default-features = false, features = ["embedded-io"] }
embedded-io = { version = "latest" }

book

Coming soon.

Enums

UbjError

An error that can occur during serializing to (or deserializing from) Universal Binary JSON

Functions

from_buf_reader

Deserialize from an IO buffering reader into a Rust value of type T.

from_vec

Deserialize from a vector (in-memory buffer) of bytes into a Rust value of type T.

to_vec

Serializes a Rust value of type T to a vector (in-memory buffer) of bytes.

to_writer

Serializes a Rust value of type T to an IO writer.

Type Aliases

UbjResult

A convenient type alias for Result<T, UbjError>