Read and write ASDF files from Rust.

ASDF (Advanced Scientific Data Format) is a hybrid format: a YAML tree describing the data, followed by binary blocks holding it. It is the native format of the Nancy Grace Roman Space Telescope and is widely used across astronomy.

This is the idiomatic Rust face of the library. It borrows rather than copies wherever the format allows, returns [Result] rather than error codes, and needs no unsafe. For C interoperability use the libasdf-rs crate instead, which exposes the same engine through libasdf's C ABI.

Reading

# fn main() -> Result<(), Box<dyn std::error::Error>> {
use asdf::AsdfFile;

let file = AsdfFile::open("observation.asdf")?;
let tree = file.tree()?.expect("a tree");

// Values are addressed by path.
if let Some(name) = tree.get("meta/instrument/name").and_then(|v| v.as_str()) {
    println!("instrument: {name}");
}

// An array reads back as whatever scalar type its values fit.
let values: Vec<f64> = file.read_array_of("data")?;
println!("{} elements", values.len());
# Ok(())
# }

Writing

# fn main() -> Result<(), Box<dyn std::error::Error>> {
use asdf::AsdfBuilder;

let mut builder = AsdfBuilder::new();
builder.set_str("name", "Dennis Richie")?;
builder.set_i64("foo", 42)?;

// An array's data goes in a binary block, referenced from the tree.
let squares: Vec<u64> = (0..100).map(|i| i * i).collect();
builder.set_array("powers/squares", &squares)?;

builder.write_to_path("out.asdf")?;
# Ok(())
# }

Editing

An existing file is changed through [AsdfFile::edit], which carries the tree and the blocks over so every source: N still points where it did.

# fn main() -> Result<(), Box<dyn std::error::Error>> {
use asdf::{AsdfFile, Compression};

let file = AsdfFile::open("observation.asdf")?;
let mut edited = file.edit()?;
edited.set_str("meta/observer", "M. Curie")?;
edited.recompress(Compression::Zlib).write_to_path("observation.asdf")?;
# Ok(())
# }