Struct Metadata 

pub struct Metadata { /* private fields */ }

A complete SigMF metadata document (.sigmf-meta).

Holds the global object, the captures and annotations arrays, and any unrecognized top-level keys. When parsed with Metadata::from_slice (or from_reader / from_path) the exact input bytes are retained and exposed through Metadata::original_bytes; any mutation through this type’s methods discards them.

Examples

use sigmf::capture::Capture;
use sigmf::global::{Datatype, Global};
use sigmf::meta::Metadata;

let global = Global::new("1.2.6", "cf32_le".parse::<Datatype>()?);
let mut metadata = Metadata::new(global, Vec::new(), vec![Capture::new(0)]);
metadata.set_sample_rate(1_000_000.0);

let bytes = metadata.to_vec()?;
let parsed = Metadata::from_slice(&bytes)?;
assert_eq!(parsed.get_sample_rate(), Some(1_000_000.0));
assert_eq!(parsed.captures().len(), 1);

Implementations

impl Metadata

pub fn global_extension<T: SigmfExtension>(&self) -> Result<T, SigmfError>

Reads extension T from the fields of the global object.

Only the keys listed in SigmfExtension::FIELDS are considered; absent keys are simply omitted before deserialization.

Errors

Returns SigmfError::InvalidMetadata if T’s scope is not ExtensionScope::Global or the fields do not deserialize into T.

pub fn set_global_extension<T: SigmfExtension>( &mut self, extension: &T, ) -> Result<(), SigmfError>

Writes extension T into the global object.

All of T’s declared FIELDS are first removed, then the serialized fields are inserted, so fields omitted by serialization (e.g. None with skip_serializing_if) are cleared. core:extensions is not modified.

Errors

Returns SigmfError::InvalidMetadata if T’s scope is not ExtensionScope::Global, extension does not serialize to a JSON object, or it serializes a key not listed in FIELDS; returns SigmfError::Serde if serialization fails. The metadata is unchanged on error.

pub fn remove_global_extension<T: SigmfExtension>( &mut self, ) -> Result<(), SigmfError>

Removes all of extension T’s declared fields from the global object.

core:extensions is not modified.

Errors

Returns SigmfError::InvalidMetadata if T’s scope is not ExtensionScope::Global.

impl Metadata

pub fn new( global: Global, annotations: Vec<Annotation>, captures: Vec<Capture>, ) -> Self

Creates a metadata document from its global object and its annotations and captures arrays.

The document has no top-level extension fields and no retained original bytes. No validation is performed; see Metadata::validate.

Examples

use sigmf::capture::Capture;
use sigmf::global::{Datatype, Global};
use sigmf::meta::Metadata;

let global = Global::new("1.2.6", "ri16_le".parse::<Datatype>()?);
let metadata = Metadata::new(global, Vec::new(), vec![Capture::new(0)]);
assert_eq!(metadata.get_version(), "1.2.6");
assert!(metadata.annotations().is_empty());

pub fn from_slice(bytes: &[u8]) -> Result<Self, SigmfError>

Parses a metadata document from JSON bytes.

Before deserializing, the input is checked for duplicate object keys and for the basic shape required by SigMF: a global object with string core:version and core:datatype, captures and annotations arrays whose entries are objects with a non-negative integer core:sample_start, and no explicit null for optional core fields. Unknown keys are preserved. The input bytes are retained and available via Metadata::original_bytes.

This does not run full semantic validation; see Metadata::validate.

Errors

• crate::SigmfError::ResourceLimit if bytes exceeds the 1 MB metadata size limit.
• crate::SigmfError::InvalidJson if the input is not valid JSON or an object contains a duplicate key.
• crate::SigmfError::InvalidMetadata if a required field is missing, has the wrong type, an optional core field is null, or the document otherwise fails to deserialize (including an invalid core:datatype).

Examples

use sigmf::meta::Metadata;

let json = br#"{
    "global": {"core:version": "1.2.6", "core:datatype": "cf32_le"},
    "captures": [{"core:sample_start": 0, "core:frequency": 915e6}],
    "annotations": []
}"#;
let metadata = Metadata::from_slice(json)?;
assert_eq!(metadata.get_datatype().to_string(), "cf32_le");
assert_eq!(metadata.captures()[0].frequency, Some(915e6));
assert_eq!(metadata.original_bytes(), Some(&json[..]));

assert!(Metadata::from_slice(br#"{"global": {}}"#).is_err());

pub fn to_vec(&self) -> Result<Vec<u8>, SigmfError>

Serializes the document as compact JSON.

Optional fields that are unset are omitted, and extension fields are written back alongside the core fields. The output is freshly serialized and is not guaranteed to match Metadata::original_bytes.

Errors

Returns crate::SigmfError::Serde if serialization fails.

pub fn to_vec_pretty(&self) -> Result<Vec<u8>, SigmfError>

Serializes the document as pretty-printed (indented) JSON.

Errors

Returns crate::SigmfError::Serde if serialization fails.

pub fn write_to( &self, writer: impl Write, policy: ValidationPolicy, ) -> Result<String, SigmfError>

Validates the document under policy, then writes its compact JSON serialization to writer.

Returns the SHA-512 digest (lowercase hex) of the exact bytes written, suitable for a collection’s core:streams hash entry. Validation warnings do not prevent writing.

Errors

• crate::SigmfError::InvalidMetadata if validation fails; nothing is written in that case.
• crate::SigmfError::Serde if serialization fails.
• crate::SigmfError::Io if writing to writer fails.

pub fn save_new( &self, path: impl AsRef<Path>, policy: ValidationPolicy, ) -> Result<String, SigmfError>

Validates the document under policy and atomically writes it to a new file at path.

The JSON is written to a temporary sibling file, synced, and then published under path without overwriting an existing file. Returns the SHA-512 digest (lowercase hex) of the bytes written.

Errors

• crate::SigmfError::InvalidMetadata if validation fails or path does not name a file.
• crate::SigmfError::Serde if serialization fails.
• crate::SigmfError::Io if path already exists or any file system operation fails.

pub fn replace_atomic( &self, path: impl AsRef<Path>, policy: ValidationPolicy, ) -> Result<String, SigmfError>

Validates the document under policy and atomically writes it to path, replacing any existing file.

The JSON is written to a temporary sibling file, synced, and renamed over path, so readers observe either the old or the new contents. Returns the SHA-512 digest (lowercase hex) of the bytes written.

Errors

• crate::SigmfError::InvalidMetadata if validation fails or path does not name a file.
• crate::SigmfError::Serde if serialization fails.
• crate::SigmfError::Io if any file system operation fails.

pub fn from_reader(reader: impl Read) -> Result<Self, SigmfError>

Reads and parses a metadata document from reader.

At most 1 MB plus one byte is read; the bytes are then parsed with Metadata::from_slice.

Errors

• crate::SigmfError::Io if reading fails.
• crate::SigmfError::InvalidMetadata if the input exceeds the 1 MB metadata size limit.
• Any error returned by Metadata::from_slice.

pub fn from_path(path: impl AsRef<Path>) -> Result<Self, SigmfError>

Opens the .sigmf-meta file at path and parses it with Metadata::from_reader.

Errors

Returns crate::SigmfError::Io if the file cannot be opened, or any error returned by Metadata::from_reader.

pub fn original_bytes(&self) -> Option<&[u8]>

Returns the exact bytes this document was parsed from, if it was parsed and has not been modified since.

Returns None for documents built with Metadata::new and after calling a mutating method on Metadata (setters, insert_*, or add_*).

pub fn original_digest(&self) -> Result<Option<String>, SigmfError>

Returns the SHA-512 digest (lowercase hex) of Metadata::original_bytes, or None if no original bytes are retained.

This is the hash a collection’s core:streams entry should record for an unmodified, previously parsed metadata file.

Errors

Returns a crate::SigmfError if hashing fails (currently infallible).

pub fn hash(&self) -> Result<String, SigmfError>

Returns the SHA-512 digest (lowercase hex) of the document’s compact serialization, as produced by Metadata::to_vec.

This may differ from Metadata::original_digest even for an unmodified document, because re-serialization does not preserve the original formatting.

Errors

Returns crate::SigmfError::Serde if serialization fails.

pub fn global(&self) -> &Global

Returns the global object.

pub fn captures(&self) -> &[Capture]

Returns the captures array in document order.

pub fn annotations(&self) -> &[Annotation]

Returns the annotations array in document order.

pub fn extra_fields(&self) -> &Map<String, Value>

Returns the unrecognized top-level keys (anything other than global, captures, and annotations).

pub fn capture_at(&self, sample_index: Integer) -> Option<&Capture>

Returns the capture segment that contains sample_index.

This is the capture with the greatest core:sample_start that is less than or equal to sample_index, regardless of the order of the captures array. Returns None if every capture starts after sample_index or there are no captures. If several captures share that start, the last one in document order is returned.

pub fn annotations_intersecting_samples( &self, start: Integer, sample_count: Integer, ) -> Result<Vec<&Annotation>, SigmfError>

Returns the annotations whose sample range overlaps the half-open range [start, start + sample_count).

An annotation’s range is [core:sample_start, core:sample_start + core:sample_count). Annotations without core:sample_count, or with a count of zero, never match. An empty query range returns no annotations. Results are in document order.

Errors

Returns crate::SigmfError::InvalidRange if start + sample_count overflows, or if a candidate annotation’s end overflows.

pub fn annotations_intersecting_frequency( &self, lower: Number, upper: Number, ) -> Result<Vec<&Annotation>, SigmfError>

Returns the annotations whose frequency range overlaps the closed interval [lower, upper] (in Hz).

Only annotations that set both core:freq_lower_edge and core:freq_upper_edge are considered; touching edges count as an overlap. Results are in document order.

Errors

Returns crate::SigmfError::InvalidRange if either bound is not finite or if lower > upper.

pub fn diff(&self, other: &Self) -> Result<Vec<MetadataChange>, SigmfError>

Computes the leaf-level differences between this document and other.

Both documents are serialized to JSON and compared recursively. Objects are compared key by key and arrays index by index, so inserting an element shifts every later index. Each reported change carries an RFC 6901 JSON Pointer; the result is empty when the serializations are equal.

Errors

Returns crate::SigmfError::Serde if either document fails to serialize.

pub fn insert_extra( &mut self, key: impl Into<String>, value: Value, ) -> Result<Option<Value>, SigmfError>

Inserts or replaces a top-level extension key.

Returns the previous value under key, if any, and clears the retained original bytes. The key is not checked against declared extensions.

Errors

Returns crate::SigmfError::InvalidMetadata if key is global, captures, or annotations.

pub fn insert_global_extra( &mut self, key: impl Into<String>, value: Value, ) -> Result<Option<Value>, SigmfError>

Inserts or replaces an extension key in the global object.

Returns the previous value under key, if any. Delegates to crate::global::Global::insert_extra. The retained original bytes are cleared even if the insertion is rejected.

Errors

Returns crate::SigmfError::InvalidMetadata if key names a core global field (for example core:version).

pub fn edit(&mut self) -> MetadataEdit<'_>

Starts a transactional edit of this document.

Changes are made to a draft copy; they are applied to self only when MetadataEdit::commit succeeds, and discarded if the MetadataEdit is dropped.

pub fn set_version(&mut self, version: String)

Sets the global core:version field: the SigMF specification version string.

Clears the retained original bytes.

pub fn set_datatype(&mut self, datatype: Datatype)

Sets the global core:datatype field: the sample format of the dataset.

Clears the retained original bytes.

pub fn set_sample_rate(&mut self, sample_rate: Number)

Sets the global core:sample_rate field: the sample rate in samples per second.

Clears the retained original bytes.

pub fn set_author(&mut self, author: String)

Sets the global core:author field: the author of the recording.

Clears the retained original bytes.

pub fn set_collection(&mut self, collection_str: String)

Sets the global core:collection field: the base name of the SigMF collection this recording belongs to.

Clears the retained original bytes.

pub fn set_data_doi(&mut self, data_doi: String)

Sets the global core:data_doi field: the DOI of the dataset file.

Clears the retained original bytes.

pub fn set_description(&mut self, description: String)

Sets the global core:description field: the free-text description of the recording.

Clears the retained original bytes.

pub fn set_hw(&mut self, hw: String)

Sets the global core:hw field: the description of the recording hardware.

Clears the retained original bytes.

pub fn set_license(&mut self, license: String)

Sets the global core:license field: the URL of the license governing the recording.

Clears the retained original bytes.

pub fn set_metadata_only(&mut self, metadata_only: bool)

Sets the global core:metadata_only field: whether the recording intentionally has no dataset file.

Clears the retained original bytes.

pub fn set_meta_doi(&mut self, meta_doi: String)

Sets the global core:meta_doi field: the DOI of the metadata file.

Clears the retained original bytes.

pub fn set_num_channels(&mut self, num_channels: Integer)

Sets the global core:num_channels field: the number of interleaved channels in the dataset.

Clears the retained original bytes.

pub fn set_offset(&mut self, offset: Integer)

Sets the global core:offset field: the index offset of the first sample in the dataset.

Clears the retained original bytes.

pub fn set_recorder(&mut self, recorder: String)

Sets the global core:recorder field: the name of the software that made the recording.

Clears the retained original bytes.

pub fn set_sha512(&mut self, hash: String)

Sets the global core:sha512 field: the SHA-512 digest of the dataset file.

Clears the retained original bytes.

pub fn set_geolocation(&mut self, geolocation: GeoJson)

Sets the global core:geolocation field: the GeoJSON location of the recording.

Clears the retained original bytes.

pub fn set_extensions(&mut self, extensions: Vec<ExtensionDeclaration>)

Sets the global core:extensions field: the list of extension namespaces used by the recording.

Clears the retained original bytes.

pub fn set_dataset(&mut self, dataset: String)

Sets the global core:dataset field: the file name of a non-conforming dataset.

Clears the retained original bytes.

pub fn set_trailing_bytes(&mut self, trailing_bytes: Integer)

Sets the global core:trailing_bytes field: the number of non-sample bytes at the end of the dataset file.

Clears the retained original bytes.

pub fn add_annotation(&mut self, annotation: Annotation)

Appends an entry to the annotations array.

No ordering is enforced. Clears the retained original bytes.

pub fn add_capture(&mut self, capture: Capture)

Appends an entry to the captures array.

No ordering is enforced. Clears the retained original bytes.

pub fn get_version(&self) -> String

Returns the global core:version field: the SigMF specification version string.

pub fn get_datatype(&self) -> Datatype

Returns the global core:datatype field: the sample format of the dataset.

pub fn get_sample_rate(&self) -> Option<Number>

Returns the global core:sample_rate field: the sample rate in samples per second, if set.

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

Returns the global core:author field: the author of the recording, if set.

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

Returns the global core:collection field: the base name of the SigMF collection this recording belongs to, if set.

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

Returns the global core:data_doi field: the DOI of the dataset file, if set.

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

Returns the global core:description field: the free-text description of the recording, if set.

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

Returns the global core:hw field: the description of the recording hardware, if set.

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

Returns the global core:license field: the URL of the license governing the recording, if set.

pub fn get_metadata_only(&self) -> Option<bool>

Returns the global core:metadata_only field: whether the recording intentionally has no dataset file, if set.

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

Returns the global core:meta_doi field: the DOI of the metadata file, if set.

pub fn get_num_channels(&self) -> Option<Integer>

Returns the global core:num_channels field: the number of interleaved channels in the dataset, if set.

pub fn get_offset(&self) -> Option<Integer>

Returns the global core:offset field: the index offset of the first sample in the dataset, if set.

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

Returns the global core:recorder field: the name of the software that made the recording, if set.

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

Returns the global core:sha512 field: the SHA-512 digest of the dataset file, if set.

pub fn get_geolocation(&self) -> Option<GeoJson>

Returns the global core:geolocation field: the GeoJSON location of the recording, if set.

pub fn get_extensions(&self) -> Option<Vec<ExtensionDeclaration>>

Returns the global core:extensions field: the list of extension namespaces used by the recording, if set.

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

Returns the global core:dataset field: the file name of a non-conforming dataset, if set.

pub fn get_trailing_bytes(&self) -> Option<Integer>

Returns the global core:trailing_bytes field: the number of non-sample bytes at the end of the dataset file, if set.

pub fn get_annotations(&self) -> Vec<Annotation>

Returns a clone of the annotations array.

Prefer Metadata::annotations to borrow without cloning.

pub fn get_captures(&self) -> Vec<Capture>

Returns a clone of the captures array.

Prefer Metadata::captures to borrow without cloning.

impl Metadata

pub fn validate(&self, policy: ValidationPolicy) -> ValidationReport

Validates this metadata against SigMF rules using policy.

Extensions declared in core:extensions are reported as unverified because no ExtensionRegistry is supplied; use validate_with_registry to verify them. See the module documentation for the full list of checks.

Example

use sigmf::datatype::Datatype;
use sigmf::global::Global;
use sigmf::meta::Metadata;
use sigmf::validation::{Severity, ValidationPolicy, ValidationStatus};
use std::str::FromStr;

// An older version is tolerated under the interoperability policy...
let metadata = Metadata::new(
    Global::new("1.0.0", Datatype::from_str("ri16_le")?),
    Vec::new(),
    Vec::new(),
);
let report = metadata.validate(ValidationPolicy::Interoperability);
assert_eq!(report.status, ValidationStatus::NotChecked);
assert_eq!(report.issues[0].severity, Severity::Warning);

// ...but rejected under the strict policy.
let report = metadata.validate(ValidationPolicy::StrictSupportedVersion);
assert_eq!(report.status, ValidationStatus::Failed);
assert!(!report.is_valid());

pub fn validate_with_registry( &self, policy: ValidationPolicy, registry: &ExtensionRegistry, ) -> ValidationReport

Validates this metadata, using registry to verify declared extensions.

In addition to the checks performed by validate, extensions declared in core:extensions whose name and version are registered are treated as verified, and their fields in the global, capture, and annotation objects are checked for the correct ExtensionScope (an error) and for being declared by the extension (a warning).

Trait Implementations

impl Clone for Metadata

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Metadata

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Metadata

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Metadata

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.