Add time predicates #within?, #before? and #after?

lib/openhab/core/items/item.rb

@@ -582,12 +582,9 @@ def unlink(channel)
         # @return [String]
         def inspect
           s = "#<OpenHAB::Core::Items::#{type}Item#{type_details} #{name} #{label.inspect} state=#{raw_state.inspect}"
-          # @deprecated OH 4.3 Remove if guard when dropping support for OH 4.3
-          if respond_to?(:last_state)
-            s += " last_state=#{last_state.inspect}" if last_state
-            s += " last_state_update=#{last_state_update}" if last_state_update
-            s += " last_state_change=#{last_state_change}" if last_state_change
-          end
+          s += " last_state=#{last_state.inspect}" if last_state
+          s += " last_state_update=#{last_state_update}" if last_state_update
+          s += " last_state_change=#{last_state_change}" if last_state_change
           s += " category=#{category.inspect}" if category
           s += " tags=#{tags.to_a.inspect}" unless tags.empty?
           s += " groups=#{group_names}" unless group_names.empty?

lib/openhab/core_ext/java/time.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../time_predicates"
+
 module OpenHAB
   module CoreExt
     module Java
@@ -24,6 +26,7 @@ def parse(*)
 
         # @!visibility private
         def self.included(klass)
+          klass.prepend(OpenHAB::CoreExt::TimePredicates)
           klass.singleton_class.prepend(ClassMethods)
           klass.remove_method(:==)
           klass.alias_method(:inspect, :to_s)

lib/openhab/core_ext/ruby/date.rb

@@ -3,11 +3,14 @@
 require "forwardable"
 require "date"
 
+require_relative "../time_predicates"
+
 # Extensions to Date
 class Date
   extend Forwardable
   include OpenHAB::CoreExt::Between
   include OpenHAB::CoreExt::Ephemeris
+  include OpenHAB::CoreExt::TimePredicates
 
   #
   # Extends {#+} to allow adding a {java.time.temporal.TemporalAmount TemporalAmount}

lib/openhab/core_ext/ruby/date_time.rb

@@ -3,6 +3,8 @@
 require "date"
 require "forwardable"
 
+require_relative "../time_predicates"
+
 # DateTime inherits from Date, but is more similar to Time semantically.
 # So it avoid alias_method chain bombs, and to ensure the correct end methods
 # exist here, we define the important methods from Time here as well.
@@ -12,6 +14,7 @@ class DateTime < Date
   extend Forwardable
   include OpenHAB::CoreExt::Between
   include OpenHAB::CoreExt::Ephemeris
+  include OpenHAB::CoreExt::TimePredicates
 
   # (see Time#plus_with_temporal)
   def plus_with_temporal(other)

lib/openhab/core_ext/ruby/time.rb

@@ -2,11 +2,14 @@
 
 require "forwardable"
 
+require_relative "../time_predicates"
+
 # Extensions to Time
 class Time
   extend Forwardable
   include OpenHAB::CoreExt::Between
   include OpenHAB::CoreExt::Ephemeris
+  include OpenHAB::CoreExt::TimePredicates
 
   #
   # @!method +(other)

lib/openhab/core_ext/time_predicates.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module CoreExt
+    # Predicate helpers for date/time-like objects.
+    module TimePredicates
+      #
+      # Checks whether the object falls within the given duration from now.
+      #
+      # @param [Java::TemporalAmount] duration the duration to check against
+      # @return [true,false]
+      # @raise [ArgumentError] if the duration is not a TemporalAmount
+      #
+      def within?(duration)
+        raise ArgumentError, "duration must be a TemporalAmount" unless duration.is_a?(Java::TemporalAmount)
+
+        threshold = duration.ago
+        comparison = self <=> threshold
+        raise ArgumentError, "comparison of #{self.class} with #{threshold.class} failed" unless comparison
+
+        comparison >= 0
+      end
+
+      #
+      # Checks whether the object is before another time-like object.
+      #
+      # @param [Object] other the other time-like object to compare against
+      # @return [true,false]
+      #
+      def before?(other)
+        comparison = self <=> other
+        raise ArgumentError, "comparison of #{self.class} with #{other.class} failed" unless comparison
+
+        comparison.negative?
+      end
+
+      #
+      # Checks whether the object is after another time-like object.
+      #
+      # @param [Object] other the other time-like object to compare against
+      # @return [true,false]
+      #
+      def after?(other)
+        comparison = self <=> other
+        raise ArgumentError, "comparison of #{self.class} with #{other.class} failed" unless comparison
+
+        comparison.positive?
+      end
+    end
+  end
+end

lib/openhab/dsl.rb

@@ -737,8 +737,8 @@ def ensure_states
     # @example
     #   persistence(:influxdb) do
     #     Item1.persist
-    #     Item1.changed_since(1.hour)
-    #     Item1.average_since(12.hours)
+    #     Item1.changed_since?(1.hour.ago)
+    #     Item1.average_since(12.hours.ago)
     #   end
     #
     # @param [Object] service Persistence service either as a String or a Symbol

spec/openhab/core_ext/time_predicates_spec.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+RSpec.describe OpenHAB::CoreExt::TimePredicates do
+  around do |example|
+    Timecop.freeze
+    example.run
+  ensure
+    Timecop.return
+  end
+
+  describe "#within?" do
+    it "returns true when a Java time is within the duration" do
+      expect(4.minutes.ago.within?(5.minutes)).to be true
+    end
+
+    it "returns false when a Java time is outside the duration" do
+      expect(6.minutes.ago.within?(5.minutes)).to be false
+    end
+
+    it "works on Ruby times" do
+      expect((Time.now - 240).within?(5.minutes)).to be true
+      expect((Time.now - 360).within?(5.minutes)).to be false
+    end
+
+    it "raises if duration isn't a TemporalAmount" do
+      expect { ZonedDateTime.now.within?(1) }.to raise_error(ArgumentError, /duration must be a TemporalAmount/)
+    end
+  end
+
+  describe "#before?" do
+    it "compares against other time-like objects" do
+      time = ZonedDateTime.parse("2022-11-09T02:09:05+00:00")
+      later = DateTimeType.new("2022-11-09T02:10:05+00:00")
+
+      expect(time.before?(later)).to be true
+      expect(time.before?(time)).to be false
+    end
+  end
+
+  describe "#after?" do
+    it "compares against other time-like objects" do
+      time = ZonedDateTime.parse("2022-11-09T02:09:05+00:00")
+      earlier = Time.parse("2022-11-09T02:08:05+00:00")
+
+      expect(time.after?(earlier)).to be true
+      expect(time.after?(time)).to be false
+    end
+  end
+
+  it "works through DateTimeType delegation" do
+    state = DateTimeType.new(4.minutes.ago)
+
+    expect(state.within?(5.minutes)).to be true
+    expect(state.after?(5.minutes.ago)).to be true
+    expect(state.before?(2.minutes.ago)).to be true
+  end
+end