DOCS / TUTORIAL

Getting started in Rust

Add packvium, call pack_json() with the request as a string, and read the result back out of the JSON it returns.

Docs for Packvium 1.11.x · contract stable since 1.0

01Install#

Rust 1.88 or newer. The published crate is named packvium; the library keeps its internal name, packvium_core, so every call site writes packvium_core:: even though Cargo.toml names the dependency packvium.

cargo add packvium

02Call pack_json() and read the result#

The crate's whole public surface for packing is one JSON contract in, one JSON string out — the same contract every other language binding speaks.

let request = r#"{
    "items": [
        {"id": "book", "quantity": 4,
         "dimensions": {"length": "210", "width": "140", "height": "30"}}
    ],
    "containers": [
        {"id": "box", "inner_dimensions": {"length": "400", "width": "300", "height": "250"}}
    ]
}"#;

let result = packvium_core::pack_json(request)?;

03Handle items the engine could not place#

Parse the result as JSON and read unpacked_items the same way any consumer of the contract does — the field names are the schema, not a Rust-specific shape.

let parsed: serde_json::Value = serde_json::from_str(&result)?;
let refused = parsed["unpacked_items"].as_array().map_or(0, Vec::len);

04What is already checked before you see it#

Every placement pack_json() returns has been re-checked by validation logic independent of the search that found it. The fixture pages on this site show that validator's verdict next to the engine's for the same request, so a wrong placement is not something you have to take on trust.

05Check a result yourself#

From 1.7.0 the reference validator ships in the crate. validate_json(request, result) reads the two JSON strings, shares no code with the solvers or with IndependentValidator, and returns every ResultIssue it finds; an empty vector means the result is valid, and a result without the documented shape is Err(MalformedResult).

let result = packvium_core::pack_json(request)?;
let issues = packvium_core::validate_json(request, &result)?;
for issue in &issues {
    println!("{}: {}", issue.code, issue.detail);
}

06Next steps#

Read the request and result contract for every public field, run your own dimensions in the Playground, or open examples/shapes.rs for items that are not their own bounding box.