docs: FileEditor — changelog, limits and leaked space, README example

known-issues records what the editor refuses, that freed space is never reused (append-workload file sizes measured 2026-09-26 on tank with the ignored measure_append_waste test; sizes are deterministic), and that there is no journal. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
2026-09-26 13:35:06 -05:00
parent 3c89a31df0
commit 677dc5ec7c
4 changed files with 105 additions and 0 deletions
@@ -433,6 +433,23 @@ b.write("groups.h5")?;
 A group holds at most 65 535 links; more is an error, as is a link over
 65 515 bytes (a very long soft-link target) in a group of more than 8 links.

+### Modifying an existing file
+
+```rust
+use clawhdf5::{AttrValue, FileEditor, Selection};
+
+// A file from h5py or clawhdf5, dataset "x" chunked with maxshape=(None,).
+let mut ed = FileEditor::open("data.h5")?; // exclusive lock, like libhdf5
+ed.resize("x", &[1100])?;                   // h5py: ds.resize((1100,))
+let sel = Selection::Hyperslab { start: vec![1000], stride: vec![1], count: vec![100], block: vec![1] };
+ed.write_values("x", &sel, &[0.5f64; 100])?; // ds[1000:1100] = 0.5
+ed.set_attr("x", "units", &AttrValue::String("m/s".into()))?;
+```
+
+Each call changes the file in place (no rewrite) and syncs it. What it
+cannot change safely is refused before anything is written; see
+[known issues](docs/known-issues.md) for the limits.
+
 ### Python

 `crates/clawhdf5-py` is a Python package (PyO3 + numpy) that reads HDF5 with