monotonic.rb 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 735b3915ec7e7b95ef1fde8effe2d2723fea5eb027f9af87d1bea9dc8552048a
-  data.tar.gz: 8497225d7afb17a9e6c5f1c6a7c79510986fc74f731c81c06c4b0529ca1fa1d1
+  metadata.gz: 31e7ee27a90e0a41a51e5739b7024b16a2d7e10f71002bde23362bc90ccef9e5
+  data.tar.gz: 48b392a44f8d69bfe6ce2ecaee02b99d47645a148317c97c304188b0584ba3d8
 SHA512:
-  metadata.gz: a9a637b1664afe2b51d8b2f6abedace3e2dd6faf150d5767da5a6add304acba0554db879f72f16867856219eee41da3ed1042418e832a76722928dea62e27511
-  data.tar.gz: fed34f80416fa88c2b31fce83a9f21576a62d678c74ca0202bedf550149842de31cd121e55cec8f377f1354b4748cd4f818333b9aed726d778310630f9c8854b
+  metadata.gz: 32e4581c05f382de37da5794488759f1c7206a54f79f1ad593d1809b9a53dde4407a17e4d3ab4eab8b4eaeaa18caea85dfc4300ab219db1e3291bcacb79987a9
+  data.tar.gz: 308211ccff21283d9ff5a851396ff660df6f605d3ffe607176c26c53075bfc930f3bbfacc5edfee758f11b6e702d7c5bf46de88e3b3193aa3636ef956dcd7664

data/CHANGELOG

@@ -1,5 +1,40 @@
 # CHANGELOG
 
+## 20260817
+
+0.10.0: + Monotonic::Measurement arithmetic, so that a speedup is a ratio which knows how well it is known.
+
+1. + Monotonic::Measurement#+ and #-: two intervals give an interval, their doubts combining in quadrature through Measurand rather than by addition. A duration joins as exact, having none of its own, and a bare number is refused, having no unit to be added to.
+2. + Monotonic::Measurement#*: scales by a number, the uncertainty scaling with it. Two intervals are refused, there being no unit of time squared, as Duration::Common refuses them.
+3. + Monotonic::Measurement#/: by a number it stays an interval; by another interval the units cancel and a Measurand is left, dimensionless and carrying the doubt of both. That ratio is t1/tn, and the reason for the release: a speedup stated without knowing whether it is real is worth little.
+4. + Monotonic::Measurement.from: builds from a measurand whose uncertainty has been propagated rather than measured, so that what comes back from arithmetic carries neither an instrument's floor nor a drift still to be applied a second time.
+5. ~ monotonic.rb.gemspec: /measurand >= 0.1.0/measurand >= 0.1.2/. Measurand#/ divided two integer values as integers until 0.1.2, so a ratio of two nanosecond counts came back as 0 rather than 0.8788. #/ is the point of this release and does not work below 0.1.2, which the added tests demonstrate: they fail twice against 0.1.0 and pass against 0.1.2.
+6. + test/Monotonic/Measurement_test.rb: each operator and what it refuses, and the ratio — that it is dimensionless, that it divides exactly, and that it carries the doubt of both operands.
+7. + test/gemspec_test.rb: that each runtime dependency declares a minimum, and which minimum. The existing test asserted the names alone, which is what let 5 above happen: the gemspec named measurand and said nothing about needing a measurand that works. Asserting the whole map means a minimum cannot move without the test being made to agree.
+8. ~ README.md: + the arithmetic to the Description, + a Monotonic::Measurement arithmetic section to Usage, and + a blank line after require in two examples, the other three having had one.
+9. ~ Monotonic::VERSION: /0.9.0/0.10.0/
+
+
+## 20260816
+
+0.9.0: Use measurand gem, + Monotonic::Measurement and Monotonic::Timer.floor.
+
+1. + measurand as a dependency, constrained to >= 0.1.0 where Measurand#place became public. How well a figure is known is its business, and it was being hand-rolled here: combining an absolute floor with a relative drift by addition gave 109.49ns where the correct combination in quadrature gives 87.78ns, a quarter out.
+2. + Monotonic::Timer.floor: what it costs to measure at all, in nanoseconds, measured by timing measurements of nothing and remembered. The clock's tick is not the limit, an interval wanting two readings and the taking of them taking time. A high percentile rather than a median, so that the ordinary case is covered and not merely the best one. It is a floor and not an error bar: the tail is unbounded and one-sided, the scheduler being free to take the processor away between the two readings, and no single measurement can detect that it did.
+3. + Monotonic::Measurement: an elapsed interval together with what it is worth. #to_s shows only as many digits as the uncertainty reaches, the least significant place being settled by Measurand#place upon the Particle Data Group convention, so 1265625ns against a floor of 84ns prints as 1.26562ms and the same count measured coarsely prints as 1.27ms. The unit ladder is powers of a thousand and stops at seconds, the scheme being a decimal-places one and minutes being sexagesimal. Nothing is capped, a day resolved to a hundred nanoseconds printing every figure it has: the absurdity is the mismatch between instrument and question, and is better seen than rounded away.
+4. + Monotonic::Measurement#uncertainty, #measurand, #unit_name, #decimals, #nanoseconds, #floor, #drift: every figure the rendering rests upon, so that a string can be walked back to the clock which produced it.
+5. + Monotonic::Measurement#floor takes a number or anything answering to #call, and Monotonic::Timer hands over its .floor method rather than its value. Measuring the floor is a thousand null measurements, and a caller which only wants a number should not set them going: a timed block costs 0.008ms where it would cost 0.307ms, the floor being measured when doubt is first asked about.
+6. + Monotonic::Measurement drift, optional and nil by default: the relative term, being the rate at which the clock's own oscillator wanders. It cannot be measured from within, weighing a clock wanting a better clock and this being the best one here, so it is supplied by a caller or not at all.
+7. + Monotonic::Measurement#to_i and #to_f, both in nanoseconds, its own unit, as Duration::Minutes answers 5 rather than 300; #to_duration for every other unit; and #<=> with Comparable, against another measurement only, a bare number having no unit to compare against.
+8. ~ BREAKING: Monotonic::Timer#time and .time return a Monotonic::Measurement rather than a Float of seconds. What comes back now says how much of itself is real, which a bare Float could not: 0.001295791 shows nine figures upon an instrument which resolves five. #total_time and #total_nanoseconds are unchanged for a number.
+9. + Monotonic::Timer#measurement and #to_s.
+10. + test/Monotonic/Measurement_test.rb: the unit chosen, the digits allowed, the uncertainty and that it combines in quadrature, the comparison, the conversions, the lazy floor, and that every figure the rendering rests upon is reachable.
+11. + test/Monotonic/Timer_test.rb: the floor, and that a timed block returns a measurement which carries the interval and the floor.
+12. ~ test/gemspec_test.rb: the runtime dependency list.
+13. ~ README.md: + the floor and the measurement, and what a timed block now hands back.
+14. ~ Monotonic::VERSION: /0.8.0/0.9.0/
+
+
 ## 20260816
 
 0.8.0: Use duration.rb gem.

data/README.md

@@ -35,6 +35,31 @@ timer.total_nanoseconds
 # => 2508000, upon a clock which ticks in whole microseconds
 ```
 
+A timed block hands back a `Monotonic::Measurement` rather than a bare number, so that what comes back says how much of itself is real. `Monotonic::Timer.floor` is what it costs to measure at all, taken by timing measurements of nothing, and the measurement shows only as many digits as that floor reaches — the doubt itself being [measurand](https://github.com/thoran/measurand)'s business, which combines an absolute floor with a relative drift in quadrature rather than by addition.
+
+```ruby
+Monotonic::Timer.floor
+# => 84
+measurement = Monotonic::Timer.time{sleep 0.001}
+measurement.to_s
+# => "1.26562 ms"
+measurement.uncertainty
+# => 84.0
+measurement.to_duration.to_microseconds.to_f
+# => 1265.625
+```
+
+Nothing is capped: a day resolved to a hundred nanoseconds prints every figure it has, the absurdity being the mismatch between what the instrument resolves and what was asked of it, which is better seen than rounded away. The floor is a floor and not an error bar — the tail is unbounded and one-sided, the scheduler being free to take the processor away between the two readings — so repeat and take a robust statistic where that matters.
+
+Measurements combine, and what may combine with what follows from the units. Two intervals add and subtract to an interval, their doubts going in quadrature; a duration joins in as exact, having none of its own; a bare number is refused, having no unit to be added to. Scaling by a number keeps the unit and scales the doubt with it, while multiplying two intervals is refused, there being no unit of time squared. Dividing one interval by another cancels the units and leaves a `Measurand` — dimensionless, and still knowing how well it is known, which is what a speedup is.
+
+```ruby
+serial = Monotonic::Timer.time{run_on_one}
+parallel = Monotonic::Timer.time{run_on_eight}
+serial / parallel
+# => Measurand(6.83, 0.00012), dimensionless
+```
+
 
 ## Installation
 
@@ -115,39 +140,69 @@ timer.total_time
 ```ruby
 require 'monotonic.rb'
 
-time = Monotonic::Timer.time do
+measurement = Monotonic::Timer.time do
   i = 0
   1_000_000.times{puts i += 1}
 end
-time
-# => 6.975823000073433
+measurement.to_s
+# => "6.97582 s"
 ```
 
 ### Monotonic::Timer with a block and block variable
 
 ```ruby
 require 'monotonic.rb'
-time = Monotonic::Timer.time do |timer|
+
+measurement = 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
+measurement.to_s
+# => "6.97582 s"
 ```
 
 ### Monotonic::Timer with a block on a timer instance
 
 ```ruby
 require 'monotonic.rb'
+
 timer = Monotonic::Timer.new
-time = timer.time do
+measurement = timer.time do
   i = 0
   1_000_000.times{puts i += 1}
 end
-time
-# => 7.033131000120193
+measurement.to_s
+# => "7.03313 s"
+```
+
+
+### Monotonic::Measurement arithmetic
+
+```ruby
+require 'monotonic.rb'
+
+a = Monotonic::Timer.time{sleep 0.001}
+b = Monotonic::Timer.time{sleep 0.002}
+
+(a + b).to_s
+# => "3.01543 ms"
+
+(a * 3).to_s
+# => "3.04629 ms"
+
+a + Duration::Microseconds.new(500)
+# => #<Monotonic::Measurement 1.51543 ms>, a duration being exact
+
+b / a
+# => Measurand(1.97, 0.00011), dimensionless
+
+a * b
+# => TypeError: there is no unit of time squared
+
+a + 5
+# => TypeError: expected an interval or a duration
 ```
 
 

data/lib/Monotonic/Measurement.rb

@@ -0,0 +1,176 @@
+# Monotonic/Measurement.rb
+# Monotonic::Measurement
+
+require 'duration.rb'
+require 'measurand'
+
+module Monotonic
+  # An elapsed interval together with what it is worth.  The count alone says
+  # nothing of how much of itself is real, so #to_s shows only as many digits as
+  # the uncertainty supports.  Nothing is capped: a day resolved to a hundred
+  # nanoseconds prints every figure it has, which looks absurd and is — the
+  # absurdity being the mismatch between what the instrument resolves and what
+  # was asked of it, and better seen than rounded away.
+  #
+  # The doubt is a Measurand's business and the unit is a Duration's; what is
+  # left here is the ladder between them and the string at the end of it.
+  class Measurement
+    include Comparable
+
+    # Powers of a thousand, and no further.  The scheme is a decimal-places one,
+    # so minutes and hours have no place in it: 90s is plainer than 1.5min, and
+    # a run of a day reads as 86400s rather than reaching for a unit which does
+    # not divide by ten.
+    UNITS = [[1, 'ns'], [1_000, 'us'], [1_000_000, 'ms'], [1_000_000_000, 's']]
+
+    class << self
+      # Built from a measurand rather than from a floor, for what comes back
+      # from arithmetic: its uncertainty has been propagated rather than
+      # measured, so it is neither an instrument's floor nor has a drift left to
+      # apply a second time.
+      def from(measurand)
+        allocate.tap{|measurement| measurement.send(:build, measurand)}
+      end
+    end # class << self
+
+    attr_reader :nanoseconds
+    attr_reader :drift
+
+    # The floor may be given as a number or as anything which answers to #call,
+    # so that measuring it can wait until somebody asks about doubt.
+    # Monotonic::Timer hands over its .floor method rather than its value, and a
+    # caller which only wants a number never sets the thousand null measurements
+    # going.
+    def floor
+      @floor = @floor.respond_to?(:call) ? @floor.call : @floor
+    end
+
+    # The floor is absolute and tells upon short intervals; drift is relative
+    # and tells upon long ones, being the rate at which the clock's own
+    # oscillator wanders.  Combining them is not addition — they are independent,
+    # so they go in quadrature — which is why the arithmetic is Measurand's and
+    # not done here.
+    def measurand
+      @measurand ||= (
+        absolute = Measurand.new(@nanoseconds, floor)
+        @drift ? absolute * Measurand.relative(1, @drift) : absolute
+      )
+    end
+
+    def uncertainty
+      measurand.uncertainty
+    end
+
+    # The arithmetic is Measurand's throughout — this only decides what may be
+    # combined with what, and hands back the right kind of thing.  Two intervals
+    # add and subtract to an interval, their uncertainties going in quadrature.
+    def +(addend)
+      self.class.from(measurand + as_measurand(addend, :add))
+    end
+
+    def -(subtrahend)
+      self.class.from(measurand - as_measurand(subtrahend, :subtract))
+    end
+
+    # Scaled by a number it stays an interval, the uncertainty scaling with it.
+    # Multiplied by another interval it would be time squared, which has no unit
+    # here, so it is refused as Duration::Common refuses it.
+    def *(multiplier)
+      if interval?(multiplier)
+        raise TypeError, "can't multiply #{self.class} by #{multiplier.class}: there is no unit of time squared"
+      end
+      self.class.from(measurand * multiplier)
+    end
+
+    # Divided by a number it stays an interval.  Divided by another interval the
+    # units cancel and a Measurand is left — dimensionless, but still knowing how
+    # well it is known, which is what a speedup or a rate is.
+    def /(divisor)
+      return measurand / divisor.measurand if divisor.respond_to?(:measurand)
+      self.class.from(measurand / divisor)
+    end
+
+    def unit
+      @unit ||= UNITS.reverse.find{|scale, _| @nanoseconds.abs >= scale} || UNITS.first
+    end
+
+    def scale
+      unit.first
+    end
+
+    def unit_name
+      unit.last
+    end
+
+    # The least significant digit worth showing is the one the uncertainty
+    # reaches, which Measurand settles by the Particle Data Group convention and
+    # reports as #place, a power of ten.  Rendering in a coarser unit moves it
+    # along by however many tens that unit is worth.  A measurand with no
+    # uncertainty has no last real digit, and answers nil.
+    def decimals
+      @decimals ||= (
+        place = measurand.place
+        place ? [Math.log10(scale) - place, 0].max.to_i : Math.log10(scale).to_i
+      )
+    end
+
+    def to_duration
+      Duration::Nanoseconds.new(@nanoseconds)
+    end
+
+    # Both answer in nanoseconds, this measurement's own unit, as
+    # Duration::Minutes answers 5 rather than 300.  Every other unit comes from
+    # #to_duration, which names the one it is asked for.  A number handed out
+    # without its unit stated must at least always mean the same thing.
+    def to_i
+      @nanoseconds
+    end
+
+    def to_f
+      @nanoseconds.to_f
+    end
+
+    def to_s
+      format("%.#{decimals}f #{unit_name}", @nanoseconds.to_f / scale)
+    end
+
+    # Against another measurement only.  A bare number has no unit, and comparing
+    # against one would have to assume which was meant, so nil is returned and ==
+    # is false, as Duration::Common does.
+    def <=>(other)
+      return nil unless other.is_a?(Monotonic::Measurement)
+      @nanoseconds <=> other.nanoseconds
+    end
+
+    def inspect
+      "#<#{self.class} #{self} (#{measurand} ns)>"
+    end
+
+    private
+
+    def initialize(nanoseconds, floor:, drift: nil)
+      @nanoseconds = nanoseconds
+      @floor = floor
+      @drift = drift
+    end
+
+    # An interval is anything which knows its own doubt, or any duration, which
+    # is exact.  A bare number is neither: it has no unit, so there is nothing to
+    # add it to.
+    def as_measurand(other, verb)
+      return other.measurand if other.respond_to?(:measurand)
+      return Measurand.new(other.to_nanoseconds.to_i) if other.respond_to?(:to_nanoseconds)
+      raise TypeError, "can't #{verb} #{other.class} #{verb == :add ? "to" : "from"} #{self.class}: expected an interval or a duration"
+    end
+
+    def interval?(other)
+      other.respond_to?(:measurand) || other.respond_to?(:to_nanoseconds)
+    end
+
+    def build(measurand)
+      @nanoseconds = measurand.value.round
+      @measurand = measurand
+      @floor = measurand.uncertainty
+    end
+  end
+end

data/lib/Monotonic/Timer.rb

@@ -2,6 +2,7 @@
 # Monotonic::Timer
 
 require 'duration.rb'
+require_relative './Measurement'
 
 module Monotonic
   class Timer
@@ -20,6 +21,10 @@ module Monotonic
     # 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)})
 
+    # How many measurements of nothing .floor takes, and which of them it keeps.
+    SAMPLES = 1_000
+    PERCENTILE = 0.95
+
     class << self
       def clock_name
         @clock_name ||= CLOCK_NAMES.find{|name| Process.const_defined?(name)}
@@ -36,6 +41,24 @@ module Monotonic
       def resolution
         Process.clock_getres(CLOCK, :nanosecond)
       end
+
+      # What it costs to measure at all, in nanoseconds, measured by timing
+      # measurements of nothing.  The clock's tick is not the limit: two readings
+      # must be taken, and taking them takes time, so an interval near this
+      # figure is mostly the measuring.
+      #
+      # It is a floor and not an error bar.  The typical cost is a tick or two;
+      # the tail is unbounded and one-sided, since the scheduler may take the
+      # processor away between the two readings and no single measurement can
+      # detect that it did.  A high percentile is taken rather than a median, so
+      # that the ordinary case is covered rather than merely the best one.
+      # Repeat and take a robust statistic if the tail matters.
+      def floor
+        @floor ||= (
+          samples = SAMPLES.times.map{timer = new; timer.start; timer.stop; timer.total_nanoseconds}.sort
+          samples[(samples.length * PERCENTILE).to_i]
+        )
+      end
     end # class << self
 
     # Where the instants come from.  Nothing supplied means the clock is read
@@ -87,6 +110,22 @@ module Monotonic
       to_duration.to_seconds.to_f
     end
 
+    # The elapsed interval together with what it is worth.  Not memoized: a timer
+    # which has not been stopped is still running, and so is its measurement.
+    # The floor is handed over as a method rather than a figure, so that a caller
+    # which only ever wants a number never sets the thousand null measurements
+    # going.
+    def measurement(drift: nil)
+      Monotonic::Measurement.new(total_nanoseconds, floor: self.class.method(:floor), drift: drift)
+    end
+
+    def to_s
+      measurement.to_s
+    end
+
+    # A Monotonic::Measurement rather than a bare Float, so that what comes back
+    # says how much of itself is real.  #total_time and #total_nanoseconds are
+    # still there for a number.
     def time
       start
       begin
@@ -94,7 +133,7 @@ module Monotonic
       ensure
         stop
       end
-      total_time
+      measurement
     end
 
     private

data/lib/Monotonic/VERSION.rb

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

data/monotonic.rb.gemspec

@@ -37,6 +37,7 @@ Gem::Specification.new do |spec|
 
   spec.dependencies = [
     ['duration.rb', '>= 0.4.0'],
+    ['measurand', '>= 0.1.2'],
     'sys-uptime'
   ]
 

data/test/Monotonic/Measurement_test.rb

@@ -0,0 +1,179 @@
+require_relative '../../lib/monotonic.rb'
+
+require 'minitest/autorun'
+require 'minitest-spec-context'
+
+describe Monotonic::Measurement do
+  def measurement(nanoseconds, floor: 84, drift: nil)
+    Monotonic::Measurement.new(nanoseconds, floor: floor, drift: drift)
+  end
+
+  describe "the unit" do
+    it "is the largest which leaves a mantissa of at least one" do
+      _(measurement(999).unit_name).must_equal('ns')
+      _(measurement(1_000).unit_name).must_equal('us')
+      _(measurement(1_265_625).unit_name).must_equal('ms')
+      _(measurement(1_000_000_000).unit_name).must_equal('s')
+    end
+
+    it "stops at seconds, the ladder being powers of a thousand" do
+      _(measurement(86_400_000_000_000).unit_name).must_equal('s')
+    end
+
+    it "is nanoseconds for nothing at all" do
+      _(measurement(0).to_s).must_equal('0 ns')
+    end
+  end
+
+  describe "the digits" do
+    it "reach as far as the uncertainty does and no further" do
+      _(measurement(1_265_625).to_s).must_equal('1.26562 ms')
+    end
+
+    it "are fewer upon a coarser instrument" do
+      _(measurement(1_265_625, floor: 100_000).to_s).must_equal('1.27 ms')
+    end
+
+    it "are none where the interval is near the floor" do
+      _(measurement(999).to_s).must_equal('999 ns')
+    end
+
+    it "are not capped, a day resolved to a hundred nanoseconds saying so" do
+      _(measurement(86_400_000_000_000).to_s).must_equal('86400.00000000 s')
+    end
+  end
+
+  describe "the uncertainty" do
+    it "is the floor alone when no drift is supplied" do
+      _(measurement(1_000_000).uncertainty).must_equal(84)
+    end
+
+    it "combines a drift in quadrature rather than by addition" do
+      combined = measurement(1_000_000_000, drift: 1e-6).uncertainty
+      _(combined).must_be_close_to(Math.sqrt(84**2 + 1_000**2), 0.01)
+      _(combined).wont_be_close_to(84 + 1_000, 1)
+    end
+
+    it "takes digits away as it grows" do
+      _(measurement(7_166_559_999, drift: 20e-6).decimals) \
+        .must_be(:<, measurement(7_166_559_999).decimals)
+    end
+
+    it "comes from a Measurand, which owns the arithmetic" do
+      _(measurement(1_000_000).measurand).must_be_instance_of(Measurand)
+    end
+  end
+
+  describe "the floor" do
+    it "may be a number" do
+      _(measurement(1_000_000, floor: 84).floor).must_equal(84)
+    end
+
+    it "may be something callable, and is not called until doubt is asked about" do
+      called = false
+      subject = Monotonic::Measurement.new(1_000_000, floor: ->{called = true; 84})
+      subject.to_i
+      subject.to_duration
+      _(called).must_equal(false)
+      subject.uncertainty
+      _(called).must_equal(true)
+      _(subject.floor).must_equal(84)
+    end
+  end
+
+  describe "comparison" do
+    it "orders one measurement against another" do
+      _(measurement(999)).must_be(:<, measurement(1_000))
+      _([measurement(1_000), measurement(999)].sort.map(&:nanoseconds)).must_equal([999, 1_000])
+    end
+
+    it "is nil against a bare number, which has no unit" do
+      _(measurement(999) <=> 999).must_be_nil
+    end
+
+    it "is therefore not equal to a bare number" do
+      _(measurement(999) == 999).must_equal(false)
+    end
+  end
+
+  describe "arithmetic" do
+    it "adds two intervals to an interval, the doubt going in quadrature" do
+      sum = measurement(1_000_000) + measurement(2_000_000)
+      _(sum).must_be_instance_of(Monotonic::Measurement)
+      _(sum.nanoseconds).must_equal(3_000_000)
+      _(sum.uncertainty).must_be_close_to(Math.sqrt(84**2 + 84**2), 0.0001)
+    end
+
+    it "subtracts likewise, the doubt growing rather than cancelling" do
+      difference = measurement(2_000_000) - measurement(1_000_000)
+      _(difference.nanoseconds).must_equal(1_000_000)
+      _(difference.uncertainty).must_be_close_to(Math.sqrt(84**2 + 84**2), 0.0001)
+    end
+
+    it "takes a duration as exact, it having no doubt of its own" do
+      sum = measurement(1_000_000) + Duration::Microseconds.new(500)
+      _(sum.nanoseconds).must_equal(1_500_000)
+      _(sum.uncertainty).must_equal(84)
+    end
+
+    it "refuses a bare number, which has no unit to add" do
+      _{measurement(1_000_000) + 5}.must_raise(TypeError)
+      _{measurement(1_000_000) - 5}.must_raise(TypeError)
+    end
+
+    it "scales by a number, the uncertainty scaling with it" do
+      product = measurement(1_000_000) * 3
+      _(product.nanoseconds).must_equal(3_000_000)
+      _(product.uncertainty).must_equal(252)
+    end
+
+    it "refuses to multiply two intervals, there being no unit of time squared" do
+      _{measurement(1_000_000) * measurement(2_000_000)}.must_raise(TypeError)
+      _{measurement(1_000_000) * Duration::Seconds.new(1)}.must_raise(TypeError)
+    end
+
+    it "divides by a number and stays an interval" do
+      quotient = measurement(1_000_000) / 2
+      _(quotient).must_be_instance_of(Monotonic::Measurement)
+      _(quotient.nanoseconds).must_equal(500_000)
+      _(quotient.uncertainty).must_equal(42)
+    end
+  end
+
+  describe "the ratio of two intervals" do
+    it "is dimensionless, the units having cancelled" do
+      ratio = measurement(9_579_583) / measurement(10_900_458)
+      _(ratio).must_be_instance_of(Measurand)
+      _(ratio.value.to_f).must_be_close_to(0.878824, 0.000001)
+    end
+
+    it "divides exactly rather than as integers, which measurand 0.1.2 settled" do
+      _((measurement(1_000_000) / measurement(3_000_000)).value).must_equal(Rational(1, 3))
+    end
+
+    it "carries the doubt of both, which is what a speedup is worth knowing" do
+      ratio = measurement(9_579_583) / measurement(10_900_458)
+      _(ratio.uncertainty).must_be_close_to(1.026e-05, 1e-8)
+    end
+  end
+
+  describe "#to_duration" do
+    it "hands the interval to duration.rb, whose business the units are" do
+      _(measurement(1_500_000_000).to_duration).must_be_instance_of(Duration::Nanoseconds)
+      _(measurement(1_500_000_000).to_duration.to_seconds.to_f).must_equal(1.5)
+    end
+  end
+
+  describe "#to_i and #to_f" do
+    it "both answer in nanoseconds, the measurement's own unit" do
+      _(measurement(1_274_625).to_i).must_equal(1_274_625)
+      _(measurement(1_274_625).to_f).must_equal(1_274_625.0)
+    end
+
+    it "agree with one another, and with #nanoseconds" do
+      subject = measurement(1_274_625)
+      _(subject.to_f).must_equal(subject.to_i.to_f)
+      _(subject.to_i).must_equal(subject.nanoseconds)
+    end
+  end
+end

data/test/Monotonic/Timer_test.rb

@@ -9,7 +9,7 @@ describe Monotonic::Timer do
       block_time = Monotonic::Timer.time do |timer|
         sleep 3
       end
-      expect(block_time.round).must_equal(3)
+      expect(block_time.to_duration.to_seconds.to_f.round).must_equal(3)
     end
 
     # Test introduced in 0.6.5 to demonstrate that the bug had been fixed.
@@ -18,7 +18,7 @@ describe Monotonic::Timer do
         sleep 3
         4
       end
-      expect(block_time.round).must_equal(3)
+      expect(block_time.to_duration.to_seconds.to_f.round).must_equal(3)
     end
 
     # Test introduced in 0.6.7 to demonstrate that the bug had been fixed.
@@ -51,7 +51,7 @@ describe Monotonic::Timer do
         timer.start
         sleep 1
       end
-      expect(block_time.round).must_equal(1)
+      expect(block_time.to_duration.to_seconds.to_f.round).must_equal(1)
     end
   end
 
@@ -88,7 +88,7 @@ describe Monotonic::Timer do
         expect(timer.total_time.round).must_equal(0)
         sleep 1
       end
-      expect(time.round).must_equal(1)
+      expect(time.to_duration.to_seconds.to_f.round).must_equal(1)
       expect(timer.total_time.round).must_equal(1)
     end
 

data/test/gemspec_test.rb

@@ -19,7 +19,17 @@ describe 'monotonic.rb.gemspec' do
   end
 
   it "declares its runtime dependencies" do
-    _(spec.runtime_dependencies.map(&:name).sort).must_equal(%w{duration.rb sys-uptime})
+    _(spec.runtime_dependencies.map(&:name).sort).must_equal(%w{duration.rb measurand sys-uptime})
+  end
+
+  # The minimum is what makes a dependency true, and naming the gem alone does
+  # not say that it will work.  0.9.0 constrained measurand to >= 0.1.0, where
+  # #place became public; #/ then became load-bearing at 0.1.2 without the
+  # constraint following it, and Measurement#/ returned 0 against a version the
+  # gemspec called satisfactory.
+  it "declares a minimum version for each runtime dependency" do
+    _(spec.runtime_dependencies.to_h{|dependency| [dependency.name, dependency.requirement.to_s]}) \
+      .must_equal({'duration.rb' => '>= 0.4.0', 'measurand' => '>= 0.1.2', 'sys-uptime' => '>= 0'})
   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.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - thoran
@@ -23,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.4.0
+- !ruby/object:Gem::Dependency
+  name: measurand
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.2
 - !ruby/object:Gem::Dependency
   name: sys-uptime
   requirement: !ruby/object:Gem::Requirement
@@ -89,11 +103,13 @@ files:
 - Gemfile
 - README.md
 - Rakefile
+- lib/Monotonic/Measurement.rb
 - lib/Monotonic/Time.rb
 - lib/Monotonic/Timer.rb
 - lib/Monotonic/VERSION.rb
 - lib/monotonic.rb
 - monotonic.rb.gemspec
+- test/Monotonic/Measurement_test.rb
 - test/Monotonic/Time_test.rb
 - test/Monotonic/Timer_test.rb
 - test/Monotonic/VERSION_test.rb