fits-header 0.3.2

Pure-Rust, MSVC-safe FITS header reader/writer: parse every card from a FITS file, CRUD single or multiple header keywords, then serialize back to a valid FITS object.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159

# fits-header

A pure-Rust library for reading and writing the header of a
[FITS](https://fits.gsfc.nasa.gov/fits_standard.html) file.

- Header-scoped: this crate never owns, inspects, or fabricates pixel data. Creating a
  file means appending your own data bytes to the header; editing a file means
  [`Header::update_file`](https://docs.rs/fits-header/latest/fits_header/struct.Header.html#method.update_file),
  which preserves the existing data unit byte-for-byte.
- Pure Rust, no C or system libraries. Builds with the MSVC toolchain.
- Every card is retained on parse; untouched cards (including long-string runs)
  re-serialize byte-for-byte. Only created or edited cards are re-rendered.
- Keyword access is strict: a bare name addresses the sole occurrence of a keyword and
  errors when it is duplicated; `("NAME", n)` selects the n-th occurrence — see
  [`Key`](https://docs.rs/fits-header/latest/fits_header/enum.Key.html).
- Create, read, update, and delete single or multiple keywords; batch mutations
  ([`set_many`](https://docs.rs/fits-header/latest/fits_header/struct.Header.html#method.set_many),
  [`remove_many`](https://docs.rs/fits-header/latest/fits_header/struct.Header.html#method.remove_many))
  are atomic (all or nothing).
- Typed reads and writes:
  [`get::<T>`](https://docs.rs/fits-header/latest/fits_header/struct.Header.html#method.get)
  covers strings, numbers, booleans, and date/times;
  [`Literal`](https://docs.rs/fits-header/latest/fits_header/struct.Literal.html)/[`Fixed`](https://docs.rs/fits-header/latest/fits_header/struct.Fixed.html)/[`Sci`](https://docs.rs/fits-header/latest/fits_header/struct.Sci.html)
  wrappers control number formatting on write.
- Long strings use the `CONTINUE` convention on read and write (with `LONGSTRN`).
- The API is an ordered
  [`Header`](https://docs.rs/fits-header/latest/fits_header/struct.Header.html) of
  [`Record`](https://docs.rs/fits-header/latest/fits_header/struct.Record.html)s — value
  cards, repeatable commentary cards, and opaque pass-through cards; it contains no
  application types.
- `HIERARCH` and other non-standard or malformed cards parse as
  [`RecordKind::Opaque`](https://docs.rs/fits-header/latest/fits_header/enum.RecordKind.html#variant.Opaque)
  records: preserved byte-for-byte on re-serialization, but not addressable by keyword
  (`get`/`set`/`remove` never see them).

## Install

```sh
cargo add fits-header
# opt into serde derives on the public types:
cargo add fits-header --features serde
```

## Usage

```rust
use fits_header::{Header, Result};

fn demo(bytes: &[u8]) -> Result<()> {
    // Read every card from a FITS header unit.
    let mut header = Header::parse(bytes)?;

    // Typed reads through one generic accessor. Access is strict: a bare
    // name errors if the keyword occurs more than once.
    let exptime: Option<f64> = header.get("EXPTIME")?;
    let object: Option<&str> = header.get_str("OBJECT")?;
    let gain: Option<i64> = header.get(("GAIN", 1))?; // second occurrence

    // Create, update, delete.
    header.set("OBJECT", "M31")?;
    header.set("EXPTIME", 300.0)?;
    header.remove("AIRMASS")?;

    // Batch mutations are atomic — all or nothing.
    header.set_many([("FILTER", "Ha"), ("TELESCOP", "EdgeHD 8")])?;

    // Serialize the header block. Untouched cards come back byte-for-byte identical.
    // Creating a file: append your own pixel data after this — this crate never
    // fabricates it.
    let block: Vec<u8> = header.to_header_bytes();
    Ok(())
}

// Editing a file on disk: the data unit (and any later HDUs) survives untouched.
fn edit_in_place(path: &std::path::Path) -> Result<()> {
    Header::update_file(path, |h| {
        h.set("OBJECT", "M31")?;
        Ok(())
    })
}
```

See the [guide](https://docs.rs/fits-header/latest/fits_header/guide/index.html) for a
longer, task-oriented walkthrough backed by
[`examples/quickstart.rs`](https://github.com/nightwatch-astro/fits-header/blob/main/examples/quickstart.rs).

## Repeated keywords (HISTORY / COMMENT)

Commentary keywords like `HISTORY` and `COMMENT` repeat.
[`append`](https://docs.rs/fits-header/latest/fits_header/struct.Header.html#method.append)
adds an occurrence,
[`get_all`](https://docs.rs/fits-header/latest/fits_header/struct.Header.html#method.get_all)
reads every one in order, and an `("HISTORY", n)` key addresses a single
occurrence to update it in place or remove it.

```rust
use fits_header::Header;

let mut header = Header::new();
header.append("HISTORY", "dark subtracted")?;
header.append("HISTORY", "flat fielded")?;
assert_eq!(header.count("HISTORY"), 2);

// Read the processing log in order.
assert_eq!(
    header.get_all::<String>("HISTORY"),
    ["dark subtracted", "flat fielded"],
);

// Update one occurrence in place, then drop another. Commentary cards carry no
// value, so read them through `get`/`get_all`, not `get_str`.
header.set(("HISTORY", 1), "flat fielded (master flat v2)")?;
header.remove(("HISTORY", 0))?;
assert_eq!(header.get_all::<String>("HISTORY"), ["flat fielded (master flat v2)"]);
# Ok::<(), fits_header::FitsError>(())
```

## Reading and writing real files

- [`Header::read_from_file(path)`](https://docs.rs/fits-header/latest/fits_header/struct.Header.html#method.read_from_file)
  — read a header from disk. Parsing stops at `END`, so the data unit is read but never
  interpreted.
- [`Header::to_header_bytes()`](https://docs.rs/fits-header/latest/fits_header/struct.Header.html#method.to_header_bytes)
  — the header block only (cards + `END`, padded to a 2880-byte multiple). Creating a new
  FITS object: write this, then append your own pixel bytes.
- [`Header::update_file(path, edit)`](https://docs.rs/fits-header/latest/fits_header/struct.Header.html#method.update_file)
  — edit an existing file in place. Reads the file, locates the header by scanning for
  `END`, hands you the parsed header to mutate, then writes the new header back followed
  by everything that came after the original one (data unit, later HDUs) untouched. The
  write is atomic (temp file + rename). Errors with
  [`FitsError::MissingEnd`](https://docs.rs/fits-header/latest/fits_header/enum.FitsError.html#variant.MissingEnd)
  if the file has no `END` card.

## Documentation

- [guide](https://docs.rs/fits-header/latest/fits_header/guide/index.html) — task-oriented quickstart.
- [docs.rs/fits-header](https://docs.rs/fits-header) — full API reference, generated
  from the crate's rustdoc. Every public item is documented; the examples are compiled
  and run as part of the test suite. Build it locally with
  `cargo doc --no-deps --all-features --open`.

## Features

- `serde` *(off by default)* — derive `Serialize`/`Deserialize` on
  [`Header`](https://docs.rs/fits-header/latest/fits_header/struct.Header.html),
  [`Record`](https://docs.rs/fits-header/latest/fits_header/struct.Record.html), and
  [`Value`](https://docs.rs/fits-header/latest/fits_header/enum.Value.html).

## Development

```sh
just verify                  # fmt-check + clippy (-D warnings) + tests
cargo test --all-features    # includes the serde suite
just doc
```

## License

Licensed under the [Apache License, Version 2.0](https://github.com/nightwatch-astro/fits-header/blob/main/LICENSE).