carray-netcdf 2.0.0 → 2.1.0

data/docs/08_cheatsheet.md

@@ -4,38 +4,36 @@ Tables of everything this gem gives you to call. Read [getting started](01_getti
 
 Conventions:
 
-- **L0** = the [netcdf](https://github.com/himotoyoshi/netcdf) gem (`::NetCDF`), a thin libnetcdf binding.
-- **L1** = `CA::NetCDF` module functions; the L0 API with the array I/O calls overridden to speak CArray. Everything else passes through because L1 `include`s L0.
-- **L2** = `CA::NetCDF::{File, Group, Var, Dim, Codec}` classes.
+- **The netcdf gem** = [netcdf](https://github.com/himotoyoshi/netcdf) (`NetCDF`), a near one-to-one binding to libnetcdf.
+- **Low-level API** = `CA::NetCDF`; the netcdf gem's API with the variable-data get / put calls overridden to speak CArray. Everything else passes through because `CA::NetCDF` `include`s the netcdf gem.
+- **High-level API** = the `CA::NetCDF::File`, `Group`, `Var` and `Dim` classes, and the codecs in `CA::NetCDF::Codec`.
 
 In every table, `→` is the return value.
 
 ---
 
-## L0 — the netcdf gem
+## The netcdf gem
 
-Layer 0 is the [netcdf](https://github.com/himotoyoshi/netcdf) gem itself: `::NetCDF`, one module function per libnetcdf function, plus the `NC_*` constants. Its own reference lists all of them, and is the place to look them up.
+This is the [netcdf](https://github.com/himotoyoshi/netcdf) gem itself: `NetCDF`, one module function per libnetcdf function, plus the `NC_*` constants. Its own reference lists all of them, and is the place to look them up.
 
-Reaching for L0 from here is the exception, not the rule. Anything it can do that layer 2 cannot is a gap worth reporting; the layers below are there to be built on, not to be called around.
+## Low-level API — `CA::NetCDF`
 
-## L1 — `CA::NetCDF`
-
-The whole `::NetCDF` module is `include`d into `CA::NetCDF`, so everything from L0 above is callable — as `CA::NetCDF.nc_open(…)` or via mixin (`include CA::NetCDF` and call `nc_open(…)` bare). Only the array I/O calls are overridden to speak CArray.
+The whole `NetCDF` module is `include`d into `CA::NetCDF`, so everything from the netcdf gem above is callable via mixin (`include CA::NetCDF` and call `nc_open(…)` bare). Called on the module, only the overridden functions below are public (`CA::NetCDF.nc_get_vara(…)`); call the rest on `NetCDF` (`NetCDF.nc_open(…)`).
 
 ### Overridden functions
 
 | Call | Behavior |
 |---|---|
-| `nc_get_var(ncid, varid, buffer=nil)` | Without buffer: L1 allocates a CArray of the variable's type (`NC_CHAR` → `:uint8`) and reads into it. With CArray buffer: read into it. |
+| `nc_get_var(ncid, varid, buffer=nil)` | Without buffer: a new CArray of the variable's type (`NC_CHAR` → `:uint8`, an enum → its base type). With a buffer (a CArray, or any MemoryView provider): reads into it and returns it. `NC_STRING` raises `NotImplementedError`; read it with `NetCDF.nc_get_var`. |
 | `nc_get_vara(ncid, varid, start, count, buffer=nil)` | Same, hyperslab. |
 | `nc_get_vars(ncid, varid, start, count, stride, buffer=nil)` | Same, strided. |
 | `nc_get_varm(ncid, varid, start, count, stride, imap, buffer=nil)` | Same, mapped. |
-| `nc_put_var(ncid, varid, ca)` | Contiguous CArray passes through. Non-contiguous view → `.copy`. Masked → `ArgumentError` (mask/fill is L2). |
+| `nc_put_var(ncid, varid, ca)` | A contiguous CArray is written as it is; a view is copied into one block first. Masked → `ArgumentError` (mask/fill belongs to the high-level API). |
 | `nc_put_vara(ncid, varid, start, count, ca)` | Same. |
 | `nc_put_vars(ncid, varid, start, count, stride, ca)` | Same. |
 | `nc_put_varm(ncid, varid, start, count, stride, imap, ca)` | Same. |
 
-Everything else on `::NetCDF` (see [L0](#l0--the-netcdf-gem) above) is a passthrough. All the `NC_*` constants are visible via the include:
+Everything else on `NetCDF` (see [the netcdf gem](#the-netcdf-gem) above) is a passthrough. All the `NC_*` constants are visible via the include:
 
 ```ruby
 CA::NetCDF::NC_DOUBLE       # => 6
@@ -52,13 +50,13 @@ CA::NetCDF.nc_get_vara(ncid, varid, [0, 0], [3, 4])   # => CArray
 class Reader
   include CA::NetCDF
   def read(ncid, varid) = nc_get_var(ncid, varid)          # bare -> CArray
-  def define(ncid, ...) = nc_def_dim(ncid, "time", 100)   # passthrough
+  def define(ncid, name) = nc_def_dim(ncid, name, 100)     # passthrough
 end
 ```
 
 ---
 
-## L2 — `CA::NetCDF::File / Group / Var / Dim / Codec`
+## High-level API — `File`, `Group`, `Var`, `Dim` and `Codec`
 
 ### `CA::NetCDF::File` (class methods)
 
@@ -66,51 +64,53 @@ end
 |---|---|
 | `File.open(path, mode = :read, codec: :auto)` | File; `mode` is `:read` / `:write` / `:append` |
 | `File.open(path, ...) { \|nc\| ... }` | value of block; auto-closes on exit / exception |
-| `File.create(path, codec: :auto, clobber: true, netcdf4: false, atomic: false, template: nil, dims: true, atts: true, vars: [], **var_defaults)` | File in define mode.  See details below. |
-| `File.create(path, ...) { \|nc\| ... }` | value of block; auto-closes.  Under `atomic: true`: commits on successful block exit, aborts (unlinks tmp) on exception.  Under `clobber: :skip` with existing target: block is not called; returns `nil`. |
+| `File.create(path, codec: :auto, clobber: true, netcdf4: nil, format: nil, atomic: false, template: nil, dims: true, atts: true, vars: [], **var_defaults)` | File in define mode. See details below. |
+| `File.create(path, ...) { \|nc\| ... }` | value of block; auto-closes. Under `atomic: true`: commits on successful block exit, aborts (unlinks tmp) on exception. Under `clobber: :skip` with existing target: block is not called; returns `nil`. |
 
 Kwargs on `File.create`:
 
 | Kwarg | Meaning |
 |---|---|
-| `codec:` | codec dispatch (`:auto` / `:identity` / `:cf` / `[:cf, opts]` / ...) — see [codec.md](04_codec.md) |
+| `codec:` | codec dispatch (`:auto` / `:identity` / `:cf` / `[:cf, opts]` / ...) — see the [Codecs chapter](04_codec.md) |
 | `clobber: true` (default) | overwrite an existing target file |
 | `clobber: false` | raise `Errno::EEXIST` if target exists |
 | `clobber: :skip` | if target exists, don't call the block, return `nil` (restartable loops) |
-| `netcdf4: true` | create as NetCDF-4 (auto-inherited from `template:` if not set) |
+| `netcdf4: true / false` | create as NetCDF-4 / classic; left out (`nil`), it follows `template:`'s format |
+| `format: :classic / :offset64 / :cdf5 / :netcdf4 / :netcdf4_classic` | create in that format (instead of `netcdf4:`); a template's format is kept the same way |
 | `atomic: true` | write to same-dir tmp; rename on successful close; unlink tmp on exception |
 | `template: file_or_group` | inherit skeleton (dims + atts + format) from another open File/Group |
 | `dims: true / false / [names]` | which template dims to copy (default all) |
 | `atts: true / false / {overrides}` | which template atts to copy; Hash merges overrides |
-| `vars: [names]` | template vars to fully copy (definition + bit-identical data) |
-| `chunks: / deflate: / shuffle: / fletcher32: / endian: / no_fill:` | file-wide var defaults, applied to every `def_var` (per-var kwarg wins) |
+| `vars: [names]` | template vars to copy in full (definition, storage settings and stored values) |
+| `chunks: / deflate: / shuffle: / zstandard: / bzip2: / szip: / blosc: / fletcher32: / endian: / no_fill:` | file-wide var defaults, applied to every `def_var` (per-var kwarg wins); values as in [Storage options](#storage-options) below |
 
-`path` may be a Zarr URL (`"file:///data/t.zarr#mode=zarr,file"`) for `open` and `create` alike; `atomic:` and `clobber: false / :skip` then raise `ArgumentError`.  See [Zarr stores](03_writing.md#zarr-stores).
+`path` may be a Zarr URL (`"file:///data/t.zarr#mode=zarr,file"`) for `open` and `create` alike; `atomic:` and `clobber: false / :skip` then raise `ArgumentError`. See [Zarr stores](03_writing.md#zarr-stores).
 
 ### `File` instance (adds these to what `Group` provides)
 
 | Call | → |
 |---|---|
 | `#filename` | on-disk path |
-| `#format` | `nc_inq_format(ncid)` |
+| `#format` | the `NC_FORMAT_*` Integer |
 | `#conventions` | tokenized `Conventions` attribute (`["CF-1.7", "ACDD-1.3"]`); `[]` if absent |
-| `#codec` | resolved codec instance (`Codec::Identity` / `::CF` / `::COARDS`) |
-| `#close` | close the file (idempotent).  For an atomic-write File, renames tmp → filename here. |
-| `#abort` | atomic-write only: close without renaming, unlink the tmp.  Idempotent. |
+| `#codec` | the codec object (`Codec::Identity`, or a `Codec::CF` / `Codec::COARDS` instance) |
+| `#netcdf4?` | true for a NetCDF-4 or NetCDF-4 classic model file |
+| `#close` | close the file (idempotent). For an atomic-write File, renames tmp → filename here. |
+| `#abort` | roll back definitions not yet committed and close (`nc_abort`); a file created here still in define mode is removed, and an atomic write's tmp unlinked. Idempotent. |
 | `#closed?` | Boolean |
 | `#atomic?` | Boolean — is this an atomic-write File that has not yet committed? |
 | `#tmp_path` | the tmp path an atomic write is going to (nil for regular / after commit) |
 | `#var_defaults` | file-wide var option defaults (frozen Hash) |
-| `#ensure_define_mode` / `#ensure_data_mode` | manual mode transitions (rarely needed) |
-| `#__transaction__(define: true) { ... }` | run block in define or data mode |
+| `#reload` | read dims / vars / groups / attributes again after low-level changes, and choose the codec again; returns `self` (also on `Group`) |
+| `#ensure_define_mode` / `#ensure_data_mode` | switch modes, when you mix low-level calls into a `File` (also on `Group`) |
 
-### `Group` (base for `File`; both act as the root group in a NetCDF-4 file)
+### `Group` (a `File` is a `Group`, the root one)
 
 **Identity**
 
 | Call | → |
 |---|---|
-| `#ncid` | raw group ncid |
+| `#ncid` | the group's id, for the low-level API |
 | `#file` | root `File` |
 | `#parent` | parent `Group`, `nil` for root |
 | `#name` | `"foo"` (or `"/"` for root) |
@@ -121,7 +121,7 @@ Kwargs on `File.create`:
 
 | Call | → |
 |---|---|
-| `#dims` | `{String => Dim}` |
+| `#dims` | `{String => Dim}` (a frozen copy, as are `vars` and `groups`) |
 | `#vars` | `{String => Var}` |
 | `#groups` | `{String => Group}` |
 | `#atts` | `{String => value}` (frozen), this group's globals |
@@ -134,7 +134,7 @@ Kwargs on `File.create`:
 
 | Call | → |
 |---|---|
-| `#[](name)` | Var — accepts `"temp"`, `"foo/temp"`, `"/foo/temp"` |
+| `#[](name)` | Var — accepts `"temp"`, `"foo/temp"`, `"/foo/temp"`; raises `KeyError` if there is none |
 | `#[]=(name, ca)` | whole-variable write |
 | `#[]=(name, *index, ca)` | hyperslab write (delegates to `Var#[]=`) |
 
@@ -142,13 +142,14 @@ Kwargs on `File.create`:
 
 | Call | → |
 |---|---|
-| `#def_dim(name, length)` | Dim; `length: :unlimited` or an integer |
-| `#def_var(name, type, dims=[], **atts_or_opts)` | Var; type is a Symbol (`:float`, `:short`, …).  Reserved kwargs (netcdf-4): `chunks:` / `deflate:` / `shuffle:` / `fletcher32:` / `endian:` / `no_fill:`.  Every other kwarg is a variable attribute. |
-| `#def_var(name, template: src_var, **overrides)` | copy a definition (type, dims, attributes) from another Var; `**overrides` merges/replaces atts.  `type` and `dims:` can also override. |
-| `#def_att(name, value)` | value; writes to this group's `NC_GLOBAL` |
+| `#def_dim(name, length)` | Dim; `length` is `:unlimited` or an Integer |
+| `#def_var(name, type = nil, dims = nil, template: nil, **atts)` | Var; `type` is a Symbol or String (`:float`, `"short"`, …) or an `NC_*` constant; `type:` and `dims:` are accepted as keywords too. Storage options ([below](#storage-options)) are reserved kwargs; every other kwarg is a variable attribute. |
+| `#def_var(name, template: src_var, **overrides)` | copy a definition (type, dims, attributes) from another Var; overrides merge into / replace its attributes, and `type` / `dims` can be given too. Between two NetCDF-4 files the storage settings come along; the chunk sizes only when the new dimensions have the template's lengths. |
+| `#def_var(name, template: group)` | the same, with the variable of the same name in that File / Group |
+| `#def_att(name, value)` | value; writes to this group's attributes (a CArray value keeps its own type). On a File, redefining `Conventions` chooses the codec again. |
 | `#def_group(name)` | Group; creates a subgroup |
 | `#copy_dim(dim_or_name, from: nil, name: nil)` | copy a dimension (unlimited status preserved); optionally rename |
-| `#copy_var(var_or_name, from: nil, name: nil, **overrides)` | copy a variable's definition **AND** its data bit-identically (raw + layer-1 write, both codec-bypassed); optionally rename / override attrs |
+| `#copy_var(var_or_name, from: nil, name: nil, **overrides)` | copy a variable's definition and its stored values unchanged; the dimensions must already exist. Optionally rename / override attributes and storage options. |
 
 ### `Var`
 
@@ -157,15 +158,19 @@ Kwargs on `File.create`:
 | Call | → |
 |---|---|
 | `#name` | variable name |
-| `#shape` | Array of Integer (refreshed on every `[]`/`[]=`, so unlimited dim growth is visible) |
+| `#shape` | current shape, asked of the file each time, so the growth of an unlimited dimension shows |
 | `#ndim` | rank |
-| `#nc_type` | raw NC_* integer |
+| `#nc_type` | the `NC_*` type constant |
+| `#varid` | the variable's id, for the low-level API |
+| `#scalar?` | true for a variable with no dimensions |
 | `#data_type` | CArray Symbol (`:float32`, `:int16`, …) |
 | `#dims` | Array of Dim (with dim inheritance resolved) |
 | `#atts` | `{String => value}` (frozen) |
-| `#att(name)` | one attribute or `nil` |
+| `#att(name)` | one attribute (frozen) or `nil` |
+| `#att_type(name)` | the `NC_*` type the attribute is stored in, or `nil` |
 | `#file` / `#group` | enclosing File / Group |
 | `#codec` | delegates to `file.codec` |
+| `#storage_options` | the variable's chunking / compression / fletcher32 / endian / no_fill settings, in `def_var`'s keyword form (`{}` in a classic file) |
 
 **Read (`[]` — lazy hyperslab + decode)**
 
@@ -179,7 +184,7 @@ Kwargs on `File.create`:
 | `#[(a..b).step(s), ...]` | strided hyperslab |
 | `#[bool_or_fancy]` | reads whole var + does CArray indexing on the result |
 | `#raw` / `#raw(*idx)` | same indexing as `#[]`, but **bypasses the codec**; `v[...] == v.codec.decode(v, v.raw(...))` |
-| `#method_missing(id, *)` | forwards to `to_ca.__send__(id, *)` — `var.mean`, `var.sum`, …; in-place methods (`fill`, `*!`, `*=`) raise |
+| any CArray method (`var.mean`, `var.sum(0)`, …) | called on `to_ca`, reading the whole variable each time; in-place methods (`fill`, `*!`, `*=`) raise `NoMethodError` |
 
 **Write (`[]=`)**
 
@@ -215,6 +220,7 @@ Kwargs on `File.create`:
 | `:coards` | `Codec::COARDS.new` |
 | `[:cf, opts]` | `Codec::CF.new(**opts)` |
 | `[:coards, opts]` | `Codec::COARDS.new(**opts)` |
+| a codec Class (e.g. `Codec::CF`) | an instance, made with no arguments |
 | a stateless codec `Module` (e.g. `Codec::Identity`) | itself |
 | any object with `#decode(var, ca)` and `#encode(var, ca)` | itself |
 
@@ -222,15 +228,15 @@ Kwargs on `File.create`:
 
 | Class method | Purpose |
 |---|---|
-| `self.claims?(conventions_string)` | Should this codec claim a file whose `Conventions` attribute equals this string?  (Only the string; deliberately no file-inspection hook — that would push the codec toward CDM Layer 2 territory.) |
+| `self.claims?(conventions_string)` | true if this codec should be chosen for this `Conventions` string (called with the whole string, then with each word). Needed only for a registered codec. |
 | Instance methods | |
-| `#decode(var, ca)` | raw on-disk → user-facing value (var-local: read `var.atts` only, never walk to `var.file`) |
-| `#encode(var, ca)` | user-facing → raw on-disk (same contract) |
+| `#decode(var, ca)` | stored values → what a read returns (use `var`'s own attributes only) |
+| `#encode(var, ca)` | what is written → the values to store (the same) |
 
 **Registration**
 
 ```ruby
-CA::NetCDF::Codec.register(MyCodec)   # later registrations win on `applies?`
+CA::NetCDF::Codec.register(MyCodec)   # registered later = tried first, by `claims?`
 ```
 
 **Built-in: `Codec::Identity`** — module, stateless; `decode`/`encode` pass values through unchanged.
@@ -240,7 +246,7 @@ CA::NetCDF::Codec.register(MyCodec)   # later registrations win on `applies?`
 | Call | Purpose |
 |---|---|
 | `CF.new(mask_valid_range: false)` | Options |
-| `CF.claims?(s)` | `"CF-*"`, `"CF "`, `"CF"` |
+| `CF.claims?(s)` | a string starting `"CF-"` or `"CF "`, or `"CF"` (case-sensitive) |
 | `#mask_valid_range` | Boolean reader |
 | `#decode(var, ca)` | fill → mask, (opt-in) valid_range → mask, unpack scale/offset, CF time → CATime |
 | `#encode(var, ca)` | reverse (CATime → count, pack, mask → fill) |
@@ -249,14 +255,14 @@ CF attributes recognized (decode order):
 
 | Attribute | Effect (decode → encode) |
 |---|---|
-| `_Unsigned` | signed on-disk → unsigned user (bit-reinterpret); reverse on write.  Runs FIRST so fill/valid/scale see numerically-correct values. |
+| `_Unsigned` | signed on-disk → unsigned user (bit-reinterpret); reverse on write. Applied before the others, so they see unsigned values. |
 | `_FillValue`, `missing_value` | mask ↔ sentinel (in unsigned space if `_Unsigned` was set) |
 | `valid_range` / `valid_min` / `valid_max` | (opt-in) out-of-range → UNDEF, same space as fill; encode not defined by CF |
 | `scale_factor`, `add_offset` | `v = packed*sf + ao` ↔ `packed = round((v-ao)/sf)` (round only when var is integer) |
 | `units: "<u> since <ref>"` + `calendar` | CATime ↔ count-since-ref int |
 | `units` = anything else | raw (no UDUNITS conversion) |
 
-Supported calendars: `standard`, `gregorian`, `proleptic_gregorian`, missing → CATime (proleptic Gregorian, UTC). Everything else (`noleap`, `360_day`, `julian`, …) warns once and returns raw values on read; write raises.
+Supported calendars: `standard`, `gregorian`, `proleptic_gregorian` (any case), missing → CATime (proleptic Gregorian, UTC). Everything else (`noleap`, `360_day`, `julian`, …) warns once per file and returns raw values on read; write raises.
 
 CF time unit words → CATime base:
 
@@ -272,9 +278,28 @@ CF time unit words → CATime base:
 | `microsecond` … `usec` … `us` | `:us` |
 | `nanosecond` … `nsec` … `ns` | `:ns` |
 
-An `<count> <base>` form like `"5 days since 2024-06-15"` is stored as CATime at the base (`:D`) with the count (`5`) folded into the numeric values — see [codec.md](04_codec.md#n-of-a-unit-intervals-5-days-since-).
+An `<count> <base>` form like `"5 days since 2024-06-15"` is stored as CATime at the base (`:D`) with the count (`5`) folded into the numeric values — see the [Codecs chapter](04_codec.md#n-of-a-unit-intervals-5-days-since-).
+
+**Built-in: `Codec::COARDS < CF`** — same transforms; chosen for a string starting with `COARDS`, or for one starting with neither `COARDS` nor `CF` that has a word starting with `COARDS` (tried before CF).
+
+---
 
-**Built-in: `Codec::COARDS < CF`** — same transforms; `claims?` matches `"COARDS"` and `"COARDS/*"`.
+## Storage options
+
+Reserved kwargs of `def_var`, and file-wide defaults on `File.create`. All but `no_fill:` and `deflate: 0` need a NetCDF-4 file; zstandard, bzip2 and blosc need libnetcdf 4.9, and a compressor libnetcdf lacks raises `NetCDF::Error`. `Var#storage_options` gives them back in this form.
+
+| Kwarg | Values |
+|---|---|
+| `chunks:` | `[sizes]`, `:contiguous` or `:compact` |
+| `deflate:` | level 1..9 (`0` / `nil` = off) |
+| `shuffle:` | `true` / `false` |
+| `zstandard:` | level (`0` / `nil` = off) |
+| `bzip2:` | level 1..9 (`0` / `nil` = off) |
+| `szip:` | `{ coding: :nn \| :ec, pixels_per_block: 32 }` |
+| `blosc:` | `{ compressor: :lz \| :lz4 \| :lz4hc \| :snappy \| :zlib \| :zstd, level: 5, blocksize: 0, shuffle: :none \| :byte \| :bit }` |
+| `fletcher32:` | `true` / `false` |
+| `endian:` | `:native`, `:little` or `:big` |
+| `no_fill:` | `true` / `false` |
 
 ---
 
@@ -311,9 +336,9 @@ An `<count> <base>` form like `"5 days since 2024-06-15"` is stored as CATime at
 | `NC_FLOAT` | `:float32` |
 | `NC_DOUBLE` | `:float64` |
 
-## Attribute name → typed writer
+## Attributes written in the variable's type
 
-L2's `def_var(..., **atts)` writes these attribute names via the typed `nc_put_att_<type>` so libnetcdf accepts them (CF §2.5.1 requires them to match the variable's on-disk type):
+`def_var(..., **atts)` and `Var#def_att` write these attributes in the variable's on-disk type, as CF §2.5.1 asks (libnetcdf requires it of `_FillValue`):
 
 | Attribute name | Written as |
 |---|---|
@@ -323,4 +348,4 @@ L2's `def_var(..., **atts)` writes these attribute names via the typed `nc_put_a
 | `valid_min` | " |
 | `valid_max` | " |
 
-Everything else goes through the generic `nc_put_att`, which infers the type from the Ruby value.
+This holds for a CArray value too. Other attributes take a NetCDF type inferred from the Ruby value; a CArray value keeps its own type, and must be unmasked (a multi-dimensional one is flattened).

data/docs/09_cli.md

@@ -1,6 +1,6 @@
 # Command-line tools
 
-The gem installs two executables.  Both work on any NetCDF file, whoever wrote it, and both are thin scripts — `ncheader` over the netcdf gem's `nc_inq_*` calls, `ncvar` over layer 1, which reads into a CArray — so read them (`gem contents carray-netcdf`) if you want a worked example of walking a file.
+The gem installs two executables.  Both work on any NetCDF file, whoever wrote it, and both are thin scripts — `ncheader` over the netcdf gem's `nc_inq_*` calls, `ncvar` over the low-level API, which reads into a CArray — so read them (`gem contents carray-netcdf`) if you want a worked example of walking a file.
 
 ## ncheader — what is in this file
 
@@ -30,7 +30,7 @@ variables:
 }
 ```
 
-The JSON and YAML forms are there for scripting — a schema check in CI, a diff between two files' structure, a generator that reads the header and writes something else.
+The JSON and YAML forms are there for scripting — a schema check in CI, a diff between two files' structure, a generator that reads the header and writes something else. A NaN or infinite attribute (a common `_FillValue`) is written as a bare `NaN` / `Infinity`, as Python's `json` does; parse it with `allow_nan` (Ruby) or Python's default. A byte in a text attribute that is not part of a UTF-8 character, as in an old Latin-1 file, is written as `\xNN`, in every format.
 
 ## ncvar — get the values out
 
@@ -51,7 +51,7 @@ ncvar -s 0,0 -c 10,20 FILE.nc temperature        # a 10x20 corner
 ncvar -s 0,0 -c 10,10 -S 1,2 FILE.nc temperature # every second column of it
 ```
 
-Omitted, `-s` is all zeros and `-c` is the rest of each dimension.  `-c` counts the elements actually read, not the span they cover, so a stride of 2 goes with half the count — asking for 20 with `-S 1,2` reaches past the end and raises `NetCDF: Start+count exceeds dimension bound`.
+Omitted, `-s` is all zeros and `-c` is the rest of each dimension, taking every stride-th element, so `-S 2` alone reads every second element to the end. A given `-c` counts the elements actually read, not the span they cover, so a stride of 2 goes with half the count — asking for 20 with `-S 1,2` reaches past the end and raises `NetCDF: Start+count exceeds dimension bound`. A `-s` past the end of a dimension is refused with a message.
 
 A variable inside a group is named by its path:
 
@@ -76,4 +76,4 @@ Since the stream carries no shape or type, take those from `ncheader` (or `-f js
 
 ### Character and string variables
 
-`NC_CHAR` is bytes, and comes out as bytes: raw mode writes them unchanged, `-f text` writes them as one string, `-f json` puts that string in `data`.  `NC_STRING` is a sequence of separate strings, so `-f text` prints one per line, `-f json` keeps the nesting of the variable's shape, and raw mode joins them with a NUL — the one case where the raw stream needs a separator to be readable at all.
+`NC_CHAR` is bytes, and comes out as bytes: raw mode writes them unchanged, `-f text` writes them as one string, `-f json` puts that string in `data`, with any byte that is not UTF-8 written as `\xNN`.  `NC_STRING` is a sequence of separate strings, so `-f text` prints one per line, `-f json` keeps the nesting of the variable's shape, and raw mode joins them with a NUL — the one case where the raw stream needs a separator to be readable at all.