monotime 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8f48959572be85d87513cfc071e48eea56af6c15e62d7c8d2b253fecf1b23d2
-  data.tar.gz: 73f63a474ba0949c4ddc2e665e9102f89524ab9031c52476a3420b49cb3656e2
+  metadata.gz: 5a97344679471a970a324027b84b560faf9dfc9597c0937094de1486cc0da602
+  data.tar.gz: 35d55277a3181f0033939263122296b3a5328c5cc1605722644dd21aa9305ac1
 SHA512:
-  metadata.gz: e03126c84a579e4096b28c56afd93eab7099bc782ea9c6ec0f2be8a9d8375e1ed90ce8efc3b22f59a93356c104b76c0945f18fd36bae0232cc0cf0f65fb68f98
-  data.tar.gz: 1f74dd4465f686198e4e1fc098d04387528a7cc99d78ba850773cc137c99a3ab62e23b34c5424c9c6d03e7bb34ee9f383d2a6173c196a857eff31df25c62c108
+  metadata.gz: 29d7c0fb1aa092127f1a1a3036552466d9f6ea83d337fa3c9ffda0e88d3b5fb4ca996f81c828701a2a1bee4bf44d8c6392395298ac9f257034b3b71b8d0437b3
+  data.tar.gz: bd3bef852b6d5b25810091e0ee7452e60e03a5cd25cc5577e25760452804d3d201cfc05efd2dcf19d91680ff6bdacbd93b9428473def942ac3c024aea4675c9d

data/.rubocop.yml

@@ -0,0 +1,2 @@
+Metrics/LineLength:
+  Max: 96

data/README.md

@@ -71,7 +71,7 @@ And how to do basic maths on itself:
 (Instant.now - Duration.from_secs(1)).elapsed.to_s # => "1.000014627s"
 
 # Instant - Instant => Duration
-(Instant.now - Instant.now).to_s                   # => "3.439μs"
+(Instant.now - Instant.now).to_s                   # => "-5.585μs"
 ```
 
 `Duration` and `Instant` are also `Comparable` with other instances of their

data/bin/console

@@ -1,14 +1,14 @@
 #!/usr/bin/env ruby
 
-require "bundler/setup"
-require "monotime"
+require 'bundler/setup'
+require 'monotime'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
 
 # (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
+# require 'pry'
 # Pry.start
 
-require "irb"
+require 'irb'
 IRB.start(__FILE__)

data/lib/monotime/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Monotime
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/monotime.rb

@@ -5,147 +5,167 @@ require 'monotime/version'
 require 'dry-equalizer'
 
 module Monotime
+  # A measurement from the operating system's monotonic clock, with up to
+  # nanosecond precision.
   class Instant
-    attr_reader :ns
+    # A measurement, in nanoseconds.  Should be considered opaque and
+    # non-portable outside the process that created it.
+    protected def ns() @ns end
 
     include Dry::Equalizer(:ns)
     include Comparable
 
-    def initialize(ns = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond))
-      raise TypeError, 'Not an Integer' unless ns.is_a? Integer
-
-      @ns = ns
+    # Create a new +Instant+ from a given nanosecond measurement, defaulting to
+    # that given by +Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond))+.
+    #
+    # Users should generally *not* pass anything to this function.
+    def initialize(nanos = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond))
+      @ns = Integer(nanos)
     end
 
+    # An alias to +new+, and generally preferred over it.
     def self.now
       new
     end
 
+    # Return a +Duration+ between this +Instant+ and another.
     def duration_since(earlier)
       case earlier
-      when Instant then self - earlier
+      when Instant then earlier - self
       else raise TypeError, 'Not an Instant'
       end
     end
 
+    # Return a +Duration+ since this +Instant+ and now.
     def elapsed
       duration_since(self.class.now)
     end
 
+    # Sugar for +elapsed.to_s+.
+    def to_s(*args)
+      elapsed.to_s(*args)
+    end
+
+    # Add a +Duration+ to this +Instant+, returning a new +Instant+.
     def +(other)
       case other
-      when Duration then Instant.new(self.ns + other.ns)
-      when Integer then Instant.new(self.ns + other)
-      else raise TypeError, 'Not a Duration or Integer'
+      when Duration then Instant.new(@ns + other.to_nanos)
+      else raise TypeError, 'Not a Duration'
       end
     end
 
+    # Subtract another +Instant+ to generate a +Duration+ between the two,
+    # or a +Duration+, to generate an +Instant+ offset by it.
     def -(other)
       case other
-      when Instant then Duration.new(other.ns - self.ns)
-      when Duration then Instant.new(self.ns - other.ns)
-      when Integer then Instant.new(self.ns - other)
-      else raise TypeError, 'Not an Instant, Duration or Integer'
+      when Instant then Duration.new(@ns - other.ns)
+      when Duration then Instant.new(@ns - other.to_nanos)
+      else raise TypeError, 'Not an Instant or Duration'
       end
     end
 
+    # Compare this +Instant+ with another.
     def <=>(other)
       case other
-      when self.class then self.ns <=> other.ns
-      else raise TypeError, 'Not a #{self.class}'
+      when Instant then @ns <=> other.ns
+      else raise TypeError, 'Not an Instant'
       end
     end
   end
 
+  # A type representing a span of time in nanoseconds.
   class Duration
-    attr_reader :ns
-
-    include Dry::Equalizer(:ns)
+    include Dry::Equalizer(:to_nanos)
     include Comparable
 
-    def initialize(ns = 0)
-      raise TypeError, 'Not an Integer' unless ns.is_a? Integer
-
-      @ns = ns
+    # Create a new +Duration+ of a specified number of nanoseconds, zero by
+    # default.
+    def initialize(nanos = 0)
+      @ns = Integer(nanos)
     end
 
     class << self
+      # Generate a new +Duration+ measuring the given number of seconds.
       def from_secs(secs)
         new(Integer(Float(secs) * 1_000_000_000))
       end
 
+      # Generate a new +Duration+ measuring the given number of milliseconds.
       def from_millis(millis)
         new(Integer(Float(millis) * 1_000_000))
       end
 
+      # Generate a new +Duration+ measuring the given number of microseconds.
       def from_micros(micros)
         new(Integer(Float(micros) * 1_000))
       end
 
+      # Generate a new +Duration+ measuring the given number of nanoseconds.
       def from_nanos(nanos)
         new(Integer(nanos))
       end
 
+      # Return a +Duration+ measuring the elapsed time of the yielded block.
       def measure
         Instant.now.tap { yield }.elapsed
       end
     end
 
+    # Add another +Duration+ to this one, returning a new +Duration+.
     def +(other)
-      case other
-      when Duration then Duration.new(self.ns + other.ns)
-      when Numeric then Duration.new(self.ns + other)
-      else raise TypeError, 'Not a Duration or Numeric'
-      end
+      Duration.new(to_nanos + other.to_nanos)
     end
 
+    # Subtract another +Duration+ from this one, returning a new +Duration+.
     def -(other)
-      case other
-      when Duration then Duration.new(self.ns - other.ns)
-      when Numeric then Duration.new(self.ns - other)
-      else raise TypeError, 'Not a Duration or Numeric'
-      end
+      Duration.new(to_nanos - other.to_nanos)
     end
 
+    # Compare this +Duration+ with another.
     def <=>(other)
-      case other
-      when self.class then self.ns <=> other.ns
-      else raise TypeError, "Not a #{self.class}"
-      end
+      to_nanos <=> other.to_nanos
     end
 
+    # Return this +Duration+ in seconds.
     def to_secs
-      @ns / 1_000_000_000
+      to_nanos / 1_000_000_000.0
     end
 
+    # Return this +Duration+ in milliseconds.
     def to_millis
-      @ns / 1_000_000
+      to_nanos / 1_000_000.0
     end
 
+    # Return this +Duration+ in microseconds.
     def to_micros
-      @ns * 1_000
+      to_nanos / 1_000.0
     end
 
+    # Return this +Duration+ in nanoseconds.
     def to_nanos
       @ns
     end
 
+    DIVISORS = [
+      [1_000_000_000.0, 's'],
+      [1_000_000.0, 'ms'],
+      [1_000.0, 'μs'],
+      [0, 'ns']
+    ].map(&:freeze).freeze
+
+    # Format this +Duration+ into a human-readable string, with a given number
+    # of decimal places.
+    #
+    # The exact format is subject to change, users with specific requirements
+    # are encouraged to use their own formatting methods.
     def to_s(precision = 9)
-      postfix = 's'
-      ns = self.ns.abs
-      num = "#{'-' if self.ns < 0}%.#{precision}f" % if ns >= 1_000_000_000
-        ns / 1_000_000_000.0
-      elsif ns >= 1_000_000
-        postfix = 'ms'
-        ns / 1_000_000.0
-      elsif ns >= 1_000
-        postfix = 'μs'
-        ns / 1_000.0
-      else
-        postfix = 'ns'
-        ns
-      end
-      num.sub(/\.?0*$/, '') << postfix
+      precision = Integer(precision).abs
+      ns = to_nanos.abs
+      div, unit = DIVISORS.find { |d, _| ns >= d }
+      ns /= div if div.nonzero?
+      num = format("#{'-' if to_nanos.negative?}%.#{precision}f", ns)
+      num.sub!(/\.?0*$/, '') if precision.nonzero?
+      num << unit
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: monotime
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Thomas Hurst
@@ -74,9 +74,9 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".rubocop.yml"
 - ".travis.yml"
 - Gemfile
-- Gemfile.lock
 - LICENSE.txt
 - README.md
 - Rakefile

data/Gemfile.lock

@@ -1,24 +0,0 @@
-PATH
-  remote: .
-  specs:
-    monotime (0.1.0)
-      dry-equalizer
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    dry-equalizer (0.2.1)
-    minitest (5.11.3)
-    rake (10.5.0)
-
-PLATFORMS
-  ruby
-
-DEPENDENCIES
-  bundler (~> 1.16)
-  minitest (~> 5.0)
-  monotime!
-  rake (~> 10.0)
-
-BUNDLED WITH
-   1.16.3