Crate asdf 

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

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());

Writing

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")?;

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.

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")?;

Structs

AsdfBuilder

Builds an ASDF file.

AsdfFile

An ASDF file opened for reading.

Civil

A calendar breakdown, in the format’s own timescale.

Datatype

A complete datatype.

Error

An error from the ASDF engine.

EventOptions

What to include in the stream.

ExtensionMetadata

A core/extension_metadata record: an extension the file was written with, and which a reader needs to make sense of its tagged values.

Field

One field of a compound datatype.

History

A file’s history: the extensions it needs and what was done to it.

HistoryEntry

A core/history_entry record: something that was done to the file.

InfoOptions

What to include in the rendering.

Location

An observer’s location, for the location-sensitive scales.

Meta

The core/asdf root’s own metadata.

Ndarray

A parsed core/ndarray.

Software

A core/software record: a piece of software, named and versioned.

Time

A time as it appears in a file.

Tree

A parsed ASDF tree.

Value

One value in a tree.

Version

A parsed version string.

Enums

ByteOrder

Byte order, mirroring asdf_byteorder_t.

ChecksumStatus

The outcome of verifying a block’s checksum.

Compression

A compression method understood by this library.

Element

One decoded array element.

ErrorCode

The error codes asdf_error_code reports.

Event

One event from the stream.

Mask

How missing values are marked.

ScalarType

The scalar element types, mirroring asdf_scalar_datatype_t.

Source

Where an array’s data comes from.

TimeFormat

How a time is written, mirroring asdf_time_format_t.

TimeScale

The time scale, mirroring asdf_time_scale_t.

Traits

ArrayElement

A scalar type an array can be written from and read back as.

Functions

native_byte_order

The default datatype for an array element, matching this machine.

render_event

Render an event the way asdf_event_print does.

scalar_datatype

A datatype for one of the scalar types.

Type Aliases

Result

The result type used throughout this crate.