feat: initial release

Assisted-by: GLM 5.3 Flash

io/doc.go

@@ -0,0 +1,61 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: MIT
+
+// Package io reads and writes the formats scientific data arrives in:
+// comma-separated text, FITS images and tables, HDF5, NetCDF classic
+// and native-endian memory maps. Every loader returns the library's
+// own Array, so a file read is an ordinary value the rest of the
+// library operates on, and every writer takes one.
+//
+// CSV is the interchange format for tabular data with spreadsheets
+// and statistical packages: LoadCSV, LoadCSVReader, SaveCSV and
+// SaveCSVWriter handle 2-D arrays, with or without a header row. The
+// writer formats every numeric dtype the core carries: the integer
+// class as exact integer text, booleans as 0 and 1, floats as float
+// text; complex is refused, because CSV carries plain numeric text
+// and a pair of raw halves would read back as two unrelated columns.
+// The readers parse everything back as float64.
+//
+// FITS is astronomy's archival format. LoadFITS reads a primary image
+// (BITPIX -64 and -32) with its header cards and applies the
+// BSCALE/BZERO scaling; SaveFITS writes one. LoadFITSTable and
+// SaveFITSTable cover the binary and ASCII table extensions, where
+// catalogues and observation logs live.
+//
+// HDF5 is read by LoadHDF5, which returns every dataset of a file by
+// path, with the attributes of the groups it sits in merged into it.
+// Superblocks 0 to 3, object headers of version 1 and 2, symbol-table
+// and link-message groups, contiguous, compact and chunked storage and
+// the deflate, shuffle and fletcher32 filters are supported. Dataset
+// values land the core dtype their datatype declares: fixed-point data
+// by stored width and signedness, the boolean enumeration convention
+// as Bool, floating-point data as float64 or float32 by width. What is
+// not supported, among it dense groups, the version 2 chunk B-tree,
+// string datasets, every big-endian datatype, bit fields, non-boolean
+// enumerations and unsigned 64-bit integers, is refused with an error
+// naming it. SaveHDF5 writes the mirror image in the classic layout
+// or, with Latest, the superblock 3 layout, and SaveHDF5Text writes
+// fixed-length string datasets.
+//
+// NetCDF classic (CDF-1 and CDF-2) is the archival format of climate
+// and ocean science: LoadNetCDF returns named dimensions, variables
+// and global attributes, and SaveNetCDF writes CDF-1. Each variable
+// lands the core dtype its classic type code carries: NC_BYTE as
+// int8, NC_CHAR as uint8 raw bytes (CHAR carries bytes at the array
+// level, never text), NC_SHORT as int16, NC_INT as int32, and
+// NC_FLOAT and NC_DOUBLE as float64. A variable that lands a narrow
+// dtype from a file is refused by SaveNetCDF, whose writer stores
+// float64, float32 and int64 arrays only; convert with Astype first.
+// Record dimensions are read and written in both directions; the
+// writer stores float64, float32 and int64 arrays, and a type code
+// beyond the classic six is refused by name.
+//
+// MapFloats, MapFloat32s and MapInts open a native-endian file as a
+// read-only array without reading it, which suits data far larger than
+// memory; release unmaps it and comes strictly last. SaveNativeFloats
+// writes the format MapFloats reads.
+//
+// Each format is covered by a documented subset and the rest is
+// refused by name, never half-read. Errors carry the library's
+// "tensor: " prefix and the name of the call that produced them.
+package io