Rust

Rust is the reference implementation of Iris. The gecode-iris crate re-exports the public reader API from iris-core; import it as gecode_iris. It returns named, typed entries, including arrays whose rows have different lengths.

Add a local dependency

Use Rust 1.88 or newer. Crates.io publication is planned; all workspace crates currently set publish = false. With your application directory beside an Iris checkout named iris, add this to your application’s Cargo.toml:

Cargo.toml

[dependencies]
gecode-iris = { path = "../iris/rust/gecode-iris" }

Adjust the path for your checkout. Keep the full Rust workspace: the umbrella crate depends on the sibling implementation crates. Package versions and language versions are separate; the current Rust packages are 0.1.0 and implement Iris 0.1.

Parse once, read input, borrow a row

Put this in your application’s src/main.rs. It follows the umbrella crate’s doc-tested example, wrapped in main.

src/main.rs

fn main() -> Result<(), Box<dyn std::error::Error>> {
    use gecode_iris::{Params, Spec};

    let spec = Spec::parse(b"n:int row[n]:int", "example.iris")?;
    let data = spec.read(b"3 10 20 30", "input.txt", &Params::new())?;
    assert_eq!(data.int("n")?, 3);
    assert_eq!(data.ints("row", &[])?, &[10, 20, 30]);
    Ok::<(), Box<dyn std::error::Error>>(())
}

Spec::parse validates the reader spec. The declaration reads n, then a row of n integers. Spec::read reads input bytes using caller parameters; an empty Params supplies none. Origin names such as example.iris and input.txt appear in diagnostics.

Data::int returns a scalar. Data::ints borrows an integer row without copying it. The empty index path selects the whole one-dimensional row here; for a column of rows, the path selects a row. The returned Data owns its entries and does not borrow the original input bytes, so the same Spec can read another input.

To run the original example from the Iris checkout, use its rust/ directory:

cargo test --locked -p gecode-iris --doc

Files, parameters, and output

Spec::read_path reads a file with caller parameters. Spec::catalog and catalog_path traverse a multi-instance file and return catalog data. The instance parameter selects an instance during a read by ordinal or name; see parameters and instances.

Data::entries visits entries in definition order. Data::value selects a borrowed value by name and index path. to_json and to_dzn return buffered output; write_dzn writes to an io::Write destination. A stream error can leave partial bytes in that destination. The data model and dzn appendix define the representations.

Handle failures

Parsing and reading return Failure. Failure::Language contains an error with a stable language code, source locations and, when applicable, a record path. Work-budget exhaustion is a language failure (E-BUDGET). Failure::Host covers host failures such as file acquisition or cancellation. Failure::Unsupported identifies an implementation feature that has not been implemented.

After a successful read, typed lookup returns AccessError for an unknown name, invalid index path or incompatible requested type. These are host API usage errors. Failure, HostError and AccessError are non-exhaustive; matching their variants requires a fallback arm.

For more detail, read the umbrella crate source and core API guide. Publication on docs.rs is planned; until then, cargo doc in the workspace builds the API documentation locally.