#[derive(Durable)] turns your own struct or enum into a durable type, as long as every persisted field is itself Durable.

What to import

Two crates: kladde for the machinery, kladde-types for the containers. Neither is on crates.io yet, so depend on the repository:

[dependencies]
kladde = { git = "https://github.com/kladde-dev/kladde-rs" }
kladde-types = { git = "https://github.com/kladde-dev/kladde-rs" }

You do not need kladde-derive or kladde-persist. The macro is re-exported from kladde behind its derive feature, which is on by default, and generated code is rooted at ::kladde, which re-exports every item it names. That is deliberate: if you had to add kladde-persist yourself, a version disagreeing with kladde’s would give you two distinct copies of the Durable trait and an error message that prints the expected and found types identically.

Here is a complete program:

use kladde::{Kladde, Durable};
use kladde_types::DurableVec;
 
#[derive(Durable)]
enum PhoneNumber {
    Mobile(String),
    Landline(String),
}
 
#[derive(Durable)]
struct Contact {
    email: String,
    phones: DurableVec<PhoneNumber>,
    starred: bool,
}
 
fn main() -> kladde::Result<()> {
    let mut contact = Kladde::new(Contact {
        email: String::from("ada@example.com"),
        phones: DurableVec::new(),
        starred: false,
    });
 
    let mut contact_mut = contact.get_mut();
    contact_mut.starred_mut().set(true)?;
    contact_mut
        .phones_mut()
        .push(PhoneNumber::Mobile(String::from("555-0100")))?;
    Ok(())
}

The Durable in that use is the derive macro. It shares its name with the Durable trait, which is legal and deliberate — they live in different namespaces, exactly as serde’s Serialize does. If you need to name the trait explicitly in the same file, import it under an alias.

Structs

The macro generates a Mut type — ContactMut — with a _mut() accessor per field, and a set that replaces the whole value:

let mut contact = /* ... a ContactMut ... */;
contact.starred_mut().set(true)?;
contact.phones_mut().push(number)?;

It also generates a ContactParts struct, and a parts() method on the Mut that returns the Muts of all fields at once, for when you need more than one at a time. A tuple struct’s accessors are named by position — field_0_mut(), field_1_mut() — and its parts() returns a tuple struct.

A struct is its fields’ encodings, back to back, inline in whatever contains it. A field’s Mut finds where the field starts: at a constant offset up to the first field whose size depends on its value — a varint, text, a container — and after that at the sum of the encoded sizes of the fields before it, which the in-memory values know. Integers wider than a byte are varints, so a u32 takes one byte below 128 and up to five above.

That includes primitive fields. bool, i32, char and friends all implement Durable, specifically so the macro can treat every field uniformly rather than special-casing leaves. So do tuples of up to twelve Durable types, encoded like a tuple struct, Option<T>, Box<T>, which is persisted as the T it holds, String, and Vec<T> of fixed-size elements.

Fixed-size values

Fixed<T> keeps a value at the same size whatever it is: every integer at its full width, every char in four bytes, and every enum with its discriminant at a fixed width and its variant padded with zeros to the largest. Use it for a field that changes often, such as a counter, which would otherwise change size whenever it crosses a power of 128, and for the elements of a large vector, which then finds element i by multiplication, keeps no index of where its elements start, and may be a plain Vec.

A derived type can be wrapped in Fixed only if it is marked #[kladde(bounded)], which requires every field’s type to have a fixed form too:

#[derive(Durable)]
#[kladde(bounded)]
struct Shape {
    x: u32,
    y: u32,
    kind: ShapeKind,       // also #[kladde(bounded)]
}
 
#[derive(Durable)]
struct Drawing {
    shapes: Vec<Fixed<Shape>>,   // eight bytes per shape, plus the kind's
    revision: Fixed<u64>,
}

Fixed<T>’s Mut replaces the value whole, with set(Fixed(...)): changing one field means building the whole value, and writing all of it, which for a fixed-size value is an overwrite in place. Types holding text, a container, or themselves have no fixed form, and wrapping one in Fixed fails to compile with an error that says so. A generic type marked #[kladde(bounded)] has a fixed form wherever its parameters do.

Newtypes

A single-field struct marked #[kladde(transparent)] is persisted exactly as its field — the same bytes and the same fingerprint — so wrapping a field in a newtype changes nothing in the file:

#[derive(Durable)]
#[kladde(transparent)]
struct Meters(u32);
 
fn walk(distance: &mut Kladde<Meters>) -> kladde::Result<()> {
    distance.get_mut().get_mut().set(42)
}

Its Mut’s get_mut() returns the field’s Mut.

Enums

An enum is its discriminant, as a varint, followed by the selected variant’s fields, each variant encoded like a struct in its own right. So a value takes the size of its own variant, not of the largest.

In the schema, every variant holds exactly one value: a unit variant holds (), a variant with one unnamed field such as Mobile(String) holds that field’s type, and any other variant holds a struct of its fields, named after the variant, its positional fields named by position, "0", "1". So moving a variant’s fields into a struct of their own changes neither the file nor the fingerprint: R { w: u32, h: u32 } and R(Rect), with struct Rect { w: u32, h: u32 }, are the same variant on file.

To mutate the current variant in place, match on the Mut’s parts(). It hands out the Muts of the current variant’s fields, in an enum named after yours, PhoneNumberParts, with the same variants:

use kladde::{Kladde, Durable};
 
#[derive(Durable)]
enum PhoneNumber {
    Mobile(String),
    Landline(String),
}
 
fn main() -> kladde::Result<()> {
    let mut number = Kladde::new(PhoneNumber::Mobile(String::from("555-01")));
 
    let mut number_mut = number.get_mut();
    match number_mut.parts() {
        PhoneNumberParts::Mobile(mut digits) => digits.push_str("00")?,
        PhoneNumberParts::Landline(mut digits) => digits.set("555-0199")?,
    }
 
    // To switch to another variant, replace the whole value.
    number_mut.set(PhoneNumber::Landline(String::from("555-0123")))?;
    assert!(matches!(number.get(), PhoneNumber::Landline(digits) if digits == "555-0123"));
    Ok(())
}

Each field’s Mut writes inside its field, so the variant stays what it was. set replaces the whole value, which is how the variant changes: it splices the new value’s encoding over the old one’s. parts() borrows the enum’s Mut, so the compiler stops you from calling set while you still hold a field’s Mut.

The discriminant is Rust’s own: the one you write (Mobile = 1), or else one more than the previous variant’s, counting from 0; negative discriminants and signed or pointer-sized reprs are not supported. The file holds it as a varint, so discriminants below 128 take one byte. Inside a Fixed value it takes a fixed width: the smallest of 1, 2, 4 or 8 bytes that holds the largest discriminant, unless an integer #[repr] such as #[repr(u16)] fixes it. Explicit values on variants with fields need a #[repr] anyway, as Rust requires:

#[derive(Durable)]
#[repr(u32)]
enum PhoneNumber {
    Mobile(String) = 1,
    Landline(String) = 2,
}

Trait objects

A Box<dyn Shape> is not durable: a file can hold only values whose types it can name. Hold an enum of the shapes instead, and let it implement the trait by forwarding to its variants: mark the trait #[kladde::dispatch], and the enum #[kladde(dispatch(Shape))].

use kladde::{Durable, Kladde};
 
#[kladde::dispatch]
trait Shape {
    fn area(&self) -> f32;
}
 
#[derive(Durable)]
struct Circle { r: f32 }
impl Shape for Circle {
    fn area(&self) -> f32 { 3.0 * self.r * self.r }
}
 
#[derive(Durable)]
struct Rect { w: f32, h: f32 }
impl Shape for Rect {
    fn area(&self) -> f32 { self.w * self.h }
}
 
#[derive(Durable)]
struct Frame { outer: Rect, hole: Rect, angle: f32, label: u32 }
impl Shape for Frame {
    fn area(&self) -> f32 { self.outer.area() - self.hole.area() }
}
 
#[derive(Durable)]
#[kladde(dispatch(Shape))]
#[repr(u32)]
enum AnyShape {
    Circle(Circle) = 1,
    Rect(Rect) = 2,
    Frame(Box<Frame>) = 3,  // boxed, so that a circle stays small in memory
}
 
fn main() -> kladde::Result<()> {
    let mut shape = Kladde::new(AnyShape::from(Circle { r: 1.0 }));
    assert_eq!(shape.get().area(), 3.0);
 
    let frame = Frame {
        outer: Rect { w: 3.0, h: 3.0 },
        hole: Rect { w: 1.0, h: 1.0 },
        angle: 0.0,
        label: 7,
    };
    shape.get_mut().set(frame.into())?;   // `From<Frame>` boxes it
    if let AnyShapeParts::Frame(mut f) = shape.get_mut().parts() {
        f.hole_mut().w_mut().set(2.0)?;
    }
    assert_eq!(shape.get().area(), 7.0);
    Ok(())
}

The enum implements every method of the trait, each forwarding to the value its current variant holds, and converts From each variant’s value. It is an ordinary durable enum otherwise: you mutate a variant through parts(), and switch variants with set.

Each variant holds one value, whose type implements the trait, or the enum fails to compile, at the variant. The discriminants are optional, as on every enum, but explicit ones keep your files readable when you add or reorder implementations. A variant may box its value, which keeps one large implementation from making every value of the enum as large in memory; it changes nothing in the file, so you can box or unbox a variant later.

The trait’s methods must take self, &self or &mut self, and mention Self nowhere else, and the trait and the enum must live in one crate; the derive macro says why.

Generics

Type parameters work, and each gets a Durable bound:

#[derive(Durable)]
struct Labelled<T> {
    label: String,
    value: T,
}

Lifetime and const parameters are not supported.

What the derive needs

Every persisted field must be Durable. In practice that means:

  • primitives and String — fine as-is;
  • Vec<T> — fine where T is fixed-size; for any other T it fails to compile, and the message points you to DurableVec<T>;
  • kladde containers — fine as-is;
  • your own derived types — fine, and they nest arbitrarily;
  • HashMap<K, V>, PathBuf and other standard types — not Durable. Use the kladde equivalents, such as DurableMap<K, V>. This is deliberate: a field’s type says whether it is durable, and the compile error tells you so.

Non-persisted fields

Sometimes a struct has a field that should not be stored — a cache, a handle, something derived. The derive macro has no attribute for this yet; the workaround is a hand-written implementation that encodes only the fields you want persisted.

Doing so does not make your type opaque to the format. A hand-written implementation that encodes exactly the bytes of a struct with two fields has that struct’s descriptor. The presence of a third, non-persisted field in your Rust source is invisible.

Encoding stability

A few things you should know before you ship a file format built on a derived type.

Field order is encoding. Reordering fields in the source changes the order of their encodings, and therefore changes the type’s fingerprint, and Kladde::open refuses a file whose fingerprint differs from your type’s. Once evolution lands, reordering will be non-breaking, because fields are identified by name.

Variant order is encoding only through implicit discriminants. A variant without an explicit discriminant takes the next number, so inserting or reordering variants renumbers the ones after them, and changes the fingerprint. With explicit discriminants, reordering changes nothing, since enum variants are canonicalized by discriminant value.

The discriminant’s width in a Fixed value is encoding too, unless you pin it. Without a #[repr], adding a 257th variant, or giving one a discriminant of 256 or more, widens the discriminant of every Fixed value of the type, and changes the fingerprint. An integer #[repr], such as #[repr(u16)], fixes the width up front.

Renaming a type is free. A struct’s or enum’s own name is not fingerprinted. Renaming a field or a variant is not free, since those are the identities evolution reconciles by.