diff --git a/CHANGELOG.md b/CHANGELOG.md index 7ca2b7f..0b6fa9e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [1.1.0] - 2026-10-12 + +### Added + +- `TCD::Writer`: writes TCD files that libtcd and XTide read (`Writer.from_reader(reader)` or plain data) +- Verify the header CRC-32 on open, as libtcd does; a mismatch raises `TCD::ChecksumError` (`Reader.new(path, verify_checksum: false)` skips it) + +### Fixed + +- Read the equilibrium and node-factor tables of a TCD whose constituent count is not a multiple of 8 (each table starts on a byte boundary, as libtcd writes it) + ## [1.0.2] - 2026-01-20 ### Fixed diff --git a/README.md b/README.md index f6a6d6b..1b0925d 100644 --- a/README.md +++ b/README.md @@ -127,6 +127,28 @@ TCD.open("harmonics.tcd") do |db| end ``` +### Writing TCD Files + +`TCD::Writer` writes a file that libtcd and XTide read. Copy a file you read: + +```ruby +TCD.open("harmonics.tcd") { |db| TCD::Writer.from_reader(db).write("copy.tcd") } +``` + +Or build one from plain data (units as the reader returns them; time offsets in minutes): + +```ruby +writer = TCD::Writer.new( + constituents: [{ name: "M2", speed: 28.9841042, equilibrium: [10.5, 200.25], node_factors: [0.98, 1.02] }], + start_year: 2025 +) +writer.add_station(name: "Example", latitude: 59.9, longitude: 10.75, tzfile: "Europe/Oslo", + level_units: "meters", amplitudes: [0.5], epochs: [120.0]) +writer.write("example.tcd") +``` + +Values that do not fit their field (for example a name over 89 bytes in ISO-8859-1) raise `ArgumentError`. `zone_offset` is a signed HHMM integer (`-500` for UTC-5), not minutes; epochs must be 0–360 degrees; dates are 0 or YYYYMMDD. + ### Command Line Tool The gem includes a `tcd-info` command for exploring TCD files: diff --git a/lib/tcd.rb b/lib/tcd.rb index ae4895d..85976b4 100644 --- a/lib/tcd.rb +++ b/lib/tcd.rb @@ -3,6 +3,7 @@ require_relative "tcd/version" require_relative "tcd/reader" require_relative "tcd/inference" +require_relative "tcd/writer" module TCD class << self diff --git a/lib/tcd/constituent.rb b/lib/tcd/constituent.rb index b4020c8..7863725 100644 --- a/lib/tcd/constituent.rb +++ b/lib/tcd/constituent.rb @@ -73,9 +73,16 @@ def load_data # Read speeds for all constituents speeds = read_speeds(num_constituents) + # libtcd writes each table into its own whole number of bytes, so skip the + # padding bits that end the previous table (none when the bit count is a + # multiple of 8, e.g. 176 constituents; some for 178). + @bit.align + # Read equilibrium arguments: constituents × years matrix equilibriums = read_equilibriums(num_constituents, num_years) + @bit.align + # Read node factors: constituents × years matrix node_factors = read_node_factors(num_constituents, num_years) diff --git a/lib/tcd/header.rb b/lib/tcd/header.rb index 4e25dde..522dca4 100644 --- a/lib/tcd/header.rb +++ b/lib/tcd/header.rb @@ -1,5 +1,7 @@ # frozen_string_literal: true +require "zlib" + module TCD # Parser for TCD ASCII header section. # The header contains [KEY] = VALUE pairs defining all encoding parameters. @@ -104,6 +106,36 @@ def country_bits; @params[:country_bits]; end def countries; @params[:countries]; end def country_size; @params[:country_size]; end + # CRC-32 of the ASCII header padded to header_size bytes, as libtcd's + # header_checksum() computes it. + def compute_checksum(io) + io.seek(0) + data = io.read(header_size) + if data.nil? || data.bytesize < header_size + raise FormatError, "file is shorter than its #{header_size}-byte header" + end + Zlib.crc32(data) + end + + # The CRC-32 stored in the 4 bytes after the header (big-endian). + def stored_checksum(io) + io.seek(header_size) + bytes = io.read(4) + raise FormatError, "file ends before the header checksum" if bytes.nil? || bytes.bytesize < 4 + bytes.unpack1("N") + end + + # Raises ChecksumError unless the stored checksum matches the header. + # libtcd refuses to open such a file. + def verify_checksum!(io) + stored = stored_checksum(io) + computed = compute_checksum(io) + return if stored == computed + + raise ChecksumError, format("header checksum mismatch: stored 0x%08x, computed 0x%08x " \ + "(the ASCII header was modified or the file is corrupt)", stored, computed) + end + private def parse(io) @@ -146,4 +178,5 @@ def validate! end class FormatError < StandardError; end + class ChecksumError < FormatError; end end diff --git a/lib/tcd/reader.rb b/lib/tcd/reader.rb index f3f5426..091e01f 100644 --- a/lib/tcd/reader.rb +++ b/lib/tcd/reader.rb @@ -12,8 +12,11 @@ module TCD class Reader attr_reader :path, :header, :lookup_tables, :constituent_data - def initialize(path) + # verify_checksum: false skips the header CRC-32 check (on by default, as + # in libtcd). Only for files known to carry no valid checksum. + def initialize(path, verify_checksum: true) @path = path + @verify_checksum = verify_checksum @file = File.open(path, "rb") @stations_loaded = false @stations = [] @@ -193,6 +196,7 @@ def stats def load_metadata # Parse ASCII header @header = Header.new(@file) + verify_checksum if @verify_checksum # Load lookup tables (handles interleaved string tables and binary data) # This also identifies the constituent data offset and station records offset @@ -207,6 +211,13 @@ def load_metadata @stations_offset = @lookup_tables.station_records_offset end + def verify_checksum + @header.verify_checksum!(@file) + rescue FormatError + close + raise + end + def load_stations return if @stations_loaded diff --git a/lib/tcd/version.rb b/lib/tcd/version.rb index c3e834c..dd9a3b2 100644 --- a/lib/tcd/version.rb +++ b/lib/tcd/version.rb @@ -1,5 +1,5 @@ # frozen_string_literal: true module TCD - VERSION = "1.0.2" + VERSION = "1.1.0" end diff --git a/lib/tcd/writer.rb b/lib/tcd/writer.rb new file mode 100644 index 0000000..56435fb --- /dev/null +++ b/lib/tcd/writer.rb @@ -0,0 +1,884 @@ +# frozen_string_literal: true + +require "zlib" + +module TCD + # Writes a TCD (Tidal Constituent Database) file in the layout libtcd 2.2.7 writes + # and reads (tide_db.c write_tide_db_header and pack_tide_record): + # + # 1. ASCII header ([KEY] = VALUE lines), padded with NULs to [HEADER SIZE] + # 2. CRC-32 of the padded header, 4 bytes big-endian + # 3. String tables: level units, direction units, restrictions, time zones, + # countries, datums, legalese (the last five padded to 2^bits entries and + # ended by "__END__"), constituent names + # 4. Speeds, equilibrium arguments, node factors (bit-packed, each table + # starting on a byte boundary) + # 5. Station records (bit-packed, each a whole number of bytes) + # + # Values use the same units as the reader: degrees, degrees per hour, time + # offsets in minutes, nil for "no direction" and "no slack time", station time + # zones with or without the leading ':' (a new table entry always gets it). + # Strings are stored as ISO-8859-1. A value that does not fit its field raises + # ArgumentError; nothing is truncated. + # + # Checks follow libtcd's check_tide_record, so libtcd and XTide read the file + # as written: + # - zone_offset is a signed HHMM integer (-500 is UTC-5, 530 is UTC+5:30), + # not minutes; its minutes part must be under 60. + # - Epochs must be 0..360 degrees; dates must be 0 or YYYYMMDD. + # - Integer fields take an Integer or a whole Float (10.0), never a fraction. + # - Strings may not contain NUL; table entries may not be "__END__"; header + # text (version, last_modified) may not hold control characters or brackets. + # - Level units, direction units, restrictions and legalese hold at most 256 + # entries; time zones, countries and datums at most 32,768. The direction + # units table must hold "degrees true" after its first entry. + # - Every bit width is at most 31. When the speeds span too much for libtcd's + # speed scale of 10^7, the writer uses the largest power of ten that fits. + # - A subordinate's reference_station must index a reference record. + # + # writer = TCD::Writer.new(constituents: [...], start_year: 2020, number_of_years: 3) + # writer.add_station(station) # a TCD::Station or a Hash with the same keys + # writer.write("out.tcd") + # + # TCD::Writer.from_reader(reader).write("copy.tcd") + class Writer + LIBTCD_VERSION = "PFM Software - libtcd v2.2.7 - 2015-08-09" + MAJOR_REV = 2 + MINOR_REV = 2 + + ONELINER_LENGTH = 90 # bytes, including the NUL + MONOLOGUE_LENGTH = 10_000 # bytes, including the NUL + MAX_CONSTITUENTS = 255 + AMPLITUDE_EPSILON = 0.00005 + NULL_SLACK_OFFSET = 0xA00 + NULL_DIRECTION = 361 + END_MARKER = "__END__" + INT32_MIN = -(2**31) + INT32_MAX = 2**31 - 1 + MAX_BITS = 31 # libtcd packs every field from a signed 32-bit int + + # Most table entries libtcd can index (tcd.h TIDE_RECORD): level units, + # direction units, restrictions and legalese are NV_U_BYTE; time zones, + # countries and datums are NV_INT16, and libtcd asserts tzfile >= 0. + TABLE_LIMITS = { + level_unit: 256, direction_unit: 256, restriction: 256, legalese: 256, + tzfile: 32_768, country: 32_768, datum: 32_768 + }.freeze + + # libtcd tide_db_default.h + DEFAULTS = { + header_size: 4096, + speed_scale: 10_000_000, equilibrium_scale: 100, node_scale: 10_000, + amplitude_bits: 19, amplitude_scale: 10_000, + epoch_bits: 16, epoch_scale: 100, + record_type_bits: 4, + latitude_bits: 25, latitude_scale: 100_000, + longitude_bits: 26, longitude_scale: 100_000, + record_size_bits: 16, + station_bits: 18, + datum_offset_bits: 28, datum_offset_scale: 10_000, + date_bits: 27, + months_on_station_bits: 10, + confidence_value_bits: 4, + time_bits: 13, + level_add_bits: 17, level_add_scale: 1000, + level_multiply_bits: 16, level_multiply_scale: 1000, + direction_bits: 9, + constituent_size: 10, + level_unit_size: 15, direction_unit_size: 15, + restriction_bits: 4, restriction_size: 30, + tzfile_bits: 10, tzfile_size: 30, + country_bits: 9, country_size: 50, + datum_bits: 7, datum_size: 70, + legalese_bits: 4, legalese_size: 70 + }.freeze + + # Header parameters a caller (or from_reader) may set. Counts and the + # bit widths that follow from counts are always derived from the data. + PARAMETER_KEYS = (DEFAULTS.keys + %i[ + speed_bits speed_offset equilibrium_bits equilibrium_offset node_bits node_offset + constituent_bits level_unit_bits direction_unit_bits + ]).freeze + + DEFAULT_LEVEL_UNITS = ["Unknown", "feet", "meters", "knots", "knots^2"].freeze + DEFAULT_DIRECTION_UNITS = ["Unknown", "degrees true", "degrees"].freeze + DEFAULT_RESTRICTIONS = ["Public Domain", "DoD/DoD Contractors Only"].freeze + DEFAULT_LEGALESES = ["NULL"].freeze + + attr_reader :stations, :constituents, :params + + # Builds a writer holding everything a Reader read: header parameters, + # tables, constituents and stations, in the same order. + def self.from_reader(reader) + lt = reader.lookup_tables + h = reader.header + writer = new( + constituents: reader.constituents.to_a, + start_year: h.start_year, + number_of_years: h.number_of_years, + version: h.version, + last_modified: h.last_modified, + params: h.params.select { |k, _| PARAMETER_KEYS.include?(k) }, + level_units: lt.level_units, + direction_units: lt.direction_units, + restrictions: lt.restrictions, + timezones: lt.timezones, + countries: lt.countries, + datums: lt.datums, + legaleses: lt.legalese + ) + offset = lt.station_records_offset + File.open(reader.path, "rb") do |io| + reader.stations.each do |station| + writer.add_station(writer.send(:restore_null_multipliers, station, io, offset)) + offset += station.record_size + end + end + writer + end + + # constituents: objects or Hashes with name, speed, equilibrium (one per + # year) and node_factors (one per year), e.g. TCD::Constituent. + # params: header parameters (bit widths, scales, offsets, sizes); missing + # ones come from the libtcd defaults or, for speeds, equilibrium + # arguments and node factors, from the data range as libtcd computes them. + # level_units ... legaleses: the string tables. Stations may also name + # strings that are not in them; those are appended. + def initialize(constituents:, start_year:, number_of_years: nil, version: nil, last_modified: nil, + params: {}, level_units: DEFAULT_LEVEL_UNITS, direction_units: DEFAULT_DIRECTION_UNITS, + restrictions: DEFAULT_RESTRICTIONS, timezones: [], countries: ["Unknown"], + datums: ["Unknown"], legaleses: DEFAULT_LEGALESES) + @constituents = constituents.map { |c| normalize_constituent(c) } + raise ArgumentError, "at least one constituent is required" if @constituents.empty? + if @constituents.size > MAX_CONSTITUENTS + raise ArgumentError, "#{@constituents.size} constituents; libtcd allows at most #{MAX_CONSTITUENTS}" + end + + @start_year = int_value(start_year, "start_year") + unless @start_year.between?(INT32_MIN, INT32_MAX) + raise ArgumentError, "start_year #{@start_year} is outside libtcd's 32-bit range" + end + @number_of_years = int_value(number_of_years || @constituents.first[:equilibrium].size, "number_of_years") + unless @number_of_years.between?(1, INT32_MAX) + raise ArgumentError, "number_of_years must be at least 1, got #{@number_of_years}" + end + @constituents.each do |c| + [:equilibrium, :node_factors].each do |key| + next if c[key].size == @number_of_years + raise ArgumentError, "constituent #{c[:name]}: #{c[key].size} #{key} values for #{@number_of_years} years" + end + end + @version = header_text(version || LIBTCD_VERSION, "version") + @last_modified = last_modified && header_text(last_modified, "last_modified") + @given_params = params.transform_keys(&:to_sym) + unknown = @given_params.keys - PARAMETER_KEYS + raise ArgumentError, "unknown header parameters: #{unknown.join(', ')}" unless unknown.empty? + @multiply_scale = int_value(@given_params.fetch(:level_multiply_scale, DEFAULTS[:level_multiply_scale]), + "header parameter level_multiply_scale") + @tables = { + level_unit: level_units.dup, + direction_unit: direction_units.dup, + restriction: restrictions.dup, + tzfile: timezones.dup, + country: countries.dup, + datum: datums.dup, + legalese: legaleses.dup + } + @stations = [] + end + + # Adds a station record (TCD::Station or a Hash with the Station keys). + # Subordinate stations name their reference by record index + # (reference_station), so add them in the order they will be numbered. + def add_station(station) + @stations << station + self + end + + # Writes the file and returns its size in bytes. + def write(path) + bytes = to_bytes + File.binwrite(path, bytes) + bytes.bytesize + end + + # The whole file as a binary String. + def to_bytes + records = @stations.map { |s| index_strings(s) } + @params = compute_params + body = String.new(encoding: Encoding::BINARY) + body << tables_bytes + body << constituent_bytes + records.each_with_index do |r, i| + if r[:record_type] == 2 + ref = r[:reference_station] + unless ref.between?(0, records.size - 1) + raise ArgumentError, "#{r[:name]}: reference_station #{ref} is not a record index (0..#{records.size - 1})" + end + # XTide asserts when a subordinate's reference is not a reference record + unless records[ref][:record_type] == 1 + raise ArgumentError, "#{r[:name]}: reference_station #{ref} is not a reference (type 1) record" + end + end + body << pack_station(r, i).first + end + + end_of_file = @params[:header_size] + 4 + body.bytesize + raise ArgumentError, "file would be #{end_of_file} bytes, over libtcd's 32-bit limit" if end_of_file > INT32_MAX + + header = header_bytes(end_of_file) + header + [Zlib.crc32(header)].pack("N") + body + end + + private + + # --------------------------------------------------------------- + # Header + + def header_bytes(end_of_file) + p = @params + n = @tables + lines = [ + ["VERSION", @version], + ["MAJOR REV", MAJOR_REV], + ["MINOR REV", MINOR_REV], + ["LAST MODIFIED", @last_modified || Time.now.strftime("%Y-%m-%d %H:%M %Z")], + ["HEADER SIZE", p[:header_size]], + ["NUMBER OF RECORDS", @stations.size], + ["START YEAR", @start_year], + ["NUMBER OF YEARS", @number_of_years], + ["SPEED BITS", p[:speed_bits]], + ["SPEED SCALE", p[:speed_scale]], + ["SPEED OFFSET", p[:speed_offset]], + ["EQUILIBRIUM BITS", p[:equilibrium_bits]], + ["EQUILIBRIUM SCALE", p[:equilibrium_scale]], + ["EQUILIBRIUM OFFSET", p[:equilibrium_offset]], + ["NODE BITS", p[:node_bits]], + ["NODE SCALE", p[:node_scale]], + ["NODE OFFSET", p[:node_offset]], + ["AMPLITUDE BITS", p[:amplitude_bits]], + ["AMPLITUDE SCALE", p[:amplitude_scale]], + ["EPOCH BITS", p[:epoch_bits]], + ["EPOCH SCALE", p[:epoch_scale]], + ["RECORD TYPE BITS", p[:record_type_bits]], + ["LATITUDE BITS", p[:latitude_bits]], + ["LATITUDE SCALE", p[:latitude_scale]], + ["LONGITUDE BITS", p[:longitude_bits]], + ["LONGITUDE SCALE", p[:longitude_scale]], + ["RECORD SIZE BITS", p[:record_size_bits]], + ["STATION BITS", p[:station_bits]], + ["DATUM OFFSET BITS", p[:datum_offset_bits]], + ["DATUM OFFSET SCALE", p[:datum_offset_scale]], + ["DATE BITS", p[:date_bits]], + ["MONTHS ON STATION BITS", p[:months_on_station_bits]], + ["CONFIDENCE VALUE BITS", p[:confidence_value_bits]], + ["TIME BITS", p[:time_bits]], + ["LEVEL ADD BITS", p[:level_add_bits]], + ["LEVEL ADD SCALE", p[:level_add_scale]], + ["LEVEL MULTIPLY BITS", p[:level_multiply_bits]], + ["LEVEL MULTIPLY SCALE", p[:level_multiply_scale]], + ["DIRECTION BITS", p[:direction_bits]], + ["LEVEL UNIT BITS", p[:level_unit_bits]], + ["LEVEL UNIT TYPES", n[:level_unit].size], + ["LEVEL UNIT SIZE", p[:level_unit_size]], + ["DIRECTION UNIT BITS", p[:direction_unit_bits]], + ["DIRECTION UNIT TYPES", n[:direction_unit].size], + ["DIRECTION UNIT SIZE", p[:direction_unit_size]], + ["RESTRICTION BITS", p[:restriction_bits]], + ["RESTRICTION TYPES", n[:restriction].size], + ["RESTRICTION SIZE", p[:restriction_size]], + ["DATUM BITS", p[:datum_bits]], + ["DATUM TYPES", n[:datum].size], + ["DATUM SIZE", p[:datum_size]], + ["LEGALESE BITS", p[:legalese_bits]], + ["LEGALESE TYPES", n[:legalese].size], + ["LEGALESE SIZE", p[:legalese_size]], + ["CONSTITUENT BITS", p[:constituent_bits]], + ["CONSTITUENTS", @constituents.size], + ["CONSTITUENT SIZE", p[:constituent_size]], + ["TZFILE BITS", p[:tzfile_bits]], + ["TZFILES", n[:tzfile].size], + ["TZFILE SIZE", p[:tzfile_size]], + ["COUNTRY BITS", p[:country_bits]], + ["COUNTRIES", n[:country].size], + ["COUNTRY SIZE", p[:country_size]], + ["END OF FILE", end_of_file] + ] + text = String.new(encoding: Encoding::BINARY) + lines.each do |key, value| + line = latin1("[#{key}] = #{value}\n", key) + # libtcd reads header lines into a ONELINER_LENGTH buffer + if line.bytesize > ONELINER_LENGTH - 2 + raise ArgumentError, "header line too long for libtcd: #{line.strip}" + end + text << line + end + text << "[END OF ASCII HEADER DATA]\n" + if text.bytesize > @params[:header_size] + raise ArgumentError, "ASCII header is #{text.bytesize} bytes, over header_size #{@params[:header_size]}" + end + text + ("\0" * (@params[:header_size] - text.bytesize)) + end + + # Header parameters: given ones, else derived from the data as libtcd's + # create_tide_db does, else the libtcd defaults. + def compute_params + given = @given_params.to_h { |k, v| [k, int_value(v, "header parameter #{k}")] } + given.each do |k, v| + ok = case k.to_s + when /_bits\z/ then v.between?(1, MAX_BITS) + when /_offset\z/ then v.between?(0, INT32_MAX) + else v.between?(1, INT32_MAX) # scales, sizes, header_size + end + next if ok + + raise ArgumentError, "header parameter #{k} = #{v} is out of range " \ + "(bit widths 1..#{MAX_BITS}, scales and sizes >= 1, offsets >= 0)" + end + p = DEFAULTS.merge(given) + + speeds = @constituents.map { |c| c[:speed] } + if speeds.any?(&:negative?) + raise ArgumentError, "negative constituent speed" + end + if @constituents.any? { |c| c[:equilibrium].any?(&:negative?) } + raise ArgumentError, "equilibrium arguments must be >= 0 (libtcd reads a negative offset as a " \ + "corrupt pre-1.11 file)" + end + if @constituents.any? { |c| c[:node_factors].any? { |f| f <= 0 } } + raise ArgumentError, "node factors must be positive" + end + # libtcd's create_tide_db scale is 10^7, asserting the width stays under + # 32 bits; when the speed range is too wide for that, use the largest + # power of ten that fits. + unless given.key?(:speed_scale) + p[:speed_scale] /= 10 while p[:speed_scale] > 1 && + range_bits(speeds, p[:speed_scale], given[:speed_offset]) > MAX_BITS + end + derive_range(p, :speed, speeds) + derive_range(p, :equilibrium, @constituents.flat_map { |c| c[:equilibrium] }) + derive_range(p, :node, @constituents.flat_map { |c| c[:node_factors] }) + + check_table_limits + # A reference record stores the count of its constituents in + # constituent_bits, so the count itself must fit. + p[:constituent_bits] = [p[:constituent_bits] || 0, calculate_bits(@constituents.size)].max + # libtcd gives a one-entry unit table a 0-bit field, which the gem's + # reader cannot read; at least 1 bit is still valid for libtcd. + p[:level_unit_bits] = [p[:level_unit_bits] || 0, calculate_bits(@tables[:level_unit].size - 1), 1].max + p[:direction_unit_bits] = [p[:direction_unit_bits] || 0, + calculate_bits(@tables[:direction_unit].size - 1), 1].max + # The padded tables need room for "__END__" after the last entry. + %i[restriction tzfile country datum legalese].each do |t| + key = :"#{t}_bits" + p[key] = [p[key], calculate_bits(@tables[t].size), 1].max + end + # reference_station is signed and holds record indexes + p[:station_bits] = [p[:station_bits], calculate_bits(@stations.size) + 1].max + p.each do |k, v| + next unless k.to_s.end_with?("_bits") && v > MAX_BITS + + raise ArgumentError, "#{k} would be #{v}; libtcd allows at most #{MAX_BITS}" + end + p + end + + # Bits needed for values at scale (offset from the minimum unless given). + def range_bits(values, scale, offset = nil) + offset ||= nint(values.min * scale) + calculate_bits([nint(values.max * scale) - offset, 0].max) + end + + # Offset and width for one bit-packed constituent table, from the data + # range unless given. + def derive_range(p, name, values) + scale = p[:"#{name}_scale"] + p[:"#{name}_offset"] ||= nint(values.min * scale) + if p[:"#{name}_offset"].negative? || p[:"#{name}_offset"] > INT32_MAX + raise ArgumentError, "#{name} offset #{p[:"#{name}_offset"]} is outside 0..#{INT32_MAX}" + end + bits = p[:"#{name}_bits"] ||= [range_bits(values, scale, p[:"#{name}_offset"]), 1].max + return if bits <= MAX_BITS + + raise ArgumentError, "#{name} values #{values.min}..#{values.max} need #{bits} bits at scale #{scale}; " \ + "libtcd allows at most #{MAX_BITS}" + end + + # libtcd's per-table limits, and the "degrees true" entry it looks up + # (unpack_tide_record asserts find_dir_units("degrees true") > 0). + def check_table_limits + TABLE_LIMITS.each do |t, max| + next if @tables[t].size <= max + + raise ArgumentError, "#{@tables[t].size} #{t} table entries; libtcd allows at most #{max}" + end + idx = @tables[:direction_unit].index("degrees true") + return if idx&.positive? + + raise ArgumentError, "the direction units table must contain \"degrees true\" after its first entry " \ + "(libtcd asserts on it); got #{@tables[:direction_unit].inspect}" + end + + # --------------------------------------------------------------- + # Tables + + def tables_bytes + p = @params + out = String.new(encoding: Encoding::BINARY) + out << exact_table(@tables[:level_unit], p[:level_unit_size], "level unit") + out << exact_table(@tables[:direction_unit], p[:direction_unit_size], "direction unit") + out << end_table(@tables[:restriction], p[:restriction_bits], p[:restriction_size], "restriction") + out << end_table(@tables[:tzfile], p[:tzfile_bits], p[:tzfile_size], "time zone") + out << end_table(@tables[:country], p[:country_bits], p[:country_size], "country") + out << end_table(@tables[:datum], p[:datum_bits], p[:datum_size], "datum") + out << end_table(@tables[:legalese], p[:legalese_bits], p[:legalese_size], "legalese") + out << exact_table(@constituents.map { |c| c[:name] }, p[:constituent_size], "constituent name") + out + end + + def exact_table(entries, size, what) + entries.map { |e| table_entry(e, size, what) }.join + end + + def end_table(entries, bits, size, what) + max = 1 << bits + if entries.size >= max + raise ArgumentError, "#{entries.size} #{what} entries do not fit #{bits} bits with the end marker" + end + out = entries.map { |e| table_entry(e, size, what) }.join + out << table_entry(END_MARKER, size, :end_marker) + out << ("\0" * ((max - entries.size - 1) * size)) + end + + def table_entry(value, size, what) + if value == END_MARKER && what != :end_marker + raise ArgumentError, "#{what} entry #{END_MARKER.inspect} would end the table early in libtcd and the reader" + end + bytes = latin1(value, what) + if bytes.bytesize + 1 > size + raise ArgumentError, "#{what} #{value.inspect} is #{bytes.bytesize} bytes; the table holds #{size - 1}" + end + bytes + ("\0" * (size - bytes.bytesize)) + end + + # --------------------------------------------------------------- + # Constituent data + + def constituent_bytes + out = String.new(encoding: Encoding::BINARY) + out << pack_table(@constituents.map { |c| c[:speed] }, :speed) + out << pack_table(@constituents.flat_map { |c| c[:equilibrium] }, :equilibrium) + out << pack_table(@constituents.flat_map { |c| c[:node_factors] }, :node) + out + end + + def pack_table(values, name) + p = @params + bits = BitPacker.new + values.each do |v| + bits.write_uint(nint(v * p[:"#{name}_scale"]) - p[:"#{name}_offset"], p[:"#{name}_bits"], name) + end + bits.bytes + rescue RangeError => e + raise ArgumentError, "#{name} table: #{e.message} (scale #{p[:"#{name}_scale"]}, " \ + "offset #{p[:"#{name}_offset"]})" + end + + # --------------------------------------------------------------- + # Station records + + # Station values with table strings replaced by indexes, time offsets as + # libtcd's signed HHMM, and nil replaced by libtcd's null values. + def index_strings(s) + label = field(s, :name).to_s + type = int_value(field(s, :record_type) || (field(s, :amplitudes) ? 1 : 2), "#{label}: record_type") + raise ArgumentError, "#{label}: record_type must be 1 (reference) or 2 (subordinate), got #{type}" unless [1, 2].include?(type) + + r = { + record_type: type, + latitude: float_value(field(s, :latitude), "#{label}: latitude"), + longitude: float_value(field(s, :longitude), "#{label}: longitude"), + tzfile: tz_index(field(s, :tzfile)), + name: clip(field(s, :name)), + reference_station: type == 1 ? -1 : int_value(field(s, :reference_station), "#{label}: reference_station"), + country: table_index(:country, field(s, :country) || "Unknown"), + source: clip(field(s, :source)), + restriction: table_index(:restriction, field(s, :restriction) || @tables[:restriction].first), + comments: clip(field(s, :comments)), + notes: clip(field(s, :notes)), + legalese: table_index(:legalese, field(s, :legalese) || @tables[:legalese].first), + station_id_context: clip(field(s, :station_id_context)), + station_id: clip(field(s, :station_id)), + date_imported: date_value(field(s, :date_imported), "#{label}: date_imported"), + xfields: field(s, :xfields).to_s, + direction_units: table_index(:direction_unit, field(s, :direction_units) || "degrees true"), + min_direction: direction_value(field(s, :min_direction), "#{label}: min_direction"), + max_direction: direction_value(field(s, :max_direction), "#{label}: max_direction"), + level_units: table_index(:level_unit, field(s, :level_units) || "Unknown") + } + raise ArgumentError, "station has no name" if r[:name].empty? + raise ArgumentError, "#{r[:name]}: latitude out of range" unless r[:latitude].between?(-90, 90) + raise ArgumentError, "#{r[:name]}: longitude out of range" unless r[:longitude].between?(-180, 180) + check_length(r, :name, ONELINER_LENGTH) + check_length(r, :source, ONELINER_LENGTH) + check_length(r, :station_id_context, ONELINER_LENGTH) + check_length(r, :station_id, ONELINER_LENGTH) + check_length(r, :comments, MONOLOGUE_LENGTH) + check_length(r, :notes, MONOLOGUE_LENGTH) + check_length(r, :xfields, MONOLOGUE_LENGTH) + + if type == 1 + n = @constituents.size + amplitudes = field(s, :amplitudes) || [] + epochs = field(s, :epochs) || [] + if amplitudes.size > n || epochs.size > n + raise ArgumentError, "#{r[:name]}: more amplitudes or epochs than the #{n} constituents" + end + r.merge!( + datum_offset: float_value(field(s, :datum_offset) || 0, "#{label}: datum_offset"), + datum: table_index(:datum, field(s, :datum) || "Unknown"), + zone_offset: hhmm_value(field(s, :zone_offset), "#{label}: zone_offset"), + expiration_date: date_value(field(s, :expiration_date), "#{label}: expiration_date"), + months_on_station: int_value(field(s, :months_on_station) || 0, "#{label}: months_on_station"), + last_date_on_station: date_value(field(s, :last_date_on_station), "#{label}: last_date_on_station"), + confidence: int_value(field(s, :confidence) || 0, "#{label}: confidence"), + amplitudes: Array.new(n) { |i| float_value(amplitudes[i] || 0, "#{label}: amplitude #{i}") }, + epochs: Array.new(n) { |i| float_value(epochs[i] || 0, "#{label}: epoch #{i}") } + ) + if r[:amplitudes].any?(&:negative?) + raise ArgumentError, "#{r[:name]}: negative amplitude" + end + # libtcd check_tide_record refuses epochs outside 0..360 + bad = r[:epochs].find { |e| !e.between?(0.0, 360.0) } + raise ArgumentError, "#{r[:name]}: epoch #{bad} is outside 0..360 degrees" if bad + else + r.merge!( + min_time_add: hhmm(field(s, :min_time_add), "#{label}: min_time_add"), + min_level_add: float_value(field(s, :min_level_add) || 0, "#{label}: min_level_add"), + min_level_multiply: multiply_value(field(s, :min_level_multiply), "#{label}: min_level_multiply"), + max_time_add: hhmm(field(s, :max_time_add), "#{label}: max_time_add"), + max_level_add: float_value(field(s, :max_level_add) || 0, "#{label}: max_level_add"), + max_level_multiply: multiply_value(field(s, :max_level_multiply), "#{label}: max_level_multiply"), + flood_begins: (v = field(s, :flood_begins)).nil? ? NULL_SLACK_OFFSET : hhmm(v, "#{label}: flood_begins"), + ebb_begins: (v = field(s, :ebb_begins)).nil? ? NULL_SLACK_OFFSET : hhmm(v, "#{label}: ebb_begins") + ) + end + r + end + + # Packs one record (libtcd pack_tide_record). Returns the bytes and the + # bit positions of the two level-multiply fields (subordinate records). + def pack_station(r, number) + p = @params + name = r[:name] + fields = BitPacker.new + fields.write_uint(0, p[:record_size_bits], "record size") # set by splice_bits + fields.write_uint(r[:record_type], p[:record_type_bits], "record type") + fields.write_int(nint(r[:latitude] * p[:latitude_scale]), p[:latitude_bits], "latitude") + fields.write_int(nint(r[:longitude] * p[:longitude_scale]), p[:longitude_bits], "longitude") + fields.write_uint(r[:tzfile], p[:tzfile_bits], "tzfile") + fields.write_string(latin1(name, "name")) + fields.write_int(r[:reference_station], p[:station_bits], "reference station") + fields.write_uint(r[:country], p[:country_bits], "country") + fields.write_string(latin1(r[:source], "source")) + fields.write_uint(r[:restriction], p[:restriction_bits], "restriction") + fields.write_string(latin1(r[:comments], "comments")) + fields.write_string(latin1(r[:notes], "notes")) + fields.write_uint(r[:legalese], p[:legalese_bits], "legalese") + fields.write_string(latin1(r[:station_id_context], "station_id_context")) + fields.write_string(latin1(r[:station_id], "station_id")) + fields.write_uint(r[:date_imported], p[:date_bits], "date imported") + fields.write_string(latin1(r[:xfields], "xfields")) + fields.write_uint(r[:direction_units], p[:direction_unit_bits], "direction units") + fields.write_uint(r[:min_direction], p[:direction_bits], "min direction") + fields.write_uint(r[:max_direction], p[:direction_bits], "max direction") + fields.write_uint(r[:level_units], p[:level_unit_bits], "level units") + + multiply_positions = nil + if r[:record_type] == 1 + fields.write_int(nint(r[:datum_offset] * p[:datum_offset_scale]), p[:datum_offset_bits], "datum offset") + fields.write_uint(r[:datum], p[:datum_bits], "datum") + fields.write_int(r[:zone_offset], p[:time_bits], "zone offset") + fields.write_uint(r[:expiration_date], p[:date_bits], "expiration date") + fields.write_uint(r[:months_on_station], p[:months_on_station_bits], "months on station") + fields.write_uint(r[:last_date_on_station], p[:date_bits], "last date on station") + fields.write_uint(r[:confidence], p[:confidence_value_bits], "confidence") + used = r[:amplitudes].each_index.select { |i| r[:amplitudes][i] >= AMPLITUDE_EPSILON } + fields.write_uint(used.size, p[:constituent_bits], "constituent count") + used.each do |i| + fields.write_uint(i, p[:constituent_bits], "constituent index") + fields.write_uint(nint(r[:amplitudes][i] * p[:amplitude_scale]), p[:amplitude_bits], "amplitude") + fields.write_uint(nint(r[:epochs][i] * p[:epoch_scale]), p[:epoch_bits], "epoch") + end + else + fields.write_int(r[:min_time_add], p[:time_bits], "min time add") + fields.write_int(nint(r[:min_level_add] * p[:level_add_scale]), p[:level_add_bits], "min level add") + min_pos = fields.bit_length + fields.write_uint(nint(r[:min_level_multiply] * p[:level_multiply_scale]), p[:level_multiply_bits], + "min level multiply") + fields.write_int(r[:max_time_add], p[:time_bits], "max time add") + fields.write_int(nint(r[:max_level_add] * p[:level_add_scale]), p[:level_add_bits], "max level add") + max_pos = fields.bit_length + fields.write_uint(nint(r[:max_level_multiply] * p[:level_multiply_scale]), p[:level_multiply_bits], + "max level multiply") + fields.write_int(r[:flood_begins], p[:time_bits], "flood begins") + fields.write_int(r[:ebb_begins], p[:time_bits], "ebb begins") + multiply_positions = [min_pos, max_pos] + end + + bytes = fields.bytes + if bytes.bytesize >= (1 << p[:record_size_bits]) + raise ArgumentError, "#{name}: record #{number} is #{bytes.bytesize} bytes, over record_size_bits" + end + [splice_bits(bytes, bytes.bytesize, p[:record_size_bits]), multiply_positions] + rescue RangeError => e + raise ArgumentError, "#{r[:name]}: #{e.message}" + end + + # Writes the record size into the first bits of the packed record. + def splice_bits(bytes, size_value, bits) + n = bytes.unpack1("B*") + n[0, bits] = size_value.to_s(2).rjust(bits, "0") + [n].pack("B*") + end + + # The reader returns 1.0 for a stored level multiply of 0 (XTide's + # meaning). To copy such a record exactly, read the stored value back + # from the source file. + def restore_null_multipliers(station, io, offset) + return station unless station.respond_to?(:subordinate?) && station.subordinate? + return station unless station.min_level_multiply == 1.0 || station.max_level_multiply == 1.0 + + @params ||= compute_params + r = index_strings(station) + _bytes, positions = pack_station(r, station.record_number) + io.seek(offset) + stored = io.read(station.record_size).unpack1("B*") + bits = @params[:level_multiply_bits] + copy = station.dup + copy.min_level_multiply = 0.0 if stored[positions[0], bits].to_i(2).zero? + copy.max_level_multiply = 0.0 if stored[positions[1], bits].to_i(2).zero? + copy + ensure + @params = nil + end + + # --------------------------------------------------------------- + # Helpers + + def normalize_constituent(c) + { + name: field(c, :name).to_s, + speed: float_value(field(c, :speed), "constituent #{field(c, :name)}: speed"), + equilibrium: Array(field(c, :equilibrium)).map { |v| float_value(v, "constituent #{field(c, :name)}: equilibrium") }, + node_factors: Array(field(c, :node_factors)).map { |v| float_value(v, "constituent #{field(c, :name)}: node factor") } + } + end + + def field(obj, key) + if obj.is_a?(Hash) + obj.key?(key) ? obj[key] : obj[key.to_s] + elsif obj.respond_to?(key) + obj.public_send(key) + end + end + + # Index of a string in a table, appending it when absent. + def table_index(table, value) + entries = @tables[table] + idx = entries.index(value) + return idx if idx + + entries << value + entries.size - 1 + end + + # Time zones are stored with a leading ':' (":America/New_York"); the reader + # strips it. Table entries are kept as given ("Unknown" has none). + def tz_index(tz) + raise ArgumentError, "station has no time zone" if tz.nil? || tz.to_s.empty? + + tz = tz.to_s + @tables[:tzfile].index(tz) || @tables[:tzfile].index(":#{tz}") || + table_index(:tzfile, tz.start_with?(":") ? tz : ":#{tz}") + end + + # libtcd clip_string: drop leading spaces, trailing spaces, CR and LF + def clip(value) + value.to_s.sub(/\A +/, "").sub(/[ \r\n]+\z/, "") + end + + def check_length(r, key, limit) + bytes = latin1(r[key], key.to_s) + return if bytes.bytesize < limit + + raise ArgumentError, "#{r[:name]}: #{key} is #{bytes.bytesize} bytes; libtcd allows #{limit - 1}" + end + + # libtcd strings are NUL-terminated, so a NUL would cut the string short + # and shift every field after it. + def latin1(value, what) + str = value.to_s + raise ArgumentError, "#{what} #{str.inspect} contains a NUL byte" if str.b.include?("\0") + + str.encode(Encoding::ISO_8859_1).force_encoding(Encoding::BINARY) + rescue EncodingError + raise ArgumentError, "#{what} #{value.to_s.inspect} has characters outside ISO-8859-1" + end + + # A header value libtcd reads back unchanged: one line, no control + # characters, no "[" or "]" (libtcd matches "[KEY]" anywhere in a line), + # no leading or trailing spaces (libtcd strips them). + def header_text(value, what) + str = value.to_s + if str.match?(/[\x00-\x1f\x7f\[\]]/) || str != str.strip + raise ArgumentError, "#{what} #{str.inspect} has a control character, a bracket, or " \ + "leading/trailing space; libtcd would read the header differently" + end + latin1(str, what) + str + end + + # An integer field: an Integer, or a Float with no fractional part. + def int_value(value, what) + case value + when Integer + value + when Float + unless value.finite? && value == value.truncate + raise ArgumentError, "#{what} must be a whole number, got #{value}" + end + value.to_i + when nil + raise ArgumentError, "#{what} is missing" + else + raise ArgumentError, "#{what} must be an integer, got #{value.inspect}" + end + end + + def float_value(value, what) + raise ArgumentError, "#{what} must be a number, got #{value.inspect}" unless value.is_a?(Numeric) + + f = value.to_f + raise ArgumentError, "#{what} must be finite, got #{f}" unless f.finite? + f + end + + # libtcd check_date: 0, or YYYYMMDD with month 1..12 and day 1..31 + def date_value(value, what) + date = int_value(value || 0, what) + return date if date.zero? + + md = date % 10_000 + unless date.positive? && (md / 100).between?(1, 12) && (md % 100).between?(1, 31) + raise ArgumentError, "#{what} #{date} is not 0 or a YYYYMMDD date" + end + date + end + + # 0..360 degrees, nil for none (stored as 361) + def direction_value(value, what) + return NULL_DIRECTION if value.nil? + + dir = int_value(value, what) + raise ArgumentError, "#{what} #{dir} is outside 0..#{NULL_DIRECTION}" unless dir.between?(0, NULL_DIRECTION) + dir + end + + # zone_offset is libtcd's signed HHMM (e.g. -500 for UTC-5, 530 for UTC+5:30), not minutes + def hhmm_value(value, what) + v = int_value(value || 0, what) + unless v.between?(-4096, 4095) && v.abs % 100 < 60 + raise ArgumentError, "#{what} #{v} is not a signed HHMM value (-4096..4095, minutes < 60)" + end + v + end + + # 0 means "none" (XTide treats it as 1.0); a positive value too small + # to store would silently become that 0. + def multiply_value(value, what) + m = float_value(value || 0, what) + raise ArgumentError, "#{what} #{m} is negative" if m.negative? + if m.positive? && nint(m * @multiply_scale).zero? + raise ArgumentError, "#{what} #{m} rounds to 0, which libtcd and XTide read as no multiplier" + end + m + end + + # Minutes (the reader's unit) to libtcd's signed HHMM + def hhmm(minutes, what = "time offset") + m = int_value(minutes || 0, what) + sign = m.negative? ? -1 : 1 + m = m.abs + sign * ((m / 60) * 100 + m % 60) + end + + # libtcd NINT: round half away from zero + def nint(value) + value.negative? ? (value - 0.5).to_i : (value + 0.5).to_i + end + + # libtcd calculate_bits: bits needed to store value (0 for 0) + def calculate_bits(value) + value.zero? ? 0 : value.bit_length + end + + # Bit-level output, most significant bit first, padded with zero bits to + # a whole byte: the mirror of BitBuffer. + class BitPacker + def initialize + @out = String.new(encoding: Encoding::BINARY) + @acc = 0 + @nbits = 0 + @total = 0 + end + + def bit_length + @total + end + + def write_uint(value, bits, what) + value = Integer(value) + if value.negative? || value >= (1 << bits) + raise RangeError, "#{what} value #{value} does not fit #{bits} unsigned bits" + end + put(value, bits) + end + + def write_int(value, bits, what) + value = Integer(value) + half = 1 << (bits - 1) + unless value >= -half && value < half + raise RangeError, "#{what} value #{value} does not fit #{bits} signed bits" + end + put(value & ((1 << bits) - 1), bits) + end + + def write_string(bytes) + bytes.each_byte { |b| put(b, 8) } + put(0, 8) + end + + def bytes + out = @out.dup + out << ((@acc << (8 - @nbits)) & 0xFF).chr if @nbits.positive? + out + end + + private + + def put(value, bits) + return if bits.zero? + + @acc = (@acc << bits) | value + @nbits += bits + @total += bits + while @nbits >= 8 + @nbits -= 8 + @out << ((@acc >> @nbits) & 0xFF).chr + end + @acc &= (1 << @nbits) - 1 + end + end + end +end diff --git a/test/checksum_test.rb b/test/checksum_test.rb new file mode 100644 index 0000000..62ea187 --- /dev/null +++ b/test/checksum_test.rb @@ -0,0 +1,78 @@ +# frozen_string_literal: true + +require_relative "test_helper" +require "tmpdir" + +# libtcd stores a CRC-32 of the padded ASCII header right after it, and refuses +# a file whose header does not match. The reader checks it the same way. +class ChecksumTest < Minitest::Test + FIXTURE = File.expand_path("fixtures/unaligned-11.tcd", __dir__) + + def with_copy(path) + Dir.mktmpdir do |dir| + copy = File.join(dir, File.basename(path)) + File.binwrite(copy, File.binread(path)) + yield copy + end + end + + def flip_byte(path, offset) + File.open(path, "r+b") do |f| + f.seek(offset) + byte = f.readbyte + f.seek(offset) + f.write((byte ^ 0x01).chr) + end + end + + def test_valid_files_open + [FIXTURE, TCD_TEST_FILE].each do |path| + TCD.open(path) { |db| assert db.constituent_count > 0 } + end + end + + def test_fixture_checksum_value + File.open(FIXTURE, "rb") do |io| + header = TCD::Header.new(io) + stored = File.binread(FIXTURE, 4, header.header_size).unpack1("N") + assert_equal stored, header.stored_checksum(io) + assert_equal stored, header.compute_checksum(io) + end + end + + def test_flipped_header_byte_raises + with_copy(FIXTURE) do |copy| + flip_byte(copy, 30) + err = assert_raises(TCD::ChecksumError) { TCD.open(copy) } + assert_match(/header checksum mismatch/, err.message) + end + end + + def test_flipped_header_padding_byte_raises + with_copy(FIXTURE) do |copy| + flip_byte(copy, 4000) + assert_raises(TCD::ChecksumError) { TCD.open(copy) } + end + end + + def test_flipped_stored_checksum_raises + with_copy(FIXTURE) do |copy| + size = File.open(copy, "rb") { |io| TCD::Header.new(io).header_size } + flip_byte(copy, size + 3) + assert_raises(TCD::ChecksumError) { TCD.open(copy) } + end + end + + def test_checksum_error_is_a_format_error + assert_operator TCD::ChecksumError, :<, TCD::FormatError + end + + def test_verification_can_be_skipped_explicitly + with_copy(FIXTURE) do |copy| + flip_byte(copy, 4000) + reader = TCD::Reader.new(copy, verify_checksum: false) + assert_equal 11, reader.constituent_count + reader.close + end + end +end diff --git a/test/fixtures/make_unaligned_tcd.c b/test/fixtures/make_unaligned_tcd.c new file mode 100644 index 0000000..230f8db --- /dev/null +++ b/test/fixtures/make_unaligned_tcd.c @@ -0,0 +1,80 @@ +/* Builds test/fixtures/unaligned-11.tcd with libtcd 2.2.7 (public domain): + * 11 constituents (not a multiple of 8) over 3 years, one reference and one + * subordinate station. All values are synthetic. + * + * cc -I/include make_unaligned_tcd.c /lib/libtcd.a -lm -o make_unaligned_tcd + * ./make_unaligned_tcd unaligned-11.tcd + */ +#include +#include +#include "tcd.h" + +#define NC 11 +#define NY 3 + +int main (int argc, char **argv) { + const char *names[NC] = {"M2", "S2", "N2", "K1", "O1", "P1", "K2", "Q1", "M4", "MS4", "SA"}; + double speeds[NC] = {28.9841042, 30.0, 28.4397295, 15.0410686, 13.9430356, 14.9589314, + 30.0821373, 13.3986609, 57.9682084, 58.9841042, 0.0410686}; + float eqs[NC][NY], nfs[NC][NY]; + const float *eqp[NC], *nfp[NC]; + DB_HEADER_PUBLIC db; + TIDE_RECORD r; + int c, y; + if (argc != 2) return 2; + for (c = 0; c < NC; ++c) { + for (y = 0; y < NY; ++y) { + eqs[c][y] = (float) ((c * 37 + y * 101) % 300) + 0.25f * y; + nfs[c][y] = 0.9f + 0.0125f * c + 0.01f * y; + } + eqp[c] = eqs[c]; + nfp[c] = nfs[c]; + } + if (!create_tide_db (argv[1], NC, names, speeds, 2020, NY, eqp, nfp)) return 1; + db = get_tide_db_header (); + + memset (&r, 0, sizeof r); + r.header.record_type = REFERENCE_STATION; + r.header.latitude = 41.5; + r.header.longitude = -70.67; + r.header.reference_station = -1; + r.header.tzfile = find_tzfile (":America/New_York"); + strcpy (r.header.name, "Synthetic Reference"); + r.country = find_country ("United States"); + strcpy (r.source, "tcd gem test fixture"); + r.restriction = 0; + r.legalese = 0; + r.direction_units = 1; + r.min_direction = r.max_direction = 361; + r.level_units = find_level_units ("meters"); + r.datum_offset = 1.2345f; + r.datum = find_datum ("Mean Lower Low Water"); + r.zone_offset = -500; + for (c = 0; c < NC; ++c) { + r.amplitude[c] = c == 4 ? 0.0f : 0.05f + 0.1f * c; + r.epoch[c] = c == 4 ? 0.0f : 10.0f * c + 0.5f; + } + if (!add_tide_record (&r, &db)) return 1; + + memset (&r, 0, sizeof r); + r.header.record_type = SUBORDINATE_STATION; + r.header.latitude = 41.6; + r.header.longitude = -70.6; + r.header.reference_station = 0; + r.header.tzfile = find_tzfile (":America/New_York"); + strcpy (r.header.name, "Synthetic Subordinate"); + r.country = find_country ("United States"); + r.direction_units = 1; + r.min_direction = r.max_direction = 361; + r.level_units = find_level_units ("meters"); + r.min_time_add = 112; + r.max_time_add = -45; + r.min_level_add = 0.1f; + r.max_level_add = -0.2f; + r.min_level_multiply = 0.9f; + r.max_level_multiply = 1.1f; + r.flood_begins = r.ebb_begins = NULLSLACKOFFSET; + if (!add_tide_record (&r, &db)) return 1; + close_tide_db (); + return 0; +} diff --git a/test/fixtures/tcd_fulldump.c b/test/fixtures/tcd_fulldump.c new file mode 100644 index 0000000..2626660 --- /dev/null +++ b/test/fixtures/tcd_fulldump.c @@ -0,0 +1,75 @@ +/* tcd_fulldump: print everything libtcd reads from a TCD file, in a fixed text form. + * + * tcd_fulldump FILE.tcd + * + * Sections: header (public fields), lookup tables, constituents (speed, every year's + * equilibrium and node factor), then every station record with every field. + * Floats are printed at the precision the file stores them, so two files that hold the + * same values print the same bytes. + * + * cc -I/include tcd_fulldump.c /lib/libtcd.a -lm -o tcd_fulldump + * TCD_LIBTCD_DUMP=./tcd_fulldump rake test + */ +#include +#include +#include "tcd.h" + +static void pstr (const char *k, const char *v) { printf ("%s=%s\n", k, v ? v : "(null)"); } + +int main (int argc, char **argv) { + if (argc != 2) { fprintf (stderr, "usage: %s FILE.tcd\n", argv[0]); return 2; } + if (!open_tide_db (argv[1])) { fprintf (stderr, "%s: libtcd could not open it\n", argv[1]); return 1; } + DB_HEADER_PUBLIC db = get_tide_db_header (); + NV_U_INT32 i, y; + printf ("version=%s\nmajor_rev=%u\nminor_rev=%u\nlast_modified=%s\n", db.version, db.major_rev, db.minor_rev, db.last_modified); + printf ("number_of_records=%u\nstart_year=%d\nnumber_of_years=%u\nconstituents=%u\n", db.number_of_records, db.start_year, db.number_of_years, db.constituents); + printf ("level_unit_types=%u\ndir_unit_types=%u\nrestriction_types=%u\ndatum_types=%u\ncountries=%u\ntzfiles=%u\nlegaleses=%u\n", + db.level_unit_types, db.dir_unit_types, db.restriction_types, db.datum_types, db.countries, db.tzfiles, db.legaleses); + for (i = 0; i < db.level_unit_types; ++i) printf ("level_unit[%u]=%s\n", i, get_level_units (i)); + for (i = 0; i < db.dir_unit_types; ++i) printf ("dir_unit[%u]=%s\n", i, get_dir_units (i)); + for (i = 0; i < db.restriction_types; ++i) printf ("restriction[%u]=%s\n", i, get_restriction (i)); + for (i = 0; i < db.datum_types; ++i) printf ("datum[%u]=%s\n", i, get_datum (i)); + for (i = 0; i < db.countries; ++i) printf ("country[%u]=%s\n", i, get_country (i)); + for (i = 0; i < db.tzfiles; ++i) printf ("tzfile[%u]=%s\n", i, get_tzfile (i)); + for (i = 0; i < db.legaleses; ++i) printf ("legalese[%u]=%s\n", i, get_legalese (i)); + for (i = 0; i < db.constituents; ++i) { + printf ("constituent[%u]=%s speed=%.7f\n eq=", i, get_constituent (i), get_speed (i)); + for (y = 0; y < db.number_of_years; ++y) printf (y ? ",%.2f" : "%.2f", get_equilibrium (i, y)); + printf ("\n nf="); + for (y = 0; y < db.number_of_years; ++y) printf (y ? ",%.4f" : "%.4f", get_node_factor (i, y)); + printf ("\n"); + } + for (i = 0; i < db.number_of_records; ++i) { + TIDE_RECORD r; + if (read_tide_record (i, &r) != (NV_INT32) i) { fprintf (stderr, "record %u unreadable\n", i); return 1; } + printf ("record[%u] size=%u type=%u lat=%.5f lon=%.5f ref=%d tz=%d:%s\n", i, r.header.record_size, r.header.record_type, + r.header.latitude, r.header.longitude, r.header.reference_station, r.header.tzfile, get_tzfile (r.header.tzfile)); + pstr (" name", r.header.name); + printf (" country=%d:%s\n", r.country, get_country (r.country)); + pstr (" source", r.source); + printf (" restriction=%u:%s\n", r.restriction, get_restriction (r.restriction)); + pstr (" comments", r.comments); + pstr (" notes", r.notes); + printf (" legalese=%u:%s\n", r.legalese, get_legalese (r.legalese)); + pstr (" station_id_context", r.station_id_context); + pstr (" station_id", r.station_id); + printf (" date_imported=%u\n", r.date_imported); + pstr (" xfields", r.xfields); + printf (" direction_units=%u:%s min_direction=%d max_direction=%d level_units=%u:%s\n", r.direction_units, + get_dir_units (r.direction_units), r.min_direction, r.max_direction, r.level_units, get_level_units (r.level_units)); + if (r.header.record_type == REFERENCE_STATION) { + printf (" datum_offset=%.4f datum=%d:%s zone_offset=%d expiration_date=%u months_on_station=%u last_date_on_station=%u confidence=%u\n", + r.datum_offset, r.datum, get_datum (r.datum), r.zone_offset, r.expiration_date, r.months_on_station, + r.last_date_on_station, r.confidence); + for (y = 0; y < db.constituents; ++y) + if (r.amplitude[y] != 0.0 || r.epoch[y] != 0.0) + printf (" c[%u]=%.4f,%.2f\n", y, r.amplitude[y], r.epoch[y]); + } else { + printf (" min_time_add=%d min_level_add=%.3f min_level_multiply=%.3f max_time_add=%d max_level_add=%.3f max_level_multiply=%.3f flood_begins=%d ebb_begins=%d\n", + r.min_time_add, r.min_level_add, r.min_level_multiply, r.max_time_add, r.max_level_add, r.max_level_multiply, + r.flood_begins, r.ebb_begins); + } + } + close_tide_db (); + return ferror (stdout) ? 1 : 0; +} diff --git a/test/fixtures/unaligned-11.tcd b/test/fixtures/unaligned-11.tcd new file mode 100644 index 0000000..f4a430a Binary files /dev/null and b/test/fixtures/unaligned-11.tcd differ diff --git a/test/unaligned_tcd_test.rb b/test/unaligned_tcd_test.rb new file mode 100644 index 0000000..f49f605 --- /dev/null +++ b/test/unaligned_tcd_test.rb @@ -0,0 +1,63 @@ +# frozen_string_literal: true + +require_relative "test_helper" + +# test/fixtures/unaligned-11.tcd was written by libtcd 2.2.7 (make_unaligned_tcd.c). +# It has 11 constituents, so its speed table (11 x 30 bits) and its equilibrium +# table (33 x 15 bits) end part-way through a byte. libtcd starts each table on a +# byte boundary; the reader must do the same. +# Expected values are libtcd's own reading of the file. +class UnalignedTCDTest < Minitest::Test + FIXTURE = File.expand_path("fixtures/unaligned-11.tcd", __dir__) + + def setup + @db = TCD.open(FIXTURE) + end + + def teardown + @db.close + end + + def test_fixture_tables_are_not_byte_aligned + assert_equal 11, @db.constituent_count + refute_equal 0, (@db.constituent_count * @db.header.speed_bits) % 8 + end + + def test_speeds + assert_in_delta 28.9841042, @db.constituent("M2").speed, 1e-7 + assert_in_delta 0.0410686, @db.constituent("SA").speed, 1e-7 + end + + def test_equilibrium_arguments_match_libtcd + assert_equal [0.00, 101.25, 202.50], @db.constituent("M2").equilibrium.map { |v| v.round(2) } + assert_equal [185.00, 286.25, 87.50], @db.constituent("P1").equilibrium.map { |v| v.round(2) } + assert_equal [70.00, 171.25, 272.50], @db.constituent("SA").equilibrium.map { |v| v.round(2) } + end + + def test_node_factors_match_libtcd + assert_equal [0.9000, 0.9100, 0.9200], @db.constituent("M2").node_factors.map { |v| v.round(4) } + assert_equal [0.9875, 0.9975, 1.0075], @db.constituent("Q1").node_factors.map { |v| v.round(4) } + assert_equal [1.0250, 1.0350, 1.0450], @db.constituent("SA").node_factors.map { |v| v.round(4) } + end + + def test_every_constituent_value + @db.constituents.each_with_index do |c, i| + assert_equal (0...3).map { |y| ((i * 37 + y * 101) % 300) + 0.25 * y }, c.equilibrium.map { |v| v.round(2) }, c.name + assert_equal (0...3).map { |y| (0.9 + 0.0125 * i + 0.01 * y).round(4) }, c.node_factors.map { |v| v.round(4) }, c.name + end + end + + def test_stations + ref, sub = @db.stations + assert_equal "Synthetic Reference", ref.name + assert_equal "America/New_York", ref.tzfile + assert_in_delta 1.2345, ref.datum_offset, 1e-9 + assert_in_delta 1.05, ref.amplitudes[10], 1e-9 + assert_in_delta 100.5, ref.epochs[10], 1e-9 + assert_equal 0.0, ref.amplitudes[4] + assert_equal "Synthetic Subordinate", sub.name + assert_equal 0, sub.reference_station + assert_equal 72, sub.min_time_add + assert_in_delta 1.1, sub.max_level_multiply, 1e-9 + end +end diff --git a/test/writer_test.rb b/test/writer_test.rb new file mode 100644 index 0000000..a80a4d7 --- /dev/null +++ b/test/writer_test.rb @@ -0,0 +1,140 @@ +# frozen_string_literal: true + +require_relative "test_helper" +require "tmpdir" + +class WriterTest < Minitest::Test + UNALIGNED = File.expand_path("fixtures/unaligned-11.tcd", __dir__) + + def round_trip(path) + TCD.open(path) { |db| TCD::Writer.from_reader(db).to_bytes } + end + + def read_bytes(bytes) + Dir.mktmpdir do |dir| + path = File.join(dir, "written.tcd") + File.binwrite(path, bytes) + TCD.open(path) { |db| yield db } + end + end + + def assert_same_database(expected_path, actual_bytes) + TCD.open(expected_path) do |want| + read_bytes(actual_bytes) do |got| + assert_equal want.header.params, got.header.params + %i[level_units direction_units restrictions timezones countries datums legalese constituents].each do |t| + assert_equal want.lookup_tables.public_send(t), got.lookup_tables.public_send(t), t + end + assert_equal want.constituents.map(&:to_h), got.constituents.map(&:to_h) + assert_equal want.station_count, got.station_count + want.stations.zip(got.stations) { |a, b| assert_equal a.to_h, b.to_h, a.name } + end + end + end + + # libtcd wrote this file; the writer reproduces it byte for byte. Its + # constituent tables end part-way through a byte. + def test_round_trip_of_libtcd_file_with_unaligned_tables_is_byte_identical + bytes = round_trip(UNALIGNED) + assert_equal File.binread(UNALIGNED).bytes, bytes.bytes + assert_same_database(UNALIGNED, bytes) + end + + def test_round_trip_of_xtide_file + bytes = round_trip(TCD_TEST_FILE) + assert_same_database(TCD_TEST_FILE, bytes) + assert_equal File.size(TCD_TEST_FILE), bytes.bytesize + assert File.binread(TCD_TEST_FILE) == bytes, "written file differs from the original" + end + + def test_header_checksum_is_crc32_of_padded_header_big_endian + bytes = round_trip(UNALIGNED) + size = 4096 + assert_equal Zlib.crc32(bytes[0, size]), bytes[size, 4].unpack1("N") + assert_equal bytes.bytesize, bytes[/\[END OF FILE\] = (\d+)/, 1].to_i + end + + def test_plain_data + writer = TCD::Writer.new( + constituents: [ + { name: "M2", speed: 28.9841042, equilibrium: [10.5, 200.25], node_factors: [0.98, 1.02] }, + { name: "S2", speed: 30.0, equilibrium: [0.0, 359.99], node_factors: [1.0, 1.0] }, + { name: "K1", speed: 15.0410686, equilibrium: [123.45, 67.89], node_factors: [1.1, 0.9] } + ], + start_year: 2025, + countries: ["Unknown", "Norway"], + datums: ["Unknown", "Lowest Astronomical Tide"] + ) + writer.add_station( + name: "Reference Ø", latitude: 59.9, longitude: 10.75, tzfile: "Europe/Oslo", + country: "Norway", level_units: "meters", datum: "Lowest Astronomical Tide", + datum_offset: 0.95, zone_offset: 100, station_id_context: "OTC", station_id: "OTC-1", + amplitudes: [0.5, 0.2, 0.0], epochs: [120.0, 150.5, 0.0] + ) + writer.add_station( + name: "Current sub", latitude: 59.8, longitude: 10.7, tzfile: ":Europe/Oslo", + reference_station: 0, level_units: "knots", min_direction: 10, max_direction: 190, + min_time_add: -75, max_time_add: 30, min_level_multiply: 0.8, max_level_multiply: 1.25, + flood_begins: 15, ebb_begins: nil + ) + read_bytes(writer.to_bytes) do |db| + assert_equal 3, db.constituent_count + assert_equal 2025..2026, db.year_range + m2 = db.constituent("M2") + assert_in_delta 28.9841042, m2.speed, 1e-9 + assert_equal [10.5, 200.25], m2.equilibrium.map { |v| v.round(2) } + assert_equal [0.98, 1.02], m2.node_factors.map { |v| v.round(4) } + assert_equal [123.45, 67.89], db.constituent("K1").equilibrium.map { |v| v.round(2) } + assert_equal [":Europe/Oslo"], db.lookup_tables.timezones + + ref, sub = db.stations + assert ref.reference? + assert_equal "Reference Ø", ref.name + assert_equal "Europe/Oslo", ref.tzfile + assert_equal "Norway", ref.country + assert_equal "Lowest Astronomical Tide", ref.datum + assert_in_delta 0.95, ref.datum_offset, 1e-9 + assert_equal 100, ref.zone_offset + assert_equal "OTC-1", ref.station_id + assert_equal [0.5, 0.2, 0.0], ref.amplitudes + assert_equal [120.0, 150.5, 0.0], ref.epochs + + assert sub.subordinate? + assert sub.current? + assert_equal 0, sub.reference_station + assert_equal "knots", sub.level_units + assert_equal [10, 190], [sub.min_direction, sub.max_direction] + assert_equal [-75, 30], [sub.min_time_add, sub.max_time_add] + assert_in_delta 1.25, sub.max_level_multiply, 1e-9 + assert_equal 15, sub.flood_begins + assert_nil sub.ebb_begins + end + end + + def small_writer + TCD::Writer.new(constituents: [{ name: "M2", speed: 28.9841042, equilibrium: [1.0], node_factors: [1.0] }], + start_year: 2025) + end + + def test_rejects_overlong_name + w = small_writer.add_station(name: "x" * 90, latitude: 0, longitude: 0, tzfile: "UTC", amplitudes: [1.0]) + err = assert_raises(ArgumentError) { w.to_bytes } + assert_match(/name is 90 bytes; libtcd allows 89/, err.message) + end + + def test_rejects_characters_outside_latin1 + w = small_writer.add_station(name: "Tōkyō", latitude: 0, longitude: 0, tzfile: "UTC", amplitudes: [1.0]) + assert_raises(ArgumentError) { w.to_bytes } + end + + def test_rejects_value_that_does_not_fit_its_field + w = small_writer.add_station(name: "A", latitude: 0, longitude: 0, tzfile: "UTC", amplitudes: [60.0]) + assert_match(/amplitude value .* does not fit 19 unsigned bits/, assert_raises(ArgumentError) { w.to_bytes }.message) + end + + def test_rejects_reference_index_outside_the_file + w = small_writer.add_station(name: "S", latitude: 0, longitude: 0, tzfile: "UTC", record_type: 2, + reference_station: 3) + assert_raises(ArgumentError) { w.to_bytes } + end +end diff --git a/test/writer_validation_test.rb b/test/writer_validation_test.rb new file mode 100644 index 0000000..82b0e14 --- /dev/null +++ b/test/writer_validation_test.rb @@ -0,0 +1,245 @@ +# frozen_string_literal: true + +require_relative "test_helper" +require "tmpdir" +require "open3" + +# The writer must never produce a file that libtcd or XTide reads wrong or +# aborts on, or that the gem cannot read back: each case below either raises +# ArgumentError or writes a correct file. +class WriterValidationTest < Minitest::Test + M2 = { name: "M2", speed: 28.9841042, equilibrium: [10.0, 20.0], node_factors: [1.0, 1.01] }.freeze + K1 = { name: "K1", speed: 15.0410686, equilibrium: [30.0, 40.0], node_factors: [0.99, 1.0] }.freeze + + def writer(constituents: [M2, K1], **kw) + TCD::Writer.new(constituents: constituents, start_year: 2025, **kw) + end + + def ref(over = {}) + { name: "Ref", latitude: 41.5, longitude: -70.6, tzfile: "America/New_York", level_units: "meters", + zone_offset: -500, amplitudes: [0.5, 0.2], epochs: [120.0, 150.5] }.merge(over) + end + + def sub(over = {}) + { name: "Sub", record_type: 2, latitude: 41.6, longitude: -70.5, tzfile: "America/New_York", + reference_station: 0, level_units: "meters", min_time_add: 30, max_time_add: -15, + min_level_multiply: 0.9, max_level_multiply: 1.1 }.merge(over) + end + + def refuses(pattern, &block) + err = assert_raises(ArgumentError, &block) + assert_match pattern, err.message + end + + def write_and_read(w) + Dir.mktmpdir do |dir| + path = File.join(dir, "t.tcd") + w.write(path) + TCD.open(path) { |db| yield db, path } + end + end + + # 1. NUL + def test_nul_in_station_string + refuses(/name .* contains a NUL byte/) { writer.add_station(ref(name: "A\0B")).to_bytes } + refuses(/comments .* contains a NUL byte/) { writer.add_station(ref(comments: "a\0b")).to_bytes } + refuses(/xfields .* contains a NUL byte/) { writer.add_station(ref(xfields: "k:v\0x")).to_bytes } + end + + def test_nul_in_table_entry + refuses(/country .* contains a NUL byte/) { writer(countries: ["Unknown", "A\0B"]).add_station(ref).to_bytes } + refuses(/contains a NUL byte/) { writer.add_station(ref(datum: "D\0")).to_bytes } + end + + # 2. "__END__" + def test_end_marker_entries + %i[country datum restriction legalese level_units direction_units].each do |key| + refuses(/"__END__" would end the table/) { writer.add_station(ref(key => "__END__")).to_bytes } + end + end + + # 3. table limits + def test_byte_indexed_tables_limited_to_256 + refuses(/257 level_unit table entries; libtcd allows at most 256/) do + writer(level_units: Array.new(257) { |i| "U#{i}" }).add_station(ref(level_units: "U1")).to_bytes + end + refuses(/257 restriction table entries/) do + writer(restrictions: Array.new(257) { |i| "R#{i}" }).add_station(ref(restriction: "R1")).to_bytes + end + refuses(/257 legalese table entries/) do + writer(legaleses: Array.new(257) { |i| "L#{i}" }).add_station(ref(legalese: "L1")).to_bytes + end + refuses(/257 direction_unit table entries/) do + writer(direction_units: ["Unknown", "degrees true"] + Array.new(255) { |i| "D#{i}" }).add_station(ref).to_bytes + end + # 256 is the most: the last index (255) still fits libtcd's byte + w = writer(level_units: Array.new(256) { |i| "U#{i}" }).add_station(ref(level_units: "U255")) + write_and_read(w) { |db| assert_equal "U255", db.stations[0].level_units } + end + + def test_int16_indexed_tables_limited_to_32768 + refuses(/32769 tzfile table entries; libtcd allows at most 32768/) do + writer(timezones: Array.new(32_769) { |i| ":Z/#{i}" }).add_station(ref(tzfile: "Z/1")).to_bytes + end + refuses(/32769 country table entries/) do + writer(countries: Array.new(32_769) { |i| "C#{i}" }).add_station(ref(country: "C1")).to_bytes + end + end + + # 4. header injection + def test_header_values + ["x\n[NUMBER OF RECORDS] = 0", "abc\r", "a\tb", "ab\0cd", "1 [MAJOR REV]", "x]", " lead", "trail "].each do |v| + refuses(/version .* libtcd would read the header differently/) { writer(version: v) } + refuses(/last_modified .* libtcd would read the header differently/) { writer(last_modified: v) } + end + write_and_read(writer(version: "OTC tcd-writer 1.1", last_modified: "2026-10-11 00:00 UTC").add_station(ref)) do |db| + assert_equal "OTC tcd-writer 1.1", db.version + assert_equal "2026-10-11 00:00 UTC", db.last_modified + end + end + + # 5. no float truncation + def test_integer_fields_refuse_fractions + refuses(/start_year must be a whole number, got 2020.7/) { TCD::Writer.new(constituents: [M2], start_year: 2020.7) } + refuses(/number_of_years must be a whole number/) { TCD::Writer.new(constituents: [M2], start_year: 2020, number_of_years: 2.5) } + refuses(/min_time_add must be a whole number, got 10.9/) { writer.add_station(ref).add_station(sub(min_time_add: 10.9)).to_bytes } + refuses(/flood_begins must be a whole number/) { writer.add_station(ref).add_station(sub(flood_begins: 30.7)).to_bytes } + refuses(/min_direction must be a whole number/) { writer.add_station(ref(min_direction: 10.9)).to_bytes } + refuses(/reference_station must be a whole number/) { writer.add_station(ref).add_station(sub(reference_station: 0.5)).to_bytes } + refuses(/zone_offset must be a whole number/) { writer.add_station(ref(zone_offset: -500.5)).to_bytes } + refuses(/confidence must be an integer/) { writer.add_station(ref(confidence: "3")).to_bytes } + refuses(/header parameter amplitude_bits must be a whole number/) { writer(params: { amplitude_bits: 19.5 }) .add_station(ref).to_bytes } + refuses(/epoch 0 must be finite/) { writer.add_station(ref(epochs: [Float::NAN, 0])).to_bytes } + end + + def test_integral_floats_are_accepted + w = writer.add_station(ref(zone_offset: -500.0, min_direction: 10.0, max_direction: 190.0)) + .add_station(sub(reference_station: 0.0, min_time_add: 30.0)) + write_and_read(w) do |db| + assert_equal(-500, db.stations[0].zone_offset) + assert_equal 10, db.stations[0].min_direction + assert_equal 30, db.stations[1].min_time_add + end + end + + # 6. 32-bit limits + def test_wide_speed_range_chooses_a_scale_that_fits + z0 = { name: "Z0", speed: 0.0, equilibrium: [0.0, 0.0], node_factors: [1.0, 1.0] } + m8 = { name: "M8", speed: 231.8728336, equilibrium: [10.0, 20.0], node_factors: [1.0, 1.0] } + w = writer(constituents: [z0, m8]).add_station(ref(amplitudes: [0.1, 0.2], epochs: [0, 10])) + write_and_read(w) do |db| + assert_operator db.header.speed_bits, :<=, 31 + assert_equal 1_000_000, db.header.speed_scale + assert_in_delta 231.872834, db.constituent("M8").speed, 1e-9 + assert_equal 0.0, db.constituent("Z0").speed + end + end + + def test_values_that_cannot_be_stored + refuses(/node values .* need 34 bits .* at most 31/) do + writer(constituents: [M2.merge(node_factors: [1e6, 1.0])]).to_bytes + end + refuses(/equilibrium arguments must be >= 0/) { writer(constituents: [M2.merge(equilibrium: [-1.0, 2.0])]).to_bytes } + refuses(/speed_bits = 32 is out of range/) { writer(params: { speed_bits: 32 }).to_bytes } + refuses(/amplitude_bits = 0 is out of range/) { writer(params: { amplitude_bits: 0 }).to_bytes } + refuses(/amplitude_scale = 0 is out of range/) { writer(params: { amplitude_scale: 0 }).to_bytes } + refuses(/speed_offset = -1 is out of range/) { writer(params: { speed_offset: -1 }).to_bytes } + refuses(/unknown header parameters: bogus/) { writer(params: { bogus: 1 }) } + refuses(/start_year 2147483648 is outside libtcd's 32-bit range/) { TCD::Writer.new(constituents: [M2], start_year: 2**31) } + end + + # L1. one-entry unit tables + def test_one_entry_level_unit_table_is_readable + w = writer(level_units: ["meters"]).add_station(ref) + write_and_read(w) do |db| + assert_equal 1, db.header.level_unit_bits + assert_equal "meters", db.stations[0].level_units + end + end + + # L2. "degrees true" + def test_direction_units_need_degrees_true_after_first_entry + refuses(/must contain "degrees true" after its first entry/) { writer(direction_units: ["degrees true"]).add_station(ref).to_bytes } + refuses(/must contain "degrees true"/) do + writer(direction_units: ["Unknown", "degrees"]).add_station(ref(direction_units: "degrees")).to_bytes + end + end + + # L3. subordinate references + def test_subordinate_reference_must_be_a_reference_record + refuses(/reference_station 1 is not a reference \(type 1\) record/) do + writer.add_station(ref).add_station(sub(reference_station: 1)).to_bytes + end + refuses(/Sub2: reference_station 1 is not a reference/) do + writer.add_station(ref).add_station(sub).add_station(sub(name: "Sub2", reference_station: 1)).to_bytes + end + refuses(/reference_station 5 is not a record index/) { writer.add_station(ref).add_station(sub(reference_station: 5)).to_bytes } + end + + # L4. ArgumentError with a clear message + def test_clear_errors + refuses(/speed table: speed value .* does not fit 3 unsigned bits/) do + writer(params: { speed_bits: 3 }).to_bytes + end + refuses(/Sub: reference_station is missing/) { writer.add_station(ref).add_station(sub(reference_station: nil)).to_bytes } + refuses(/record_type must be 1 \(reference\) or 2 \(subordinate\), got 3/) { writer.add_station(ref(record_type: 3)).to_bytes } + refuses(/number_of_years must be at least 1, got 0/) do + TCD::Writer.new(constituents: [M2.merge(equilibrium: [], node_factors: [])], start_year: 2025, number_of_years: 0) + end + end + + # Docs items: zone_offset HHMM, dates, epochs + def test_zone_offset_is_hhmm + refuses(/zone_offset -560 is not a signed HHMM value/) { writer.add_station(ref(zone_offset: -560)).to_bytes } + refuses(/zone_offset 4096 is not a signed HHMM/) { writer.add_station(ref(zone_offset: 4096)).to_bytes } + write_and_read(writer.add_station(ref(zone_offset: 530))) { |db| assert_equal 530, db.stations[0].zone_offset } + end + + def test_dates + refuses(/date_imported 20261301 is not 0 or a YYYYMMDD date/) { writer.add_station(ref(date_imported: 20_261_301)).to_bytes } + refuses(/expiration_date 20260100 is not 0 or a YYYYMMDD date/) { writer.add_station(ref(expiration_date: 20_260_100)).to_bytes } + write_and_read(writer.add_station(ref(date_imported: 20_261_011))) { |db| assert_equal 20_261_011, db.stations[0].date_imported } + end + + def test_epochs_outside_0_to_360 + refuses(/epoch 400.0 is outside 0..360/) { writer.add_station(ref(epochs: [400.0, 0])).to_bytes } + refuses(/epoch -0.5 is outside 0..360/) { writer.add_station(ref(epochs: [-0.5, 0])).to_bytes } + write_and_read(writer.add_station(ref(epochs: [360.0, 0]))) { |db| assert_equal 360.0, db.stations[0].epochs[0] } + end + + def test_multiplier_that_would_round_to_none + refuses(/min_level_multiply 0.0004 rounds to 0/) { writer.add_station(ref).add_station(sub(min_level_multiply: 0.0004)).to_bytes } + end + + # libtcd-backed: set TCD_LIBTCD_DUMP to a binary built from + # test/fixtures/tcd_fulldump.c against libtcd; skipped otherwise. + def test_libtcd_reads_written_files + dump = ENV["TCD_LIBTCD_DUMP"] + skip "set TCD_LIBTCD_DUMP to run libtcd checks" unless dump && File.executable?(dump) + + z0 = { name: "Z0", speed: 0.0, equilibrium: [0.0, 0.0], node_factors: [1.0, 1.0] } + m8 = { name: "M8", speed: 231.8728336, equilibrium: [10.0, 20.0], node_factors: [1.0, 1.0] } + cases = { + "wide speeds" => [writer(constituents: [z0, m8]).add_station(ref(amplitudes: [0.1, 0.2], epochs: [0, 10])), + ["constituent[1]=M8 speed=231.8728340"]], + "one level unit" => [writer(level_units: ["meters"]).add_station(ref), + ["level_units=0:meters"]], + "256 level units" => [writer(level_units: Array.new(256) { |i| "U#{i}" }).add_station(ref(level_units: "U255")), + ["level_units=255:U255"]], + "subordinate" => [writer.add_station(ref).add_station(sub(min_time_add: 90, flood_begins: -45)), + ["min_time_add=130", "flood_begins=-45", "min_level_multiply=0.900"]], + "hhmm and dates" => [writer.add_station(ref(zone_offset: 530, date_imported: 20_261_011, epochs: [360.0, 0])), + ["zone_offset=530", "date_imported=20261011", "c[0]=0.5000,360.00"]] + } + Dir.mktmpdir do |dir| + cases.each do |label, (w, expected)| + path = File.join(dir, "#{label.tr(' ', '_')}.tcd") + w.write(path) + out, err, status = Open3.capture3(dump, path) + assert status.success?, "#{label}: libtcd failed: #{err}" + assert_empty err, label + expected.each { |e| assert_includes out, e, label } + end + end + end +end