Skip to content

Fix constituent table alignment, verify header CRC, add a TCD writer (1.1.0) - #1

Merged
jpr5 merged 6 commits into
masterfrom
reader-alignment-and-writer
Oct 12, 2026
Merged

jpr5 merged 6 commits into
masterfrom
reader-alignment-and-writer

Conversation

@jpr5

@jpr5 jpr5 commented Oct 12, 2026

Copy link
Copy Markdown
Owner

Release 1.1.0. Two new features and one reader fix, all checked against libtcd 2.2.7 and XTide 2.15.6.

What changed

  • Constituent table alignment (fix). libtcd starts each equilibrium and node-factor table on a byte boundary. The reader did not, so any TCD whose constituent count is not a multiple of 8 read wrong values. The stock XTide file read correctly; the 178-constituent OTC file read 175 of 178 equilibrium rows and all 178 node-factor rows wrong. New fixture test/fixtures/unaligned-11.tcd (built with libtcd) covers it.
  • Header CRC verification (feature). Reader.new now checks the header CRC-32, as libtcd does, and raises TCD::ChecksumError on a mismatch. verify_checksum: false skips it.
  • TCD::Writer (feature). Writes TCD files that libtcd and XTide read, from a reader (Writer.from_reader) or from plain data.
  • Writer input validation. The writer refuses input that libtcd or XTide would misread with an ArgumentError instead of writing a corrupt file.
  • Version 1.1.0, README and CHANGELOG updated.

Proof

  • Reader vs libtcd full dump (header, every table, every constituent for every year, every station field): stock and OTC both IDENTICAL (about 245,700 lines each). Before the fix, OTC differed as described above.
  • CRC: before the change, the gem opened a stock file with one header byte flipped while libtcd refused it; after, the gem refuses it too. Mutation check: 7/7 killed.
  • Writer: reading then writing the stock and OTC files gives byte-identical output. libtcd opens the written files and dumps them identically. XTide gives identical station lists (8,065 lines) and identical hourly predictions for 2026 at 5 stations (tide and current, reference and subordinate). Shifting the M2 epoch by 10 degrees makes XTide differ, so the comparison is sensitive. Mutation check: 11/11 killed.
  • Validation: adversarial cases now either round-trip through the gem and libtcd or are refused by the writer (97 refusals). 23/23 new guards are killed by the tests.
  • Suite: 90 runs, 9136 assertions, 0 failures, 0 errors, 0 skips (with the libtcd-backed test turned on via TCD_LIBTCD_DUMP).
  • gem build builds tcd-1.1.0.gem with every lib file included.

jpr5 added 6 commits October 11, 2026 20:09
libtcd writes the speed, equilibrium and node-factor tables each into a
whole number of bytes. The reader read them as one bit stream, so when
the constituent count is not a multiple of 8 (for example 178) every
equilibrium argument and node factor came back wrong. Skip the padding
bits before each table.

Adds a small libtcd-written fixture with 11 constituents, and its
generator.
libtcd stores a CRC-32 of the padded ASCII header after it and refuses
a file whose header does not match. The reader skipped those 4 bytes
and opened a corrupted file without complaint. It now computes the
CRC-32 and raises TCD::ChecksumError on a mismatch. Reader.new takes
verify_checksum: false to skip the check explicitly.
Writes a TCD file in the layout libtcd 2.2.7 writes: the ASCII header
padded to its size, its CRC-32 (big-endian), the string tables, the
speed, equilibrium and node-factor tables (each byte-aligned), and the
reference and subordinate station records. Bit widths, scales and
offsets come from the caller, from the data range as libtcd computes
them, or from libtcd's defaults. A value that does not fit its field,
or a string over libtcd's length limits or outside ISO-8859-1, raises
ArgumentError instead of being truncated.

Writer.from_reader copies a file read by the gem; it reproduces the
stock XTide file and libtcd's own test fixture byte for byte. A stored
level multiply of 0 (which the reader returns as 1.0) is read back from
the source so the copy keeps it.
The writer now raises ArgumentError instead of writing a file that
libtcd or XTide reads wrong or aborts on, or that the gem cannot read
back:

- NUL in any string; "__END__" as a table entry
- tables over libtcd's index limits (256 for level units, direction
  units, restrictions and legalese; 32,768 for time zones, countries
  and datums), and a direction units table without "degrees true"
  after its first entry
- control characters, brackets or edge spaces in header text
- fractional values in integer fields, non-finite floats
- bit widths over 31, zero scales, negative offsets and equilibrium
  arguments, out-of-range header integers; a speed range too wide for
  scale 10^7 now uses the largest power of ten that fits
- subordinates whose reference is not a reference record
- zone offsets that are not HHMM, invalid dates, epochs outside 0..360,
  level multipliers that round to 0
- one-entry unit tables get a 1-bit field instead of 0

Errors from bit packing, a missing reference_station, an unknown
record_type and zero years are now ArgumentErrors that name the field.
A libtcd-backed test runs when TCD_LIBTCD_DUMP points at a binary
built from test/fixtures/tcd_fulldump.c.
@jpr5
jpr5 merged commit 8a9ae00 into master Oct 12, 2026
4 checks passed
@jpr5
jpr5 deleted the reader-alignment-and-writer branch October 12, 2026 18:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant