Enhance time arithmetic methods for unit-based calculations and improve documentation

Author: olbrich

README.md

@@ -144,19 +144,61 @@ Unit.new("100 kg").to_s(:stone)   # returns 15 stone, 10 lb
 
 ### Time Helpers
 
-`Time`, `Date`, and `DateTime` objects can have time units added or subtracted.
+Ruby-units extends the `Time`, `Date`, and `DateTime` classes to support unit-based arithmetic,
+allowing you to add or subtract durations from time objects naturally.
+
+#### Adding and Subtracting Durations
 
 ```ruby
-Time.now + Unit.new("10 min")
+Time.now + Unit.new("10 min")   #=> 10 minutes from now
+Time.now - Unit.new("2 hours")  #=> 2 hours ago
 ```
 
-Several helpers have also been defined. Note: If you include the 'Chronic' gem,
-you can specify times in natural language.
+**Important:** When adding or subtracting large time units (years, decades, centuries),
+the duration is first converted to days and rounded to maintain calendar accuracy.
+This means `1 year` is treated as approximately 365 days rather than an exact number of seconds.
 
 ```ruby
-Unit.new('min').since(DateTime.parse('9/18/06 3:00pm'))
+Time.now + Unit.new("1 year")    #=> Approximately 365 days from now
+Time.now - Unit.new("1 decade")  #=> Approximately 3650 days ago
+```
+
+For more precise durations, use smaller units (hours, minutes, seconds):
+
+```ruby
+Time.now + Unit.new("24 hours")  #=> Exactly 24 hours from now
+```
+
+#### Converting Time to Units
+
+You can convert `Time` objects to units representing the duration since the Unix epoch:
+
+```ruby
+Time.now.to_unit              #=> Duration in seconds since epoch
+Time.now.to_unit('hours')     #=> Duration in hours since epoch
+Time.now.to_unit('days')      #=> Duration in days since epoch
+```
+
+#### Creating Time from Units
+
+Use `Time.at` to create a Time object from a duration unit:
+
+```ruby
+Time.at(Unit.new("1000 seconds"))           #=> Time 1000 seconds after epoch
+Time.at(Unit.new("1 hour"), 500, :ms)       #=> Time 1 hour + 500 milliseconds after epoch
+```
+
+#### Convenience Methods
+
+The `Time.in` method provides a shorthand for calculating future times:
+
+```ruby
+Time.in('5 min')    #=> 5 minutes from now
+Time.in('2 hours')  #=> 2 hours from now
 ```
 
+#### Duration Formats
+
 Durations may be entered as 'HH:MM:SS, usec' and will be returned in 'hours'.
 
 ```ruby
@@ -168,6 +210,21 @@ Unit.new('0:30:30')  #=> 0.5 h + 30 sec
 If only one ":" is present, it is interpreted as the separator between hours and
 minutes.
 
+#### Compatibility with Chronic
+
+Several helpers are available for working with natural language time parsing.
+Note: If you include the 'Chronic' gem, you can specify times in natural language.
+
+```ruby
+Unit.new('min').since(DateTime.parse('9/18/06 3:00pm'))
+```
+
+#### Range Errors and DateTime Fallback
+
+If time arithmetic would result in a date outside the valid range for the `Time` class
+(typically 1970-2038 on 32-bit systems), ruby-units automatically falls back to using
+`DateTime` objects to handle the calculation.
+
 ### Ranges
 
 ```ruby

lib/ruby_units/time.rb

@@ -8,77 +8,146 @@ module RubyUnits
   # is in years, decades, or centuries.  This leads to less precise values, but ones that match the
   # calendar better.
   module Time
-    # Class methods for [Time] objects
+    # Class methods for [::Time] objects
     module ClassMethods
       # Convert a duration to a [::Time] object by considering the duration to be
-      # the number of seconds since the epoch
+      # the number of seconds since the epoch.
       #
-      # @param [Array<RubyUnits::Unit, Numeric, Symbol, Hash>] args
-      # @return [::Time]
-      def at(*args, **kwargs)
-        case args.first
-        when RubyUnits::Unit
-          options = args.last.is_a?(Hash) ? args.pop : kwargs
-          secondary_unit = args[2] || "microsecond"
-          case args[1]
-          when Numeric
-            super((args.first + RubyUnits::Unit.new(args[1], secondary_unit.to_s)).convert_to("second").scalar, **options)
-          else
-            super(args.first.convert_to("second").scalar, **options)
-          end
-        else
-          super
-        end
+      # @example Create time from a Unit duration
+      #   Time.at(Unit.new("5 min"))  #=> Time object 300 seconds after epoch
+      #
+      # @example Create time from Unit with offset
+      #   Time.at(Unit.new("1 h"), 500, :millisecond)  #=> Time 1 hour + 500 ms after epoch
+      #
+      # @param [Array<RubyUnits::Unit, Numeric, Symbol, Hash>] args Arguments passed to Time.at
+      # @param [Hash] kwargs Keyword arguments (e.g., in: timezone)
+      # @return [::Time] A Time object representing the duration since epoch
+      def at(*args, **)
+        first_arg = args.first
+        return super unless first_arg.is_a?(RubyUnits::Unit)
+
+        time_in_seconds = calculate_time_in_seconds(first_arg, args[1], args[2])
+        remaining_args = build_remaining_args(args)
+
+        super(time_in_seconds, *remaining_args, **)
       end
 
-      # @example
-      #  Time.in '5 min'
-      # @param duration [#to_unit]
-      # @return [::Time]
+      # Calculate a future time by adding a duration to the current time.
+      # This is a convenience method equivalent to Time.now + duration.
+      #
+      # @example Get time 5 minutes from now
+      #   Time.in('5 min')  #=> Time object 5 minutes in the future
+      #
+      # @example Using various duration formats
+      #   Time.in('2 hours')  #=> 2 hours from now
+      #   Time.in(Unit.new('30 sec'))  #=> 30 seconds from now
+      #
+      # @param duration [String, RubyUnits::Unit, #to_unit] A duration that can be converted to a Unit
+      # @return [::Time] A Time object representing the current time plus the duration
+      # :reek:UtilityFunction - This is a class method convenience wrapper, state independence is by design
       def in(duration)
         ::Time.now + duration.to_unit
       end
+
+      private
+
+      # Calculate the time in seconds from a Unit and optional offset
+      # @param base_unit [RubyUnits::Unit] The base time unit
+      # @param offset_value [Numeric, nil] Optional offset value
+      # @param offset_unit [String, Symbol, nil] Unit for the offset (default: "microsecond")
+      # @return [Numeric] Time in seconds
+      # :reek:UtilityFunction - Private helper method, state independence is acceptable
+      # :reek:ControlParameter - Default parameter handling is appropriate here
+      def calculate_time_in_seconds(base_unit, offset_value, offset_unit)
+        return base_unit.convert_to("second").scalar unless offset_value.is_a?(Numeric)
+
+        unit_str = offset_unit&.to_s || "microsecond"
+        (base_unit + RubyUnits::Unit.new(offset_value, unit_str)).convert_to("second").scalar
+      end
+
+      # Build remaining arguments to pass to super, skipping the first 3 processed args
+      # @param args [Array] Original arguments array
+      # @return [Array] Remaining arguments after the first three
+      # :reek:UtilityFunction - Private helper method, state independence is acceptable
+      def build_remaining_args(args)
+        args[3..] || []
+      end
     end
 
-    # Convert a [::Time] object to a [RubyUnits::Unit] object. The time is
-    # considered to be a duration with the number of seconds since the epoch.
+    # Convert a [::Time] object to a [RubyUnits::Unit] object representing
+    # the duration in seconds since the Unix epoch (January 1, 1970 00:00:00 UTC).
+    #
+    # @example Convert time to unit
+    #   Time.now.to_unit  #=> Unit representing seconds since epoch
+    #
+    # @example Convert time to specific unit
+    #   Time.now.to_unit('hour')  #=> Unit in hours since epoch
     #
-    # @param other [String, RubyUnits::Unit]
-    # @return [RubyUnits::Unit]
+    # @param other [String, RubyUnits::Unit, nil] Optional target unit for conversion
+    # @return [RubyUnits::Unit] A Unit object representing the time as a duration
     def to_unit(other = nil)
-      other ? RubyUnits::Unit.new(self).convert_to(other) : RubyUnits::Unit.new(self)
+      unit = RubyUnits::Unit.new(self)
+      other ? unit.convert_to(other) : unit
     end
 
-    # @param other [::Time, RubyUnits::Unit]
-    # @return [RubyUnits::Unit, ::Time]
+    # Add a duration to a time. For large units (years, decades, centuries),
+    # the duration is first converted to days and rounded to handle calendar complexities.
+    # If the result would be out of range for Time, falls back to DateTime.
+    #
+    # @example Add hours to time
+    #   Time.now + Unit.new('2 hours')  #=> Time 2 hours in future
+    #
+    # @example Add years (rounded to days)
+    #   Time.now + Unit.new('1 year')  #=> Time ~365 days in future
+    #
+    # @param other [::Time, RubyUnits::Unit, Numeric] Value to add
+    # @return [::Time, DateTime] The resulting time, or DateTime if out of Time range
     def +(other)
-      case other
-      when RubyUnits::Unit
-        other = other.convert_to("d").round.convert_to("s") if %w[y decade century].include? other.units
-        begin
-          super(other.convert_to("s").scalar)
-        rescue RangeError
-          to_datetime + other
-        end
-      else
-        super
-      end
+      return super unless other.is_a?(RubyUnits::Unit)
+
+      duration_in_seconds = convert_to_seconds(other)
+      super(duration_in_seconds)
+    rescue RangeError
+      to_datetime + other
     end
 
-    # @param other [::Time, RubyUnits::Unit]
-    # @return [RubyUnits::Unit, ::Time]
+    # Subtract a duration from a time. For large units (years, decades, centuries),
+    # the duration is first converted to days and rounded to handle calendar complexities.
+    # If the result would be out of range for Time, falls back to DateTime.
+    #
+    # @example Subtract hours from time
+    #   Time.now - Unit.new('2 hours')  #=> Time 2 hours in past
+    #
+    # @example Subtract years (rounded to days)
+    #   Time.now - Unit.new('1 year')  #=> Time ~365 days in past
+    #
+    # @param other [::Time, RubyUnits::Unit, Numeric] Value to subtract
+    # @return [::Time, DateTime, Numeric] The resulting time (DateTime if out of range),
+    #   or numeric difference in seconds if subtracting another Time
     def -(other)
-      case other
-      when RubyUnits::Unit
-        other = other.convert_to("d").round.convert_to("s") if %w[y decade century].include? other.units
-        begin
-          super(other.convert_to("s").scalar)
-        rescue RangeError
-          public_send(:to_datetime) - other
-        end
-      else
-        super
-      end
+      return super unless other.is_a?(RubyUnits::Unit)
+
+      duration_in_seconds = convert_to_seconds(other)
+      super(duration_in_seconds)
+    rescue RangeError
+      public_send(:to_datetime) - other
+    end
+
+    private
+
+    # Convert a unit to seconds, rounding large time units (years, decades, centuries) to days first.
+    # This handles calendar complexities where years don't have a fixed number of seconds.
+    #
+    # @param unit [RubyUnits::Unit] The duration unit to convert
+    # @return [Numeric] The duration in seconds
+    # :reek:UtilityFunction - Private helper method, state independence is acceptable
+    def convert_to_seconds(unit)
+      normalized_unit = if %w[y decade century].include?(unit.units)
+                          unit.convert_to("d").round.convert_to("s")
+                        else
+                          unit.convert_to("s")
+                        end
+      normalized_unit.scalar
     end
   end
 end