monotonic.rb 0.7.3 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ed52df8a021bca41cae021d5b11408c8bd6b0fc80025a46a56b688cafa4fcdc
-  data.tar.gz: c45841b92c1da76259799f4c6c55ba9a540b9b25464acd82560f30a2c10e9234
+  metadata.gz: 735b3915ec7e7b95ef1fde8effe2d2723fea5eb027f9af87d1bea9dc8552048a
+  data.tar.gz: 8497225d7afb17a9e6c5f1c6a7c79510986fc74f731c81c06c4b0529ca1fa1d1
 SHA512:
-  metadata.gz: 4cf743fb3e9303efe1439f0532462045525b1439523bce53cfc96f293df4da5d33a94676e1b71e995cb908b29cb8295470111dc7857d6712e569ca348a45f6f6
-  data.tar.gz: 739e6a9032050231fdc5f761a6581a70aded2512981f7cf9e34e6774a43215e87db9d3911c6aec214269ac1a08282ef5933920e2121ab11119f6b0c34f5ef0a1
+  metadata.gz: a9a637b1664afe2b51d8b2f6abedace3e2dd6faf150d5767da5a6add304acba0554db879f72f16867856219eee41da3ed1042418e832a76722928dea62e27511
+  data.tar.gz: fed34f80416fa88c2b31fce83a9f21576a62d678c74ca0202bedf550149842de31cd121e55cec8f377f1354b4748cd4f818333b9aed726d778310630f9c8854b

data/CHANGELOG

@@ -1,5 +1,30 @@
 # CHANGELOG
 
+## 20260816
+
+0.8.0: Use duration.rb gem.
+
+1. + duration.rb as a dependency, constrained to >= 0.4.0 where sys-uptime is unconstrained. Units and the arithmetic between them are its business, and were being hand-rolled here. 0.4.0 is where Duration::Nanoseconds arrived, which this gem names, and is the true minimum rather than a guess: the whole API used here exercises clean against it, and everything between is additive.
+2. ~ monotonic.rb.gemspec: spec.dependencies takes a name and a requirement as well as a bare name, the splat in #dependencies= already allowing for it. sys-uptime stays unconstrained as before.
+3. - Monotonic::NANOSECONDS_PER_SECOND, introduced at 0.7.0 and by now divided by in four places. It existed only because the conversion was hand-rolled; a duration converts by exact ratios and stays a Rational until to_f is asked for, where the constant dropped to Float a step early.
+4. + Monotonic::Timer#to_duration, being a Duration::Nanoseconds. An elapsed interval is a duration, and every unit follows from this one exactly.
+5. ~ Monotonic::Timer#total_time: derived from #to_duration. It returns a Float of seconds as before.
+6. ~ Monotonic::Time#seconds_since_boot: converted by a duration rather than by division. It returns a Float as before.
+7. ~ BREAKING: Monotonic::Time#- returns a Duration::Nanoseconds where it returned a Float of seconds. The difference of two instants is a duration, and that is the reason a monotonic clock is read at all. Given a duration instead it returns the earlier instant.
+8. ~ BREAKING: Monotonic::Time#+ takes a Duration and returns a later Monotonic::Time. Given another instant it raises TypeError, where it formerly returned the sum of two seconds-since-boot figures: a quantity which moves when the epoch moves is not a quantity, and the README demonstrated it producing 2417598.681896, which was nothing at all. Ruby's own Time raises upon time + time for the same reason.
+9. ~ Monotonic::Time#initialize takes an optional nanoseconds-since-boot, defaulting to the clock, so that #+ and #- can answer with an instant other than now.
+10. ~ lib/Monotonic/Timer.rb: the constants moved above the methods, CLOCK no longer following .clock_name. + Monotonic::Timer::CLOCK_NAMES, declaring what would be accepted and in what order, so that CLOCK derives from it rather than from a method and need not come after one.
+11. ~ test/Monotonic/Time_test.rb: #+ and #- rewritten for the arithmetic above, including that an instant plus an instant raises and a bare number is refused.
+12. + test/Monotonic/Timer_test.rb: #to_duration, that it carries the same figure as #total_nanoseconds and converts to the same seconds as #total_time.
+13. ~ test/gemspec_test.rb: the runtime dependency list.
+14. ~ README.md: + what belongs to duration.rb and why, and the usage for the arithmetic and #to_duration.
+15. ~ Monotonic::Time#+ and #-: dispatch upon what the argument answers to rather than upon its class. One question tells the two cases apart — does this know where it sits since boot? — and it is asked of the object: an instant subtracts to a duration, and anything converting to nanoseconds shifts the instant. The refusal of instant plus instant is asked of the same duck, since leaving it to Monotonic::Time happening not to answer #to_nanoseconds would be an accident rather than a rule. A bare number still raises TypeError, the guard asking respond_to? rather than is_a?: duck typing forbids asking after a class, not asking after a capability. Ruby raises TypeError for an unsuitable operand throughout — Time, Integer, Float, Rational — and NoMethodError is a NameError, the family meaning that something named does not exist, where here the caller named #- which does. The message carries the protocol a duck must satisfy, so nothing is lost by not letting it escape. The parameters are named for their arithmetic role rather than for a type: /monotonic_time_addend/addend/ and /monotonic_time_subtrahend/subtrahend/, the type half of each having been an unenforced claim in any case, the old #- never having checked what it was given.
+16. + Monotonic::Timer#initialize takes instants:, defaulting to nil, which reads the clock directly as before. Supplied with Monotonic::Time it times upon CLOCK_MONOTONIC instead: coarser, at 1000ns against 42ns, but placeable against the wall clock through #to_time. Anything answering .now will do. This is what 0.7.0 took away without saying so, Timer having read Monotonic::Time as its substrate since 0.1.0 until the two took different clocks — and it could not be given back before now, Monotonic::Time#- having answered with a bare Float of seconds until this release, so that an interval taken from it would have been reported as nanoseconds and been wrong by a factor of a billion.
+17. ~ Monotonic::Timer#total_nanoseconds asks the elapsed figure to say itself in nanoseconds where it can, a raw difference already being in them and an instant's difference being a duration.
+18. + test/Monotonic/Timer_test.rb: which source is read, that either answers in nanoseconds, and that a supplied source times upon its own clock, the figure falling upon a multiple of that clock's resolution.
+19. ~ Monotonic::VERSION: /0.7.3/0.8.0/
+
+
 ## 20260816
 
 0.7.3: Require Monotonic::Time from the gem, and stop every instant fetching the boot time.
@@ -13,7 +38,6 @@
 7. + .gitignore: the standard list, as duration.rb and namo carry verbatim, in place of the three lines here. It is not among spec.files, so nothing in the published gem changes by it.
 8. ~ Monotonic::VERSION: /0.7.2/0.7.3/
 
-
 ## 20260812
 
 0.7.2: + gemspec test.

data/README.md

@@ -14,35 +14,46 @@ Which clock is read follows from that. `Monotonic::Timer` measures intervals and
 How finely a clock advances is the platform's business and not this library's to claim, so it is asked rather than tabulated:
 
 ```ruby
-  Monotonic::Timer.resolution
-  # => 42
-  Monotonic::Time.resolution
-  # => 1000
+Monotonic::Timer.resolution
+# => 42
+Monotonic::Time.resolution
+# => 1000
 ```
 
-A reading is denominated in nanoseconds whether or not the clock affords them, so that is the method which says what a reading is worth. Two figures give the sense of it upon the finer clock: reading it costs about 34ns against the 42ns it takes to advance, the two being close enough that there is little to be had by going finer, and a pair of `Float`s would not begin to lose it until some six years of uptime — but they would begin.
+A reading is denominated in nanoseconds whether or not the clock affords it, so that is the method which says what a reading is worth. Two figures give the sense of it upon the finer clock: reading it costs about 34ns against the 42ns it takes to advance, the two being close enough that there is little to be had by going finer, and a pair of `Float`s would not begin to lose it until some six years of uptime — but they would begin.
+
+Units and the arithmetic between them belong to [duration.rb](https://github.com/thoran/duration.rb), which this gem depends upon rather than reimplementing. An elapsed interval is a duration, so `Monotonic::Timer#to_duration` hands one back and every unit follows from it exactly, a Rational until `to_f` is asked for. An instant is not a duration: `Monotonic::Time#-` gives the duration between two instants, `#+` takes a duration and gives a later instant, and adding one instant to another raises — a quantity which moves when you move the epoch is not a quantity, and Ruby's own `Time` refuses it for the same reason.
 
 What `Monotonic::Time` is for follows from that. It is the point type: `Monotonic::Timer` used it as its own substrate until 0.7.0, when the two took different clocks, and what remains to it is what a point is good for — the difference of two instants, which is the reason a monotonic clock is read at all, and `#to_time`, which places one against the wall clock by way of the boot time.
 
+Where a timing is taken from can be chosen. `Monotonic::Timer.new` reads the clock directly, as it always has and much the cheapest; `Monotonic::Timer.new(instants: Monotonic::Time)` times upon `CLOCK_MONOTONIC` instead, coarser but placeable against the wall clock. Anything answering `.now` will do.
+
+```ruby
+timer = Monotonic::Timer.new(instants: Monotonic::Time)
+timer.start; sleep 0.002; timer.stop
+timer.total_nanoseconds
+# => 2508000, upon a clock which ticks in whole microseconds
+```
+
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-  gem 'monotonic.rb'
+gem 'monotonic.rb'
 ```
 
 And then execute:
 
 ```bash
-  $ bundle install
+$ bundle install
 ```
 
 Or install it yourself as:
 
 ```bash
-  $ gem install monotonic.rb
+$ gem install monotonic.rb
 ```
 
 
@@ -51,74 +62,92 @@ Or install it yourself as:
 ### Monotonic::Time
 
 ```ruby
-  require 'monotonic.rb'
-  monotonic_time = Monotonic::Time.new
-  monotonic_time.nanoseconds_since_boot
-  # => 2614365376498000
-  monotonic_time.seconds_since_boot
-  # => 1208799.325906
-  monotonic_time + Monotonic::Time.now
-  # => 2417598.681896
-  monotonic_time - Monotonic::Time.now
-  # => -0.044104999862611294
-  monotonic_time.to_s
-  # => "1164320.268127 seconds since boot."
-  monotonic_time.to_time
-  # => 2021-06-07 09:27:08 8249692651179/8388608000000 +1000
+require 'monotonic.rb'
+
+monotonic_time = Monotonic::Time.new
+monotonic_time.nanoseconds_since_boot
+# => 2614365376498000
+
+monotonic_time.seconds_since_boot
+# => 1208799.325906
+
+monotonic_time + Duration::Seconds.new(30)
+# => #<Monotonic::Time>, thirty seconds later
+
+Monotonic::Time.now - monotonic_time
+# => #<Duration::Nanoseconds @nanoseconds=44104999>
+
+monotonic_time + Monotonic::Time.now
+# => TypeError: an instant plus an instant is not an instant
+
+monotonic_time.to_s
+# => "1164320.268127 seconds since boot."
+
+monotonic_time.to_time
+# => 2021-06-07 09:27:08 8249692651179/8388608000000 +1000
 ```
 
 ### Monotonic::Timer without a block
 
 ```ruby
-  require 'monotonic.rb'
-  timer = Monotonic::Timer.new
-  timer.start
-  i = 0
-  1_000_000.times{puts i += 1}
-  timer.stop
-  timer.total_nanoseconds
-  # => 27734000
-  timer.total_time
-  # => 7.166559999808669
+require 'monotonic.rb'
+
+timer = Monotonic::Timer.new
+timer.start
+i = 0
+1_000_000.times{puts i += 1}
+timer.stop
+timer.total_nanoseconds
+# => 27734000
+
+timer.to_duration
+# => #<Duration::Nanoseconds @nanoseconds=27734000>
+
+timer.to_duration.to_microseconds.to_f
+# => 27734.0
+
+timer.total_time
+# => 0.027734
 ```
 
 ### Monotonic::Timer with a block
 
 ```ruby
-  require 'monotonic.rb'
-  time = Monotonic::Timer.time do
-    i = 0
-    1_000_000.times{puts i += 1}
-  end
-  time
-  # => 6.975823000073433
+require 'monotonic.rb'
+
+time = Monotonic::Timer.time do
+  i = 0
+  1_000_000.times{puts i += 1}
+end
+time
+# => 6.975823000073433
 ```
 
 ### Monotonic::Timer with a block and block variable
 
 ```ruby
-  require 'monotonic.rb'
-  time = Monotonic::Timer.time do |timer|
-    i = 0
-    500_000.times{puts i += 1}
-    p timer.total_time
-    500_000.times{puts i += 1}
-  end
-  time
-  # => 6.975823000073433
+require 'monotonic.rb'
+time = Monotonic::Timer.time do |timer|
+  i = 0
+  500_000.times{puts i += 1}
+  p timer.total_time
+  500_000.times{puts i += 1}
+end
+time
+# => 6.975823000073433
 ```
 
 ### Monotonic::Timer with a block on a timer instance
 
 ```ruby
-  require 'monotonic.rb'
-  timer = Monotonic::Timer.new
-  time = timer.time do
-    i = 0
-    1_000_000.times{puts i += 1}
-  end
-  time
-  # => 7.033131000120193
+require 'monotonic.rb'
+timer = Monotonic::Timer.new
+time = timer.time do
+  i = 0
+  1_000_000.times{puts i += 1}
+end
+time
+# => 7.033131000120193
 ```
 
 

data/lib/Monotonic/Time.rb

@@ -1,22 +1,23 @@
 # Monotonic/Time.rb
 # Monotonic::Time
 
+require 'duration.rb'
 require 'sys-uptime'
 
 module Monotonic
-  NANOSECONDS_PER_SECOND = 1_000_000_000
-
   class Time
+    # An instant, which #to_time maps back onto the wall clock by way of the
+    # boot time, so the clock wanted here is the one which tracks time since
+    # boot as the wall clock understands it.  That is CLOCK_MONOTONIC, sleep and
+    # all.  Monotonic::Timer measures intervals rather than instants and chooses
+    # a finer clock of its own.
+    #
+    # Unlike Timer's, this one is chosen rather than found, there being no
+    # alternative which would still answer to #to_time.  .clock_name is a method
+    # all the same, so that the two classes answer the question alike.
+    CLOCK = Process::CLOCK_MONOTONIC
+
     class << self
-      # An instant, which #to_time maps back onto the wall clock by way of the
-      # boot time, so the clock wanted here is the one which tracks time since
-      # boot as the wall clock understands it.  That is CLOCK_MONOTONIC, sleep
-      # and all.  Monotonic::Timer measures intervals rather than instants and
-      # chooses a finer clock of its own.
-      #
-      # Unlike Timer's, this one is chosen rather than found, there being no
-      # alternative which would still answer to #to_time.  It is a method all
-      # the same, so that the two classes answer the question alike.
       def clock_name
         :CLOCK_MONOTONIC
       end
@@ -25,27 +26,14 @@ module Monotonic
         self.new
       end
 
-      # Invariant for the life of the process, coming from kern.boottime, which
-      # does not move.  It was asked afresh upon every instance and cost 1740ns
-      # of the 1947ns an instant took to make.
-      def boot_time
-        @boot_time ||= Sys::Uptime.boot_time
-      end
-
       # How finely this clock advances, in nanoseconds.  It is asked rather than
       # tabulated, being a property of the processor and the operating system
       # and not of this library: upon macOS CLOCK_MONOTONIC answers 1000 here.
-      # A reading is denominated in nanoseconds whatever the answer, so this is
-      # the method which says what a reading is worth.
       def resolution
         Process.clock_getres(CLOCK, :nanosecond)
       end
     end # class << self
 
-    # Read upon every instance, so a constant rather than a lookup.  It follows
-    # .clock_name, and so must come after it.
-    CLOCK = Process.const_get(clock_name)
-
     attr_reader :nanoseconds_since_boot
 
     # The clock is read in nanoseconds because it answers there with an Integer,
@@ -53,19 +41,45 @@ module Monotonic
     # Seconds are derived rather than read, so that the reading loses nothing and
     # the rounding happens where it is asked for.
     def seconds_since_boot
-      @nanoseconds_since_boot / NANOSECONDS_PER_SECOND.to_f
+      Duration::Nanoseconds.new(@nanoseconds_since_boot).to_seconds.to_f
     end
 
-    def initialize
-      @nanoseconds_since_boot = Process.clock_gettime(CLOCK, :nanosecond)
+    def initialize(nanoseconds_since_boot = Process.clock_gettime(CLOCK, :nanosecond))
+      @nanoseconds_since_boot = nanoseconds_since_boot
     end
 
-    def +(monotonic_time_addend)
-      seconds_since_boot + monotonic_time_addend.seconds_since_boot
+    # One question tells the two cases apart, and it is asked of the object
+    # rather than of its class: does this know where it sits since boot?  If it
+    # does it is an instant, and if it converts to nanoseconds it is a duration.
+    # Nothing here names a class, so anything answering the same messages will
+    # do.
+    #
+    # An instant plus a duration is an instant.  An instant plus an instant is
+    # nothing at all: it depends upon where the epoch was arbitrarily put, and a
+    # quantity which moves when you move the origin is not a quantity.  Ruby's
+    # own Time refuses it, with "time + time?", and so does this.  The refusal is
+    # asked of the duck too, since leaving it to Monotonic::Time happening not to
+    # answer #to_nanoseconds would be an accident rather than a rule.
+    def +(addend)
+      if addend.respond_to?(:nanoseconds_since_boot)
+        raise TypeError, "can't add #{addend.class} to #{self.class}: an instant plus an instant is not an instant"
+      end
+      unless addend.respond_to?(:to_nanoseconds)
+        raise TypeError, "can't add #{addend.class} to #{self.class}: expected something answering to #to_nanoseconds"
+      end
+      self.class.new(@nanoseconds_since_boot + addend.to_nanoseconds.to_i)
     end
 
-    def -(monotonic_time_subtrahend)
-      seconds_since_boot - monotonic_time_subtrahend.seconds_since_boot
+    # Minus an instant it is the duration between them; minus a duration it is
+    # the earlier instant.  The first is why a monotonic clock is read at all.
+    def -(subtrahend)
+      if subtrahend.respond_to?(:nanoseconds_since_boot)
+        Duration::Nanoseconds.new(@nanoseconds_since_boot - subtrahend.nanoseconds_since_boot)
+      elsif subtrahend.respond_to?(:to_nanoseconds)
+        self.class.new(@nanoseconds_since_boot - subtrahend.to_nanoseconds.to_i)
+      else
+        raise TypeError, "can't subtract #{subtrahend.class} from #{self.class}: expected an instant, or something answering to #to_nanoseconds"
+      end
     end
 
     def to_s

data/lib/Monotonic/Timer.rb

@@ -1,23 +1,28 @@
 # Monotonic/Timer.rb
 # Monotonic::Timer
 
-require_relative './Time'
+require 'duration.rb'
 
 module Monotonic
   class Timer
+    # An interval is not an instant, and wants a different clock.  Upon Darwin
+    # CLOCK_UPTIME_RAW advances in some 42ns against the 1000ns of
+    # CLOCK_MONOTONIC, and holds while the machine sleeps, which is the right
+    # answer for a timed block: a closed lid is not execution.  Linux has no such
+    # clock, but its CLOCK_MONOTONIC already holds while suspended and advances
+    # finely, so the fallback carries the same meaning and not merely the same
+    # name.  This is what would be accepted, in order; which of them exists is
+    # the platform's business, and .clock_name reports what was found.
+    CLOCK_NAMES = %i[CLOCK_UPTIME_RAW CLOCK_MONOTONIC]
+
+    # Read twice upon every measurement, against a floor of some tens of
+    # nanoseconds, so this is the one place here where a constant is worth the
+    # rigidity: a method call would be a measurable part of what it measures.
+    CLOCK = Process.const_get(CLOCK_NAMES.find{|name| Process.const_defined?(name)})
+
     class << self
-      # An interval is not an instant, and wants a different clock.  Upon Darwin
-      # CLOCK_UPTIME_RAW advances in some 42ns against the 1000ns of
-      # CLOCK_MONOTONIC, and holds while the machine sleeps, which is the right
-      # answer for a timed block: a closed lid is not execution.  Linux has no
-      # such clock, but its CLOCK_MONOTONIC already holds while suspended and
-      # advances finely, so the fallback carries the same meaning and not merely
-      # the same name.
-      #
-      # Which clocks exist is the platform's business, so this is asked rather
-      # than declared, as .resolution is.
       def clock_name
-        @clock_name ||= %i[CLOCK_UPTIME_RAW CLOCK_MONOTONIC].find{|name| Process.const_defined?(name)}
+        @clock_name ||= CLOCK_NAMES.find{|name| Process.const_defined?(name)}
       end
 
       def time(&block)
@@ -33,11 +38,20 @@ module Monotonic
       end
     end # class << self
 
-    # Read twice upon every measurement, against a floor of some tens of
-    # nanoseconds, so this is the one place here where a constant is worth the
-    # rigidity: a method call would be a measurable part of what it measures.
-    # It follows .clock_name, and so must come after it.
-    CLOCK = Process.const_get(clock_name)
+    # Where the instants come from.  Nothing supplied means the clock is read
+    # directly, which is what this has always done and is much the cheapest: a
+    # raw reading costs some 57ns against the 171ns of making a Monotonic::Time,
+    # and two are taken per measurement.
+    #
+    # Supplying Monotonic::Time times upon CLOCK_MONOTONIC instead — coarser, at
+    # 1000ns against 42ns, but it maps back onto the wall clock, so a timing can
+    # be placed as well as measured.  Anything answering .now will do, its
+    # instants needing only to subtract to something which can say itself in
+    # nanoseconds.  That is what 0.7.0 took away without saying so, Timer having
+    # read Monotonic::Time until the two took different clocks.
+    def initialize(instants: nil)
+      @instants = instants
+    end
 
     def start
       @finish_nanoseconds = nil
@@ -51,12 +65,26 @@ module Monotonic
     # Two exact integers differenced, which spends none of the reading.  A pair
     # of Floats would not begin to lose the clock at this resolution until some
     # six years of uptime, but they would begin.
+    #
+    # Raw readings difference to nanoseconds already.  Instants difference to
+    # whatever their own subtraction gives, so it is asked to say itself in
+    # nanoseconds — which is why this could not be done before 0.8.0, where
+    # Monotonic::Time#- began answering with a duration rather than a bare Float
+    # of seconds.
     def total_nanoseconds
-      finish_nanoseconds - @start_nanoseconds
+      elapsed = finish_nanoseconds - @start_nanoseconds
+      elapsed.respond_to?(:to_nanoseconds) ? elapsed.to_nanoseconds.to_i : elapsed
+    end
+
+    # An elapsed interval is a duration, so here is one, and every unit follows
+    # from it exactly.  #total_time is the same figure in seconds, that being
+    # the unit this library has always answered in.
+    def to_duration
+      Duration::Nanoseconds.new(total_nanoseconds)
     end
 
     def total_time
-      total_nanoseconds / NANOSECONDS_PER_SECOND.to_f
+      to_duration.to_seconds.to_f
     end
 
     def time
@@ -77,7 +105,7 @@ module Monotonic
     end
 
     def now
-      Process.clock_gettime(CLOCK, :nanosecond)
+      @instants ? @instants.now : Process.clock_gettime(CLOCK, :nanosecond)
     end
   end
 end

data/lib/Monotonic/VERSION.rb

@@ -2,5 +2,5 @@
 # Monotonic::VERSION
 
 module Monotonic
-  VERSION = '0.7.3'
+  VERSION = '0.8.0'
 end

data/monotonic.rb.gemspec

@@ -35,9 +35,10 @@ Gem::Specification.new do |spec|
     Dir['test/**/*.rb'],
   ].flatten
 
-  spec.dependencies = %w{
-    sys-uptime
-  }
+  spec.dependencies = [
+    ['duration.rb', '>= 0.4.0'],
+    'sys-uptime'
+  ]
 
   spec.development_dependencies = %w{
     minitest

data/test/Monotonic/Time_test.rb

@@ -55,14 +55,35 @@ describe Monotonic::Time do
   end
 
   describe "#+" do
-    it "returns an instance of string" do
-      expect((subject + Monotonic::Time.now).class).must_equal(Float)
+    it "returns a later instant when given a duration" do
+      expect((subject + Duration::Seconds.new(5)).class).must_equal(Monotonic::Time)
+    end
+
+    it "advances by exactly that duration" do
+      expect((subject + Duration::Seconds.new(5)).nanoseconds_since_boot - subject.nanoseconds_since_boot) \
+        .must_equal(5_000_000_000)
+    end
+
+    it "refuses another instant, there being no such quantity" do
+      expect{subject + Monotonic::Time.now}.must_raise(TypeError)
+    end
+
+    it "refuses a bare number, which has no unit" do
+      expect{subject + 5}.must_raise(TypeError)
     end
   end
 
   describe "#-" do
-    it "returns an instance of time" do
-      expect((subject - Monotonic::Time.now).class).must_equal(Float)
+    it "returns the duration between two instants" do
+      expect((subject - Monotonic::Time.now).class).must_equal(Duration::Nanoseconds)
+    end
+
+    it "returns an earlier instant when given a duration" do
+      expect((subject - Duration::Seconds.new(5)).class).must_equal(Monotonic::Time)
+    end
+
+    it "refuses a bare number, which has no unit" do
+      expect{subject - 5}.must_raise(TypeError)
     end
   end
 

data/test/Monotonic/Timer_test.rb

@@ -128,6 +128,57 @@ describe Monotonic::Timer do
     end
   end
 
+  context "where the instants come from" do
+    it "reads the clock directly when nothing is supplied" do
+      timer = Monotonic::Timer.new
+      timer.start
+      timer.stop
+      expect(timer.total_nanoseconds.class).must_equal(Integer)
+    end
+
+    it "takes them from whatever is supplied, in nanoseconds still" do
+      timer = Monotonic::Timer.new(instants: Monotonic::Time)
+      timer.start
+      sleep 0.01
+      timer.stop
+      expect(timer.total_nanoseconds.class).must_equal(Integer)
+      expect(timer.total_nanoseconds).must_be :>, 5_000_000
+    end
+
+    it "times upon that source's clock rather than its own" do
+      timer = Monotonic::Timer.new(instants: Monotonic::Time)
+      timer.start
+      sleep 0.01
+      timer.stop
+      expect(timer.total_nanoseconds % Monotonic::Time.resolution).must_equal(0)
+    end
+  end
+
+  context "as a duration" do
+    it "hands back a Duration::Nanoseconds" do
+      timer = Monotonic::Timer.new
+      timer.start
+      timer.stop
+      expect(timer.to_duration.class).must_equal(Duration::Nanoseconds)
+    end
+
+    it "carries the same figure as #total_nanoseconds" do
+      timer = Monotonic::Timer.new
+      timer.start
+      sleep 0.01
+      timer.stop
+      expect(timer.to_duration.to_i).must_equal(timer.total_nanoseconds)
+    end
+
+    it "converts exactly, #total_time being the same in seconds" do
+      timer = Monotonic::Timer.new
+      timer.start
+      sleep 0.01
+      timer.stop
+      expect(timer.to_duration.to_seconds.to_f).must_equal(timer.total_time)
+    end
+  end
+
   context "in nanoseconds" do
     it "returns an instance of integer" do
       timer = Monotonic::Timer.new

data/test/gemspec_test.rb

@@ -19,7 +19,7 @@ describe 'monotonic.rb.gemspec' do
   end
 
   it "declares its runtime dependencies" do
-    _(spec.runtime_dependencies.map(&:name).sort).must_equal(%w{sys-uptime})
+    _(spec.runtime_dependencies.map(&:name).sort).must_equal(%w{duration.rb sys-uptime})
   end
 
   it "declares its development dependencies" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: monotonic.rb
 version: !ruby/object:Gem::Version
-  version: 0.7.3
+  version: 0.8.0
 platform: ruby
 authors:
 - thoran
@@ -9,6 +9,20 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: duration.rb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.4.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.4.0
 - !ruby/object:Gem::Dependency
   name: sys-uptime
   requirement: !ruby/object:Gem::Requirement