iers 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4977c2dce8a969f0590cabc8c9c2a992e946b14d5def3fd9e7b6635c76a5cd83
-  data.tar.gz: fd23f09386c87acbc6f4b25207d023198a41c9f55502c341859188496fc6f66b
+  metadata.gz: 4132b4709810d88306f0ea6bde33b1664d1fdbfeef985e0191cba65c98c01f8a
+  data.tar.gz: 5e3bef64e668f1320bc9c3876e571bf4bb452ea2df52cd09539303bafbf03ea0
 SHA512:
-  metadata.gz: c219975975bd14d24c47c45062868592999f4da0f19d254d73a01676b71b5d881faebd8f73afbb3d3155ef5da341459414846165e4f2540570f78e9487bba435
-  data.tar.gz: 0b13b6a3dc0daa6d2012e112662c3605b59de6c4d6b1437f4162912095bb424772cd13fb1c0cddb7cb3e234e85bfd0658ecf63ecf977a8281f063e13da05ceaa
+  metadata.gz: c2bd5f8b1d3a088bc9aa8d822013a9c04570cea94c6036f080eb4d34d8ad53ac0346e6547092f5ce95fe61f95df6de32006e59371894e3b77768565be15354a1
+  data.tar.gz: 8b32049edecc0955026664f02cbf89a1af9d518050374538cbf1b1c3b08d572509b971d522a1d368490d6d07bcbd90bb807bd9fd5c4223d074431a60583244f5

data/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.2.0 - 2026-07-25
+
+### Added
+
+- `LeapSecond.expires_on`, `LeapSecond.expired?` and
+  `LeapSecond.updated_through` expose the expiry date and IERS bulletin that
+  `Leap_Second.dat` states in its header. Both were previously discarded with
+  the rest of the comment lines. Unlike `Data.status.cache_age`, which measures
+  when a file was downloaded, these describe how long the data itself stays
+  authoritative.
+- `LeapSecond.at` now answers 1961-01-01 through 1972-01-01, the era when UTC
+  was steered by rate adjustments rather than whole leap seconds. It returns
+  those values as exact `Rational`s. The coefficients come from the USNO
+  `tai-utc.dat` file and are bundled in source, since they are fixed. The
+  change is additive: the pre-1972 range previously raised, so no successful
+  call returns anything different. `TAI.utc_to_tai` and `TAI.tai_to_utc` gain
+  the same range for free.
+
+### Changed
+
+- `Parsers::LeapSecond.parse` returns a `Table` of `entries` and `metadata`
+  instead of an array of entries. `Parsers` is internal; the public API is
+  unaffected.
+- `Parsers::LeapSecond.parse` no longer raises `Encoding::CompatibilityError`
+  on a file containing invalid UTF-8. Header metadata is read on a best-effort
+  basis and an unreadable data row raises `ParseError` as before.
+
+## 0.1.1 - 2026-06-27
+
+### Changed
+
+- Refreshed the bundled `finals2000A.all` snapshot from IERS. Final values now
+  extend through 2026-06-25 (previously 2026-02-19) and predictions through
+  2027-08-22.
+
 ## 0.1.0 - 2026-02-27
 
 Initial public release.

data/README.md

@@ -242,14 +242,28 @@ entries = IERS::EOP.between(
 Look up TAI−UTC at a given date:
 
 ```ruby
-IERS::LeapSecond.at(Time.utc(2017, 1, 1))  # => 37.0 (seconds)
+IERS::LeapSecond.at(Time.utc(2017, 1, 1))  # => 37 (seconds)
 ```
 
+`at` covers 1961-01-01 onward. From 1972 it returns a whole number of seconds
+as an `Integer`. Between 1961 and 1972, UTC was steered by small rate
+adjustments rather than whole leap seconds, so TAI−UTC was a fraction of a
+second that changed daily. `at` returns those values as exact `Rational`s:
+
+```ruby
+IERS::LeapSecond.at(mjd: 38_900)       # => (1910137/500000)
+IERS::LeapSecond.at(mjd: 38_900).to_f  # => 3.820274 (seconds, 1965-05-20)
+```
+
+The coefficients for that era are fixed and will never change, so they are
+bundled in the gem rather than downloaded. Anything before 1961-01-01 has no
+published UTC and raises `OutOfRangeError`.
+
 List all leap seconds:
 
 ```ruby
 IERS::LeapSecond.all
-# => [#<data IERS::LeapSecond::Entry effective_date=#<Date: 1972-01-01>, tai_utc=10.0>, ...]
+# => [#<data IERS::LeapSecond::Entry effective_date=#<Date: 1972-01-01>, tai_utc=10>, ...]
 ```
 
 Check for a future scheduled leap second:
@@ -258,6 +272,27 @@ Check for a future scheduled leap second:
 IERS::LeapSecond.next_scheduled  # => #<data IERS::LeapSecond::Entry ...> or nil
 ```
 
+#### Leap second file validity
+
+`Leap_Second.dat` states when it stops being authoritative and which IERS
+bulletin it was updated through. Both are read from the file that is actually
+loaded, so a custom or cached file reports its own header:
+
+```ruby
+IERS::LeapSecond.expires_on       # => #<Date: 2026-12-28> or nil
+IERS::LeapSecond.expired?         # => false
+IERS::LeapSecond.updated_through  # => "IERS Bulletin 71 issued in January 2026"
+```
+
+The stated date is itself still valid, so a file expiring on 28 December 2026
+is expired on the 29th. An expired file is not wrong: it means the IERS has
+published a newer one and a leap second may have been announced since.
+
+This is unrelated to `Data.status.cache_age`, which measures when the file was
+downloaded rather than how long it stays valid. A bundled snapshot can be a year
+old and still valid while a file downloaded this morning can be a week from
+expiry.
+
 ### TAI
 
 Convert between UTC and TAI time scales:
@@ -295,6 +330,10 @@ end
 
 Without `coverage_days_ahead`, the check ensures predictions cover today.
 
+`ensure_fresh!` is about prediction coverage in `finals2000A.all` only. Leap
+second file validity is a separate question, answered by
+`IERS::LeapSecond.expired?`.
+
 ### Data status and cache management
 
 ```ruby
@@ -358,6 +397,9 @@ release a new version, update the version number in `version.rb`, and then run
 `bundle exec rake release`, which will create a git tag for the version, push
 git commits and the created tag, and push the `.gem` file to [rubygems.org].
 
+To refresh the bundled snapshot in `data/`, run `bundle exec rake data:update`.
+A monthly workflow runs this and opens a pull request automatically.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License].

data/Rakefile

@@ -10,3 +10,31 @@ require "rubocop/rake_task"
 RuboCop::RakeTask.new
 
 task default: %i[test rubocop]
+
+namespace :data do
+  desc "Download the latest IERS data"
+  task :update do
+    require "iers"
+
+    data_dir = File.expand_path("data", __dir__)
+    IERS.configure do |config|
+      config.finals_path = File.join(data_dir, "finals2000A.all")
+      config.leap_second_path = File.join(data_dir, "Leap_Second.dat")
+    end
+
+    result = IERS::Data.update!
+
+    unless result.success?
+      result.errors.each do |source, error|
+        warn "#{source}: #{error.class} - #{error.message}"
+      end
+      abort "IERS data update failed"
+    end
+
+    IERS::Data.clear_loaded!
+    IERS::Data.ensure_fresh!(coverage_days_ahead: 90)
+    IERS::Data.leap_second_entries
+
+    puts "Updated: #{result.updated_files.join(", ")}"
+  end
+end