3.3 Input Routines

3.3.1 Setup and Sequential Reading

• Reader::open — Opens a path and reads its SDDS header.
• Reader::fromStdin — Reads an SDDS stream from standard input.
• Reader::fromSource — Reads from an application-provided InputSource.
• Reader::openHeaderless and Reader::fromHeaderlessSource — Read data without an SDDS header using a caller-supplied, validated Layout.
• Reader::next — Returns the next page as std::optional<Page>; an empty optional indicates end of input.
• Reader::readAll — Materializes all remaining pages when a streaming loop is not appropriate.

The layout is available immediately after the reader is opened and remains valid for the lifetime of the reader. A minimal page loop is:

The destructor closes an open reader, so an explicit close is not required during exception unwinding. Calling it explicitly is useful when an application wants I/O errors reported before the object leaves scope.

3.3.2 Field and Row Selection

ReadRequest independently selects parameter, array, and column fields. Each FieldSelection may request all fields, no fields, or only named fields. RowSlice selects the first row, an optional count, and a positive stride. Alternatively, last requests a trailing number of rows and is mutually exclusive with first and count.

Projection is applied by the ASCII and binary decoders. Unrequested values are not retained, and fixed-width binary regions are skipped when possible. Every Page nevertheless retains the complete file layout. The parameterLoaded, arrayLoaded, and columnLoaded methods report whether values are present; attempting to access an unloaded field throws StateError. Trailing-row selection on input without a known row count uses bounded storage rather than materializing all rows.

3.3.3 Page Access and Indexing

Parameter, array, and column values may be selected by name or by layout index. Layout::parameterIndex, arrayIndex, and columnIndex validate names and provide indexes for repeated access. Page::row returns a zero-copy RowView; Page::matchRows builds a composable RowMask. The filtered and projected methods return immutable page transformations.

For seekable input, gotoPage positions the next read at a one-based page number. The reader lazily caches page offsets as it scans. Calling buildPageIndex eagerly indexes the complete file, and indexedPageCount reports the count when known. A page seek begins at the nearest cached offset rather than rescanning from the beginning.