Bovnar — Rust Bindings

Bovnar (BVNR) spec 1.2 documentation · Also available as Markdown and PDF.

Spec version: 1.2 Status: Reference — the Rust crate as implemented Scope: Installation, the high-level and streaming APIs, the DOM, Quantity and the exact numbers, JSON conversion, and the thread rules.

Rust bindings for the Bovnar (BVNR) typed serialisation library (library 2.1.0, format spec 1.2).

The crate is a thin wrapper around the C library: build.rs compiles the C sources into the crate, so there is no system library to install and nothing is looked up at run time. One module is not a wrapper: bovnar::codec, the incremental framing codec for live streams, is pure Rust (§4.8). The API stays close to the C library's own shapes: parse / to_string over a dynamic Value, Reader callbacks, Writer calls and a random-access DOM. There is no serde integration, no builder API for values and no typed deserialisation; the DOM has the C library's node builder (§12.5). Where Rust's types can say more at no cost, they do: the C enums are Rust enums, and an error carries the library's error kind.

Table of Contents

1. Requirements
2. Installation
3. Building the C library
   • 3.1 WebAssembly (wasm32-wasip2)
   • 3.2 Unit-profile features
   • 3.3 How the published crate is made
4. Quick-start
   • 4.1 High-level API (parse / to_string)
   • 4.2 SAX-style streaming reader
   • 4.3 Collecting events
   • 4.4 DOM (random-access) API
   • 4.5 Low-level writer
   • 4.6 Streaming / framing (bovnar::stream)
   • 4.7 Files and I/O streams (std::io::Read / Write)
   • 4.8 Live streams: the framing codec (bovnar::codec)
   • 4.9 Live documents through C (bovnar::live)
   • 4.10 Canonical form
5. Unit helpers
   • 5.1 The unit-profile notations (spec 1.2)
   • 5.2 Extended unit functions
   • 5.3 UnitFlags
   • 5.4 Prefix
   • 5.5 Inline unit suffix
   • 5.6 UnitPolicy — validation and conversion without a callback
   • 5.7 Building a Unit
   • 5.8 Validators and literal helpers
6. Quantity
   • 6.1 Construction
   • 6.2 Fields and methods
   • 6.3 Exact numbers (Decimal, BigRational, BvnFloat)
   • 6.4 to_string() integration
   • 6.5 Civil time and calendars
7. write_array helper
8. JSON conversion
9. Currency helpers
10. Reader reference
    • 10.1 Construction
    • 10.2 read_mem
    • 10.3 ReadOptions
    • 10.4 EventData and EventPayload
    • 10.5 iter_mem
    • 10.6 Error-state accessors
11. Writer reference
    • 11.1 Construction
    • 11.2 Output retrieval
    • 11.3 Scalar write methods
    • 11.4 Extended integer writers
    • 11.5 Struct helpers
    • 11.6 Version directive
    • 11.7 Array helpers
    • 11.8 Low-level emit
    • 11.9 Observing the output: on_event
    • 11.10 The C per-type helpers
12. DOM API
    • 12.1 DomDoc::parse
    • 12.2 DomDoc
    • 12.3 DomNode
    • 12.4 DomType
    • 12.5 Building a tree (NewNode)
13. Error handling
14. Threads
15. Running the test suite
16. Crate layout
17. Enums and BaseUnit
18. Spec 1.1 additions
19. License

• See also

1. Requirements

The only optional features are the unit-profile notations, all on by default (§3.2). There are no optional dependencies and no integration with third-party unit or array libraries; see §16.

2. Installation

The crate carries the version of the C library it wraps (2.1.0: version in Cargo.toml is the project(bovnar VERSION x.y.z) of the top-level CMakeLists.txt, and CI fails when the two differ). It is published to crates.io with each release:

[dependencies]
bovnar = "2.1.0"

A repository checkout works too, as a path dependency or straight from Git, where Cargo finds the crate inside the repository. Built that way it needs Python 3 at build time (§1):

[dependencies]
bovnar = { path = "../bovnar/rust" }
# or
bovnar = { git = "https://github.com/sothis/bovnar" }

To work on the crate itself:

cd rust
cargo build
cargo test

3. Building the C library

The crate has no shared library to find: build.rs compiles the C library into the crate. The crate from crates.io carries the C sources and the generated unit tables in c/ and compiles those; in a repository checkout build.rs runs the table generators and compiles ../src and ../include instead. Either way a downstream crate needs a C compiler at build time (plus Python 3 in the checkout case, §1) and nothing at run time.

build.rs re-runs when the C sources, the generators, the interpreter override, the enabled features or WASI_SDK_PATH change.

3.1 WebAssembly (wasm32-wasip2)

A WebAssembly build needs a C compiler for WASI, wasi-sdk. Point WASI_SDK_PATH at it and build for wasm32-wasip2:

rustup target add wasm32-wasip2
export WASI_SDK_PATH=/opt/wasi-sdk        # where wasi-sdk is unpacked
cargo build --release --target wasm32-wasip2

The same applies to a crate that depends on this one and is built for wasm32-wasip2: set WASI_SDK_PATH for its build.

The crate's own tests run there under wasmtime, which must see the checkout (the examples the tests read, and the build's output):

CARGO_TARGET_WASM32_WASIP2_RUNNER="wasmtime run --dir $(git rev-parse --show-toplevel)" \
    cargo test --target wasm32-wasip2 --lib --tests

A non-default CARGO_TARGET_DIR outside the checkout needs a --dir of its own. WASI has no threads and a panic aborts, so the one test of each is ignored there; the doctests run on native targets only.

3.2 Unit-profile features

Each unit-profile notation of doc/11 is a Cargo feature, and all seven are on by default:

Leaving a feature out drops that notation's tables from the library, as -DBVNR_WITH_<NAME>_PROFILE=OFF does for the CMake build, and the reader then refuses its codes. THIRD_PARTY_NOTICES.md says why a distributor may want to leave out ucum or cf:

[dependencies]
bovnar = { version = "2.1.0", default-features = false, features = ["unece", "qudt", "qudt-qk", "udunits", "om"] }

3.3 How the published crate is made

build.rs reaches ../src, which a package made from rust/ would not contain, so rust/Cargo.toml keeps publish = false and the crate is published from a staged copy. rust/package.py builds that copy: the crate without tests/ and fuzz/ (they read ../examples and ../src/gendata), LICENSE, THIRD_PARTY_NOTICES.md, and in c/ the headers, the C sources build.rs compiles and the generators' output. It then runs cargo on the copy:

python3 rust/package.py                          # cargo package: pack and verify
python3 rust/package.py -- publish --dry-run     # what CI runs on every push

CI's rust_package job runs that dry run on every push, and publish_crate publishes the same way on a vX.Y.Z tag through crates.io Trusted Publishing.

The crate carries PROVENANCE.json: the repository, the commit and, on a release, the tag it was staged from, and for every file in the crate its SHA-256 and the repository path it was copied from ("generated" for the tables in c/generated/). A program that vendors the C library from c/ can tie what it compiles, and the notices it ships, to that one revision by comparing its copies against those hashes. Before cargo runs, package.py checks the staged copy with check_crate_provenance.py, which stages the named commit again and requires the same files byte for byte. rust_package checks the packed .crate the same way, and a publish refuses uncommitted changes and a commit without its vX.Y.Z tag. To check a published crate against the repository:

python3 check_crate_provenance.py bovnar-X.Y.Z.crate --tag vX.Y.Z

4. Quick-start

4.1 High-level API (parse / to_string)

The dynamic document type is Value. parse reads BVNR bytes into a Value and to_string writes a Value out as BVNR bytes:

use bovnar::{Value, parse, to_string};

fn main() -> Result<(), bovnar::Error> {
    // Serialise a document to BVNR bytes
    let data = Value::Struct(vec![
        ("sensor_id".into(), Value::Int(42)),
        ("temperature".into(), Value::Float(-3.7)),
        ("label".into(), Value::String("outdoor".into())),
        ("active".into(), Value::Bool(true)),
        ("payload".into(), Value::Null),
    ]);
    let bvnr_bytes = to_string(&data, true)?;

    // Deserialise it back
    let recovered = parse(&bvnr_bytes)?;
    assert_eq!(recovered, data);
    let Value::Struct(fields) = recovered else { unreachable!() };
    assert_eq!(fields[0], ("sensor_id".to_string(), Value::Int(42)));
    Ok(())
}

Value is what parse returns and to_string takes:

parse_typed is parse with typed values kept: they come back as Value::Quantity instead of being decoded to native scalars. That preserves the original text representation, exact type width, numeral base and physical unit for lossless round trips. What only the annotation carries comes back too: a quoted numeric literal under a default annotation (<float:64,_10> "5.7"), and a typed null, alone (<float:64> ;) or as an array element ([<uint:32>, <sint:64>]):

use bovnar::{Value, parse_typed, to_string};

fn main() -> Result<(), bovnar::Error> {
    let bvnr = b".pressure = <float:32,Pa> 101325.0;";
    let doc = parse_typed(bvnr)?;
    let Value::Struct(fields) = &doc else { unreachable!() };
    let Value::Quantity(q) = &fields[0].1 else { unreachable!() };
    assert_eq!(q.raw.as_deref(), Some("101325.0"));
    assert_eq!(q.unit_str(), "Pa");

    // to_string() accepts Quantity values — annotation and raw text are re-emitted as-is
    let out = to_string(&doc, true)?;
    assert_eq!(parse_typed(&out)?, doc);
    Ok(())
}

to_string(value, pretty) takes a Value::Struct — any other top-level value is an Error::Argument. Its write buffer starts at 4 MiB and doubles on overflow up to 256 MiB; there is no cap argument. It returns Vec<u8> rather than String, because an octet stream is written raw. write_to(value, pretty, out) does the same into any std::io::Write, and parse_reader(input) / parse_typed_reader(input) read from any std::io::Read (§4.7).

parse and its siblings read with the default ReadOptions; parse_with_options(data, typed, &options) and parse_reader_with_options(input, typed, &options) take any of them (§10.3) — a total cap, strict_version, text_only, the length and nesting caps — with typed choosing between parse and parse_typed:

use bovnar::{ErrorCode, ReadOptions};

fn main() {
    let untrusted = ReadOptions {
        max_file_size: 1 << 20,
        max_string_length: 4096,
        strict_version: true,
        ..ReadOptions::default()
    };
    let err = bovnar::parse_with_options(b"#!bovnar 9.0\n.a = 1;", false, &untrusted)
        .unwrap_err();
    assert_eq!(err.code(), Some(ErrorCode::UnsupportedSpecVersion));
}

to_string() writes what parse() reads — the streaming tier, not the document tier. parse() checks the grammar and each value's own type, unit and range and stops there; to_string() is its inverse and stops in the same place, so to_string(&parse(x)?) works for every x that parse() accepts. Three shapes are therefore written without complaint and then refused by the document tier (DomDoc::parse, bovnar validate), where an array is homogeneous and rectangular:

Rust value	Written as	Document tier says
Array(vec![Int(1), String("a".into())]) — an array mixing kinds	[1, "a"]	array_element_type_mismatch
a ragged array of arrays — rows of 1 and 2 elements	[[1], [2, 3]]	array_row_size_mismatch
structs that do not share their keys	[{.a = <uint:64> 1;}, {.b = <uint:64> 2;}]	struct_shape_mismatch

An array mixing Int and Float, or holding Null beside values, is fine at both tiers. If the output has to pass bovnar validate, run it through DomDoc::parse before shipping it.

What to_string() does refuse, with Error::Argument, is what neither tier reads: an array whose elements carry different units, an integer wider than 64 bits in an array that cannot take the width annotation it needs ([Int(1 << 70), Float(1.5)]), and a Decimal past the range of float_dec:64. A key that is not a string is not on the list: a struct key is a String, so the type system has already refused it.

4.2 SAX-style streaming reader

The callback receives exactly one argument, the EventData. There is no userdata/context argument — capture external state in the closure instead. The closure returns true to go on and false to stop the read (which then ends in an Error::Parse).

use bovnar::{Event, EventData, ReadOptions, Reader};

fn main() -> Result<(), bovnar::Error> {
    let bvnr_bytes = b".a = 1; .b = \"two\";";
    let mut keys = Vec::new();
    let mut values = Vec::new();
    let mut on_event = |d: &EventData<'_>| {
        if d.event == Event::AssignmentStart {
            keys.push(d.text());
        } else if d.event == Event::Data {
            values.push(d.raw.to_vec());
        }
        true // returning false stops parsing (an Error::Parse)
    };

    let mut r = Reader::new()?;
    r.read_mem(bvnr_bytes, &ReadOptions::default(), Some(&mut on_event), None)?;
    assert_eq!(keys, ["a", "b"]);
    assert_eq!(values[0], b"1");
    Ok(())
}

EventData is the payload passed to a callback:

The borrow ends with the callback. EventData<'a> borrows the reader's memory, so a field cannot be kept past the call; copy what you need (text(), d.raw.to_vec()). The owned copy that can outlive its callback is EventPayload, which iter_mem collects for you.

4.3 Collecting events

Reader::iter_mem returns the events as a Vec of owned EventPayload values (the whole stream, read to the end):

use bovnar::Reader;

fn main() -> Result<(), bovnar::Error> {
    let bvnr_bytes = b".a = 1; .b = 2;";
    let mut r = Reader::new()?;
    for payload in r.iter_mem(bvnr_bytes, true, 0)? {
        println!("{:?} {}", payload.event, payload.text());
    }
    Ok(())
}

4.4 DOM (random-access) API

use bovnar::{DomDoc, DomType};

fn main() -> Result<(), bovnar::Error> {
    let bvnr_bytes = br#"
        .sensor_id = 42;
        .config = { .host = "example.com"; };
        .values = [1.5, 2.5, 3.5];
    "#;
    let doc = DomDoc::parse(bvnr_bytes)?;

    // Top-level key lookup
    let node = doc.get("sensor_id").expect("present");
    assert_eq!(node.as_i64(), Some(42));
    assert_eq!(node.value_type().width, 64);

    // Struct traversal — by member, or by dotted path
    let cfg = doc.get("config").expect("present");
    assert_eq!(cfg.get("host").and_then(|n| n.as_str()), Some("example.com"));
    assert_eq!(doc.lookup("config.host").and_then(|n| n.as_str()), Some("example.com"));

    // Array access
    let arr = doc.get("values").expect("present");
    assert_eq!(arr.dom_type(), Some(DomType::Array));
    let sum: f64 = (0..arr.len()).filter_map(|i| arr.at(i)?.as_float()).sum();
    assert_eq!(sum, 7.5);

    // Convert the entire document to a plain Value (drops type/unit info)
    let value = doc.to_value()?;
    assert!(matches!(value, bovnar::Value::Struct(_)));
    Ok(())
}

A DomNode is a Copy view that borrows its DomDoc, so the compiler — not a convention — keeps the document alive for as long as a node is in use.

4.5 Low-level writer

use bovnar::{Base, Writer};

fn main() -> Result<(), bovnar::Error> {
    let mut w = Writer::to_mem(4096, true)?;
    w.write_float("velocity", 9.81, 64)?;
    w.write_uint("count", 1024, 32, Base::DECIMAL)?;
    w.finish()?;

    let output: &[u8] = w.get_output();
    assert_eq!(bovnar::parse(output)?, bovnar::parse(b".velocity = 9.81; .count = <uint:32> 1024;")?);
    Ok(())
}

The scalar writers take no unit arguments: write a value with a unit through write_quantity or write_array, which take a Unit.

4.6 Streaming / framing (bovnar::stream)

Bindings for the streaming layer (see Streaming, Framing & Multiplexing for the full treatment). The functions work on in-memory buffers:

use bovnar::{Value, parse, stream, to_string};

fn main() -> Result<(), bovnar::Error> {
    let one = Value::Struct(vec![("id".into(), Value::Int(1))]);
    let two = Value::Struct(vec![("id".into(), Value::Int(2))]);

    // Multi-document record framing
    let blob = stream::dump_documents(&[one.clone(), two.clone()], true)?;
    let docs = stream::load_documents(&blob, false, false, 0)?;
    assert_eq!(docs, [Some(one.clone()), Some(two)]);
    // With continue_past_failed = true a document that fails is None and the rest are read
    let docs = stream::load_documents(&blob, false, true, 0)?;
    assert_eq!(docs.len(), 2);

    // Octet multiplexing: (channel, payload) of any size, interleaved & reassembled
    let multiplexed = stream::mux_dump(&[(1, b"hello".as_slice()), (42, b"world".as_slice())], "mux")?;
    let messages = stream::mux_load(&multiplexed, 0, None)?;
    assert_eq!(messages, [(1, b"hello".to_vec()), (42, b"world".to_vec())]);

    // Document-in-document
    let outer = stream::embed_document(&to_string(&one, true)?, "payload", true)?;
    let Value::Struct(fields) = parse(&outer)? else { unreachable!() };
    let Value::Bytes(inner) = &fields[0].1 else { unreachable!() };
    assert_eq!(stream::parse_embedded(inner, false)?, one);
    Ok(())
}

All arguments are positional:

load_documents with continue_past_failed gives None for a document that failed, and the error is gone. load_documents_results (and load_documents_reader_results) keep it: every frame is read, as with continue_past_failed, and the document at index i is Ok(value) or the Err it failed with — an Error::Parse with the document's error code and no position, which the frame reader does not report. The outer Err is the stream's own failure: the framing, a frame over the cap. live::FrameParser hands each document's index and result to on_document already (§4.9).

use bovnar::{ErrorCode, ReadOptions, Value, stream};

fn main() -> Result<(), bovnar::Error> {
    let frames = stream::frame_documents(&[&b".a = 1;"[..], b".a = @;", b".b = 2;"])?;
    let docs = stream::load_documents_results(&frames, false, 0, &ReadOptions::default())?;
    assert_eq!(docs[0], Ok(Value::Struct(vec![("a".into(), Value::Int(1))])));
    assert_eq!(docs[1].as_ref().unwrap_err().code(), Some(ErrorCode::UnexpectedInputByte));
    assert!(docs[2].is_ok());
    Ok(())
}

parse_embedded returns an Error::Parse carrying the inner document's own error code and, where the library reported one, its position. mux_dump channels are u64, so the channel range is checked by the type.

The readers read with the default ReadOptions. Each has a twin that takes them as its last argument — load_documents_with_options, mux_load_with_options, parse_embedded_with_options, and the same for the *_reader functions — and reads under them: load_documents each document, with max_file_size capping one document and max_document_size one frame; mux_load the document around the stream; parse_embedded the embedded document, as a document of its own, with max_file_size capping its bytes.

Each function has a twin for std::io::Read or std::io::Write (§4.7).

The Reader and Writer types of §10 and §11 are the building blocks underneath: use them directly when a document is produced or consumed event by event rather than as one buffer.

4.7 Files and I/O streams (std::io::Read / Write)

Every entry point that reads or writes a whole document has a twin that takes any std::io::Read or std::io::Write: a File, a pipe, a socket, a Cursor. There is no separate path-based or file-descriptor form; open the File and pass it in.

use std::io::Cursor;
use bovnar::{Base, DomDoc, ReadOptions, Reader, Writer};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let path = std::env::temp_dir().join(format!("bovnar-doc-{}.bvnr", std::process::id()));

    // Write: the document streams into the file, the rest on finish()
    let mut w = Writer::to_writer(std::fs::File::create(&path)?, false)?;
    w.write_uint("port", 443, 16, Base::DECIMAL)?;
    w.finish()?;
    drop(w);

    // Random access over the file
    let dom = DomDoc::parse_reader(std::fs::File::open(&path)?)?;
    assert_eq!(dom.lookup("port").and_then(|n| n.as_u64()), Some(443));
    std::fs::remove_file(&path)?;

    // Streaming over any reader
    let mut keys = Vec::new();
    let mut on_event = |d: &bovnar::EventData<'_>| {
        if d.event == bovnar::Event::AssignmentStart {
            keys.push(String::from_utf8_lossy(d.raw).into_owned());
        }
        true
    };
    Reader::new()?.read_reader(Cursor::new(b".a = 1;"), &ReadOptions::default(), Some(&mut on_event), None)?;
    assert_eq!(keys, ["a"]);
    Ok(())
}

The plain-value and stream functions have twins too:

use std::io::Cursor;
use bovnar::{parse_reader, stream, write_to};

fn main() -> Result<(), bovnar::Error> {
    let value = parse_reader(Cursor::new(b".a = 1;"))?;

    // Serialise into any Write; here a Vec<u8>
    let mut out = Vec::new();
    write_to(&value, false, &mut out)?;
    assert_eq!(bovnar::parse(&out)?, value);

    // Framed documents round-trip through a Write and a Read
    let mut framed = Vec::new();
    stream::dump_documents_to(&[value.clone(), value.clone()], false, &mut framed)?;
    let docs = stream::load_documents_reader(Cursor::new(framed), false, false, 0)?;
    assert_eq!(docs, [Some(value.clone()), Some(value)]);
    Ok(())
}

They stream. A reader twin hands its Read to the C library as a callback source (bvnr_source_from_callback): the library pulls from it as it parses, so the events of what has arrived are delivered while the rest is still to come, and the input is never held whole (Reader::read_reader keeps memory flat however long the input is; the twins that return values hold those values). The results are those of the in-memory twin for the same bytes, file_too_long at the same offset for a document over ReadOptions::max_file_size and the max_document_size and max_message of load_documents_reader and mux_load_reader included. The input is read until it reports its end (Ok(0)), so these suit a file, a pipe or a blocking socket; for input that is handed over when it arrives, use the fed readers of §4.9. Only the DOM reads its input into memory first, up to DOM_READ_MAX_BYTES (256 MiB, the cap of bvn_dom_parse_fd), because it builds the whole document anyway.

A writer twin, and Writer::to_writer, push the document into out through a callback sink (bvnr_sink_to_callback) as it is serialised: the C writer batches its output as it does for an fd, so out receives 64 KiB blocks as they fill and the rest on finish(), which then flushes out once; a to_writer writer also hands over what it holds whenever flush() is called (§11.5). The bytes are those of the in-memory twin. Since output leaves as it is made, a value that cannot be serialised part-way through leaves the blocks before it in out (a value that is not a struct at all leaves nothing), and a to_writer writer dropped unfinished drops what it still holds. to_writer has no cap on the document's size; to_writer_with(out, cap, …) keeps cap as one, and output past it fails with sink_buffer_exhausted, as with Writer::to_mem -- from the call that pushes it into out (the write that fills a block, or flush() or finish()), not necessarily the write that made it. Writer::get_output() is empty for such a writer. out must be Send + 'static; the writer stays Send (§14).

Short reads and writes are continued and Interrupted is retried. A failing input or out is an Error::Io (§13) with the code the C library gives an unreadable fd source or unwritable fd sink (reading_from_source_fd, writing_to_sink), after the events of what had arrived, and a to_writer writer reports it from every later call too. A panic inside input or out reaches the caller, as one in an event handler does (§13); it never unwinds through the C library. No file descriptor is involved, so these work the same on Windows.

4.8 Live streams: the framing codec (bovnar::codec)

The stream functions of §4.6 work on whole buffers. bovnar::codec does the same two wire conventions — octet multiplexing and BVF1 frames (Streaming §2 and §3) — on a live stream: the writer hands out each message's bytes as it is sent, and the reader is fed bytes in pieces of any size, as they arrive from a socket or a pipe, and hands out each message as soon as its last byte is in. The module is pure Rust (#![forbid(unsafe_code)]): no message goes through the C library, and nothing is allocated per message once the reader's buffers have grown to the largest message.

use bovnar::codec::{MuxReader, MuxWriter};

fn main() -> Result<(), bovnar::Error> {
    // A stream under the key "media" that opens with ordinary values
    let mux = MuxWriter::with_preamble(b".meta = { .codec = \"av1\"; .rate = 30; };", "media")?;
    let mut wire = Vec::new(); // stands in for a socket
    wire.extend_from_slice(mux.opener());
    let mut head = Vec::new();
    for (channel, frame) in [(1, &b"key frame"[..]), (2, b"audio"), (1, b"delta")] {
        // Only the chunk headers are written, into `head`; the frame is
        // borrowed, ready for a vectored write
        for part in mux.encode(&mut head, channel, frame) {
            wire.extend_from_slice(part);
        }
    }
    wire.extend_from_slice(mux.terminator());

    // The C library reads the same bytes
    assert_eq!(bovnar::stream::mux_load(&wire, 0, Some("media"))?.len(), 3);

    // Fed in pieces, as from a socket
    let mut reader = MuxReader::with_options(0, Some("media"))?;
    let mut received = Vec::new();
    for piece in wire.chunks(7) {
        let mut input = piece;
        while let Some(m) = reader.read(&mut input)? {
            received.push((m.channel, m.payload.to_vec()));
        }
    }
    reader.finish()?; // the input ended where a stream may end
    assert_eq!(received[1], (2, b"audio".to_vec()));
    let meta = reader.preamble_value(false)?.expect("the stream is open");
    assert_eq!(meta, bovnar::parse(b".meta = { .codec = \"av1\"; .rate = 30; };")?);
    Ok(())
}

Writing. MuxWriter::new(key) or MuxWriter::with_preamble(preamble, key) validates the key (1 to 255 bytes, the identifier rules of spec §4.2: what the C writer accepts and a reader at its defaults reads) and the preamble, once. A stream is opener(), the messages, then terminator(); begin(&mut vec) and finish(&mut vec) append them to a Vec. Each message is one of:

A message is cut into chunks exactly as bvnr_mux_send cuts it (a message of at most stream::BVNR_MUX_MAX_MESSAGE bytes is one chunk), so the bytes are those of stream::mux_dump for the same key and messages.

Reading. MuxReader::read(&mut input) takes input: &mut &[u8], the bytes not yet read, reads from its front and returns the next complete message as Message { channel, payload }. None means every byte of input was taken (an unfinished message is kept inside the reader), so the buffer can be refilled; after a message, call again with the same slice until None. A message that lies whole in input is borrowed from it; one that spans pieces or chunks is gathered in a buffer per channel that is reused. The slice is valid until the next call. finish() checks that the input ended after the document's ; (or before its first byte); reset() readies the reader for another stream, keeping the buffers it has grown. The reader reads every valid octet region, not only what bvnr_mux_send writes: several messages packed into one chunk, channels interleaved chunk by chunk, a length varint split across chunks.

Peek, skip, forward. For a router or relay, next_item(&mut input, n) also stops at the start of each message with Item::Peek, holding its channel, its declared length and its first n bytes; nothing else of the message has been read. Drop the peek to receive the message as Item::Message, call skip() to have its bytes passed over as they arrive, or forward() to receive it as Item::Wire: whole chunks carrying that message alone, which can be written into any other multiplexed stream between two messages. When those chunks lie consecutive in the input, Wire::bytes is the input itself, not copied; otherwise the reader gathers the message and writes it out again as MuxWriter would.

use bovnar::codec::{Item, MuxReader, MuxWriter};

fn main() -> Result<(), bovnar::Error> {
    let mux = MuxWriter::new("mux")?;
    let mut inbound = Vec::new();
    mux.begin(&mut inbound);
    for (channel, msg) in [(1, &b"for the relay"[..]), (2, b"local only"), (1, b"again")] {
        mux.write_message(&mut inbound, channel, msg);
    }
    mux.finish(&mut inbound);

    // Forward channel 1, drop the rest, decided on the peek alone
    let mut reader = MuxReader::new();
    let mut outbound = mux.opener().to_vec();
    let mut input = &inbound[..];
    while let Some(item) = reader.next_item(&mut input, 0)? {
        match item {
            Item::Peek(p) if p.channel == 1 => p.forward(),
            Item::Peek(p) => p.skip(),
            Item::Wire(w) => outbound.extend_from_slice(w.bytes),
            Item::Message(_) => unreachable!("every message was decided"),
        }
    }
    outbound.extend_from_slice(mux.terminator());
    let relayed = bovnar::stream::mux_load(&outbound, 0, None)?;
    assert_eq!(relayed, [(1, b"for the relay".to_vec()), (1, b"again".to_vec())]);
    Ok(())
}

The preamble. Text before the stream's assignment — complete statements, a #!bovnar directive first if needed — lets a stream carry ordinary values about itself in the same document. with_preamble checks it once with the full parser; it must be text, so an octet stream in it is octet_stream_forbidden (a reader takes the document's first 0x00 for the stream's opener). The reader gathers the text up to that 0x00, requires it to end with the assignment .KEY =, checks the preamble with the full parser (once per stream; a bare .KEY= or .KEY = skips the check), and then reads the octet stream in pure Rust. read_preamble(&mut input) reads only up to the opener and returns the preamble, so it can be acted on before any message; preamble() returns it afterwards and preamble_value(typed) parses it into a Value. A C-written document with values before bvnr_mux_begin reads the same way.

What the reader reads. A preamble (possibly empty), one octet stream as the value of the document's last assignment (.KEY =, with no comment between the = and the stream), ;, then only whitespace and comments, which may also come before the ;. A statement after the stream, or any other byte after it, is unexpected_input_byte: the codec reads multiplexed streams, not the grammar. Parse a general document with stream::mux_load or a Reader.

Errors are Error::Parse with the code the C demultiplexer gives (mux_load gives the same code for a desync, an oversized message, the 4097th channel and a cut-off stream; what only the codec refuses -- bytes after the stream, a preamble over its cap, a key other than the expected one -- has a code of its own), and they are latched:

Frames. codec::frame_header(len), write_frame(&mut vec, doc) and write_frame_to(&mut out, doc) (one vectored write, no copy) write what bvnr_frame_write writes. FrameReader::read(&mut input) returns each complete document's bytes, borrowed when whole in the input, gathered otherwise; parse each with parse, a Reader or DomDoc. FrameReader::with_max_document_size(n) caps a document (0 is 256 MiB, as in bvnr_doc_stream_read; the buffer only grows with bytes that arrived). A bad magic is unexpected_input_byte, a length over the cap value_out_of_range, and finish() inside a frame got_incomplete_bvnr_stream.

use bovnar::codec::{FrameReader, write_frame};

fn main() -> Result<(), bovnar::Error> {
    let mut wire = Vec::new();
    write_frame(&mut wire, b".id = 1;");
    write_frame(&mut wire, b".id = 2;");
    assert_eq!(wire, bovnar::stream::frame_documents(&[".id = 1;", ".id = 2;"])?);

    let mut reader = FrameReader::new();
    let mut ids = Vec::new();
    for piece in wire.chunks(5) {
        let mut input = piece;
        while let Some(doc) = reader.read(&mut input)? {
            ids.push(bovnar::parse(doc)?);
        }
    }
    reader.finish()?;
    assert_eq!(ids.len(), 2);
    Ok(())
}

Cost per message, from cargo bench --bench codec: a release build pinned to one core (taskset -c 3) of an Intel Core i7-2700K (2011), whose clock scales with load. Each figure is the median of seven runs (each run the median of nine passes over at least 64 MiB of messages), and in brackets the fastest run. The stream is a few MiB held in the cache, as the bytes of a socket read are when the reader sees them; it is opened once and fed the same messages every pass, as a live stream is fed, so opening it is not counted. A 400 KB message spans seven chunks.

write is encode (the headers only, for a vectored write); write + copy is write_message into a reused Vec; peek + skip and forward are next_item, a look at the channel and the first payload byte, and the decision, the forwarded chunks borrowed from the input; read is read, which gathers (copies) a message that spans chunks, so the 400 KB one; mux_dump and mux_load are the batch functions through the C library, for comparison (mux_load copies every message into the Vec it returns, which the C demux alone does not: doc/10 §8.4). Counted in instructions, which the clock does not move, a 150-byte message is about 145 to write, 120 to read and 140 to peek at and skip, the benchmark's loop included. From a stream much larger than the cache, every chunk header a 400 KB message has is a cache miss, which puts peek and forward at about 130 ns for it, and small messages are read as fast as memory delivers them: about 24 ns to read a 150-byte one and 29 ns to peek at and skip it. The other figures move little.

4.9 Live documents through C (bovnar::live)

The codec of §4.8 reads the framing; it does not parse documents. bovnar::live wraps the C library's push-fed readers (Streaming §8) for that: they are handed bytes in pieces of any size, as they come from a non-blocking socket, an event loop, a frame or another document's octet stream, and are told separately when the input is over. Each keeps one C object for its whole life, so an endless stream costs one setup, and whatever the cuts, the events, values and errors are exactly those the batch functions give for the whole input (the frame readers' framing errors aside, below).

Documents. DocumentFeed::new(&options) takes the ReadOptions of a Reader (and set_unit_policy its policy). feed(bytes, handler) delivers the events those bytes complete before it returns, so the buffer can be reused at once; running out of input is never an error there. finish(handler) declares the end: a document cut off fails there, with the code and position read_mem reports. reset() starts the next document on the same reader. An error ends the document, and every later feed or finish returns it until reset(). ValueFeed does the same and appends to a Vec each assignment the bytes complete, those before an error included: a scalar, a struct or an octet stream with its last event, an array (which a / may still continue) with the event after it. A key assigned twice comes twice, and nothing is kept once it is handed out, so an endless document is read in constant memory. Its text is capped by the library's default of 2 147 483 647 bytes per document (error_text_data_too_long, doc/10 §1), and each array at as many items: set ReadOptions::max_text_bytes (and max_array_items) to u64::MAX for a document that does not end, and max_file_size where a cap still matters.

use bovnar::live::ValueFeed;
use bovnar::{ReadOptions, Value};

fn main() -> Result<(), bovnar::Error> {
    // An endless document arriving from a socket, cut anywhere
    let pieces: [&[u8]; 4] = [b".temp = 21", b".5; .unit = \"C\"; .te", b"mp = 22.0;", b" .tag = [1, 2];"];
    let mut feed = ValueFeed::new(false, &ReadOptions::default())?;
    let mut got = Vec::new();
    for piece in pieces {
        feed.feed(piece, &mut got)?;
    }
    assert_eq!(got[0], ("temp".to_string(), Value::Float(21.5)));
    assert_eq!(got.len(), 3, "the array may still go on");
    feed.finish(&mut got)?; // the end of the document completes it
    assert_eq!(got[3].0, "tag");
    Ok(())
}

Every handler. feed and finish take the event handler alone. feed_with(bytes, handlers) and finish_with(handlers) take a ReadHandlers (§10.2), as Reader::read_mem_with does: on_verified, the raw lexer events of on_unverified, the want_unit hook and on_error — which sees each error a continue_on_error document recovers from — called inside the call that parses the bytes they concern. ValueFeed takes them through its own feed_with(bytes, out, handlers) and finish_with(out, handlers), its on_verified seeing each event after the value builder has. The C reader is given its callbacks when a document starts, so the first call of a document decides whether on_unverified and want_unit are called for the whole of it: a later call that needs one the document was not started with is an Error::Argument (reset() starts the next document, decided afresh), and a later call may pass fewer. A panic in a handler reaches the caller of the call, and the document has failed.

use bovnar::live::DocumentFeed;
use bovnar::{EventData, ReadHandlers, ReadOptions, Unit};

fn main() -> Result<(), bovnar::Error> {
    let mut feed = DocumentFeed::new(&ReadOptions::default())?;
    let (mut tokens, mut metres) = (0, Vec::new());
    for piece in [&b".d = <uint:64,k~m"[..], b"> 3; .e = 4;"] {
        let mut on_raw = |_: &EventData<'_>| { tokens += 1; true };
        let mut want = |d: &EventData<'_>| {
            (!d.value_unit.is_dimensionless()).then(|| (Unit::parse("m").unwrap(), 0))
        };
        let mut on_value = |d: &EventData<'_>| {
            if d.converted { metres.push(String::from_utf8_lossy(d.converted_text).into_owned()); }
            true
        };
        feed.feed_with(piece, ReadHandlers {
            on_verified: Some(&mut on_value),
            on_unverified: Some(&mut on_raw),
            want_unit: Some(&mut want),
            on_error: None,
        })?;
    }
    feed.finish(&mut |_| true)?;
    assert!(tokens > 0);
    assert_eq!(metres, ["3000"]);
    Ok(())
}

The mirror. set_mirror(w) gives the feed any std::io::Write + Send that receives every byte the reader consumes (src_mirror, a debugging aid): each piece fed, once the reader has parsed it, and a document that fails has mirrored the input up to the byte the error is at. It starts the next document, as reset() does, and stays for every document after; take_mirror::<W>() hands it back as the type it was given (None, and the mirror kept, for another type), and the rest of a document in progress is not mirrored. A failing mirror fails the document with an Error::Io with writing_to_sink; a panic in it reaches the caller. ValueFeed has the same two methods. For a Reader, read_mem_mirror and read_reader_mirror take a &mut dyn std::io::Write for the one read (§10.2). The frame readers and the demux take no mirror, as the C objects behind them do not: their caller holds the bytes it feeds.

use bovnar::ReadOptions;
use bovnar::live::DocumentFeed;

fn main() -> Result<(), bovnar::Error> {
    let mut feed = DocumentFeed::new(&ReadOptions::default())?;
    feed.set_mirror(Vec::<u8>::new())?;
    for piece in [&b".a = 1;"[..], b"  # note\n.b = 2;"] {
        feed.feed(piece, &mut |_| true)?;
    }
    feed.finish(&mut |_| true)?;
    assert_eq!(feed.take_mirror::<Vec<u8>>().unwrap(), b".a = 1;  # note\n.b = 2;");
    Ok(())
}

Frames. FramePull hands out each framed document's bytes, to be parsed by a reused DocumentFeed or ValueFeed (or parse); codec::FrameReader does the same in pure Rust. FrameParser::new(&options, continue_past_failed, max_document_size) parses every document as stream::load_documents does, streaming each frame's payload into one reused reader so that a frame is never held whole: feed(bytes, on_event, on_document) calls on_document(index, result) for each document it completes — Ok(()) or the Err with the document's error code — and its returning false ends the stream with scanner_callback_failed. feed_with(bytes, handlers, on_document) takes a ReadHandlers for the documents, as DocumentFeed::feed_with does; the frame reader is given its callbacks when the stream starts, so the first feed decides whether on_unverified and want_unit are called. A bad magic is unexpected_input_byte, a frame over the cap value_out_of_range, a stream that does not end on a frame boundary got_incomplete_bvnr_stream at finish.

use bovnar::live::{FramePull, ValueFeed};
use bovnar::{ReadOptions, stream};

fn main() -> Result<(), bovnar::Error> {
    let wire = stream::frame_documents(&[&b".id = 1;"[..], b".id = 2;"])?;
    let mut frames = FramePull::new(0)?;
    let mut values = ValueFeed::new(false, &ReadOptions::default())?;
    let mut ids = Vec::new();
    for piece in wire.chunks(5) {
        let mut input = piece;
        while let Some(doc) = frames.next(&mut input)? {
            values.reset()?;
            values.feed(doc, &mut ids)?;
            values.finish(&mut ids)?;
        }
    }
    frames.finish()?;
    assert_eq!(ids.len(), 2);
    Ok(())
}

Multiplexed streams. Demux::new(&DemuxOptions { max_message, key, deliver_events, read }) reads the document that carries the stream, with the key scope, max_message, the 4096-channel limit and every error of stream::mux_load. Each next returns a DemuxItem::Message { channel, payload } or, with deliver_events, a DemuxItem::Event for every event but the stream's chunks, in document order: the metadata before the stream comes out before its first message, and a ValueBuilder makes values of it (the demux withholds the stream's chunks but not its start and end, so the builder also hands out the stream's own key, as an empty Value::Bytes, once the stream ends; Python's DemuxFeed(values=True) leaves it out). After finish(), next on an empty slice hands out the closing events (more input is refused with an Error::Argument); reset() starts the next document: the channel buffers are kept, the channel ids (and with them the 4096-channel count) start afresh, as codec::MuxReader::reset does. recovery_count(), skipped_bytes() and declared_version() are those of the demux's reader, as on DocumentFeed. next_with(input, handlers) and finish_with(handlers) take a ReadHandlers for that reader, which parses inside next and finish: its on_verified sees every verified event, the stream's chunks included, before the demux does, and on_unverified, want_unit and on_error are a Reader's. The first call of a document decides which of on_verified, on_unverified and want_unit its reader calls, as for DocumentFeed.

use bovnar::live::{Demux, DemuxItem, DemuxOptions, ValueBuilder};
use bovnar::Writer;

fn main() -> Result<(), bovnar::Error> {
    // Metadata, the stream, and a value after it, as a C writer writes them
    let mut w = Writer::to_mem(1 << 16, false)?;
    w.begin_struct("meta")?;
    w.write_string("codec", "av1")?;
    w.end_struct()?;
    w.mux_begin("media")?;
    w.mux_send(1, b"key frame")?;
    w.mux_send(2, b"audio")?;
    w.mux_end()?;
    w.write_bool("complete", true)?;
    w.finish()?;
    let wire = w.get_output().to_vec();

    let options = DemuxOptions { key: Some("media".into()), deliver_events: true, ..DemuxOptions::default() };
    let mut demux = Demux::new(&options)?;
    let mut meta = ValueBuilder::new(false);
    let mut messages = Vec::new();
    for piece in wire.chunks(6) {
        let mut input = piece;
        while let Some(item) = demux.next(&mut input)? {
            match item {
                DemuxItem::Event(e) => meta.push(&e.data()),
                DemuxItem::Message { channel, payload } => {
                    if messages.is_empty() {
                        // Everything before the stream is here already
                        assert_eq!(meta.drain().next().map(|(k, _)| k).as_deref(), Some("meta"));
                    }
                    messages.push((channel, payload.to_vec()));
                }
            }
        }
    }
    demux.finish()?;
    while let Some(item) = demux.next(&mut &[][..])? {
        if let DemuxItem::Event(e) = item {
            meta.push(&e.data());
        }
    }
    assert_eq!(messages, [(1, b"key frame".to_vec()), (2, b"audio".to_vec())]);
    assert!(meta.drain().any(|(k, _)| k == "complete"));
    Ok(())
}

Draining. FramePull::next and Demux::next take &mut &[u8] and return one item per call; unlike the codec's readers, they do not advance the slice past each item. An item that lies whole in the input is borrowed from it without a copy; one that spans pieces or chunks is gathered in a buffer the reader keeps and reuses. Either way it borrows the reader until the next call, which the borrow checker enforces. The C object keeps a pointer into the bytes until they are drained, so pass the same slice to every call until one returns None (which empties it): the slice is not shortened meanwhile, another one is refused with an Error::Argument, and so is finish() while bytes are left. A warm Demux or FramePull allocates nothing per message or document.

Embedded documents. Writer::embed_document(key, doc) puts a document into an open writer (§11.5), one after another into a to_writer stream if you like. To read them while the outer document arrives, hand its events to an EmbeddedFeed: it feeds each embedded document's chunks to one reused DocumentFeed as they come and returns the document's value, or its error, when its octet stream closes; stream::parse_embedded gathers the bytes and starts a reader for every document instead.

use bovnar::live::{DocumentFeed, EmbeddedFeed};
use bovnar::{EventData, ReadOptions, Value, Writer};

fn main() -> Result<(), bovnar::Error> {
    let mut w = Writer::to_mem(4096, false)?;
    for n in 1..=3 {
        w.embed_document("payload", format!(".n = {n};").as_bytes())?;
    }
    w.finish()?;
    let outer = w.get_output().to_vec();

    let mut embedded = EmbeddedFeed::new("payload", false)?;
    let mut docs = Vec::new();
    let mut on_event = |d: &EventData<'_>| {
        docs.extend(embedded.push(d));
        true
    };
    let mut feed = DocumentFeed::new(&ReadOptions::default())?;
    for piece in outer.chunks(4) {
        feed.feed(piece, &mut on_event)?;
    }
    feed.finish(&mut on_event)?;
    assert_eq!(docs.len(), 3);
    assert_eq!(docs[2], Ok(Value::Struct(vec![("n".into(), Value::Int(3))])));
    Ok(())
}

live::Demux or codec::MuxReader? Both read a multiplexed stream as it arrives, with the C demultiplexer's limits and error codes.

Errors are those of the batch functions for the same document or mux stream, as Error::Parse: with a position when the document failed, the demultiplexer's code alone (octet_stream_out_of_sync, value_out_of_range, octet_stream_truncated) when the stream did, as mux_load reports them. A frame reader's errors carry no position, as load_documents' do not, and its framing errors are load_documents' too: a bad magic is unexpected_input_byte, a frame over the cap value_out_of_range and a stream cut inside a frame got_incomplete_bvnr_stream. A panic in a handler reaches the caller, as for Reader (§13).

What it costs, from cargo bench --bench live: a release build pinned to one core (taskset -c 4) of the same i7-2700K as §4.8, load average under 2; the median of three runs, each the median of nine passes. The input is a few MiB held in the cache; pieces feeds it in 1460-byte pieces, a TCP segment's payload, so most messages and documents straddle a feed. The mux_load and MuxReader columns were measured in the same run as the rest of this table, not taken from §4.8's, which is a separate run; compare figures within one table. Per message:

A message whole in the fed buffer is borrowed, so its cost does not grow with its size; one that straddles a feed or spans chunks is gathered, and copying it is most of the cost, in the codec as in the demux. mux_load copies every message into a Vec. The codec is about ten times cheaper per small message: no C call and no grammar. Per document (a struct of integers and strings per line, an octet stream every 512 lines), with the throughput in brackets:

Feeding costs what reading the whole buffer costs, wherever the pieces are cut: the time is the parser's. ValueFeed hands each assignment out as it completes. parse builds the whole document, and past 32 entries keeps an index from key to entry instead of scanning the keys already there — which took its 402 KB column from 113 ms to 30 ms.

4.10 Canonical form

bovnar::canonicalize(data, pretty, &options) re-serialises a document from its verified events through the C library's canonicalising observer (bvnr_canon_observer_*, doc/08 §3.6) and returns the bytes; canonicalize_reader(input, out, pretty, &options) reads any std::io::Read as it parses and writes to any std::io::Write as the output is made, in 64 KiB pieces, so neither is held whole.

use bovnar::{ReadOptions, canonicalize};

fn main() -> Result<(), bovnar::Error> {
    let options = ReadOptions::default();
    let canon = canonicalize(b".a = 1 ;  # one\n.b = { .c = \"x\"; };", false, &options)?;
    assert_eq!(canon, b".a=<uint:64,_10,no_unit>1;.b={.c=<utf8>\"x\";};");
    assert_eq!(canonicalize(&canon, false, &options)?, canon); // idempotent
    assert_eq!(canonicalize(b".a=1;.b={.c=\"x\";};", false, &options)?, canon);
    let mut out = Vec::new();
    bovnar::canonicalize_reader(&b"#!bovnar 1.1\n.a = 1;"[..], &mut out, true, &options)?;
    assert!(out.starts_with(b"#!bovnar 1.1\n"));
    Ok(())
}

It is the form bovnar events -d prints (-p for pretty): the compact one is a single line with no whitespace outside literals, each value written with the annotation the reader gives it (1 as <uint:64,_10,no_unit>1). Two documents that differ only in layout, comments and the spelling of separators canonicalise to the same bytes, and canonicalising the output again gives it back unchanged; the order of the keys is kept. Units are written as the document spelled them: this is not bovnar pretty-print --canonical, which writes through a writer under UnitFlags::REDUCE | UnitFlags::NUM_CANONICAL and folds them to one form. A leading #!bovnar M.N directive is kept — from an std::io::Read it is found in the first bytes read, before the reader sees them.

The document is read under options, and one the reader refuses is its Error::Parse. Under continue_on_error a document the reader had to recover from is refused too, with the first error it recovered from (code and position): the observer writes what it is fed, and the statement a recovery leaves without its value would make the output unreadable. A failing input is an Error::Io with reading_from_source_fd, a failing out one with writing_to_sink, and a panic in either reaches the caller; after an error out may hold the start of the output. The observer's C function is the reader's on_verified itself, with the observer as its userdata, so no Rust runs per event.

5. Unit helpers

The unit functions live in the bovnar::units module; Unit itself is at the crate root.

use bovnar::Unit;
use bovnar::units::{unit_factor, unit_prefix_factor, unit_to_str};

fn main() -> Result<(), bovnar::Error> {
    // Parse a unit string into a Unit
    let u = Unit::parse("k~g·m/s²")?;

    // Convert a Unit back to its canonical string
    assert_eq!(unit_to_str(&u)?, "k~g·m/s²");
    assert_eq!(u.to_string(), "k~g·m/s²"); // Display is the canonical spelling too

    // Scalar SI/IEC PREFIX factor of a unit — the prefix only, never the
    // base unit's own factor.
    assert_eq!(unit_prefix_factor(&Unit::parse("M~Hz")?), 1_000_000.0);
    assert_eq!(unit_prefix_factor(&Unit::parse("in")?), 1.0); // NOT 0.0254 — the inch has no prefix
    assert_eq!(unit_prefix_factor(&Unit::parse("h")?), 1.0);  // NOT 3600.0

    // unit_factor() takes the unit as text and is the same prefix factor
    assert_eq!(unit_factor("M~Hz")?, 1_000_000.0);
    assert_eq!(unit_factor("in")?, 1.0);
    assert_eq!(unit_factor("h")?, 1.0);

    // The FULL factor to coherent SI is Unit::factor
    assert_eq!(Unit::parse("in")?.factor()?, 0.0254);
    assert_eq!(Unit::parse("h")?.factor()?, 3600.0);
    Ok(())
}

unit_factor is the prefix scale, not the full factor. It is unit_prefix_factor on a unit given as text, and reports only what the prefixes contribute: 1000000.0 for M~Hz, 1.0 for in and h. The full factor to coherent SI is Unit::factor on the parsed unit (or unit_to_si_factor); it fails for an affine unit (°C) or one with no SI factor.

Unit is the one unit type; every function that takes a unit takes a &Unit.

5.1 The unit-profile notations (spec 1.2)

These notations are spec 1.2: in a document they need a #!bovnar 1.2 directive, while the API entry points below have no document and take them unconditionally. Unit::parse takes a profile notation as readily as the native one, and returns the same Unit either way — so everything else in this chapter works on the result unchanged. Seven namespaces are accepted — ucum:, unece:, qudt:, qudt-qk:, udunits:, om: and cf: — but each is a compile-time switch of the C library, so which of them a given build carries is a question to ask rather than assume; see available_profiles() below.

use bovnar::{ErrorCode, Unit};
use bovnar::units::{
    available_profiles, units_compatible, unit_error_code, unit_is_profile_only, unit_to_profile,
    unit_to_str, unit_to_ucum,
};

fn main() -> Result<(), bovnar::Error> {
    let vu = Unit::parse("ucum:mm[Hg]")?;
    assert_eq!(unit_to_str(&vu)?, "mmHg");               // the native canonical form
    assert_eq!(unit_to_ucum(&vu)?, "mm[Hg]");            // back to a UCUM code
    assert!(units_compatible(&vu, &Unit::parse("k~Pa")?));

    // Which profiles THIS build carries. Unit::parse fails with the same
    // Error::Argument for an absent namespace as for a bad unit;
    // unit_error_code() is what tells the two apart (49 against 32).
    assert_eq!(available_profiles(), ["ucum", "unece", "qudt", "qudt-qk", "udunits", "om", "cf"]);

    // The same unit in other vocabularies — all one Unit
    let kg = Unit::parse("k~g")?;
    assert_eq!(unit_to_profile("ucum", &kg)?, "kg");
    assert_eq!(unit_to_profile("unece", &kg)?, "KGM");
    assert_eq!(unit_to_profile("qudt", &kg)?, "KiloGM");
    assert_eq!(unit_to_profile("udunits", &kg)?, "kg");
    assert_eq!(kg.to_profile("unece")?, "KGM");           // the method form

    let iu = Unit::parse("ucum:[IU]/mL")?;
    assert!(unit_is_profile_only(&iu));                   // no native spelling exists
    assert_eq!(unit_to_str(&iu)?, "ucum:[IU].mL-1");

    let packaging = Unit::parse("unece:XBX")?;
    assert!(packaging.is_profile_only());              // a countable package
    assert_eq!(unit_to_str(&packaging)?, "unece:XBX");    // in its OWN namespace

    assert_eq!(unit_error_code("ucum:B[SPL]"), ErrorCode::UnitProfileUnsupported as i32); // 50
    assert_eq!(unit_error_code("udunits:days since 1970-01-01"), 50); // valid UDUNITS, not carryable
    assert_eq!(unit_error_code("nosuch:m"), ErrorCode::UnitProfileUnknown as i32);        // 49
    assert_eq!(unit_error_code("m/s"), 0);                // it parses
    Ok(())
}

unit_to_profile and unit_to_ucum fail rather than inventing a code, in three situations. A native unit outside that vocabulary's transliteration table has no form in it — the Old German units, the water-hardness degrees, the turbidity kinds and every currency. An opaque unit belonging to a different profile has none either: [IU] is UCUM's, so unit_to_profile("unece", …) refuses it. And a flat vocabulary (unece, qudt, qudt-qk, om) can spell only a single component — no product, quotient or exponent, though a prefixed one is fine (k~g is unece:KGM) — because a flat code is one whole token with no operator to build it out of — so k~m/h has no UNECE form even though unece:KMH parses to exactly it.

In a document the notation additionally requires a #!bovnar 1.2 directive; without it parse fails with unit_illegal. Unit::parse has no document and therefore no declared version, so it accepts the notation unconditionally.

See Unit Profiles for the transliteration tables and the codes that have no representation.

5.2 Extended unit functions

The following functions operate on Unit values and live in bovnar::units.

use bovnar::{BaseUnit, Exponent, IECPrefix, Prefix, Unit};
use bovnar::units::{
    convert_value, exponent_to_int, int_to_exponent, prefix_unit_valid, unit_convert_factor,
    unit_dimension_vector, unit_prefix_exponent, unit_prefix_factor, unit_reduce,
    unit_to_si_factor, unit_to_str_ex, unit_valid, units_compatible, UnitFlags,
};

fn main() -> Result<(), bovnar::Error> {
    let km = Unit::parse("k~m")?;
    let gib = Unit::parse("Gi~B")?;

    // Validate a Unit
    assert!(unit_valid(&km));

    // Prefix scale factor (SI or IEC) for a Unit
    assert_eq!(unit_prefix_factor(&km), 1000.0);
    assert_eq!(unit_prefix_factor(&gib), 2f64.powi(30));

    // Prefix exponent (base-10 for SI, base-2 for IEC)
    assert_eq!(unit_prefix_exponent(&km), 3);
    assert_eq!(unit_prefix_exponent(&gib), 30);

    // Validate a prefix for a base unit (IEC prefixes are only valid on bit/byte)
    let p = Prefix::Iec(IECPrefix::Gibi);
    assert!(prefix_unit_valid(p, BaseUnit::Byte));
    assert!(!prefix_unit_valid(p, BaseUnit::Meter));

    // Full SI conversion including affine terms (e.g. Celsius → Kelvin)
    let c = unit_to_si_factor(&Unit::parse("°C")?)?;
    assert!(c.is_affine);
    assert_eq!(c.affine_offset, 273.15);

    // Check convertibility: same SI dimension vector AND same quantity kinds
    assert!(units_compatible(&km, &Unit::parse("m")?));
    assert!(!units_compatible(&Unit::parse("b")?, &Unit::parse("B")?)); // the dimensions agree, the kinds do not

    // Conversion factor between two compatible units
    let conv = unit_convert_factor(&km, &Unit::parse("m")?)?;
    assert_eq!((conv.factor, conv.requires_affine, conv.ok()), (1000.0, false, true));

    // 7-element SI dimension exponent vector [m, kg, s, A, K, mol, cd]
    assert_eq!(unit_dimension_vector(&Unit::parse("m/s")?)?, [1, 0, -1, 0, 0, 0, 0]);

    // Fold every prefix out and combine repeated bases. NOT the named-SI collapse:
    // the reduced unit of k~g·m/s² is "m·g/s²", and it is
    // unit_to_str_ex(.., UnitFlags::REDUCE) that gives "N". See the warning in §5.3
    // before applying r.scale to a value you are also going to serialise.
    let r = unit_reduce(&Unit::parse("k~g·m/s²")?)?;
    assert_eq!(r.unit.to_string(), "m·g/s²");
    assert_eq!(r.scale, 1000.0);

    // Convert a scalar value between units (handles affine conversions)
    let kelvin = convert_value(25.0, &Unit::parse("°C")?, &Unit::parse("K")?)?;
    assert!((kelvin - 298.15).abs() < 1e-9);

    // ... or EXACTLY, as the reader's want_unit does: (BigRational, exact),
    // exact false for an irrational factor (° to rad)
    let v = num_rational::BigRational::from_integer(42.into());
    let (ms, exact) =
        bovnar::units::convert_rational(&v, &Unit::parse("k~m/h")?, &Unit::parse("m/s")?)?;
    assert_eq!(ms, num_rational::BigRational::new(35.into(), 3.into()));
    assert!(exact);

    // Serialise with formatting options (see UnitFlags below)
    let force = Unit::parse("k~g·m/s²")?;
    assert_eq!(unit_to_str_ex(&Unit::parse("m/s²")?, UnitFlags::ASCII_EXP)?, "m/s^2"); // ^N instead of superscripts
    assert_eq!(unit_to_str_ex(&force, UnitFlags::REDUCE)?, "N");                      // reduce first — but see the warning below
    assert_eq!(unit_to_str_ex(&force, UnitFlags::REDUCE | UnitFlags::ASCII_EXP)?, "N");

    // Exponent ↔ integer conversions
    assert_eq!(exponent_to_int(Exponent::NEG_SQUARE), -2);
    assert_eq!(int_to_exponent(-2), Exponent::NEG_SQUARE);
    Ok(())
}