carray-netcdf 2.0.0 → 2.1.0

data/docs/01_getting_started.md

@@ -16,13 +16,13 @@ Then:
 gem install carray-netcdf
 ```
 
-That brings in CArray and the netcdf gem.
-
 Requires:
 
-- Ruby >= 3.1
-- carray >= 3.0.1, < 3.1
-- libnetcdf >= 4.1
+- Ruby >= 3.2
+- libnetcdf >= 4.1, with its headers (`nc-config` or `pkg-config` on PATH)
+- A C compiler, to build the netcdf gem
+- carray >= 3.0.1, installed as a dependency
+- the netcdf gem, installed as a dependency
 
 ## Loading
 
@@ -32,25 +32,23 @@ require "carray-netcdf"
 NC = CA::NetCDF     # optional short alias used throughout this guide
 ```
 
-Loading the gem pulls in carray, the netcdf gem, layer 1 (the `nc_*` functions), and layer 2 (`File`, `Group`, `Var`, `Dim`, `Codec`).
-
 ## Reading in three lines
 
 ```ruby
 NC::File.open("data.nc") do |nc|
-  data = nc["temperature"].to_ca   # => CArray (already decoded via CF codec if applicable)
+  data = nc["temp"].to_ca   # => CArray (already decoded via CF codec if applicable)
 end
 ```
 
 - `NC::File.open` opens for reading by default. The block form auto-closes.
-- `nc["temperature"]` returns a lazy `Var` handle — no I/O yet.
-- `.to_ca` reads the whole variable and returns a `CArray`. If the file declares `Conventions: CF-*` and the variable has `_FillValue` / `scale_factor` / `add_offset` / CF time units, all of that is decoded automatically.
+- `nc["temp"]` returns a lazy `Var` handle — no I/O yet.
+- `.to_ca` reads the whole variable and returns a `CArray`. If the file's `Conventions` attribute names CF or COARDS and the variable has `_FillValue` / `scale_factor` / `add_offset` / CF time units, all of that is decoded automatically.
 
 ## Reading a slice
 
 ```ruby
 NC::File.open("data.nc") do |nc|
-  t = nc["temperature"]
+  t = nc["temp"]
   t.shape                    # => e.g. [365, 73, 144]
   t.dims.map(&:name)         # => ["time", "lat", "lon"]
 
@@ -60,7 +58,7 @@ NC::File.open("data.nc") do |nc|
 end
 ```
 
-The `[]` accepts anything `CArray.scan_index` accepts: integers, ranges, `nil` for a whole axis, arrays, boolean masks. Point-and-block indexing maps directly to `nc_get_var1` / `nc_get_vara` / `nc_get_vars` under the hood, so you only ever read what you ask for.
+The `[]` accepts any index a CArray accepts. Integers, ranges, strides and `nil` for a whole axis read only the part you index; an index array reads the block its indices span and picks from it, and a boolean mask reads the whole variable.
 
 ## Writing a file in ten lines
 
@@ -76,13 +74,13 @@ NC::File.create("out.nc") do |nc|
   nc.def_att("Conventions", "CF-1.7")
   nc.def_att("title",       "Demo file")
 
-  nc["temp"] = CArray.float32(1, 73, 144) { rand * 30 + 260 }
+  nc["temp"] = CArray.float32(1, 73, 144).random(30) + 260
 end
 ```
 
 - `File.create` opens the file in **define mode** and drops you into it.
-- `def_dim` / `def_var` / `def_att` build the schema. Pass `:unlimited` (or the string `"unlimited"` in YAML-ish contexts) for an unlimited dimension. Types are Symbols: `:byte :short :int :int64 :float :double`, plus the CArray-style aliases (`:int32`, `:float32`, `:float64` …).
-- Variable attributes go as keyword arguments to `def_var` (any Ruby-side Numeric / String / Array is fine). Attributes that CF requires to match the variable's type — `_FillValue`, `missing_value`, `valid_range`, `valid_min`, `valid_max` — are automatically written in the variable's type so libnetcdf doesn't reject them.
+- `def_dim` / `def_var` / `def_att` build the schema. Pass `:unlimited` for an unlimited dimension. Types are Symbols: `:byte :short :int :int64 :float :double`, plus the CArray-style aliases (`:int32`, `:float32`, `:float64` …).
+- Variable attributes go as keyword arguments to `def_var` (any Ruby-side Numeric / String / Array is fine). `_FillValue`, `missing_value`, `valid_range`, `valid_min` and `valid_max` are written in the variable's type, as CF expects; libnetcdf itself requires it of `_FillValue`.
 - `nc["temp"] = ca` is a whole-variable write. `nc["temp", 0, nil, nil] = ca` is a hyperslab write. `File` switches between define and data mode for you.
 
 ## The three access idioms
@@ -99,16 +97,9 @@ NC::File.open("data.nc") do |nc|
   slab = nc["temp"][0..9, nil, nil]
 
   # (3) treat the Var as if it were a CArray
-  #     method_missing delegates to .to_ca — convenient for interactive work,
-  #     but each call re-reads the whole variable, so cache if you loop.
+  #     a method a Var doesn't have is called on its to_ca — convenient for
+  #     interactive work, but each call reads the whole variable again, so
+  #     keep the CArray if you loop.
   nc["temp"].mean
 end
 ```
-
-## Where to go next
-
-- [Reading files](02_reading.md) — the full `File` / `Var` / `Dim` surface, plus what codecs turn raw bytes into (masks, physical values, CATime).
-- [Writing files](03_writing.md) — schema definition, hyperslab writes, packing, unlimited dimensions.
-- [Codecs and CF conventions](04_codec.md) — what CF decoding actually does, how to opt in to `valid_range` masking, how to write custom codecs.
-- [Groups](05_groups.md) — NetCDF-4 groups.
-- [Cookbook](07_cookbook.md) — end-to-end scenarios pulled from real use cases.

data/docs/02_reading.md

@@ -10,8 +10,6 @@ ca  = var[0, nil, nil]     # this is the read: libnetcdf fills a CArray, the cod
 
 A `Var` is a lazy handle. Holding one costs nothing, and the index you give it decides how much of the variable is read — a point, a slab, a strided subset, or the whole thing with `to_ca`. What comes back is a CArray, with the file's conventions already applied to it, so a packed variable arrives as physical values and its missing entries arrive as a mask.
 
-Everything else on this page is detail around those three steps.
-
 ## Opening
 
 ```ruby
@@ -42,15 +40,15 @@ NC::File.open("data.nc", :append)  # alias of :write
 
 For creating a new file, see [Writing files](03_writing.md).
 
-A Zarr store opens the same way, through a URL in place of the path: `NC::File.open("file:///data/t.zarr#mode=zarr,file")`.  See [Zarr stores](03_writing.md#zarr-stores).
+A Zarr store opens the same way, through a URL in place of the path: `NC::File.open("file:///data/t.zarr#mode=zarr,file")`. See [Zarr stores](03_writing.md#zarr-stores).
 
 ## Introspection
 
 ```ruby
 NC::File.open("data.nc") do |nc|
   nc.filename    # => "data.nc"     (OS path)
-  nc.format      # => "NC_FORMAT_CLASSIC" / "NC_FORMAT_NETCDF4" / ...
-  nc.path        # => "/"           (netcdf-4 group path — always "/" for the root)
+  nc.format      # => NetCDF::NC_FORMAT_CLASSIC, NetCDF::NC_FORMAT_NETCDF4, ... (Integer constants)
+  nc.path        # => "/"           (NetCDF-4 group path; "/" for the root)
 
   nc.dims        # => {"time" => Dim, "lat" => Dim, "lon" => Dim}
   nc.vars        # => {"temp" => Var, "time" => Var, "lat" => Var, "lon" => Var}
@@ -65,7 +63,7 @@ NC::File.open("data.nc") do |nc|
 end
 ```
 
-Names are Strings — always. `nc["temp"]` and `nc.var("temp")` work; Symbols are not coerced.
+Names are Strings; a Symbol is accepted too, so `nc[:temp]` is the same as `nc["temp"]`.
 
 ## The Var handle
 
@@ -94,28 +92,31 @@ t.codec         # => the codec that will decode reads from this variable
 ca = nc["temp"].to_ca      # equivalent to nc["temp"][]
 ```
 
-Returns a CArray of shape `t.shape` and type `t.data_type` (or the codec's choice, e.g. Float64 after scale/offset, CATime after CF time decode). The codec has already run — `_FillValue` cells are `UNDEF`, physical values are unpacked, time coordinates are CATime.
+Returns a CArray of shape `t.shape` and type `t.data_type` (or the codec's choice, e.g. `:float64` after scale/offset, CATime after CF time decode). The codec has already run — `_FillValue` cells are `UNDEF`, physical values are unpacked, time coordinates are CATime.
+
+An `NC_STRING` variable has no CArray type, so reading it through a `Var` raises `NotImplementedError`. Read it with the netcdf gem, which returns Strings: `NetCDF.nc_get_var(nc.ncid, nc["names"].varid)`.
 
 ## Hyperslab reads (`nc[var][i, j, k]`)
 
-`Var#[]` accepts anything `CArray.scan_index` accepts:
+`Var#[]` accepts any index a CArray accepts:
 
 ```ruby
 t = nc["temp"]
 
 t[]                        # whole variable  (same as t.to_ca)
 t[0, nil, nil]             # first time step (rank-2 CArray, shape [73, 144])
-t[0]                       # first cell if 1-D, or a slab if the axis is size 1;
-                           #   for higher-rank vars, use explicit nil for the rest
+t[0]                       # first element: a single integer is a flat address, as on a CArray;
+                           #   give every axis to get a slab
 t[0, 0, 0]                 # single element (scalar — Float / Integer / Element)
 t[0..9, nil, nil]          # first 10 time steps
-t[(0..-1).step(2), nil, nil]   # every other time step (netcdf stride under the hood)
-t[[0, 5, 10], nil, nil]    # not hyperslab-able (uses `nc_get_var` + CArray indexing)
+t[(0..-1).step(2), nil, nil]   # every other time step
+t[CA_INT([0, 5, 10]), nil, nil]  # time steps 0, 5 and 10 (reads steps 0..10, then picks)
 ```
 
-- Point indices (`0, 0, 0`) go through `nc_get_var1` and return a **decoded scalar** — a `Float` after scale/offset, `UNDEF` for a fill cell, a `CATime::Element` for a CF time coordinate, or a plain Numeric if the variable has no codec transforms.
-- Block indices with all-unit strides go through `nc_get_vara`; strided block indices go through `nc_get_vars`. `CArray.scan_index` treats a form like `[start, count, stride]` (an Array of three ints) as a strided block, so `t[[0, 5, 2], nil, nil]` is a *hyperslab*, not fancy indexing.
-- Genuine fancy indexing — a boolean mask, a scatter/gather via an integer index array — falls back to reading the whole variable and indexing the resulting CArray. That's a correctness fallback, not a performance path; for large files, prefer hyperslab-shaped indices.
+- A point index (`0, 0, 0`) returns a **decoded scalar** — a `Float` after scale/offset, `UNDEF` for a fill cell, a `CATime::Element` for a CF time coordinate, or a plain Numeric if the variable has no codec transforms.
+- A range, a stride or `nil` reads only the elements it covers. An Array of three integers is `[start, count, stride]`, as on a CArray, so `t[[0, 5, 2], nil, nil]` reads time steps 0, 2, 4, 6 and 8.
+- An index array on an axis reads the block from its smallest to its largest index, and picks from that; a few flat addresses (`t[CA_INT([1, 7, -1])]`) are read one by one. A boolean mask covers the whole variable, so it reads all of it.
+- `elements`, `size`, `dim0`..`dim3`, `first` and `last` are answered from the file without reading the variable.
 
 Scalar decoding examples:
 
@@ -127,14 +128,13 @@ nc["time"][0].to_time              # => 2022-01-01 00:00:00 UTC (Ruby Time)
 nc["time"][0].to_date              # => #<Date: 2022-01-01>
 ```
 
-## `method_missing`: use a Var like a CArray
+## Using a Var like a CArray
 
-`Var` forwards unknown methods to `to_ca`, so anything you can call on a CArray, you can call on a Var directly:
+A method a `Var` doesn't have is called on its `to_ca`, so anything you can call on a CArray, you can call on a Var directly:
 
 ```ruby
 nc["temp"].mean            # => the mean of the whole array
 nc["temp"].max             # => the max
-nc["temp"].shape           # (Var#shape is defined, so this is not method_missing)
 nc["temp"].sum(0)          # => reduction along axis 0
 ```
 
@@ -151,22 +151,22 @@ temp.sum(0)
 
 ## Reading a subset into an existing buffer
 
-For streaming big files a slab at a time, allocate one buffer once and reuse it.  Layer 1's `nc_get_vara` accepts an explicit CArray as the last argument and reads into it — no allocation per slab:
+For streaming big files a slab at a time, allocate one buffer once and reuse it. The low-level API's `nc_get_vara` accepts an explicit CArray as the last argument and reads into it — no allocation per slab:
 
 ```ruby
 NC::File.open("big.nc") do |nc|
-  varid = ::NetCDF.nc_inq_varid(nc.ncid, "temp")
+  varid = nc["temp"].varid
   buf   = CArray.float32(73, 144)          # one time slice, reused
 
   365.times do |k|
     CA::NetCDF.nc_get_vara(nc.ncid, varid, [k, 0, 0], [1, 73, 144], buf)
-    # buf now holds day k; no allocation, no codec, raw physical bytes.
+    # buf now holds day k, as stored (not decoded)
     process(buf)
   end
 end
 ```
 
-This bypasses layer 2 (and the codec).  Use it when you're staying at raw values on purpose and want zero-allocation streaming.  See [layer1.md](06_layer1.md) for the full API.
+This skips the codec, so use it when you want the stored values and no allocation per read. See the [low-level API chapter](06_low_level_api.md) for all of it.
 
 ## Dimensions
 
@@ -189,7 +189,7 @@ Attributes are surfaced as native Ruby values by the underlying netcdf gem:
 
 - `NC_CHAR` / `NC_STRING` → `String`
 - Numeric scalar (single-element) → `Integer` or `Float`
-- Numeric multi-element → `CArray` (or Ruby `Array` for very short cases — the netcdf gem picks the natural shape)
+- Numeric multi-element → Ruby `Array`
 
 Examples:
 
@@ -197,15 +197,15 @@ Examples:
 nc.att("Conventions")            # => "CF-1.7"
 nc.att("title")                  # => "Demo file"
 nc["temp"].att("units")          # => "K"
-nc["temp"].att("_FillValue")     # => -999.9  (Float; typed as the variable)
-nc["temp"].att("valid_range")    # => CArray([0.0, 400.0])
+nc["temp"].att("_FillValue")     # => -999.9000244140625  (-999.9 stored as float)
+nc["temp"].att("valid_range")    # => [0.0, 400.0]
 ```
 
 An unknown attribute returns `nil`. `nc.atts` returns the frozen hash of everything (global on `nc`, per-variable on `nc["temp"]`).
 
 ## Turning decoding off
 
-If you want raw bytes — no `_FillValue` masking, no unpacking, no CATime — pass `codec: :identity`:
+If you want the stored values — no `_FillValue` masking, no unpacking, no CATime — pass `codec: :identity`:
 
 ```ruby
 NC::File.open("data.nc", codec: :identity) do |nc|

data/docs/03_writing.md

@@ -27,12 +27,17 @@ NC::File.create("out.nc") do |nc|
   # ... define dims/vars/atts, then write data
 end
 
-# NetCDF-4 (needed for groups, compression, unlimited multi-D, etc.)
+# NetCDF-4 (needed for groups, compression, chunking, and more than one unlimited dimension)
 NC::File.create("out.nc", netcdf4: true) do |nc|
   # ...
 end
 
-# Refuse to overwrite an existing file
+# Any format by name: :classic, :offset64 (CDF-2), :cdf5, :netcdf4, :netcdf4_classic
+NC::File.create("big.nc", format: :cdf5) do |nc|
+  # ...
+end
+
+# Refuse to overwrite an existing file (raises Errno::EEXIST)
 NC::File.create("out.nc", clobber: false)
 
 # Atomic write: publish only on success.  Bytes go to a same-directory
@@ -40,15 +45,13 @@ NC::File.create("out.nc", clobber: false)
 # Any exception from the block unlinks the tmp; the target file is
 # untouched (an earlier version, if any, survives intact).
 NC::File.create("out.nc", atomic: true) do |nc|
-  # ... define + write.  On raise: tmp cleaned up, "out.nc" NOT created /
+  # ... define + write.  On raise: tmp cleaned up, "out.nc" not created /
   # overwritten.  On success: "out.nc" appears atomically at end of block.
 end
 ```
 
 **Atomic write caveat.** Consumers polling the target path won't see anything until close — for a long-running unlimited-dim streaming write where a downstream reader wants incremental visibility, prefer `atomic: false` (the default).
 
-`create` opens the file in **define mode**. The block is the natural place to declare the schema; `File` will drop out of define mode automatically before the first data write, and back into it for further definitions.
-
 ## Defining dimensions
 
 ```ruby
@@ -57,7 +60,7 @@ nc.def_dim("lat", 73)            # fixed length
 nc.def_dim("lon", 144)
 ```
 
-`:unlimited` (or the string `"unlimited"`) creates an unlimited dimension. Every other value is coerced with `Integer(...)`. `def_dim` returns the `Dim` and stores it under `nc.dims[name]`.
+`:unlimited` creates an unlimited dimension. Every other value is coerced with `Integer(...)`. `def_dim` returns the `Dim` and stores it under `nc.dims[name]`.
 
 ## Defining variables
 
@@ -74,7 +77,7 @@ nc.def_var("temp", :float, ["time", "lat", "lon"],
 - 3rd arg: list of dimension names (Strings). An empty list makes a scalar.
 - Keyword args: attributes to attach at define time. Any Ruby-side Numeric, String, or Array is fine.
 
-**Type-matched attributes.** `_FillValue`, `missing_value`, `valid_range`, `valid_min`, and `valid_max` must be written in the variable's on-disk type (CF §2.5.1 and libnetcdf enforce this). The gem handles that for you: it detects those attribute names and writes them via typed `nc_put_att_*`, so `_FillValue: -999.9` on a `:float` var becomes `nc_put_att_float`, not the default `nc_put_att_double`. Other attributes go through the generic `nc_put_att` (which infers a reasonable NetCDF type from the Ruby value).
+**Type-matched attributes.** `_FillValue`, `missing_value`, `valid_range`, `valid_min`, and `valid_max` must be written in the variable's on-disk type (CF §2.5.1 asks for this, and libnetcdf requires it of `_FillValue`). The gem handles that for you, so `_FillValue: -999.9` on a `:float` variable is stored as a float. Other attributes take a NetCDF type inferred from the Ruby value.
 
 **NetCDF-4 storage / filter options.** `def_var` recognizes these keyword arguments alongside the attributes (only effective on a NetCDF-4 file):
 
@@ -84,7 +87,11 @@ nc.def_var("temp", :float, ["time", "lat", "lon"],
 | `chunks: :contiguous` | force `NC_CONTIGUOUS` |
 | `chunks: :compact` | `NC_COMPACT` (small variables only) |
 | `deflate: 4` | zlib compression level 1..9 (0 / omitted / `nil` = off) |
-| `shuffle: true` | shuffle filter (usually paired with deflate) |
+| `shuffle: true` | shuffle filter (usually paired with a compressor) |
+| `zstandard: 3` | zstandard compression level (0 / omitted / `nil` = off) |
+| `bzip2: 9` | bzip2 compression level 1..9 (0 / omitted / `nil` = off) |
+| `szip: { coding: :nn, pixels_per_block: 32 }` | szip compression; `coding:` is `:nn` or `:ec` |
+| `blosc: { compressor: :lz4, level: 5, blocksize: 0, shuffle: :byte }` | blosc compression; `compressor:` is `:lz`, `:lz4`, `:lz4hc`, `:snappy`, `:zlib` or `:zstd`, and `shuffle:` is `:none`, `:byte` or `:bit` |
 | `fletcher32: true` | per-chunk fletcher32 checksum |
 | `endian: :little / :big / :native` | on-disk byte order |
 | `no_fill: true` | disable pre-fill (perf: skip fill on unwritten cells) |
@@ -100,7 +107,9 @@ NC::File.create("compressed.nc", netcdf4: true) do |nc|
 end
 ```
 
-These get passed through to `nc_def_var_chunking` / `nc_def_var_deflate` / `nc_def_var_fletcher32` / `nc_def_var_endian` / `nc_def_var_fill` and take effect immediately.  On a NetCDF-3 file, any of them causes libnetcdf to raise; that raise propagates unchanged.
+zstandard, bzip2 and blosc need libnetcdf 4.9 or later, and every compressor needs libnetcdf built with it: when it is missing, `def_var` raises `NetCDF::Error` rather than writing the data uncompressed. `var.storage_options` reads a variable's settings back in this keyword form. A file compressed with zstandard, bzip2, szip or blosc needs the same filter where it is read: netCDF4-python's wheels, for one, find them only when `HDF5_PLUGIN_PATH` points at libnetcdf's plugin directory.
+
+`chunks:`, `deflate:` (a level above 0), `shuffle:`, the other compressors, `fletcher32:` and `endian:` need a NetCDF-4 file; on NetCDF-3, `def_var` raises `ArgumentError` before defining anything. `no_fill:` and `deflate: 0` work on both.
 
 **File-wide defaults.** The same kwargs on `File.create` set defaults for every subsequent `def_var` in that file — write once, no need to repeat per variable:
 
@@ -114,7 +123,7 @@ NC::File.create("compressed.nc", netcdf4: true,
 end
 ```
 
-Per-var kwargs on `def_var` always override the file-wide default (including `deflate: 0` / `shuffle: false` to explicitly turn off). Note that "file-wide compression" is a convention: libnetcdf has no file-level compression attribute — internally we just call `nc_def_var_deflate` on each new variable with the file's default.  If you `def_var` in a second session (after re-open), the earlier file default is *not* remembered and applies only within the create block.
+Per-var kwargs on `def_var` always override the file-wide default (including `deflate: 0` / `shuffle: false` to explicitly turn off). Compression — the compressors and `shuffle` — is taken whole from one place: the kwargs if they name any compressor, else a template's settings if it has one, else the file-wide defaults. So `zstandard: 3` on a file created with `deflate: 4` gives zstandard alone, and `deflate: 0` drops a default `shuffle:` too. A template variable with no compression gets the file-wide default, as a new variable does. These defaults last only while the file created by `create` is open: libnetcdf has no file-level compression setting, so `File.open` takes none, and a variable defined after reopening the file gets none of them.
 
 Add attributes after the fact with `Var#def_att`:
 
@@ -125,38 +134,42 @@ nc["temp"].def_att("long_name", "air temperature")
 
 ## Inheriting from an existing file (`template:`)
 
-The most common workflow — "read one NetCDF, transform, write another with the same skeleton" — is a single kwarg away.  Every `def_var` accepts a `template:` argument that supplies its definition (type, dims, attributes) from an existing `Var` (or from a `File` / `Group` by same-name lookup):
+The most common workflow — "read one NetCDF, transform, write another with the same skeleton" — needs only one keyword argument. Every `def_var` accepts a `template:` argument that supplies its definition (type, dims, attributes) from an existing `Var` (or from a `File` / `Group` by same-name lookup):
 
 ```ruby
 NC::File.open("in.nc") do |src|
   NC::File.create("out.nc") do |dst|
     dst.def_dim("lat", 3)
-    dst.def_var("lat", template: src["lat"])          # copy definition
-    dst.def_var("lat", template: src)                  # look up "lat" in src
-    dst.def_var("latitude", template: src["lat"])     # rename on copy
-    dst.def_var("lat", template: src["lat"],           # override attributes
-                units: "arc_degrees_north")
-    dst.def_var("lat", :double, template: src["lat"]) # override type
+    dst.def_var("lat", template: src["lat"])          # copy the definition
+
+    # or any one of:
+    #   dst.def_var("lat", template: src)                 # look up "lat" in src
+    #   dst.def_var("latitude", template: src["lat"])     # rename on copy
+    #   dst.def_var("lat", template: src["lat"],          # override an attribute
+    #               units: "degrees_north")
+    #   dst.def_var("lat", :double, template: src["lat"]) # override the type
   end
 end
 ```
 
-Positional args (`type` / `dims`) and kwargs override what the template provides.  `dims:` and `type:` are also accepted as keyword arguments when mixing with `template:` reads better than positional:
+When both files are NetCDF-4, the template's storage settings — chunk sizes, compression, shuffle, fletcher32 — come along too; its chunk sizes are copied only when the new variable's dimensions have the template's lengths, and libnetcdf chooses them otherwise. Positional args (`type` / `dims`) and kwargs override what the template provides, storage options included. `dims:` and `type:` are also accepted as keyword arguments when mixing with `template:` reads better than positional:
 
 ```ruby
+dst.def_dim("latitude", 3)
 dst.def_var("lat", template: src["lat"], dims: ["latitude"])
 ```
 
-`copy_var` combines the definition copy above with a bit-identical raw data copy — perfect for coordinate variables that pass through unchanged:
+`copy_var` copies a variable's definition, as above, and its values with it, which suits coordinate variables that pass through unchanged. The dimensions have to exist in the destination first: copy them with `copy_dim`, or start the file with `File.create(template:)`. Attribute and storage options (`units:`, `deflate:`, ...) override the source's, as with `def_var`.
 
 ```ruby
+dst.copy_dim("lat", from: src)                        # the dimension first
 dst.copy_var(src["lat"])                              # same name, values included
 dst.copy_var(src["lat"], name: "latitude")            # rename
 dst.copy_var("lat", from: src)                        # look up by name
 %w[time lat lon].each { |n| dst.copy_var(n, from: src) }
 ```
 
-The data goes through the source's `raw` (no decode) and layer 1 (no encode), so the on-disk bytes match exactly — a codec-mediated variable (scale/offset, `_FillValue`) round-trips without any floating-point drift.  If you want a codec-mediated copy, drop back to `def_var(template:)` and write `dst[name] = src[name].to_ca` yourself.
+The stored values are copied unchanged, so a packed variable, or one with a `_FillValue`, is copied with no rounding drift. For a copy that goes through the codec, define the variable with `def_var(template:)` and write `dst[name] = src[name].to_ca` yourself.
 
 `copy_dim` copies a dimension (including the unlimited flag) but not its coordinate variable:
 
@@ -183,7 +196,7 @@ end
 
 | Kwarg | Meaning |
 |---|---|
-| `template: src` | inherit dims, atts, and format (netcdf-4 upgrades) |
+| `template: src` | inherit dims, atts and format (a NetCDF-4 template makes the new file NetCDF-4) |
 | `dims: true` (default) | copy all template dims |
 | `dims: false` | copy no dims |
 | `dims: %w[time lat]` | copy just these dims |
@@ -210,13 +223,13 @@ NC::File.open("reference.nc") do |ref|
       dst.def_var("time", :int, ["time"],
                   units: "hours since #{window.origin}", calendar: "standard")
       dst.def_var("temp", :float, ["time","lat","lon"], _FillValue: -999.9)
-      window.slabs { |t, slab| dst["temp", t, nil, nil] = slab }
+      window.each_slab { |t, slab| dst["temp", t, nil, nil] = slab }
     end
   end
 end
 ```
 
-With `atomic: true` on top, a mid-loop crash leaves neither a partial file nor a stale one — `Dir["out_*.nc"]` tells the truth about what completed.  See the [cookbook batch chapter](07_cookbook.md) for a full example.
+With `atomic: true` on top, an exception mid-loop leaves neither a partial file nor a stale one (a killed process can leave a `*.tmp` file behind) — `Dir["out_*.nc"]` tells the truth about what completed. See the [cookbook](07_cookbook.md#9-generate-a-batch-of-files-from-a-single-reference) for a full example.
 
 ## Defining global attributes
 
@@ -236,7 +249,7 @@ nc.def_att("history", "Created #{Time.now}")
 nc["temp"] = CArray.float32(1, 73, 144) { |i, j, k| some_data(i, j, k) }
 ```
 
-The CArray shape must match the variable's shape. Non-contiguous CArrays (views) are automatically materialized to a contiguous buffer before the write.
+Every fixed dimension must match the CArray's shape; an unlimited one grows to the array's length. A scalar fills the whole variable (`nc["v"] = 7`).
 
 ### Hyperslab write
 
@@ -251,8 +264,6 @@ nc["temp", 5..14, nil, nil] = ten_days  # ten_days.shape == [10, 73, 144]
 nc["temp", 0, 0, 0] = 273.15
 ```
 
-Under the hood the index dispatches to `nc_put_var1` (single point), `nc_put_vara` (contiguous slab), or `nc_put_vars` (strided slab).
-
 ### Unlimited-dimension streaming
 
 An unlimited dimension grows to fit whatever you write:
@@ -263,7 +274,7 @@ NC::File.create("stream.nc") do |nc|
   nc.def_dim("station", 10)
   nc.def_var("obs", :double, ["time", "station"])
 
-  # Write day-by-day.  netcdf grows the time dimension automatically.
+  # Write day by day; libnetcdf grows the time dimension.
   100.times do |day|
     nc["obs", day, nil] = daily_observations(day)   # shape [10]
   end
@@ -274,7 +285,7 @@ You don't need to declare the eventual size — writing beyond the current lengt
 
 ### Writing with a mask
 
-Layer 2 handles masks for you via the codec. On a variable with a `_FillValue` attribute, `UNDEF` cells are encoded to the fill sentinel on write; on read, fill cells decode back to `UNDEF` (see [Codecs](04_codec.md)):
+When the file's `Conventions` attribute names CF or COARDS, the codec handles masks. On a variable with a `_FillValue` attribute, `UNDEF` cells are written as the fill value, and read back as `UNDEF` (see [Codecs](04_codec.md)):
 
 ```ruby
 NC::File.create("masked.nc") do |nc|
@@ -288,21 +299,21 @@ NC::File.create("masked.nc") do |nc|
 end
 ```
 
-Writing a masked CArray to a variable without a `_FillValue` attribute raises — the gem refuses to invent a sentinel silently.
+Writing a masked CArray to a variable with neither `_FillValue` nor `missing_value` raises — the gem refuses to invent a sentinel silently. Without a CF or COARDS `Conventions` attribute (or a codec given with `codec:`), a masked write raises too, so define `Conventions` before the first masked write.
 
 ## Type-matched writes and libnetcdf coercion
 
-You can hand libnetcdf any numeric type; it converts on the way out to match the on-disk type:
+You can write any numeric type; libnetcdf converts it to the on-disk type:
 
 ```ruby
 nc.def_var("count", :int, ["time"])
-nc["count"] = CArray.int64(...)      # OK, libnetcdf narrows int64 -> int32
+nc["count"] = CArray.int64(24).seq   # OK, libnetcdf narrows int64 -> int32
 
 nc.def_var("temp", :float, ["time"])
-nc["temp"] = CArray.float64(...)     # OK, libnetcdf narrows double -> float
+nc["temp"] = CArray.float64(24).seq  # OK, libnetcdf narrows double -> float
 ```
 
-If a value would overflow the target type, libnetcdf raises. When you're writing physical values into a **packed** (scale/offset) variable, the codec divides by `scale_factor`, subtracts `add_offset`, and rounds to the target integer type before the write — see the [Codecs chapter](04_codec.md).
+A float value written to an integer variable is rounded to the nearest integer (`1.7` → `2`), by an array write and a point write alike. If a value would overflow the target type, libnetcdf raises; that includes one that rounding takes past the end of the range (`127.6` into a byte is `128`). When you're writing physical values into a **packed** (scale/offset) variable, the codec subtracts `add_offset`, divides by `scale_factor`, and rounds to the target integer type before the write — see the [Codecs chapter](04_codec.md).
 
 ## Modifying an existing file
 
@@ -316,13 +327,13 @@ end
 
 `File.open(:write)` opens for modification. Adding a new dimension or variable is possible too — `File` re-enters define mode as needed.
 
-Adding a new variable to an existing NetCDF-3 file rewrites the file layout (a libnetcdf constraint, not ours). NetCDF-4 files (`netcdf4: true`) are more flexible.
+Adding a variable to an existing NetCDF-3 file can make libnetcdf rewrite the file, which is slow for a large one. A NetCDF-4 file takes new variables without a rewrite.
 
 ## Zarr stores
 
-libnetcdf 4.8 and later can read and write Zarr.  libnetcdf calls this support NCZarr.  A Zarr store is a directory, not one file: each chunk of a variable is a file of its own, and the metadata is in small JSON files.
+If your libnetcdf (4.8 or later) was built with NCZarr — `nc-config --has-nczarr` says — it can read and write Zarr stores. A Zarr store is a directory, not one file: each chunk of a variable is a file of its own, and the metadata is in small JSON files.
 
-The gem has no separate API for it.  Pass a URL where a path would go, and give the format in its `#mode=` part:
+The gem has no separate API for it. Pass a URL where a path would go, and give the format in its `#mode=` part:
 
 ```ruby
 url = "file:///data/t.zarr#mode=zarr,file"
@@ -339,15 +350,13 @@ NC::File.open(url)          { |nc| nc["t"][] }        # decoded as from a .nc fi
 NC::File.open(url, :write)  { |nc| nc["t", 0, nil] = row }
 ```
 
-- `mode=zarr` reads and writes plain Zarr, the form other tools such as xarray use.  `mode=nczarr` also writes netCDF's own metadata, such as shared dimensions, into the store.
-- `file` puts the store in a local directory.  `s3` puts it in Amazon S3, when libnetcdf was built with S3 support.
-- The `#mode=` part is required.  A plain path ending in `.zarr` creates an ordinary HDF5 file.
-
-Dimensions, attributes, groups, chunking, compression, the codec and hyperslab reads and writes all work as for a NetCDF-4 file.  User-defined types do not.
+- `mode=zarr` reads and writes plain Zarr, the form other tools such as xarray use. `mode=nczarr` also writes NetCDF's own metadata, such as shared dimensions, into the store.
+- `file` puts the store in a local directory. `s3` puts it in Amazon S3, when libnetcdf was built with S3 support.
+- The `#mode=` part is required. A plain path ending in `.zarr` creates an ordinary NetCDF file.
 
-`atomic:` and `clobber: false` / `clobber: :skip` need a file path, so `File.create` raises `ArgumentError` when they come with a URL.  To keep an existing store, check for its directory yourself before calling `create`.
+Dimensions, attributes, groups, chunking, compression, the codec and hyperslab reads and writes all work as for a NetCDF-4 file. User-defined types do not.
 
-This needs a libnetcdf built with NCZarr.  `nc-config --has-nczarr` says whether yours was.
+`atomic:` and `clobber: false` / `clobber: :skip` need a file path, so `File.create` raises `ArgumentError` when they come with a URL. To keep an existing store, check for its directory yourself before calling `create`.
 
 ## A complete CF-compliant example
 
@@ -413,6 +422,6 @@ NC::File.open("cf_demo.nc") do |nc|
   t[0]                            # => #<CATime::Element 2022-01-01T00:00:00Z>
 
   temp = nc["temp"].to_ca         # decoded; fill sentinel -> mask
-  temp.mean                       # centered around 273-290 K
+  temp.mean                       # about 273.5 K
 end
 ```