duration.rb 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f7d0f0552f3ce6cb16fd75947bad208ccf403bd8e572b23ae262d4b6aada58f
-  data.tar.gz: 7423385510fa2bb3769521892430705fb036eb12b1a40c276a9b4b5445b7bc94
+  metadata.gz: 9e8c196994e5358c6875d3ee17471f379cf8cffe2fa9924856729a6fc64c88d0
+  data.tar.gz: de2a825ddec433cb81b9797015833a61eac8b5548166b592686623f86cc9101a
 SHA512:
-  metadata.gz: be48eabdcaddff69c28452886f068623646af55255ea06f17809e38b2fafd0c343ccc7592478952bb1a7879ef60b10433ad074fbbfa0d47ee0c54405b0066723
-  data.tar.gz: 852569a9d5a66c7e576c9c33310c549e6846e369bf934da1eae13d9c54a343a9c6bc06e0dcdbb5da12768fc24f0feabf9c20a1c1b0d3c405b6a40b7f299d9af3
+  metadata.gz: e47937b8086f02fd9ab15d4444bc9b9f38c7d7b01e8948c99c500adfaef01697ea17d8898c93cc727b8961610f904810e3aaeb9da00aa762fbee4a1ffd25ed57
+  data.tar.gz: 17f71a43aa5680b73bc5ca532e2c172964cf988d74668b2bfa253105c4b46d31a34810e9ee31ff37a0e85d36a91df42fd39194394c7429186ddff34afb1274b1

data/CHANGELOG

@@ -1,5 +1,16 @@
 # CHANGELOG
 
+## 20260811
+
+0.5.0: + Multiplication and division, and with them the dimensionless ratio.
+
+1. + Duration::Common#*: a duration times a number is a duration, in the receiver's own unit as the rest of the arithmetic is. A duration times a duration raises TypeError, there being no unit of time squared: refused rather than quietly given some plausible answer.
+2. + Duration::Common#/: divided by a number a duration stays a duration; divided by a duration it becomes the dimensionless ratio of the two, the units having cancelled. That ratio is the shape of a rate or a speedup, and until now it could not be written at all: a timing had to be dropped back to a bare number before it could be divided, which is the point at which its unit is lost.
+3. + Duration::Common#scale and #ratio, private, being the two halves of what #* and #/ mean. Division goes through Numeric#quo rather than #/, so that an Integer quantity divides exactly: 1.quo(3) is (1/3) where 1 / 3 is 0. A Float quantity stays a Float, this library manufacturing no precision it was not given.
+4. + test/Duration/Common_test.rb: multiplication and division, including that 1.second / 3 holds a third rather than nothing, that 1.hour / 30.minutes is 2, and that 1.second / 3.milliseconds is exactly 1000/3.
+5. ~ Duration::VERSION: /0.4.0/0.5.0/
+
+
 ## 20260718
 
 0.4.0: + Nanoseconds and Microseconds, arithmetic and comparison, exact conversions without a base, and the Numeric monkeypatch made opt-in.

data/README.md

@@ -98,6 +98,20 @@ The examples below use the `Numeric` sugar, so they assume
 90.seconds > 1.minute           # => true
 [1.hour, 30.seconds, 5.minutes].sort
                                 # => [30.seconds, 5.minutes, 1.hour]
+
+# Scaled by a number, a duration stays a duration and keeps its unit:
+5.minutes * 3                   # => #<Minutes @minutes=15>
+1.hour / 4                      # => #<Hours @hours=(1/4)>
+1.second / 3                    # => #<Seconds @seconds=(1/3)>  (not 0)
+
+# Divided by a duration, the units cancel and a plain number is left. It is a
+# Rational when both quantities are exact, as Numeric#quo gives, so it compares
+# and calculates as the number it is; call to_f at the edge.
+1.hour / 30.minutes             # => (2/1)
+1.second / 3.milliseconds       # => (1000/3)
+
+# There is no unit of time squared, so this is refused rather than answered:
+5.minutes * 3.minutes           # => TypeError
 ```
 
 ### Time Calculations

data/lib/Duration/Common.rb

@@ -13,6 +13,24 @@ module Duration
       combine(:-, other)
     end
 
+    # A duration times a number is a duration.  A duration times a duration
+    # would be time squared, which has no unit here and few enough anywhere, so
+    # it is refused rather than quietly given some plausible answer.
+    def *(other)
+      if other.is_a?(Duration::Common)
+        raise TypeError, "can't multiply #{self.class} by #{other.class}: there is no unit of time squared"
+      end
+      scale(:*, other)
+    end
+
+    # Divided by a number a duration stays a duration.  Divided by a duration it
+    # becomes the dimensionless ratio of the two, the units having cancelled,
+    # which is how a rate or a speedup is arrived at.
+    def /(other)
+      return ratio(other) if other.is_a?(Duration::Common)
+      scale(:quo, other)
+    end
+
     def <=>(other)
       return nil unless other.is_a?(Duration::Common)
       quantity <=> other.send(:"to_#{unit}").quantity
@@ -32,5 +50,19 @@ module Duration
       end
       self.class.new(quantity.send(operator, other.send(:"to_#{unit}").quantity))
     end
+
+    # Division goes through #quo rather than #/ so that an Integer quantity
+    # divides exactly: 1.quo(3) is (1/3) where 1 / 3 is 0.  A Float quantity
+    # stays a Float, this library manufacturing no precision it was not given.
+    def scale(operator, other)
+      unless other.is_a?(Numeric)
+        raise TypeError, "can't scale #{self.class} by #{other.class}"
+      end
+      self.class.new(quantity.send(operator, other))
+    end
+
+    def ratio(other)
+      quantity.quo(other.send(:"to_#{unit}").quantity)
+    end
   end
 end

data/lib/Duration/VERSION.rb

@@ -1,3 +1,3 @@
 module Duration
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

data/test/Duration/Common_test.rb

@@ -30,6 +30,46 @@ describe Duration::Common do
     end
   end
 
+  describe "multiplication" do
+    it "scales a duration by a number, keeping the unit" do
+      result = 5.minutes * 3
+      _(result).must_be_instance_of Duration::Minutes
+      _(result.to_i).must_equal 15
+    end
+
+    it "raises upon a duration, there being no unit of time squared" do
+      _{5.minutes * 3.minutes}.must_raise TypeError
+    end
+
+    it "raises upon a non-numeric" do
+      _{5.minutes * "3"}.must_raise TypeError
+    end
+  end
+
+  describe "division" do
+    it "scales a duration by a number, keeping the unit" do
+      result = 1.hour / 4
+      _(result).must_be_instance_of Duration::Hours
+      _(result.to_minutes.to_f).must_equal 15.0
+    end
+
+    it "divides exactly rather than as integers" do
+      _(1.second / 3).must_equal Duration::Seconds.new(Rational(1, 3))
+    end
+
+    it "returns the dimensionless ratio of two durations" do
+      _(1.hour / 30.minutes).must_equal 2
+    end
+
+    it "takes the ratio across units exactly" do
+      _(1.second / 3.milliseconds).must_equal Rational(1000, 3)
+    end
+
+    it "raises upon a non-numeric" do
+      _{5.minutes / "3"}.must_raise TypeError
+    end
+  end
+
   describe "comparison" do
     it "compares durations of different units exactly" do
       _(5.minutes).must_equal 300.seconds

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: duration.rb
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - thoran
@@ -107,7 +107,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.18
 specification_version: 4
 summary: Objects for handling durations of time.
 test_files: []