nearest 0.0.2 → 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bd2dbd1bc667a5358a73443710dd7b8a1ecfbec9ce768ac89f824db55ce9b95a
+  data.tar.gz: 556bb3486e33520b1517a2ce69ad0d58336af9b5ba8730ba5a9831464917a7b1
+SHA512:
+  metadata.gz: baf9badd33d6a39a3439c005755fec697e6aeb1c68d6fd51558297678d8cec80cf3507dc51588141f7ab7736ce23cbb08da6994aa6e40e86cc63564066da66fe
+  data.tar.gz: 1b5eef52ca6752b3db438905276fbca3f87304ca1df3feee797dce5329f95a6b33b72eb2a42a90db902bdde269a396eb893a468103c06191bf3271885c18dbfa

data/lib/nearest/core.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+# Rounds a time-like object to the nearest interval.
+#
+# The algorithm converts time to epoch seconds, then uses divmod to split into
+# whole intervals (quotient) and leftover seconds (remainder). Multiplying the
+# quotient back by the interval gives the earlier boundary; quotient + 1 gives
+# the later boundary. The remainder decides which one to pick.
+#
+# Example: 1:10pm rounded to 15-minute intervals (900 seconds)
+#
+#   epoch_seconds = 47400  (seconds since midnight for 1:10pm)
+#   quotient, remainder = 47400.divmod(900)  # => [52, 600]
+#
+#   quotient * 900     = 46800  => 1:00pm  (earlier boundary)
+#   (quotient + 1) * 900 = 47700  => 1:15pm  (later boundary)
+#   remainder = 600  (10 minutes past the earlier boundary)
+#
+#   round: :next    => quotient + 1 => 1:15pm  (always advances, even from a boundary)
+#   round: :up      => quotient + 1 => 1:15pm
+#   round: :nearest => 600 * 2 >= 900, so quotient + 1 => 1:15pm
+#   round: :down    => quotient     => 1:00pm
+#   round: :prev    => quotient     => 1:00pm  (always retreats, even from a boundary)
+class Nearest
+  @warned_intervals = Set.new
+
+  class << self
+    def warn_once(seconds)
+      int = seconds.to_i
+      return if (3600 % int).zero?
+      return unless @warned_intervals.add?(int)
+
+      Kernel.warn "nearest: #{int}s does not evenly divide 3600; " \
+                  'boundaries may not align with clock minutes. ' \
+                  'Use anchor: :hour or anchor: :day for clock-aligned rounding'
+    end
+
+    def reset_warnings!
+      @warned_intervals.clear
+    end
+  end
+
+  def initialize(time)
+    @time = time
+  end
+
+  def nearest(seconds, round: :nearest, anchor: nil)
+    anchor_defaulted = anchor.nil?
+    anchor ||= :epoch
+    validate!(seconds, round, anchor)
+    self.class.warn_once(seconds) if anchor_defaulted
+    rebuild(rounded_epoch(seconds, round, anchor))
+  end
+
+  private
+
+  def rounded_epoch(seconds, round, anchor) # rubocop:disable Metrics/CyclomaticComplexity
+    base, offset = base_and_offset(anchor)
+    quotient, remainder = offset.divmod(seconds)
+    rounded = case round
+              when :next    then quotient + 1                                       # always advance
+              when :up      then remainder.zero? ? quotient : quotient + 1          # advance, unless exact
+              when :nearest then remainder * 2 >= seconds ? quotient + 1 : quotient # round at midpoint
+              when :down    then quotient                                           # truncate
+              when :prev    then remainder.zero? ? quotient - 1 : quotient          # always retreat
+              end
+    base + (rounded * seconds)
+  end
+
+  def base_and_offset(anchor)
+    case anchor
+    when :epoch
+      [0, @time.to_i]
+    when :hour
+      local_offset = (@time.min * 60) + @time.sec
+      [@time.to_i - local_offset, local_offset]
+    when :day
+      local_offset = (@time.hour * 3600) + (@time.min * 60) + @time.sec
+      [@time.to_i - local_offset, local_offset]
+    end
+  end
+
+  def rebuild(epoch)
+    if @time.respond_to?(:time_zone)
+      Time.at(epoch).utc.in_time_zone(@time.time_zone)
+    elsif @time.is_a?(DateTime)
+      Time.at(epoch, in: @time.to_time.utc_offset).to_datetime
+    else
+      new_time = Time.at(epoch, in: @time.utc_offset)
+      @time.utc? ? new_time.utc : new_time
+    end
+  end
+
+  def validate!(seconds, round, anchor)
+    raise ArgumentError, 'seconds must be a positive number' unless seconds.is_a?(Numeric) && seconds.positive?
+
+    unless %i[next up nearest down prev].include?(round)
+      raise ArgumentError, "round must be :next, :up, :nearest, :down, or :prev (got #{round.inspect})"
+    end
+
+    return if %i[epoch hour day].include?(anchor)
+
+    raise ArgumentError, "anchor must be :epoch, :hour, or :day (got #{anchor.inspect})"
+  end
+end

data/lib/nearest/date_time.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative 'core'
+
+class DateTime # rubocop:disable Style/Documentation
+  def nearest(seconds, round: :nearest, anchor: nil)
+    Nearest.new(self).nearest(seconds, round:, anchor:)
+  end
+end

data/lib/nearest/time.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative 'core'
+
+class Time # rubocop:disable Style/Documentation
+  def nearest(seconds, round: :nearest, anchor: nil)
+    Nearest.new(self).nearest(seconds, round:, anchor:)
+  end
+end

data/lib/nearest/time_with_zone.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'core'
+
+module ActiveSupport
+  class TimeWithZone # rubocop:disable Style/Documentation
+    def nearest(seconds, round: :nearest, anchor: nil)
+      Nearest.new(self).nearest(seconds, round:, anchor:)
+    end
+  end
+end

data/lib/nearest.rb

@@ -1,8 +1,6 @@
-class Time
-  def nearest(seconds, opts={})
-    method = opts[:force] ? (opts[:force] == :future ? 'ceil' : 'floor') : 'round'
+# frozen_string_literal: true
 
-    new_time = Time.at((self.to_f / seconds).send(method) * seconds)
-    utc? ? new_time.utc : new_time
-  end
-end
+require_relative 'nearest/core'
+require_relative 'nearest/time'
+require_relative 'nearest/date_time'
+require_relative 'nearest/time_with_zone' if defined?(ActiveSupport::TimeWithZone)

metadata

@@ -1,45 +1,48 @@
 --- !ruby/object:Gem::Specification
 name: nearest
 version: !ruby/object:Gem::Version
-  version: 0.0.2
-  prerelease: 
+  version: 1.0.0
 platform: ruby
 authors:
 - Aaron Rosenberg
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-07-03 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: Adds the nearest method to the Time class.
+description: Round Time, DateTime, or ActiveSupport::TimeWithZone to the nearest interval.
+  Use the standalone Nearest class or opt-in monkey patches.
 email: aarongrosenberg@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - lib/nearest.rb
-homepage: https://github.com/LtCmdDudefellah/nearest
-licenses: []
-post_install_message: 
+- lib/nearest/core.rb
+- lib/nearest/date_time.rb
+- lib/nearest/time.rb
+- lib/nearest/time_with_zone.rb
+homepage: https://github.com/agrberg/nearest
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/agrberg/nearest
+  bug_tracker_uri: https://github.com/agrberg/nearest/issues
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 1.8.22
-signing_key: 
-specification_version: 3
-summary: Find the nearest X minutes to a given time.
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Round times to the nearest interval.
 test_files: []