carray-netcdf 2.0.0 → 2.1.0

data/docs/04_codec.md

@@ -6,36 +6,25 @@ A **codec** turns raw on-disk values into Ruby-side values on read and back agai
 - **`CF`** — the CF Conventions value transforms.
 - **`COARDS`** — CF's predecessor; functionally identical for the value transforms this codec touches.
 
-The codec runs transparently inside `Var#[]` / `Var#[]=` (both array and scalar paths — see the [reading chapter](02_reading.md#hyperslab-reads-ncvari-j-k)). You usually don't call codec methods directly.
+Every read and write through a `Var` goes through the file's codec — a whole variable, a slab or a single point — so you rarely call a codec yourself.
 
 ## What CF actually does (and doesn't)
 
 | CF attribute | Codec does |
 |---|---|
-| `_Unsigned` | Read: bit-reinterpret signed on-disk type to its unsigned counterpart (`int8 → uint8`, etc.).  Write: reverse.  Runs FIRST so fill/valid/scale all see the correct numeric interpretation. |
-| `_FillValue`, `missing_value` | Read: mask (`UNDEF`).  Write: `UNDEF` → fill sentinel.  If `_Unsigned` is set, the attribute value is reinterpreted to unsigned space before comparison. |
-| `scale_factor`, `add_offset` | Read: `packed × scale + offset`.  Write: `round((v − offset) / scale)` into var type. |
-| `valid_range`, `valid_min`, `valid_max` | Read (opt-in): out-of-range → `UNDEF`.  Write: no effect. |
-| `units` = `"<u> since <ref>"` (+ `calendar`) | Read: `CATime`.  Write: `CATime` → count since ref (a fraction only into a float variable). |
+| `_Unsigned` | Read: bit-reinterpret signed on-disk type to its unsigned counterpart (`int8 → uint8`, etc.). Write: reverse. Applied before the others, so they see unsigned values. |
+| `_FillValue`, `missing_value` | Read: mask (`UNDEF`). Write: `UNDEF` → fill sentinel. If `_Unsigned` is set, the attribute value is reinterpreted to unsigned space before comparison. |
+| `scale_factor`, `add_offset` | Read: `packed × scale + offset`, in float32 when the attributes are float32 (as xarray does). Write: `round((v − offset) / scale)` into var type. |
+| `valid_range`, `valid_min`, `valid_max` | Read (opt-in): out-of-range → `UNDEF`. Write: no effect. |
+| `units` = `"<u> since <ref>"` (+ `calendar`) | Read: `CATime`. Write: `CATime` → count since ref (a fraction only into a float variable). |
 | `units` = anything else (`"m s-1"`, `"K"`, `"kg m-3"`, …) | Raw attribute, **no UDUNITS conversion**. |
 | everything else (`standard_name`, `grid_mapping`, `cell_methods`, `coordinates`, `ancillary_variables`, …) | Raw attribute, no interpretation. |
 
-The last two rows are important: **this codec is a var-local value codec, not a CF data model builder**.  Coordinate systems, cell methods, standard names, grid mappings — all preserved as attributes (`var.att("grid_mapping")` works), but the codec does not interpret them, nor does it walk to sibling variables.  If you need CF data model support (a real coordinate-system layer akin to netCDF-Java's `CoordSystemBuilder`), either build it on top of this codec or reach for a heavier library.
-
-### Contract for codec methods
-
-Every codec method takes `(var, ca)` and only that.  A codec:
-
-- Reads attributes off `var` (own attributes only).
-- Transforms the CArray `ca` (own values only).
-- **Does NOT** walk to `var.file` to reach other variables or global state. Ruby cannot enforce this structurally, but doing so is a contract violation and puts the codec on the wrong side of the boundary.
-- **Does NOT** rely on `var.dims` beyond reading their names (for documentation purposes, if at all) — again, that leaves the variable's frame of reference.
-
-The dispatch that picks a codec at File.open time DOES look at the whole file (specifically the `Conventions` attribute) — that's a one-shot selection, not a per-transform operation, so it stays on the right side of the boundary.
+The codec works on one variable's values. Coordinate systems, grid mappings, cell methods and standard names stay as plain attributes (`var.att("grid_mapping")` works); see [Beyond this gem](00_introduction.md#beyond-this-gem).
 
 ## Codec selection
 
-By default, `File.open` inspects the `Conventions` global attribute:
+By default, a file's codec follows its `Conventions` global attribute. `File.open` looks at it when the file is opened; a file being created looks at it on its first read or write, so define `Conventions` before writing data.
 
 ```ruby
 NC::File.open("cf_file.nc") do |nc|
@@ -51,14 +40,15 @@ NC::File.open("no_conventions.nc") do |nc|
 end
 ```
 
-Naming rules (checked in registry order):
+The rules:
 
 - `Conventions: "COARDS"` (or combos like `"COARDS/CF-1.0"`) → `COARDS`.
 - `Conventions: "CF-1.7"` / `"CF-1.8"` / `"CF 1.7"` / `"CF"` → `CF`.
 - When the whole string matches neither, each of its tokens (split on spaces, commas and slashes) is tried, so `"ACDD-1.3, CF-1.8"` → `CF`.
-- Anything else, including missing → `Identity`.
+- Anything else, including missing → `Identity`. A file with no `Conventions` whose variables carry `_FillValue`, `scale_factor` or time units — what xarray and netCDF4-python write — warns once and suggests `codec: :cf`.
+- Matching is case-sensitive: `"cf-1.8"` is not recognised.
 
-Override on open:
+Choose the codec yourself with `codec:`, on `File.open` or `File.create`:
 
 ```ruby
 NC::File.open("data.nc", codec: :identity)                        # raw only
@@ -84,7 +74,7 @@ end
 NC::File.open("fill.nc") do |nc|
   v = nc["v"].to_ca
   v.is_masked[1]      # => true    (decoded to mask)
-  v[1]                # => UNDEF   (scalar decode too)
+  nc["v"][1]          # => UNDEF   (a point read is decoded too)
   v.count_masked      # => 1
 end
 
@@ -96,12 +86,12 @@ end
 
 If a variable has **both** `_FillValue` and `missing_value`, both sentinels are masked. `missing_value` may be a scalar or an array (multiple sentinels).
 
-Writing `UNDEF` to a variable without a `_FillValue` raises:
+Writing `UNDEF` to a variable with neither `_FillValue` nor `missing_value` raises:
 
 ```ruby
 ca = CA_SHORT([1, 2, 3])
 ca[1] = UNDEF
-nc["v"] = ca   # ArgumentError: no _FillValue to encode masked cells
+nc["v"] = ca   # ArgumentError: variable 'v' has masked values but no _FillValue to encode them
 ```
 
 ## `scale_factor` and `add_offset`
@@ -135,7 +125,7 @@ NC::File.open("packed.nc", codec: :identity) do |nc|
 end
 ```
 
-**Rounding is required.** A bare cast to an integer variable would truncate (`1.0 / 0.1 == 9.999...` → `9`); the codec rounds. Symmetric on read: no rounding, just the linear transform.
+**Rounding is required.** A bare cast to an integer variable would truncate (`0.29 / 0.01 == 28.999999999999996` → `28`); the codec rounds. Reading needs no rounding.
 
 Interaction with `_FillValue`: **fill is judged in packed space, before unpacking.** So `_FillValue: -32768` on a packed short is compared against the raw short values, not against the unpacked physical values.
 
@@ -213,14 +203,20 @@ end
 
 ### N-of-a-unit intervals: `"5 days since ..."`
 
-The codec stores CATime at the base resolution (day, in this case) and folds the count `5` into the numeric values. That way any reference date representable in the base works — including the normal case where the ref doesn't land on the coarser `count × base` grid from the epoch (e.g. `"5 days since 2024-06-15"` — 2024-06-15 is not on a 5-day-from-1970 grid, but it IS on the day grid). The count information isn't lost: it stays on `atts["units"]`, we just don't bake it into CATime's storage tick.
+A count in units such as `"5 days since 2024-06-15"` reads as a CATime at the base unit, a day here, so a stored `1` is 2024-06-20. A write into an integer variable has to land on the 5-day grid; an instant between its steps raises `ArgumentError` (a float variable takes the fraction):
 
 ```ruby
-# raw N reads as N*5 days past 2024-06-15
-dt = CA_INT64([0, 5, 10]).time(unit: :D, origin: "2024-06-15")
-# writing dt to units="5 days since 2024-06-15":
-#   codec.timesteps(unit: :D, origin: "2024-06-15") -> [0, 5, 10]
-#   then / 5 -> [0, 1, 2]  (on-disk)
+NC::File.create("five.nc") do |nc|
+  nc.def_att("Conventions", "CF-1.8")
+  nc.def_dim("time", 3)
+  nc.def_var("time", :int, ["time"], units: "5 days since 2024-06-15")
+  nc["time"] = CA_INT64([0, 5, 10]).time(unit: :D, origin: "2024-06-15")
+end
+
+NC::File.open("five.nc") do |nc|
+  nc["time"].raw.to_a          # => [0, 1, 2]
+  nc["time"][1].to_s           # => "2024-06-20"
+end
 ```
 
 ### Float time coordinates
@@ -234,20 +230,22 @@ units: "days since ..."  with float values 0.0, 0.5, 1.25 -> CATime at 1 h: +0 h
 
 Only `year` and `month` fractions are rounded to the nearest whole tick, since those units have no fixed length.
 
-On write, an instant finer than the units' interval is written as a fraction into a float variable (`01:30` into `"days since ..."` is `0.0625`). An integer variable can't hold one, so the write raises `ArgumentError` instead of truncating.
+On write, an instant finer than the units' interval is written as a fraction into a float variable (`01:30` into `"days since ..."` is `0.0625`). An integer variable can't hold one, so the write raises `ArgumentError` instead of truncating. `months since` and `years since` take only instants on their own grid, into either kind of variable, since a month has no fixed length; a monthly CATime written to `"days since ..."` lands on each month's first day.
+
+The reference time need not fall on the unit's grid. `"days since 2000-01-01 12:00:00"`, a time zone (`+09:00`) or fractional seconds are worked through in the finer unit they need, so a stored `0` reads as the reference instant itself. A short year in the UDUNITS style (`"days since 1-1-1"`) is year 1, not 2001. A `months since` or `years since` reference that is not the head of a month or year is the one case read as raw values, with a warning.
 
 ### Calendars
 
 The codec handles these calendar attribute values:
 
-- `standard`, `gregorian`, `proleptic_gregorian`, or missing → CATime (proleptic Gregorian, UTC).
-- Anything else — `noleap`, `365_day`, `all_leap`, `366_day`, `360_day`, `julian`, `none` — is unsupported. The codec warns once per distinct calendar value and returns raw values unchanged. Writing a `CATime` to a variable with an unsupported calendar raises.
+- `standard`, `gregorian`, `proleptic_gregorian` (in any case), or missing → CATime (proleptic Gregorian, UTC).
+- Anything else — `noleap`, `365_day`, `all_leap`, `366_day`, `360_day`, `julian`, `none` — is unsupported. The codec warns once per calendar value in each opened file and returns raw values unchanged. Writing a `CATime` to a variable with an unsupported calendar raises.
 
-For post-1582 dates, `standard` and `proleptic_gregorian` agree, so CATime is exact for modern climate/ocean data. Pre-1582 or non-standard calendars belong in an external gem.
+`standard` and `gregorian` are CF's mixed calendar: Julian before 1582-10-15, Gregorian from then on. A reference time before the reform (the NCEP-style `"hours since 1-1-1 00:00:0.0"`) is read as the Julian date it is, so every instant from the reform on comes out as cftime and UDUNITS give it. Instants before the reform are shown as proleptic Gregorian, with a warning, and writing one into such units raises; use `calendar: "proleptic_gregorian"` for those, and another library for non-standard calendars.
 
 ## Identity codec
 
-Skip all transforms — raw bytes only:
+Skip all transforms and get the stored values:
 
 ```ruby
 NC::File.open("data.nc", codec: :identity) do |nc|
@@ -257,11 +255,11 @@ NC::File.open("data.nc", codec: :identity) do |nc|
 end
 ```
 
-Useful for round-tripping unknown files, debugging what a producer actually wrote, or side-stepping a codec bug.
+Useful for copying unknown files unchanged, or for seeing what a producer actually wrote.
 
 ## COARDS codec
 
-COARDS (1995) is CF's predecessor. Every adherent COARDS file is also an adherent CF file — spec-inclusion, not just similarity — so `COARDS < CF` inherits every transform; only `self.claims?` differs. Everything above (`_FillValue`, scale/offset, `valid_range`, CF time, calendar policy) applies verbatim.
+COARDS (1995) is CF's predecessor, and a COARDS file is also a CF file, so the COARDS codec is a subclass of CF and applies every transform above. Only the `Conventions` strings it is chosen for differ.
 
 ```ruby
 NC::File.open("coards_file.nc") do |nc|
@@ -271,11 +269,11 @@ NC::File.open("coards_file.nc") do |nc|
 end
 ```
 
-**Check `is_a?(COARDS)` BEFORE `is_a?(CF)`** in an upper-layer dispatcher — COARDS pins the coordinate axis order to `T, Z, Y, X`, so an upper layer that treats a COARDS file as generic CF may silently accept looser axis orderings.  (This value codec doesn't touch axis order, so at THIS layer the distinction doesn't matter; it matters at the layer above.)
+To tell COARDS files apart, test `is_a?(NC::Codec::COARDS)` before `is_a?(NC::Codec::CF)`, because a COARDS codec is also a CF one.
 
 `Conventions` strings that route to COARDS:
-- `"COARDS"` alone.
-- Combos starting with `COARDS` (e.g. `"COARDS/CF-1.0"`) — some tools emit these.
+- A string that starts with `COARDS` (`"COARDS"`, `"COARDS/CF-1.0"`).
+- A string that starts with neither `COARDS` nor `CF`, when one of its words (split at spaces, commas and slashes) starts with `COARDS` — even if another word names CF (`"ACDD-1.3, COARDS"`).
 
 COARDS predates the `calendar` attribute; a COARDS time variable without an explicit calendar lands on the same proleptic-Gregorian axis as CF `"standard"` (identical for post-1582 dates).
 
@@ -285,27 +283,38 @@ The codec interface is minimal:
 
 ```ruby
 class MyCodec
-  # Optional: class method for auto-selection by the Conventions attribute.
-  # Only inspects the Conventions string — deliberately does NOT take the
-  # File, to keep dispatch out of the CDM Layer 2 territory (a "look at
-  # coordinate variables to sniff CF" hook is intentionally not provided).
-  def self.claims?(conventions_string)  = ...
-
-  # Required: the two transforms.  Both are var-local — see the contract
-  # note earlier in this chapter.
-  def decode(var, ca) = ...     # var: Var, ca: raw CArray -> processed value
-  def encode(var, ca) = ...     # var: Var, ca: value -> raw CArray for the on-disk write
+  # Optional: return true for the Conventions strings this codec should be
+  # chosen for. It sees the string only.
+  def self.claims?(conventions)
+    conventions.start_with?("MYCONV")
+  end
+
+  # Required: the two transforms.
+  def decode(var, ca)    # stored values -> what a read returns
+    ca
+  end
+
+  def encode(var, ca)    # what is written -> the values to store
+    ca
+  end
 end
+```
+
+Both methods get one variable and its values. Read what you need from the attributes of `var` itself, and leave other variables alone: a codec runs on every read and write, down to a single point.
 
+Register it so that files whose `Conventions` it claims pick it up:
+
+```ruby
 CA::NetCDF::Codec.register(MyCodec)
 ```
 
-Registered codecs are matched in reverse registration order (later registrations win).  `resolve` accepts:
+A registered class is created with `.new`, with no arguments, when a file's `Conventions` matches it; later registrations are tried first. The `codec:` option of `File.open` and `File.create` accepts:
 
 - `:auto` (default) — match by `Conventions`; fallback `Identity`
 - `:identity` / `false` / `nil` → `Identity`
 - `:cf`, `:coards` → the named codec with defaults
 - `[:cf, opts]`, `[:coards, opts]` → with keyword options
+- a Class — instantiated with no arguments
 - a `Module` (used as-is, e.g. `Identity`)
 - any object that responds to `#decode(var, ca)` and `#encode(var, ca)`
 
@@ -324,30 +333,21 @@ class OnlyMasksCodec
 end
 
 NC::File.open("data.nc", codec: OnlyMasksCodec.new) do |nc|
-  ...
+  # ...
 end
 ```
 
-## Full pipeline order
-
-Decode (read):
-
-1. `decode_unsigned` — `_Unsigned` reinterprets signed on-disk bits to their unsigned counterpart.  Runs FIRST so every subsequent comparison (fill, valid_range) sees the numerically-correct value.
-2. `decode_fill` — `_FillValue` / `missing_value` → mask (in unsigned space if `_Unsigned` was set; the attribute value is reinterpreted).
-3. `decode_valid` — `valid_range` / `valid_min` / `valid_max` → mask (opt-in, same space as fill).
-4. `decode_scale` — `packed × scale + offset`.
-5. `decode_time` — `count-since-ref` → `CATime`.
-
-Encode (write) runs in reverse:
+## Order of the transforms
 
-1. `encode_time` — `CATime` → `count-since-ref`.
-2. `encode_scale` — `round((v − offset) / scale)` for integer var types.
-3. `encode_fill` — `UNDEF` → fill sentinel (in the user's unsigned space).
-4. `encode_unsigned` — reinterpret unsigned user values back to signed on-disk bits.
+Reading applies them in this order, and writing in the reverse:
 
-(`valid_range` has no defined encode direction in CF, and the codec doesn't invent one.)
+1. `_Unsigned` — signed stored values are read as unsigned.
+2. `_FillValue` / `missing_value` — matching values become masked.
+3. `valid_range` / `valid_min` / `valid_max` — values out of range become masked (opt-in, and on reading only; CF defines no write direction).
+4. `scale_factor` / `add_offset` — packed values are unpacked.
+5. A time `units` — counts become CATime.
 
-## Debug / inspect a variable's decode
+## Seeing what the codec changed
 
 ```ruby
 NC::File.open("data.nc") do |nc|
@@ -355,19 +355,11 @@ NC::File.open("data.nc") do |nc|
   v.atts                       # everything the codec might read
   v.codec                      # which codec will run
 
-  raw     = v.raw              # bypass codec → the on-disk values
-  decoded = v.to_ca            # === v.codec.decode(v, v.raw)   (identity)
+  raw     = v.raw              # the stored values, not decoded
+  decoded = v.to_ca            # the same as v.codec.decode(v, v.raw)
 
   # diff them cell by cell to see what the codec actually changed
 end
 ```
 
-The identity `v.to_ca == v.codec.decode(v, v.raw)` holds by construction, so `v.raw` is the canonical descent point when you want to work below the codec — no `instance_variable_get` needed.
-
-You can also open the file with `codec: :identity` to skip decoding for every read in the block:
-
-```ruby
-NC::File.open("data.nc", codec: :identity) do |nc|
-  nc["temp"].to_ca            # raw bytes, uniformly for every variable
-end
-```
+`v.raw` takes the same indexes as `v[...]`, so you can compare a slab before and after decoding.

data/docs/05_groups.md

@@ -2,7 +2,7 @@
 
 NetCDF-4 files can organize their contents in a tree of **groups** — much like directories in a filesystem. Each group has its own dimensions, variables, and global attributes; nested groups form a hierarchy.
 
-The classic NetCDF-3 model is a single root group; every file has one, so in this library **every `File` IS a Group** (the root group). Everything you can do on `File` — `def_dim`, `def_var`, `def_att`, `nc[name]`, `nc[name] = ...` — is a `Group` method, plus subgroup navigation.
+The classic NetCDF-3 model is a single root group; every file has one, so in this library **every `File` is a Group** (the root group). Everything you can do on `File` — `def_dim`, `def_var`, `def_att`, `nc[name]`, `nc[name] = ...` — is a `Group` method, plus subgroup navigation.
 
 ## Creating groups
 
@@ -48,7 +48,7 @@ NC::File.open("model.nc") do |nc|
   surface = ocean.group("surface")
   surface.path                 # => "/ocean/surface"
 
-  nc.name                      # => "/"    (netcdf's root name)
+  nc.name                      # => "/"    (libnetcdf's name for the root group)
   nc.path                      # => "/"
   nc.root?                     # => true
 end
@@ -135,7 +135,7 @@ nc.group("child").resolve_dim("bogus")    # => raises KeyError
 
 ## Per-group attributes
 
-Every group has its own global-attribute set (netcdf-4 changes `NC_GLOBAL` from a single set to per-group). `def_att` / `atts` / `att` on a Group operate on that set:
+In NetCDF-4 each group has its own attributes; `def_att` / `atts` / `att` on a Group read and write that group's:
 
 ```ruby
 NC::File.create("attrs.nc", netcdf4: true) do |nc|
@@ -156,7 +156,7 @@ end
 
 ## Codecs are inherited from the root
 
-The codec is a whole-file policy — `Conventions` at the root determines which codec applies to every variable, including those in subgroups. `Group#codec` delegates to the File.
+The codec is a whole-file policy — `Conventions` at the root determines which codec applies to every variable, including those in subgroups. A `Conventions` attribute on a subgroup is ignored. `Group#codec` delegates to the File.
 
 ```ruby
 NC::File.create("cf_groups.nc", netcdf4: true) do |nc|
@@ -188,7 +188,7 @@ end
 | `group.parent` | parent Group, or `nil` for root |
 | `group.root?` | Boolean |
 | `group.file` | the enclosing File (root Group) |
-| `group.ncid` | raw group ncid (int) |
+| `group.ncid` | the group's id (`grpid` in the netcdf gem), for use with the low-level API |
 | `group.dims` | `{String => Dim}` — this group only |
 | `group.vars` | `{String => Var}` — this group only |
 | `group.groups` | `{String => Group}` — direct children |

data/docs/06_low_level_api.md

@@ -0,0 +1,161 @@
+# Low-level API — the `nc_*` functions
+
+Everyday code uses the high-level API (`File`, `Var`, ...). The low-level API is the CArray-flavored view of the netcdf gem's `nc_*` functions — same names, same argument order, but numeric buffers are CArrays.
+
+Use it when:
+
+- You want to work with ncid and varid integers directly, as in C.
+- You want to stream a very large variable into a preallocated buffer (`nc_get_vara` with an explicit buffer = zero allocation per read).
+- You're bridging to code that already speaks the C `nc_*` idiom.
+- You want to skip the codec and everything else the high-level API adds, for a specific operation.
+
+## The module
+
+`CA::NetCDF` is the low-level API. It `include`s `NetCDF` (the netcdf gem's module) and overrides only the functions that read and write variable data, so that they speak CArray. A class that mixes `CA::NetCDF` in can call every `nc_*` function and `NC_*` constant bare. Called on the module itself, only the overridden get and put functions are public: `NC.nc_get_vara(...)` works, while `NC.nc_open(...)` raises `NoMethodError` — call those on `NetCDF`.
+
+```ruby
+require "carray-netcdf"
+NC = CA::NetCDF
+```
+
+Two idioms:
+
+```ruby
+# (a) call style — module functions
+NC.nc_get_vara(ncid, varid, [0, 0], [3, 4])   # => CArray
+NC::NC_DOUBLE                                  # constants inherited from NetCDF
+
+# (b) mixin style — `nc_*` become bare methods in your class
+class Reader
+  include CA::NetCDF
+  def read_all(ncid, varid) = nc_get_var(ncid, varid)   # bare, returns CArray
+  def define(ncid, name)    = nc_def_dim(ncid, name, 100)   # passes through
+end
+```
+
+## What the low-level API overrides vs passes through
+
+Overridden (numeric array I/O):
+
+- `nc_get_var`, `nc_get_vara`, `nc_get_vars`, `nc_get_varm`
+- `nc_put_var`, `nc_put_vara`, `nc_put_vars`, `nc_put_varm`
+
+Everything else — `nc_open`, `nc_create`, `nc_def_dim`, `nc_def_var`, `nc_put_att`, `nc_get_att`, `nc_inq_*`, `nc_def_grp`, `nc_close`, `NC_DOUBLE`, `NC_CLOBBER`, ... — comes straight from the netcdf gem, which the low-level API includes without modifying.
+
+## `nc_get_var*` — buffer-less returns a CArray
+
+Without a buffer argument, the low-level API allocates a CArray of the requested shape, typed from the variable's on-disk type (`NC_CHAR` as `:uint8`, an enum as its base type), and reads into it:
+
+```ruby
+ncid = NetCDF.nc_open("grid.nc", NetCDF::NC_NOWRITE)   # temp[y, x], a 2-D variable
+vid  = NetCDF.nc_inq_varid(ncid, "temp")
+
+ca = NC.nc_get_var(ncid, vid)                          # whole variable  -> CArray
+ca = NC.nc_get_vara(ncid, vid, [0, 0], [3, 4])         # hyperslab       -> CArray
+ca = NC.nc_get_vars(ncid, vid, [0, 0], [3, 4], [1, 2]) # strided         -> CArray
+ca = NC.nc_get_varm(ncid, vid, [0, 0], [3, 4], [1, 1], [4, 1])  # mapped -> CArray
+
+NetCDF.nc_close(ncid)
+```
+
+No codec runs — this is raw, no `_FillValue → UNDEF`, no scale/offset, no CATime. Use the high-level API for those.
+
+An `NC_STRING` variable has no CArray type: read it with the netcdf gem's `NetCDF.nc_get_var(ncid, varid)`, which returns Strings. An opaque variable raises `NotImplementedError`; read it into a buffer of your own.
+
+## `nc_get_var*` — with a buffer, reads into it
+
+Pass an existing CArray and libnetcdf reads into it, so a slab at a time can be streamed with **no allocation per read**:
+
+```ruby
+ncid = NetCDF.nc_open("big.nc", NetCDF::NC_NOWRITE)
+vid  = NetCDF.nc_inq_varid(ncid, "temp")
+
+buf = CArray.float32(73, 144)   # one time slice
+
+365.times do |day|
+  NC.nc_get_vara(ncid, vid, [day, 0, 0], [1, 73, 144], buf)
+  process(buf)                  # buf now holds day `day`
+end
+
+NetCDF.nc_close(ncid)
+```
+
+The buffer must be one contiguous block of memory: a CArray you allocated, or a contiguous slice of one. A strided view is refused, and so is a buffer too small for the read. Type conversion is handled by libnetcdf — you can read a short variable into a float64 buffer and libnetcdf converts.
+
+## `nc_put_var*` — CArray as buffer
+
+Symmetric. A contiguous CArray goes through as-is:
+
+```ruby
+NC.nc_put_vara(ncid, vid, [0, 0], [3, 4], CArray.float32(3, 4).seq!)
+```
+
+A non-contiguous CArray (a view / slice / reference) is materialized to a contiguous entity before the write:
+
+```ruby
+big = CArray.float32(100, 4).seq!
+NC.nc_put_vara(ncid, vid, [0, 0], [3, 4], big[10..12, nil])
+# big[10..12, nil] is a view of big; it is copied into one block of
+# memory before the write
+```
+
+A **masked** CArray is refused, since the low-level API applies no convention; filling masked elements is the codec's job in the high-level API. Strip the mask first:
+
+```ruby
+ca = CA_SHORT([1, 2, 3])
+ca[1] = UNDEF
+NC.nc_put_vara(ncid, vid, [0], [3], ca)          # ArgumentError
+NC.nc_put_vara(ncid, vid, [0], [3], ca.strip_mask(-32768))    # OK, fill baked in
+```
+
+## `nc_get_var1` / `nc_put_var1` — scalar
+
+These are the netcdf gem's own functions, unchanged; call them on `NetCDF` (or bare, through the mixin):
+
+```ruby
+value = NetCDF.nc_get_var1(ncid, vid, [0, 0])     # Numeric
+NetCDF.nc_put_var1(ncid, vid, [0, 0], 273.15)     # writes one cell
+```
+
+The high-level API's scalar decode/encode wraps these calls in a 1-cell CArray to run through the codec — see [Codecs](04_codec.md).
+
+## Definition, inquiry, attribute — all passthrough
+
+The netcdf gem covers everything else. Call these on `NetCDF`, or bare through the mixin; only `nc_put_var` below is `CA::NetCDF`'s, because it writes a CArray:
+
+```ruby
+# create + define
+ncid = NetCDF.nc_create("out.nc", NetCDF::NC_CLOBBER | NetCDF::NC_NETCDF4)
+tid  = NetCDF.nc_def_dim(ncid, "time", 24)
+vid  = NetCDF.nc_def_var(ncid, "temp", NetCDF::NC_FLOAT, [tid])
+NetCDF.nc_put_att(ncid, vid, "units", "K")
+NetCDF.nc_enddef(ncid)
+
+# write and close
+NC.nc_put_var(ncid, vid, CArray.float32(24).seq!)
+NetCDF.nc_close(ncid)
+
+# inquire
+ncid = NetCDF.nc_open("out.nc", NetCDF::NC_NOWRITE)
+NetCDF.nc_inq_ndims(ncid)                              # => 1
+NetCDF.nc_inq_nvars(ncid)                              # => 1
+NetCDF.nc_inq_varname(ncid, 0)                         # => "temp"
+NetCDF.nc_inq_vardimid(ncid, 0)                        # => [0]
+NetCDF.nc_inq_dimlen(ncid, 0)                          # => 24
+NetCDF.nc_close(ncid)
+```
+
+## Moving between the two APIs
+
+A `File`, `Group` or `Var` gives the ids the low-level API takes: `nc.ncid`, `group.ncid` and `var.varid`. A `File` keeps track of define and data mode itself, so inside one, switch modes with `nc.ensure_data_mode` / `nc.ensure_define_mode` rather than `nc_enddef` / `nc_redef`:
+
+```ruby
+NC::File.open("big.nc") do |nc|
+  buf = CArray.float32(73, 144)
+  NC.nc_get_vara(nc.ncid, nc["temp"].varid, [0, 0, 0], [1, 73, 144], buf)
+end
+```
+
+The high-level objects read a file's dimensions, variables, groups and attributes when it is opened, and keep them up to date through their own `def_*` calls. A change made through the low-level API — an attribute added with `nc_put_att`, a variable renamed or defined on `nc.ncid` — is seen after `nc.reload` (or `group.reload`), which also chooses the codec again; take new `Var` / `Dim` objects after it.
+
+`CA::NetCDF` leaves the netcdf gem's `NetCDF` module unchanged: `NetCDF.nc_get_vara(ncid, varid, start, count, buf)` still reads into whatever buffer you pass.