horologium 0.0.1 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7acd6f601c9ea6b6023d91c7b6891d82bede556ce4a744ab821b722615bb4f1c
-  data.tar.gz: f968a52ed82141bdadaef004483cfe56f48511e05d4c2c6db1b27c6557b53166
+  metadata.gz: 513d825c2d141d84274c76333af312631c4b9a077803d2e2921033782af518ce
+  data.tar.gz: '0108ee60e9bf9c1f149baefafe6e78f8d735dd824148ed91c69267b5ca10aad8'
 SHA512:
-  metadata.gz: f6e0f093c7f13b748beed1a6c8a7f53dd18fdcddce28b3bd33caa8b06cd2ffd1a1042ca77569dd6766ca3572fc6e3cc108cb6defbbfd34c9bc389963c4cfda0f
-  data.tar.gz: c3f4bd6142298f451311c76bbbb210023ba04002f6677488d8b22ee850d58f4f127d671bd8d9b425034930ba27d8c00fe4fab6865e32d6b3b46bd80cb5d6ed14
+  metadata.gz: edfa8b82fc1b2d4f795abbf0c01b0a9753cbfb31aa03c37de952b5ea64e62687207bb4efde740d05246ec9df63b6226d682d998ef5d917e401f48fae2cf4402d
+  data.tar.gz: a75b50d13419e546ae0b8cca4d0dce80d078a90578e3e80664a65b2f207ae5535900eb9f36a6291b5a303ce41ccd834b9cd5c226c46e4992d081cf1949b2ba56

data/CHANGELOG.md

@@ -1,5 +1,77 @@
 # Changelog
 
+## 0.0.3 - 2026-08-22
+
+The scale conversions arrive. An instant is now a point with no scale of its
+own, given in one scale and read back in another, and it comes out as a Julian
+Date, a calendar date, or an ISO 8601 string.
+
+### Features
+
+- Add time scales, each converting to and from TAI, the scale an instant is
+  stored in: `TAI`, `TT` at its fixed 32.184 s, `TDB` over the full 787-term
+  Fairhead and Bretagnon model, and `UTC` with its leap seconds
+- Add `Instant#to`, which reads an instant in a scale, and `ScaleReading`,
+  which is that reading, with `#as` for the shape it comes out in
+- Add the representations a reading comes out as: `julian_date`,
+  `modified_julian_date`, `civil`, and `iso8601`, each as a Float, a Rational,
+  or a two-part Float where that makes sense
+- Add `Instant.from_julian_date`, `from_modified_julian_date`, `from_civil`,
+  and `from_iso8601`, each reading its value in a named scale
+- Add `Instant.from_tai`, `from_tt`, `from_tdb`, and `from_utc`, the same
+  calendar constructor with the scale in the name
+- Add `CivilTime`, the calendar fields a clock and a calendar show, in the
+  proleptic Gregorian calendar with astronomical year numbering
+- Read and write a leap second as second 60, on the days that hold one, and
+  refuse it on the days that do not
+- Add `ScaleReading#provenance`, `:measured` up to the date the leap second
+  data vouches for and `:extrapolated` after it, with
+  `Configuration#leap_second_horizon` to refuse an extrapolation instead
+- Add `Configuration#register_scale`, so a caller can add a scale of its own,
+  and `Configuration#leap_second_source`, so it can supply its own leap seconds
+- Add duration arithmetic: `+`, `-`, unary `-`, `zero?`, `negative?`,
+  `positive?`, and `to_r` and `to_f` in SI seconds
+- Add value equality to `ScaleReading`, and `inspect` to `Instant`, `Duration`,
+  and `ScaleReading`
+- Refuse a calendar reading before -4799, where the conversion stops, so a
+  reading out always reads back in
+
+### Fixes
+
+- Build the configuration under a lock, so two threads reaching it at once
+  cannot each build one and lose the other's scales
+
+**Full Changelog**: https://github.com/rhannequin/horologium/compare/v0.0.2...v0.0.3
+
+## 0.0.2 - 2026-07-14
+
+The first functional release. It ships the numeric core and the two value
+objects the rest of the library is built on: `Instant` and `Duration`. The
+scale conversions are not here yet, so an instant is built directly from a
+TAI Julian Date for now.
+
+### Features
+
+- Add `Numeric::TwoPartFloat`, a number kept as a high and a low `Float` for
+  about twice the precision of one, with Shewchuk error-free arithmetic
+- Add `Numeric::Exact`, a value kept as an exact `Rational`, with no rounding
+- Add the precision contract: every value carries a precision, `:standard` or
+  `:exact`, set when it is built and never changed. Mixing the two promotes
+  the result to `:exact` instead of dropping to `:standard`
+- Add `Horologium.configure` for the set-once default precision, and
+  `Horologium.with_precision` for a scoped, per-fiber override
+- Add `Instant`, a frozen point on the TAI timeline, built with
+  `Instant.from_tai_julian_date`
+- Add `Duration`, a frozen span in SI seconds, built with `Duration.seconds`,
+  `Duration.days`, and `Duration.nanoseconds`
+- Add instant and duration arithmetic: shift an instant by a duration, and
+  subtract two instants to measure the duration between them
+- Add `Instant#equal_within?` for comparison inside a tolerance
+- Guard against meaningless operations: adding two instants raises
+  `DimensionalError`
+
+**Full Changelog**: https://github.com/rhannequin/horologium/compare/v0.0.1...v0.0.2
+
 ## 0.0.1 - 2026-07-06
 
 - Gem creation

data/README.md

@@ -3,30 +3,322 @@
 [![Tests](https://github.com/rhannequin/horologium/workflows/CI/badge.svg)](https://github.com/rhannequin/horologium/actions?query=workflow%3ACI)
 
 Horologium is a Ruby library dedicated to **scientific time**: the time scales
-(UTC, TAI, TT, TDB, TCG, TCB, UT1, GPS), high-precision instants, Julian Dates,
+(TAI, TT, TDB, and UTC so far), high-precision instants, Julian Dates,
 intervals, and rigorous conversions between scales that astronomy and physics
 require.
 
+Ruby already has `Time`, `Date`, `DateTime`, and `ActiveSupport` for civil time:
+time zones, calendars, human formatting. None of them knows the difference
+between UTC and a continuous scale, the TAI, TT, and TDB scales an ephemeris
+needs, or a Julian Date kept precise to the nanosecond. That is the gap
+Horologium fills.
+
+## Content
+
+- [Installation](#installation)
+- [Usage](#usage)
+- [Precision](#precision)
+- [Status](#status)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+- [Code of Conduct](#code-of-conduct)
+
 ## Installation
 
-Install the gem and add it to the application's Gemfile by running:
+Install the gem and add it to the application's Gemfile by executing:
+
+    $ bundle add horologium
+
+If [Bundler] is not being used to manage dependencies, install the gem by
+executing:
+
+    $ gem install horologium
+
+## Usage
+
+An `Instant` is a single point on the timeline, kept internally as a TAI Julian
+Date. A `Duration` is an amount of time in SI seconds, with no date and no scale
+attached. You shift an instant by a duration, and you subtract two instants to
+get the duration between them.
+
+```rb
+require "horologium"
+
+a = Horologium::Instant.from_julian_date(2_460_000.5, scale: :tai)
+b = Horologium::Instant.from_julian_date(2_460_001.5, scale: :tai)
+
+a + Horologium::Duration.days(1) == b        # => true
+a < b                                        # => true
+b - a == Horologium::Duration.days(1)        # => true
+```
+
+An instant has no scale of its own. You give it a Julian Date read in a scale,
+and you read it back in any scale the library knows: `to` chooses the scale, and
+`as` chooses the shape it comes out in.
+
+```rb
+instant = Horologium::Instant.from_julian_date(2_443_144.5, scale: :tai)
+
+instant.to(:tt).as(:julian_date)               # => 2443144.5003725
+instant.as(:modified_julian_date, scale: :tt)  # => 43144.0003725
+```
+
+A calendar date is a shape too, and the one a person reads. It comes out as a
+`CivilTime`, whose fields are the ones a clock and a calendar show, in the
+proleptic Gregorian calendar.
+
+```rb
+civil = instant.as(:civil, scale: :tt)
+
+civil.year    # => 1977
+civil.month   # => 1
+civil.second  # => 32
+```
+
+You can build an instant from those fields as well, and nothing is lost on the
+way in: the date becomes a whole number of days and the time of day an exact
+fraction of one. Give a fractional second as a `Rational` to say it exactly.
 
-```sh
-bundle add horologium
+```rb
+Horologium::Instant.from_civil(2025, 5, 1, 12, 0, 0, scale: :tt)
+Horologium::Instant.from_civil(2025, 5, 1, 12, 0, Rational(1, 4), scale: :tt)
 ```
 
-Or install it directly:
+Each scale has its own shortcut, so the scale is in the name instead of a
+keyword.
+
+```rb
+Horologium::Instant.from_tt(2025, 5, 1, 12, 0, 0)
+Horologium::Instant.from_tai(2025, 5, 1, 12, 0, 0)
+Horologium::Instant.from_tdb(2025, 5, 1, 12, 0, 0)
+```
+
+A date that does not exist is refused rather than rolled over, and the message
+says which field is wrong.
+
+```rb
+Horologium::Instant.from_civil(1900, 2, 29, scale: :tt)
+# => raises Horologium::InvalidCivilTimeError
+```
+
+The same date and time write out as an extended ISO 8601 string, and read back
+from one. The scale is not written into the string: there is no ISO 8601
+designator for TAI or TT, and `Z` means UTC, so a bare time is a coordinate in
+the scale you asked for.
+
+```rb
+instant.as(:iso8601, scale: :tt)   # => "1977-01-01T00:00:32.184000000"
+
+Horologium::Instant.from_iso8601("2025-05-01T12:00:00", scale: :tt)
+Horologium::Instant.from_iso8601("2025-05-01", scale: :tt)  # midnight
+```
+
+The parser reads a strict subset: a calendar date, an optional time of day
+after a `T`, a fraction of a second kept to every digit, and an optional `Z` or
+numeric offset applied as plain arithmetic, not a time zone. A week date, an
+ordinal date, or anything outside the subset is refused with a `ParseError`.
+
+UTC is the scale of civil clocks, the one that holds a leap second now and
+then to keep step with the Earth's rotation. `from_utc` reads a UTC date, and
+a leap second is a legal reading: the second is 60 on a day that holds one, and
+that moment really existed.
+
+```rb
+Horologium::Instant.from_utc(2025, 5, 1, 12, 0, 0)
+
+leap = Horologium::Instant.from_utc(2016, 12, 31, 23, 59, 60)
+leap.as(:iso8601, scale: :utc)  # => "2016-12-31T23:59:60.000000000Z"
+```
+
+A leap second is a real second on the timeline, so the arithmetic is right
+across it: the second before 23:59:60, the leap second, and the next midnight
+are one SI second apart each. Second 60 on a day with no leap second is
+refused.
+
+```rb
+before = Horologium::Instant.from_utc(
+  2016, 12, 31, 23, 59, 59,
+  precision: :exact
+)
+leap = Horologium::Instant.from_utc(
+  2016, 12, 31, 23, 59, 60,
+  precision: :exact
+)
+after = Horologium::Instant.from_utc(
+  2017, 1, 1, 0, 0, 0,
+  precision: :exact
+)
+
+leap - before == Horologium::Duration.seconds(1)   # => true
+after - leap == Horologium::Duration.seconds(1)    # => true
+
+Horologium::Instant.from_utc(2020, 6, 15, 23, 59, 60)
+# => raises Horologium::InvalidCivilTimeError
+```
+
+The `:exact` above is what makes `==` the right question to ask. At the default
+`:standard` precision the same three instants land a rounding step apart, well
+under a nanosecond but not zero, so compare those with `equal_within?`.
+
+UTC runs from 1961, whole leap seconds from 1972 and the earlier
+rate-adjustment drift before that, where a UTC second was fractionally longer
+than an SI one. An earlier UTC date raises `Horologium::OutOfRangeError`. The
+instant is still reachable, only its UTC label is not, so the error names the
+continuous scales, which have no lower bound. The leap seconds and the drift
+come from the [iers] gem, with no network access: the data ships with the gem.
 
-```sh
-gem install horologium
+```rb
+Horologium::Instant.from_utc(1960, 12, 31)                  # => OutOfRangeError
+Horologium::Instant.from_civil(1960, 12, 31, scale: :tt)    # reaches any date
 ```
 
+Leap seconds are announced about six months ahead, so past the date its data
+vouches for, the last known offset is the best there is. A UTC reading says
+which it rests on: `:measured` up to that date, `:extrapolated` after, where a
+leap second announced since would not be known.
+
+```rb
+instant.to(:utc).provenance   # => :measured, or :extrapolated past the horizon
+```
+
+A pipeline that must not rest on an offset a leap second could overturn sets a
+strict horizon, and a reading past it raises instead.
+
+```rb
+Horologium.configure { |c| c.leap_second_horizon = :raise }
+# => reading a date past the data horizon raises OutOfDataRangeError
+```
+
+The configuration is set once, in a single `Horologium.configure` block, and
+frozen when the block returns. See [Precision](#precision).
+
+A Julian Date is around 2.46 million, which leaves a single `Float` about 40
+microseconds for the fraction of a day, and the loss is already in the literal
+before Horologium sees it. So the lossless shapes come first: a `String` and a
+`Rational` say the Julian Date exactly, and a high and a low part say it to
+about twice what one `Float` holds.
+
+```rb
+Horologium::Instant.from_julian_date("2456463.052272", scale: :tt)
+Horologium::Instant.from_julian_date(
+  Rational(2_456_463_052_272, 1_000_000),
+  scale: :tt
+)
+Horologium::Instant.from_julian_date(2_456_463.0, 0.052272, scale: :tt)
+
+Horologium::Instant.from_modified_julian_date(60_796.0, scale: :tai)
+```
+
+A `Duration` counts SI seconds, so `Duration.days(1)` is always 86,400 SI
+seconds. Because of leap seconds a civil day can be a second longer or shorter,
+so a duration and a calendar day are different things.
+
+```rb
+Horologium::Duration.days(1) == Horologium::Duration.seconds(86_400)  # => true
+Horologium::Duration.nanoseconds(1_000_000_000) ==
+  Horologium::Duration.seconds(1)                                     # => true
+```
+
+Durations add, subtract, and negate among themselves, and read back out in SI
+seconds.
+
+```rb
+Horologium::Duration.seconds(30) + Horologium::Duration.seconds(12)
+Horologium::Duration.seconds(30) - Horologium::Duration.seconds(42)  # negative
+-Horologium::Duration.seconds(3)
+
+Horologium::Duration.days(1).to_r  # => (86400/1), the whole value
+Horologium::Duration.days(1).to_f  # => 86400.0
+```
+
+Adding a duration to an instant makes sense, but adding two instants together
+does not, so it raises an error.
+
+```rb
+instant + instant  # => raises Horologium::DimensionalError
+```
+
+Exact equality is rarely what scientific code wants, so you can compare within a
+tolerance:
+
+```rb
+a = Horologium::Instant.from_julian_date(2_460_000.5, scale: :tai)
+near = a + Horologium::Duration.nanoseconds(1)
+
+a.equal_within?(near, Horologium::Duration.nanoseconds(2))  # => true
+```
+
+## Precision
+
+A modern Julian Date is around 2.46 million. A single `Float` spends most of its
+digits on that large number and has only tens of microseconds left for the
+fraction of a day. That is too coarse for scientific time. Horologium stores an
+instant across two `Float`s whose sum is the Julian Date, so the second one
+starts where the first runs out of digits. This is the representation [ERFA]
+uses, it keeps the precision below a nanosecond for any date, and it does so
+with ordinary floating-point arithmetic.
+
+Every value carries one of two precisions, fixed when it is built:
+
+- `:standard`, the default, keeps the value as a two-part float. It is fast and
+  stays within a few nanoseconds of the true value.
+- `:exact` keeps the value as a `Rational`, with no rounding. The test suite
+  uses it to check that `:standard` stays within its stated precision.
+
+Set the default once at boot. `Horologium.configure` freezes the configuration
+when its block returns, so it is called once and everything is set in the one
+block. A second call raises `Horologium::ConfigurationError`.
+
+```rb
+Horologium.configure do |c|
+  c.default_precision = :exact
+  c.leap_second_horizon = :raise
+end
+```
+
+Choose it for a single value, or for a scoped block:
+
+```rb
+Horologium::Instant.from_julian_date(
+  2_460_000.5,
+  scale: :tai,
+  precision: :exact
+)
+
+Horologium.with_precision(:exact) do
+  # instants and durations built here default to :exact
+end
+```
+
+Exactness is contagious. An operation between two `:standard` values stays
+`:standard`. Mixing a `:standard` and an `:exact` value gives an `:exact`
+result, so precision is not quietly lost. `:exact` guarantees the arithmetic
+Horologium performs. It cannot bring back precision that an input already lost
+when it was built.
+
+## Status
+
+This library is in early development, before its first public release. The
+public API is not stable, so new versions will probably introduce breaking
+changes until a 1.0 release. Changes are documented in the [CHANGELOG].
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run
 `rake` to run the tests and RuboCop, or `rake steep` to type-check the
-signatures in `sig/`. You can also run `bin/console` for an interactive prompt
-that will allow you to experiment.
+signatures in `sig/`. Run `COVERAGE=true rake test` to measure test coverage,
+which is enforced at 100% of lines and branches in CI. You can also run
+`bin/console` for an interactive prompt that will allow you to experiment.
+
+`sig/` holds Horologium's own signatures and ships with the gem. `sig-vendor/`
+holds stubs for gems that ship none of their own, and stays out of the gem so
+it cannot clash with a downstream RBS collection.
+
+Run `bin/ci` to run every check that GitHub Actions runs (RuboCop, Steep, YARD
+documentation coverage, and the tests with coverage) in a single pass. It runs
+each check even when an earlier one fails, so you see everything that needs
+fixing at once.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To
 release a new version, update the version number in `version.rb`, and then run
@@ -47,6 +339,9 @@ The gem is available as open source under the terms of the [MIT License].
 Everyone interacting in the Horologium project's codebases, issue trackers, chat
 rooms and mailing lists is expected to follow the [code of conduct].
 
+[Bundler]: https://bundler.io
+[ERFA]: https://github.com/liberfa/erfa
+[CHANGELOG]: https://github.com/rhannequin/horologium/blob/main/CHANGELOG.md
 [rubygems.org]: https://rubygems.org
 [MIT License]: https://opensource.org/licenses/MIT
 [code of conduct]: https://github.com/rhannequin/horologium/blob/main/CODE_OF_CONDUCT.md

data/Rakefile

@@ -2,16 +2,29 @@
 
 require "bundler/gem_tasks"
 require "minitest/test_task"
-
-Minitest::TestTask.create
-
 require "rubocop/rake_task"
+require "yard"
+
+Minitest::TestTask.create do |t|
+  t.framework = %(require "test_helper")
+end
 
 RuboCop::RakeTask.new
+YARD::Rake::YardocTask.new
 
 desc "Type check with Steep"
 task :steep do
   sh "steep check"
 end
 
+desc "Verify YARD documentation coverage is 100%"
+task :yard_coverage do
+  require "open3"
+  output, status = Open3.capture2e("yard", "stats", "--list-undoc")
+  puts output
+  unless status.success? && output.include?("100.00% documented")
+    abort "YARD documentation coverage is below 100%"
+  end
+end
+
 task default: %i[test rubocop]