duration.rb 0.6.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96a11b338ddcec99f2b1b42f0c98b478937688114644edf233bee9b6a894c75d
-  data.tar.gz: 74717586689952c86539c811efbb6c4666b768b9dd2345759b0f4638a7b9b7a7
+  metadata.gz: c8e29deede3e2da3e3291bda645d370df91c119d6b6263c33dfe4c902f927583
+  data.tar.gz: 0166b41b22ce52109bdf30a99a141bd766e18094dbaa0ec7ae55b39a8ead08fa
 SHA512:
-  metadata.gz: 501a0a8bc4e39897ac84e5c3ec1ad346115a68b0a2c6f99b8bd1b7d3622bebe5821ccc8cf058e961c52285920783ef57ce9c0f8ec7bb085cb69f1db3fc4c37d9
-  data.tar.gz: eb816a10954321a09980a31c0cce9409574a556ee958b4500d9cccfdb849813c683279f9c94d239b6d212275e1f08fd4157e092f113d6ef2ba813bbe87e88138
+  metadata.gz: 5587052c84be1c21d2616745be9eb1cdf009dc5877db0b0e2e66ec8eb4983867c67b6a1449e10e27d5ccac61dd5a06629034611171a412edc458ab45ad3da6f1
+  data.tar.gz: 20a868eb602e70efa4dada46349ccbafca1c53e9c9bdc9021a797fb37b286da729c3d4f1a67472a451b06a13b1219bdf3981809e17d15e9f5c7b996f9f27d8a8

data/CHANGELOG

@@ -1,5 +1,15 @@
 # CHANGELOG
 
+## 20260822
+
+0.7.0: + Duration::Common#to_s, #inspect.
+
+1. + Duration::Common#to_s: the quantity and the unit, as "45 days". The unit is the class, so naming it says which duration this is without repeating the class. A quantity of one drops the plural.
+2. + Duration::Common#inspect: the class and the quantity as it is held, as "Duration::Days(45)", after measurand's. Collections call inspect upon their elements, which is where the default ivar-and-address form was most often met. It is the one place an Integer 45 and a Rational 45/1 can be told apart, #to_s rendering both as "45 days".
+3. ~ README.md: the eleven `# =>` comments which render a duration, being what irb prints and so #inspect, brought to the form it now returns. They had shown an approximation of the default, `#<Nanoseconds @nanoseconds=500>`, which was never quite what was printed either; + a Rendering section for #to_s and #inspect.
+4. ~ Duration::VERSION: /0.6.2/0.7.0/
+
+
 ## 20260819
 
 0.6.2: ~ duration.rb.gemspec: spec.files reordered, the globs first.

data/README.md

@@ -64,15 +64,15 @@ minutes reads the files for seconds and minutes and leaves the rest unread.
 ### Basic Duration Creation
 ```ruby
 # Create durations using convenience methods
-500.nanoseconds         # => #<Nanoseconds @nanoseconds=500>
-500.microseconds        # => #<Microseconds @microseconds=500>
-200.milliseconds        # => #<Milliseconds @milliseconds=200>
-1.second                # => #<Seconds @seconds=1>
-30.minutes              # => #<Minutes @minutes=30>
-2.hours                 # => #<Hours @hours=2>
-7.days                  # => #<Days @days=7>
-4.weeks                 # => #<Weeks @weeks=4>
-6.months                # => #<Months @months=6>
+500.nanoseconds         # => Duration::Nanoseconds(500)
+500.microseconds        # => Duration::Microseconds(500)
+200.milliseconds        # => Duration::Milliseconds(200)
+1.second                # => Duration::Seconds(1)
+30.minutes              # => Duration::Minutes(30)
+2.hours                 # => Duration::Hours(2)
+7.days                  # => Duration::Days(7)
+4.weeks                 # => Duration::Weeks(4)
+6.months                # => Duration::Months(6)
 ```
 
 ### Conversions
@@ -83,13 +83,46 @@ minutes reads the files for seconds and minutes and leaves the rest unread.
 
 # Convert between units. The result is exact (a Rational internally) when the
 # input is exact; call to_f at the edge for a float.
-90.minutes.to_hours             # => #<Hours @hours=(3/2)>
+90.minutes.to_hours             # => Duration::Hours((3/2))
 90.minutes.to_hours.to_f        # => 1.5
 1.5.hours.to_minutes.to_i       # => 90
 1.day.to_seconds.to_i           # => 86400
 5.minutes.to_hours.to_f         # => 0.08333333333333333
 ```
 
+### Rendering
+
+`to_s` names the quantity and the unit — the unit being the class, naming it says
+which duration this is without repeating it.
+
+```ruby
+45.days.to_s            # => "45 days"
+1.day.to_s              # => "1 day"
+1.5.hours.to_s          # => "1.5 hours"
+```
+
+The quantity prints as it is held. A Rational which came out whole prints as a whole
+number, and one which did not stays a ratio rather than being expanded into a decimal
+it is not:
+
+```ruby
+45.days.to_weeks.to_s   # => "45/7 weeks"
+90.minutes.to_hours.to_s  # => "3/2 hours"
+```
+
+Call `to_f` where a decimal is wanted, as elsewhere — the rounding happens upon
+request and not before.
+
+`inspect` is the other form: the class and the quantity as it is actually held. It is
+the one place an `Integer` 45 and a `Rational` 45/1 can be told apart, `to_s` rendering
+both as `"45 days"`.
+
+```ruby
+45.days.inspect             # => "Duration::Days(45)"
+45.days.to_weeks.inspect    # => "Duration::Weeks((45/7))"
+{held_for: 45.days}.inspect # => "{held_for: Duration::Days(45)}"
+```
+
 ### Arithmetic and Comparison
 ```ruby
 # Durations add and subtract, with the left operand's unit deciding the result:
@@ -101,7 +134,7 @@ minutes reads the files for seconds and minutes and leaves the rest unread.
 5.minutes == 300.seconds        # => true
 90.seconds > 1.minute           # => true
 [1.hour, 30.seconds, 5.minutes].sort
-                                # => [30.seconds, 5.minutes, 1.hour]
+                                # => [Duration::Seconds(30), Duration::Minutes(5), Duration::Hours(1)]
 
 # Scaled by a number, a duration stays a duration and keeps its unit:
 5.minutes * 3                   # => #<Minutes @minutes=15>

data/lib/Duration/Common.rb

@@ -36,6 +36,24 @@ module Duration
       quantity <=> other.send(:"to_#{unit}").quantity
     end
 
+    # The unit is the class, so naming it says which duration this is without
+    # repeating the class: 45 days rather than #<Duration::Days:0x000... The
+    # quantity is rendered as it is held, an exact Rational staying exact, this
+    # library manufacturing no precision it was not given and discarding none
+    # it was.
+    def to_s
+      "#{rendered_quantity} #{quantity == 1 ? unit.to_s.chomp('s') : unit}"
+    end
+
+    # The class and the quantity as it is actually held, after measurand: to_s
+    # is what a reader wants and inspect is what the object is.  It is the one
+    # place the difference between an Integer 45 and a Rational 45/1 shows,
+    # which in a library this careful about exactness is worth being able to
+    # see.
+    def inspect
+      "#{self.class}(#{quantity.inspect})"
+    end
+
     protected
 
     def quantity
@@ -44,6 +62,13 @@ module Duration
 
     private
 
+    # A Rational which came out whole prints as its numerator, since 45/1 days
+    # says nothing 45 days does not.  A Rational which did not stays a ratio:
+    # 45/7 weeks is what 45 days is, and 6.428571428571429 is not.
+    def rendered_quantity
+      quantity.is_a?(Rational) && quantity.denominator == 1 ? quantity.numerator.to_s : quantity.to_s
+    end
+
     def combine(operator, other)
       unless other.is_a?(Duration::Common)
         raise TypeError, "can't combine #{self.class} with #{other.class}"

data/lib/Duration/VERSION.rb

@@ -1,3 +1,3 @@
 module Duration
-  VERSION = '0.6.2'
+  VERSION = '0.7.0'
 end

data/test/Duration/Common_test.rb

@@ -98,4 +98,58 @@ describe Duration::Common do
       _((1.hour - 50.minutes).to_minutes.to_f).must_equal 10.0
     end
   end
+
+  describe "#to_s" do
+    it "names the quantity and the unit" do
+      _(45.days.to_s).must_equal '45 days'
+      _(500.nanoseconds.to_s).must_equal '500 nanoseconds'
+    end
+
+    it "drops the plural at one" do
+      _(1.day.to_s).must_equal '1 day'
+      _(1.month.to_s).must_equal '1 month'
+    end
+
+    it "keeps a float a float" do
+      _(1.5.hours.to_s).must_equal '1.5 hours'
+    end
+
+    it "prints a whole Rational as a whole number" do
+      _(Duration::Days.new(45r).to_s).must_equal '45 days'
+    end
+
+    it "keeps an exact ratio a ratio rather than expanding it" do
+      # 45 days is exactly 45/7 weeks, and 6.428571428571429 is not.
+      _(45.days.to_weeks.to_s).must_equal '45/7 weeks'
+    end
+
+    it "reads the unit from the class rather than repeating it" do
+      _(90.minutes.to_hours.to_s).must_equal '3/2 hours'
+    end
+  end
+
+  describe "#inspect" do
+    it "names the class and the quantity as held" do
+      _(45.days.inspect).must_equal 'Duration::Days(45)'
+      _(1.5.hours.inspect).must_equal 'Duration::Hours(1.5)'
+    end
+
+    it "carries no address or ivar dump" do
+      _(45.days.inspect).wont_match(/0x|@days/)
+    end
+
+    it "shows an exact quantity as the Rational it is, where to_s does not" do
+      _(45.days.to_weeks.to_s).must_equal '45/7 weeks'
+      _(45.days.to_weeks.inspect).must_equal 'Duration::Weeks((45/7))'
+    end
+
+    it "distinguishes a whole Rational from an Integer, where to_s cannot" do
+      _(Duration::Days.new(45r).to_s).must_equal 45.days.to_s
+      _(Duration::Days.new(45r).inspect).wont_equal 45.days.inspect
+    end
+
+    it "reaches a duration held inside a collection" do
+      _({held_for: 45.days}.inspect).must_equal '{held_for: Duration::Days(45)}'
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: duration.rb
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.7.0
 platform: ruby
 authors:
 - thoran