Struct Archive 

pub struct Archive {
    pub collection: Option<Collection>,
    pub collection_name: Option<String>,
    pub recordings: Vec<RecordingRef>,
    pub archive_path: Option<String>,
    /* private fields */
}

An opened .sigmf archive: a tar file of recordings and an optional collection.

Metadata members are indexed and parsed when the archive is loaded; dataset members are read lazily on request. Each recording::RecordingRef carries the SHA-512 digest of its metadata member, which is re-checked whenever the metadata is read back from the archive.

An archive created with Default has no archive_path; in that case recordings are resolved as <name>.sigmf-meta and <name>.sigmf-data files in the current working directory.

Examples

let archive = sigmf::Archive::load("recordings.sigmf")?;
for recording in archive.get_recordings() {
    let metadata = archive.get_meta_from_recording(&recording)?;
    println!("{}: {}", recording.get_name(), metadata.global().datatype);
}

Fields

collection: Option<Collection>

The archive’s .sigmf-collection object, if it has one.

collection_name: Option<String>

Name (file stem) of the collection member, e.g. "collection" for collection.sigmf-collection.

recordings: Vec<RecordingRef>

References to the recordings in the archive, in member order.

archive_path: Option<String>

Filesystem path of the .sigmf tar file backing this archive.

Implementations

impl Archive

pub fn validate_collection_references(&self) -> Option<ValidationReport>

Checks that the archive’s collection streams resolve to its recordings.

Each core:streams entry is matched by name against the archive’s recordings. A missing recording yields an unresolved-recording-reference warning (making the status ValidationStatus::NotChecked); a recording whose metadata hash differs (case-insensitively) from the reference yields a collection-reference-digest-mismatch error.

Returns None if the archive has no collection.

impl Archive

pub fn new(path: String) -> Self

Creates an empty archive handle pointing at path without reading it.

Use Archive::load to open and index an existing archive.

pub fn load(path: &str) -> Result<Self, SigmfError>

Opens and indexes a .sigmf tar archive.

All .sigmf-meta members are parsed and at most one top-level .sigmf-collection member is accepted. Equivalent to ArchiveWriter::load.

Errors

Returns an error if path does not end in .sigmf, cannot be read, is not a valid tar file, contains unsafe or duplicate member paths, non-regular members, invalid metadata, oversized (> 1 MB) metadata, or no recordings.

pub fn save(&self, save_path: &str) -> Result<(), SigmfError>

Writes a new .sigmf archive at save_path containing only this archive’s current recordings.

Members are copied from the source archive at archive_path. Metadata and dataset members of recordings that were removed (for example by retain_recordings_with_minimum_frames) are dropped, other members are preserved, and the collection is replaced when collection is set. The destination must not already exist.

Errors

Returns an error if the source path is unset, the destination exists, a referenced member is missing, or a metadata digest no longer matches its recording::RecordingRef.

pub fn retain_recordings_with_minimum_frames( &mut self, minimum_frames: Integer, ) -> Result<(), SigmfError>

Removes recordings whose datasets hold fewer than minimum_frames frames.

Frame counts are derived from member sizes, core:num_channels, core:datatype, NCD core:header_bytes, and core:trailing_bytes without reading sample data. Metadata-only recordings count as zero frames.

Errors

Returns an error if metadata cannot be read or a dataset layout is inconsistent with its size. On error the recordings are left unchanged.

pub fn set_recordings(&mut self, recordings: Vec<RecordingRef>)

Replaces the list of recording references.

pub fn set_collection(&mut self, collection: Collection)

Sets the collection, naming it collection if no name is set yet.

pub fn set_collection_member( &mut self, name: impl Into<String>, collection: Collection, ) -> Result<(), SigmfError>

Sets the collection along with its archive member name (file stem).

Errors

Returns SigmfError::InvalidMetadata if name is not a safe, top-level member name.

pub fn set_path(&mut self, path: &str)

Sets the path of the backing .sigmf file.

pub fn add_recording(&mut self, recording: RecordingRef)

Appends a recording reference.

pub fn add_collection(&mut self, collection: Collection)

Sets the collection; alias for Archive::set_collection.

pub fn get_recordings(&self) -> Vec<RecordingRef>

Returns a copy of the recording references.

pub fn get_collection(&self) -> Option<Collection>

Returns a copy of the collection, if any.

pub fn get_path(&self) -> Option<String>

Returns the path of the backing .sigmf file, if set.

pub fn get_names(&self) -> Vec<String>

Returns the name of every recording, in order.

A recording’s name is its member path without the .sigmf-meta extension, e.g. "dir/burst" for dir/burst.sigmf-meta.

pub fn get_recording_from_name(&self, name: &str) -> Option<RecordingRef>

Finds a recording reference by name.

pub fn get_meta_from_recording( &self, recording: &RecordingRef, ) -> Result<Metadata, SigmfError>

Returns the parsed metadata for recording.

Metadata parsed at load time is reused when its digest still matches; otherwise the member is re-read and its SHA-512 digest is checked against RecordingRef::get_hash.

Errors

Returns SigmfError::HashMismatch if the digest differs, SigmfError::NotFound if the member is missing, or a parse error.

pub fn get_meta_from_name(&self, name: &str) -> Result<Metadata, SigmfError>

Returns the parsed metadata for the recording called name.

Errors

Returns SigmfError::NotFound if no recording has that name, or any error from Archive::get_meta_from_recording.

pub fn get_samples_from_recording( &self, recording: &RecordingRef, ) -> Result<Vec<SampleValue>, SigmfError>

Reads and decodes every sample of recording into memory.

See Archive::get_samples_from_name.

pub fn get_samples_from_name( &self, name: &str, ) -> Result<Vec<SampleValue>, SigmfError>

Reads and decodes every sample of the recording called name into memory.

Samples are returned frame by frame, interleaved across core:num_channels. The whole dataset member is decoded as plain samples, so use recording_file::Recording for NCD datasets or for streaming large recordings.

Errors

Returns SigmfError::NoDataset for metadata-only recordings, or an error if the dataset cannot be read or does not hold whole frames.

Trait Implementations

impl Debug for Archive

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

Formats the value using the given formatter.

impl Default for Archive

fn default() -> Self

Returns the “default value” for a type.