Struct AsdfFile 

pub struct AsdfFile { /* private fields */ }

An ASDF file opened for reading.

Implementations

impl AsdfFile

pub fn open(path: impl AsRef<Path>) -> Result<Self>

Open a file from disk.

The file is memory-mapped, so a large array costs nothing until it is actually read.

pub fn from_bytes(bytes: Vec<u8>) -> Result<Self>

Open a file already held in memory.

pub fn format_version(&self) -> &Version

The ASDF file-format version from the header line.

pub fn standard_version(&self) -> Option<&Version>

The ASDF Standard version, if the file records one.

pub fn tree(&self) -> Result<Option<Tree>>

The YAML tree.

A file in exploded form may legitimately have none, hence the Option.

pub fn tree_inlined(&self) -> Result<Option<(Tree, Vec<String>)>>

The tree with every block-backed array replaced by inline data.

This is the transformation the ASDF Standard’s reference corpus prescribes before comparing files. Arrays whose data lives outside this file are left alone and named in the returned list.

pub fn block_count(&self) -> usize

The number of binary blocks.

pub fn block_data(&self, index: usize) -> Result<Cow<'_, [u8]>>

A block’s data, decompressed if it needs to be.

An uncompressed block borrows directly from the mapped file.

pub fn block_raw(&self, index: usize) -> Result<&[u8]>

A block’s bytes exactly as stored, without decompressing.

pub fn block_compression(&self, index: usize) -> Result<Compression>

How a block is compressed.

pub fn verify_block(&self, index: usize) -> Result<ChecksumStatus>

Verify a block’s MD5 checksum.

An absent checksum is reported as ChecksumStatus::Absent rather than as a failure: the standard makes it optional.

pub fn read_array(&self, array: &Ndarray) -> Result<Vec<Element>>

Read every element of a block-backed or external array.

An array whose source names another file – the standard’s exploded form – is followed, provided this file was opened from a path and the name resolves to a file beneath its directory.

An array whose data is inline in the tree carries no block, so it is an error here; read one with Tree::read_array, which has the tree the values live in.

pub fn read_array_at(&self, path: &str) -> Result<Vec<Element>>

Read every element of the array at path, wherever its data lives.

The one call that covers all four cases: a block in this file, the last block, another file, or inline in the tree. It parses the tree each time, so a loop over many arrays is better served by holding a Tree and using Tree::read_array or AsdfFile::read_array.

pub fn read_array_f64(&self, array: &Ndarray) -> Result<Vec<f64>>

Read an array converted to f64.

Every numeric type converts; a string or compound array does not.

pub fn read_array_i64(&self, array: &Ndarray) -> Result<Vec<i64>>

Read an array converted to i64.

A float with a fractional part is an error rather than being truncated silently.

pub fn read_array_f64_at(&self, path: &str) -> Result<Vec<f64>>

AsdfFile::read_array_at converted to f64.

pub fn read_array_i64_at(&self, path: &str) -> Result<Vec<i64>>

AsdfFile::read_array_at converted to i64.

pub fn read_array_of<T: ArrayElement>(&self, path: &str) -> Result<Vec<T>>

Read an array as a Vec of any scalar type.

A value that will not fit the requested type is an error rather than a silent truncation: a caller asking for Vec<i32> wants the numbers the file holds, not whatever survives the cast.

let file = asdf::AsdfFile::open("observation.asdf")?;
let counts: Vec<u16> = file.read_array_of("data")?;

pub fn edit(&self) -> Result<AsdfBuilder>

A builder holding this file’s tree and blocks, for editing.

This is how a file is changed and written back: open it, edit the builder, write it out. The blocks are carried over decompressed and with their block indices intact, so every source: N in the tree still points where it did.

use asdf::AsdfFile;

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

pub fn info(&self, options: InfoOptions) -> Result<String>

Render the file the way asdf info does.

The rendering is what the command-line tool prints, so it is a human-readable summary rather than anything to parse.

pub fn events(&self, options: EventOptions) -> Vec<Event>

The low-level event stream: what the file contains, in order.

Rather than building a tree, this reports what is there – the version headers, any comments, the block index, the tree’s extent and optionally the YAML events inside it, then each block. It is what asdf events prints, and what a tool inspecting a damaged file wants, since a tree that will not parse still yields everything around it.

Trait Implementations

impl Debug for AsdfFile

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.