duration.rb 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f7d0f0552f3ce6cb16fd75947bad208ccf403bd8e572b23ae262d4b6aada58f
-  data.tar.gz: 7423385510fa2bb3769521892430705fb036eb12b1a40c276a9b4b5445b7bc94
+  metadata.gz: b6ba0b1a782117f5c6f5b7798620456110e617f5cf2f59ccedd45845cab01674
+  data.tar.gz: aa225e9b5369e6f334fc0a0962e57cb64c5a6ead3008d91fcbc74448c91fba2e
 SHA512:
-  metadata.gz: be48eabdcaddff69c28452886f068623646af55255ea06f17809e38b2fafd0c343ccc7592478952bb1a7879ef60b10433ad074fbbfa0d47ee0c54405b0066723
-  data.tar.gz: 852569a9d5a66c7e576c9c33310c549e6846e369bf934da1eae13d9c54a343a9c6bc06e0dcdbb5da12768fc24f0feabf9c20a1c1b0d3c405b6a40b7f299d9af3
+  metadata.gz: '045846aba621660eabc73c4115457a15e5f3838a0ba8fcced57fa5381c20ce68cc73ea64b51c2acf1d5bfbe7efc3c36c4854c41f019e9d156eb2687826ad4a4a'
+  data.tar.gz: d0f3455bd9631c7f423151f3aa14fc1a0b4f9bca264a4fe83ad56e535404e4d48b246af457814d5077f429ccfcc064b3f376d9bf649995fe1abff71301d9a349

data/CHANGELOG

@@ -1,5 +1,26 @@
 # CHANGELOG
 
+## 20260812
+
+0.5.1: + VERSION test.
+
+1. + test/Duration/VERSION_test.rb: Ensure that VERSION is a string, that it has three dotted numbers, and that it matches the newest entry in the CHANGELOG. A release edits both files and this now ensure that one moves with the other.
+2. + .gitignore
+3. ~ README.md: /Months is slated for removal in 0.5.0/Months is therefore slated for removal/, 0.5.0 having been and gone with Months still in place.
+4. ~ Duration::VERSION: /0.5.0/0.5.1/
+
+
+## 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
@@ -124,8 +138,8 @@ the calendar. Its conversions use the Gregorian mean month (2629746 seconds),
 so they are honest only as a statistical average, never as calendar-correct
 arithmetic. Its `ago`/`hence` inherit this — they displace by the mean month,
 so they are approximate rather than calendar-correct; reach for a
-calendar-anchored type such as `month.rb` when that matters. `Months` is slated
-for removal in 0.5.0.
+calendar-anchored type such as `month.rb` when that matters. `Months` is
+therefore slated for removal.
 
 ## Contributing
 

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.1'
 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

data/test/Duration/VERSION_test.rb

@@ -0,0 +1,22 @@
+# test/duration/version_test.rb
+
+require_relative '../test_helper'
+
+# Note that VERSION.rb is the one file duration.rb requires rather than autoloaded, because an autoloaded file goes unread until its constant is named and nothing else here names this one.
+
+describe Duration do
+  describe "VERSION" do
+    it "is a string" do
+      _(Duration::VERSION).must_be_instance_of String
+    end
+
+    it "is three numbers separated by dots" do
+      _(Duration::VERSION).must_match(/\A\d+\.\d+\.\d+\z/)
+    end
+
+    it "matches the newest entry in the CHANGELOG" do
+      changelog = File.read(File.expand_path('../../CHANGELOG', __dir__))
+      _(changelog[/^(\d+\.\d+\.\d+):/, 1]).must_equal Duration::VERSION
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: duration.rb
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.1
 platform: ruby
 authors:
 - thoran
@@ -87,6 +87,7 @@ files:
 - test/Duration/Nanoseconds_test.rb
 - test/Duration/Numeric_test.rb
 - test/Duration/Seconds_test.rb
+- test/Duration/VERSION_test.rb
 - test/Duration/Weeks_test.rb
 - test/test_helper.rb
 homepage: http://github.com/thoran/duration.rb
@@ -107,7 +108,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: []