fits_header/lib.rs
1//! # fits-header
2//!
3//! A pure-Rust, MSVC-safe library for reading and writing the header of a
4//! [FITS](https://fits.gsfc.nasa.gov/fits_standard.html) file.
5//!
6//! It reads a header unit into an ordered [`Header`] of records, retaining every card so untouched
7//! cards serialize byte-for-byte and only created or modified cards are re-rendered. Access is
8//! strict and keyword-oriented: [`Header::get`] and friends take a [`Key`] that is either a bare
9//! name (unique-or-[`FitsError::AmbiguousKeyword`]) or `(name, occurrence)`. Values read through a
10//! generic [`FromCard`] and write through [`IntoValue`]; batch edits are atomic; long strings use
11//! the `CONTINUE` convention.
12//!
13//! ```
14//! use fits_header::Header;
15//!
16//! let mut h = Header::new();
17//! h.set("OBJECT", "M31").unwrap();
18//! h.set("EXPTIME", 120.0).unwrap();
19//! assert_eq!(h.get::<f64>("EXPTIME").unwrap(), Some(120.0));
20//!
21//! // The header block only — creating a file means appending your own pixel data after
22//! // this; editing an existing file means Header::update_file, which preserves it.
23//! let bytes = h.to_header_bytes();
24//! assert_eq!(bytes.len() % fits_header::BLOCK_LEN, 0);
25//! ```
26//!
27//! ## Design
28//!
29//! - Pure Rust, no C or system libraries; builds with the MSVC toolchain.
30//! - An untouched card (and untouched long-string run) re-emits identical bytes.
31//! - Ambiguous keyword access errors instead of guessing.
32//!
33//! ## Features
34//!
35//! - `serde` *(off)* — derive `Serialize`/`Deserialize` on the public types.
36#![forbid(unsafe_code)]
37
38mod dates;
39mod error;
40mod header;
41mod key;
42mod parse;
43mod record;
44mod value;
45mod write;
46
47/// Bytes per header card.
48pub const CARD_LEN: usize = 80;
49/// Bytes per FITS block (36 cards).
50pub const BLOCK_LEN: usize = 2880;
51
52pub use crate::dates::{format_datetime, parse_datetime};
53pub use crate::error::{FitsError, Result};
54pub use crate::header::Header;
55pub use crate::key::Key;
56#[allow(deprecated)]
57pub use crate::parse::parse;
58pub use crate::record::{Record, RecordKind, Value};
59pub use crate::value::{parse_f64, parse_i64, Fixed, FromCard, IntoValue, Literal, Sci};
60
61/// Compiles the README's code blocks as doctests so the documented API cannot drift.
62#[cfg(doctest)]
63#[doc = include_str!("../README.md")]
64struct ReadmeDoctests;