Struct Header

Source

pub struct Header { /* private fields */ }

Expand description

An ordered FITS header unit: records in appearance order, with strict keyword access and CRUD.

Equality is semantic (records compare by content, not by retained bytes).

Implementations§

Source §

impl Header

Source

pub fn new() -> Self

An empty header.

Source

pub fn cards(&self) -> &[Record]

The records in order (read-only escape hatch).

Source

pub fn iter(&self) -> impl Iterator<Item = &Record>

Iterate the records in order.

Source

pub fn count(&self, name: &str) -> usize

How many records carry this keyword.

Source

pub fn get<T: FromCard>( &self, key: impl Into<Key>, ) -> Result<Option<T>, FitsError>

Read a keyword as T. Err only on an ambiguous bare name; Ok(None) when absent or the value does not convert; never panics.

§Examples

let mut h = Header::new();
h.set("EXPTIME", 120.0).unwrap();
assert_eq!(h.get::<f64>("EXPTIME").unwrap(), Some(120.0));
assert_eq!(h.get::<i64>("MISSING").unwrap(), None);

Source

pub fn get_str(&self, key: impl Into<Key>) -> Result<Option<&str>, FitsError>

Borrow a keyword’s string value (Str content, non-empty); None for empty or a literal.

Source

pub fn get_all<T: FromCard>(&self, name: &str) -> Vec<T>

Every value for a keyword, in order.

Source

pub fn set( &mut self, key: impl Into<Key>, value: impl IntoValue, ) -> Result<(), FitsError>

Update the addressed record in place, or append when the (unique) name is absent. The keyword must be FITS-standard (≤8, A-Z 0-9 - _); use set_raw for vendor keys.

§Examples

let mut h = Header::new();
h.set("OBJECT", "M31").unwrap(); // appends
h.set("OBJECT", "NGC 7000").unwrap(); // updates in place
assert_eq!(h.count("OBJECT"), 1);

let err = h.set("object", 1); // lowercase is not FITS-standard
assert!(matches!(err, Err(FitsError::InvalidKeyword { .. })));

Source

pub fn set_raw( &mut self, keyword: &str, value: impl IntoValue, ) -> Result<(), FitsError>

Like set but accepts any ≤8-char printable-ASCII keyword (vendor escape hatch).

Source

pub fn append( &mut self, name: &str, value: impl IntoValue, ) -> Result<(), FitsError>

Always add a record (a value card, or a commentary card for COMMENT/HISTORY/blank).

§Examples

let mut h = Header::new();
h.append("HISTORY", "dark subtracted").unwrap();
h.append("HISTORY", "flat fielded").unwrap();
assert_eq!(h.get_all::<String>("HISTORY").len(), 2);

Source

pub fn set_comment( &mut self, key: impl Into<Key>, comment: impl Into<String>, ) -> Result<(), FitsError>

Set or replace the addressed value card’s inline comment. No-op if the keyword is absent or not a value card.

Source

pub fn remove(&mut self, key: impl Into<Key>) -> Result<bool, FitsError>

Remove the addressed record. Returns whether anything was removed.

§Examples

let mut h = Header::new();
h.set("AIRMASS", 1.2).unwrap();
assert!(h.remove("AIRMASS").unwrap());
assert!(!h.remove("AIRMASS").unwrap());

Source

pub fn set_many<K, V>( &mut self, entries: impl IntoIterator<Item = (K, V)>, ) -> Result<(), FitsError>
where K: Into<Key>, V: IntoValue,

Apply several mutations atomically: validate every entry first, then apply all or none.

§Examples

let mut h = Header::new();
h.set_many([("FILTER", "Ha"), ("TELESCOP", "EdgeHD 8")]).unwrap();

// A rejected batch leaves the header untouched.
assert!(h.set_many([("GAIN", "1"), ("TOOLONGKEY", "2")]).is_err());
assert_eq!(h.count("GAIN"), 0);

Source

pub fn remove_many<K: Into<Key>>( &mut self, keys: impl IntoIterator<Item = K>, ) -> Result<usize, FitsError>

Remove several keys atomically (validation only guards ambiguity). Returns the count removed.

Source

pub fn to_header_bytes(&self) -> Vec<u8> ⓘ

Serialize the header block only (cards, END, padded to a 2880 multiple) for splicing onto an existing file’s data.

§Examples

let mut h = Header::new();
h.set("OBJECT", "M31").unwrap();
let bytes = h.to_header_bytes();
assert_eq!(bytes.len() % fits_header::BLOCK_LEN, 0);

Source

pub fn to_bytes( &self, structural: &StructuralHints, ) -> Result<Vec<u8>, FitsError>

Serialize a standalone FITS object (header + a minimal zero data block). Mandatory structural cards are synthesized only when absent; structural is a fallback.

Errors with FitsError::DataTooLarge when the declared data segment exceeds MAX_ZERO_FILL — for real-file edits, serialize with to_header_bytes and splice the original data.

§Examples

let mut h = Header::new();
h.set("OBJECT", "M31").unwrap();
let file = h.to_bytes(&StructuralHints::default()).unwrap();
assert!(file.starts_with(b"SIMPLE"));