Add Astronoby::Duration

Author: rhannequin

docs/lunar_eclipses.md

@@ -50,7 +50,7 @@ eclipse.shadow_axis_distance.km     # => 2222.37
 
 ## Phases
 
-An eclipse exposes its phases as `Astronoby::EclipsePhase` objects, each with a `#starting_instant`, an `#ending_instant`, and a `#duration` in seconds. The penumbral phase is always present. The partial phase is present for partial and total eclipses, and the total phase (totality) only for total eclipses. A phase that does not occur is `nil`.
+An eclipse exposes its phases as `Astronoby::EclipsePhase` objects, each with a `#starting_instant`, an `#ending_instant`, and a `#duration` (an `Astronoby::Duration`). The penumbral phase is always present. The partial phase is present for partial and total eclipses, and the total phase (totality) only for total eclipses. A phase that does not occur is `nil`.
 
 ```rb
 eclipse.penumbral.starting_instant.to_time # => 2025-03-14 03:57:29 UTC (P1)
@@ -60,7 +60,7 @@ eclipse.total.ending_instant.to_time       # => 2025-03-14 07:31:32 UTC (U3)
 eclipse.partial.ending_instant.to_time     # => 2025-03-14 08:47:55 UTC (U4)
 eclipse.penumbral.ending_instant.to_time   # => 2025-03-14 10:00:08 UTC (P4)
 
-eclipse.total.duration # => 3931 (seconds of totality)
+eclipse.total.duration.seconds # => 3931 (seconds of totality)
 ```
 
 For a penumbral eclipse, `#partial` and `#total` are `nil`. For a partial eclipse, `#total` is `nil`.

lib/astronoby.rb

@@ -12,6 +12,7 @@
 require "astronoby/constellations/data"
 require "astronoby/constellations/finder"
 require "astronoby/distance"
+require "astronoby/duration"
 require "astronoby/center"
 require "astronoby/body"
 require "astronoby/position"

lib/astronoby/bodies/sun.rb

@@ -90,7 +90,7 @@ def apparent_magnitude
     #  Edition: 2nd edition
     #  Chapter: 28 - Equation of Time
 
-    # @return [Integer] Equation of time in seconds
+    # @return [Astronoby::Duration] Equation of time
     def equation_of_time
       right_ascension = apparent.equatorial.right_ascension
       t = (@instant.julian_date - JulianDate::J2000) / Constants::DAYS_PER_JULIAN_MILLENIA
@@ -103,7 +103,7 @@ def equation_of_time
       nutation = Nutation.new(instant: instant).nutation_in_longitude
       obliquity = TrueObliquity.at(@instant)
 
-      (
+      seconds = (
         Angle
           .from_degrees(
             l0 -
@@ -112,6 +112,7 @@ def equation_of_time
               nutation.degrees * obliquity.cos
           ).hours * Constants::SECONDS_PER_HOUR
       ).round
+      Duration.from_seconds(seconds)
     end
 
     # @return [nil] the Sun has no phase angle as seen from Earth

lib/astronoby/duration.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class Duration
+    include Comparable
+
+    class << self
+      # @return [Astronoby::Duration] a zero duration
+      def zero
+        new(0)
+      end
+
+      # @param seconds [Numeric] the duration in seconds
+      # @return [Astronoby::Duration] a new Duration
+      def from_seconds(seconds)
+        new(seconds)
+      end
+
+      # @param minutes [Numeric] the duration in minutes
+      # @return [Astronoby::Duration] a new Duration
+      def from_minutes(minutes)
+        seconds = minutes * Constants::SECONDS_PER_MINUTE
+        from_seconds(seconds)
+      end
+
+      # @param hours [Numeric] the duration in hours
+      # @return [Astronoby::Duration] a new Duration
+      def from_hours(hours)
+        seconds = hours * Constants::SECONDS_PER_HOUR
+        from_seconds(seconds)
+      end
+
+      # @param days [Numeric] the duration in days
+      # @return [Astronoby::Duration] a new Duration
+      def from_days(days)
+        seconds = days * Constants::SECONDS_PER_DAY
+        from_seconds(seconds)
+      end
+    end
+
+    # @return [Numeric] the duration in seconds
+    attr_reader :seconds
+
+    # @param seconds [Numeric] the duration in seconds
+    def initialize(seconds)
+      @seconds = seconds
+      freeze
+    end
+
+    # @return [Float] the duration in minutes
+    def minutes
+      @seconds / Constants::SECONDS_PER_MINUTE
+    end
+
+    # @return [Float] the duration in hours
+    def hours
+      @seconds / Constants::SECONDS_PER_HOUR
+    end
+
+    # @return [Float] the duration in days
+    def days
+      @seconds / Constants::SECONDS_PER_DAY
+    end
+
+    # @param other [Astronoby::Duration] duration to add
+    # @return [Astronoby::Duration] the sum
+    def +(other)
+      self.class.from_seconds(@seconds + other.seconds)
+    end
+
+    # @param other [Astronoby::Duration] duration to subtract
+    # @return [Astronoby::Duration] the difference
+    def -(other)
+      self.class.from_seconds(@seconds - other.seconds)
+    end
+
+    # @return [Astronoby::Duration] the negated duration
+    def -@
+      self.class.from_seconds(-@seconds)
+    end
+
+    # @return [Astronoby::Duration] the absolute duration
+    def abs
+      self.class.from_seconds(@seconds.abs)
+    end
+
+    # @return [Boolean] true if the duration is positive
+    def positive?
+      @seconds > 0
+    end
+
+    # @return [Boolean] true if the duration is negative
+    def negative?
+      @seconds < 0
+    end
+
+    # @return [Boolean] true if the duration is zero
+    def zero?
+      @seconds.zero?
+    end
+
+    # @return [Integer] hash value
+    def hash
+      [@seconds, self.class].hash
+    end
+
+    # @param other [Astronoby::Duration] duration to compare with
+    # @return [Integer, nil] -1, 0, or 1; nil if not comparable
+    def <=>(other)
+      return unless other.is_a?(self.class)
+
+      seconds <=> other.seconds
+    end
+    alias_method :eql?, :==
+  end
+end

lib/astronoby/events/eclipse_phase.rb

@@ -17,9 +17,11 @@ def initialize(starting_instant:, ending_instant:)
       freeze
     end
 
-    # @return [Integer] phase duration in seconds
+    # @return [Astronoby::Duration] phase duration
     def duration
-      (@ending_instant.to_time - @starting_instant.to_time).round
+      Duration.from_seconds(
+        (@ending_instant.to_time - @starting_instant.to_time).round
+      )
     end
   end
 end

spec/astronoby/bodies/sun_spec.rb

@@ -503,15 +503,15 @@
   end
 
   describe "#equation_of_time" do
-    it "returns an Integer" do
+    it "returns a Duration" do
       time = Time.new
       instant = Astronoby::Instant.from_time(time)
       ephem = test_ephem_sun
       sun = described_class.new(instant: instant, ephem: ephem)
 
       equation_of_time = sun.equation_of_time
 
-      expect(equation_of_time).to be_an Integer
+      expect(equation_of_time).to be_a Astronoby::Duration
     end
 
     # Source:
@@ -527,7 +527,7 @@
 
       equation_of_time = sun.equation_of_time
 
-      expect(equation_of_time).to eq(-392)
+      expect(equation_of_time.seconds).to eq(-392)
       # Value from Practical Astronomy: 392
     end
 
@@ -544,7 +544,7 @@
 
       equation_of_time = sun.equation_of_time
 
-      expect(equation_of_time).to eq(199)
+      expect(equation_of_time.seconds).to eq(199)
       # Value from Celestial Calculations: 199
     end
 
@@ -561,7 +561,7 @@
 
       equation_of_time = sun.equation_of_time
 
-      expect(equation_of_time).to eq(-336)
+      expect(equation_of_time.seconds).to eq(-336)
       # Value from Celestial Calculations: 337
     end
 
@@ -578,7 +578,7 @@
 
       equation_of_time = sun.equation_of_time
 
-      expect(equation_of_time).to eq(202)
+      expect(equation_of_time.seconds).to eq(202)
       # Value from Celestial Calculations: 201
     end
 
@@ -595,7 +595,7 @@
 
       equation_of_time = sun.equation_of_time
 
-      expect(equation_of_time).to eq(-185)
+      expect(equation_of_time.seconds).to eq(-185)
       # Value from Celestial Calculations: 187
     end
   end