monotime 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09910c8dfa9bdc7777e55f6eb606b49f8c6ca23d563e09ae8e5109b116b7781f'
-  data.tar.gz: 5db6e948d04836e8523cbeaf92e4f599c5ed9238055f5fb79d94dfcab1969a19
+  metadata.gz: c88bca715126cabf9bf5ea1af377e16d43da5ecc06ee45f98dad584360eaa15b
+  data.tar.gz: 8f741d6219cfe4b9050f892f2df905ed603f859e4a79f930a4eb954c213bf639
 SHA512:
-  metadata.gz: '087abc138dd09dd52d5b3adb5bc6ad276e0ad5936e9aa381ce43dbf12a62dfc1f65449b0d36454a78527842d70ca3ab7752d94ffea7cecbf9f05b85917c11d95'
-  data.tar.gz: e2b45aaef34322a3ef71fdf7317af1a363a5e7b1f3e86d6b8c65df8b444dcfa03d210a11ee7adb051cd22794776b02e984781fb69db5183fcd76659683dbee1b
+  metadata.gz: 5ed67631407691f935ffdd30727c4054b3fa7f5964a9cdcb0db0f94e1a2aecddb83eac4b1e4a8e032cd3c57145152e6649ddf14093643329ff23b5d43348000f
+  data.tar.gz: f38b77609652866fa4c1b7bfee164977a7f7895feeb0f76d8dd5e71a05da31b0cda24c680f5b2aef19c3f5c7787da237f580ee56ccb86e456dae576fc95d0e89

data/.rubocop.yml

@@ -1,6 +1,17 @@
+AllCops:
+  Exclude:
+    - "bin/*"
+    - "test/*"
+    - "*.gemspec"
+    - "Rakefile"
+    - "Gemfile"
+
 Metrics/LineLength:
   Max: 96
 
+Metrics/ClassLength:
+  Max: 120
+
 Style/AsciiComments:
   Enabled: false
 

data/.travis.yml

@@ -3,6 +3,8 @@ sudo: false
 language: ruby
 cache: bundler
 rvm:
-  - 2.5.1
-  - jruby
-before_install: gem install bundler -v 1.16.3
+  - 2.4.6
+  - 2.5.5
+  - 2.6.3
+  - jruby-9.2.7.0
+before_install: gem install bundler -v "~> 2"

data/CHANGELOG.md

@@ -1,6 +1,18 @@
 # Changelog
 
-## [0.6.1] - 2018-10-27
+## [0.7.0] - 2019-04-24
+### Added
+ - `Duration.with_measure`, which yields and returns an array containing its
+   evaluated return value and its `Duration`.
+
+### Changed
+ - Break `Duration` and `Instant` into their own files.
+ - Rename `Monotime::VERSION` to `Monotime::MONOTIME_VERSION` to reduce
+   potential for collision if the module is included.
+ - Update to bundler 2.0.
+ - Rework README.md.  Includes fix for [issue #1] (added a "See Also" section).
+
+## [0.6.1] - 2018-10-26
 ### Fixed
  - Build gem from a clean git checkout, not my local development directory.
    No functional changes.
@@ -81,4 +93,6 @@
 [0.5.0]: https://github.com/Freaky/monotime/commits/v0.5.0
 [0.6.0]: https://github.com/Freaky/monotime/commits/v0.6.0
 [0.6.1]: https://github.com/Freaky/monotime/commits/v0.6.1
+[0.7.0]: https://github.com/Freaky/monotime/commits/v0.7.0
+[issue #1]: https://github.com/Freaky/monotime/issues/1
 [@celsworth]: https://github.com/celsworth

data/README.md

@@ -1,5 +1,7 @@
 [![Gem Version](https://badge.fury.io/rb/monotime.svg)](https://badge.fury.io/rb/monotime)
 [![Build Status](https://travis-ci.org/Freaky/monotime.svg?branch=master)](https://travis-ci.org/Freaky/monotime)
+[![Inline docs](http://inch-ci.org/github/Freaky/monotime.svg?branch=master)](http://inch-ci.org/github/Freaky/monotime)
+[![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](https://www.rubydoc.info/gems/monotime)
 
 # Monotime
 
@@ -21,21 +23,17 @@ Or install it yourself as:
 
     $ gem install monotime
 
-## Usage
-
-The typical way everyone does "correct" elapsed-time measurements in Ruby is
-this pile of nonsense:
+`Monotime` is tested on Ruby 2.4—2.6 and recent JRuby 9.x releases.
 
-```ruby
-start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-do_something
-elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
-```
+## Usage
 
-Not only is it long-winded, it's imprecise, converting to floating point instead
-of working off precise timestamps.
+`Monotime` offers a `Duration` type for describing spans of time, and an
+`Instant` type for describing points in time.  Both operate at nanosecond
+resolution to the limits of whatever your Ruby implementation supports.
 
-`Monotime` offers this alternative:
+For example, to measure an elapsed time, either create an `Instant` to mark the
+start point, perform the action and then ask for the `Duration` that has elapsed
+since:
 
 ```ruby
 include Monotime
@@ -43,44 +41,54 @@ include Monotime
 start = Instant.now
 do_something
 elapsed = start.elapsed
+```
 
-# or
+Or use a convenience method:
+
+```ruby
 elapsed = Duration.measure { do_something }
+
+# or
+
+return_value, elapsed = Duration.with_measure { compute_something }
 ```
 
-`elapsed` is not a dimensionless `Float`, but a `Duration` type, and internally
-both `Instant` and `Duration` operate in *nanoseconds* to most closely match
-the native timekeeping types used by most operating systems.
+`Duration` offers formatting:
+
+```ruby
+Duration.millis(42).to_s       # => "42ms"
+Duration.nanos(12345).to_s     # => "12.345μs"
+Duration.secs(1.12345).to_s(2) # => "1.12s"
+```
 
-`Duration` knows how to format itself:
+Conversions:
 
 ```ruby
-Duration.from_millis(42).to_s       # => "42ms"
-Duration.from_nanos(12345).to_s     # => "12.345μs"
-Duration.from_secs(1.12345).to_s(2) # => "1.12s"
+Duration.secs(10).millis    # => 10000.0
+Duration.micros(12345).secs # => 0.012345
 ```
 
-And how to do basic maths on itself:
+And basic mathematical operations:
 
 ```ruby
-(Duration.from_millis(42) + Duration.from_secs(1)).to_s  # => "1.042s"
-(Duration.from_millis(42) - Duration.from_secs(1)).to_s  # => "-958ms"
-(Duration.from_secs(42) * 2).to_s                        # => "84s"
-(Duration.from_secs(42) / 2).to_s                        # => "21s"
+(Duration.millis(42) + Duration.secs(1)).to_s  # => "1.042s"
+(Duration.millis(42) - Duration.secs(1)).to_s  # => "-958ms"
+(Duration.secs(42) * 2).to_s                   # => "84s"
+(Duration.secs(42) / 2).to_s                   # => "21s"
 ```
 
 `Instant` does some simple maths too:
 
 ```ruby
 # Instant - Duration => Instant
-(Instant.now - Duration.from_secs(1)).elapsed.to_s # => "1.000014627s"
+(Instant.now - Duration.secs(1)).elapsed.to_s      # => "1.000014627s"
 
 # Instant - Instant => Duration
 (Instant.now - Instant.now).to_s                   # => "-5.585μs"
 ```
 
 `Duration` and `Instant` are also `Comparable` with other instances of their
-type, and support `#hash` for use in, er, hashes.
+type, and can be used in hashes, sets, and similar structures.
 
 ## Sleeping
 
@@ -89,9 +97,9 @@ is not yet implemented):
 
 ```ruby
 # Equivalent
-sleep(Duration.from_secs(1).to_secs)  # => 1
+sleep(Duration.secs(1).secs)  # => 1
 
-Duration.from_secs(1).sleep           # => 1
+Duration.secs(1).sleep           # => 1
 ```
 
 So can `Instant`, taking a `Duration` and sleeping until the given `Duration`
@@ -99,7 +107,7 @@ past the time the `Instant` was created, if any.  This may be useful if you wish
 to maintain an approximate interval while performing work in between:
 
 ```ruby
-poke_duration = Duration.from_secs(60)
+poke_duration = Duration.secs(60)
 loop do
   start = Instant.now
   poke_my_api(api_to_poke, what_to_poke_it_with)
@@ -111,13 +119,13 @@ end
 Or you can declare a future `Instant` and ask to sleep until it passes:
 
 ```ruby
-next_minute = Instant.now + Duration.from_secs(60)
+next_minute = Instant.now + Duration.secs(60)
 do_stuff
 next_minute.sleep # => sleeps any remaining seconds
 ```
 
-`Instant#sleep` returns a `Duration` which was slept, or a negative `Duration` if
-the desired sleep period has passed.
+`Instant#sleep` returns a `Duration` which was slept, or a negative `Duration`
+if the desired sleep period has passed.
 
 ## Duration duck typing
 
@@ -133,8 +141,8 @@ class Numeric
   end
 end
 
-(Duration.from_secs(1) + 41).to_s  # => "42s"
-(Instant.now - 42).to_s            # => "42.000010545s"
+(Duration.secs(1) + 41).to_s  # => "42s"
+(Instant.now - 42).to_s       # => "42.000010545s"
 ```
 
 ## Development
@@ -150,3 +158,21 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/Freaky
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## See Also
+
+### Core Ruby
+
+For a zero-dependency alternative, see
+[`Process.clock_gettime`](https://ruby-doc.org/core-2.6.3/Process.html#method-c-clock_gettime).
+`monotime` currently only uses `Process::CLOCK_MONOTONIC`, but others may offer higher precision
+depending on platform.
+
+### Other Gems
+
+[hitimes](https://rubygems.org/gems/hitimes) is a popular and mature alternative
+which also includes a variety of features for gathering statistics about
+measurements, and may offer higher precision on some platforms.
+
+Note until [#73](https://github.com/copiousfreetime/hitimes/pull/73) is closed it
+depends on compiled C/Java extensions.

data/lib/monotime.rb

@@ -1,469 +1,5 @@
 # frozen_string_literal: true
 
-require 'monotime/version'
-
-module Monotime
-  # A measurement from the operating system's monotonic clock, with up to
-  # nanosecond precision.
-  class Instant
-    # A measurement, in nanoseconds.  Should be considered opaque and
-    # non-portable outside the process that created it.
-    attr_reader :ns
-    protected :ns
-
-    include Comparable
-
-    # Create a new +Instant+ from an optional nanosecond measurement.
-    #
-    # Users should generally *not* pass anything to this function.
-    #
-    # @param nanos [Integer]
-    # @see #now
-    def initialize(nanos = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond))
-      @ns = Integer(nanos)
-    end
-
-    # An alias to +new+, and generally preferred over it.
-    #
-    # @return [Instant]
-    def self.now
-      new
-    end
-
-    # Return a +Duration+ between this +Instant+ and another.
-    #
-    # @param earlier [Instant]
-    # @return [Duration]
-    def duration_since(earlier)
-      raise TypeError, 'Not an Instant' unless earlier.is_a?(Instant)
-
-      earlier - self
-    end
-
-    # Return a +Duration+ since this +Instant+ and now.
-    #
-    # @return [Duration]
-    def elapsed
-      duration_since(self.class.now)
-    end
-
-    # Return whether this +Instant+ is in the past.
-    #
-    # @return [Boolean]
-    def in_past?
-      elapsed.positive?
-    end
-
-    alias past? in_past?
-
-    # Return whether this +Instant+ is in the future.
-    #
-    # @return [Boolean]
-    def in_future?
-      elapsed.negative?
-    end
-
-    alias future? in_future?
-
-    # Sleep until this +Instant+, plus an optional +Duration+, returning a +Duration+
-    # that's either positive if any time was slept, or negative if sleeping would
-    # require time travel.
-    #
-    # @example Sleeps for a second
-    #   start = Instant.now
-    #   sleep 0.5 # do stuff for half a second
-    #   start.sleep(Duration.from_secs(1)).to_s # => "490.088706ms" (slept)
-    #   start.sleep(Duration.from_secs(1)).to_s # => "-12.963502ms" (did not sleep)
-    #
-    # @example Also sleeps for a second.
-    #   one_second_in_the_future = Instant.now + Duration.from_secs(1)
-    #   one_second_in_the_future.sleep.to_s     # => "985.592712ms" (slept)
-    #   one_second_in_the_future.sleep.to_s     # => "-4.71217ms" (did not sleep)
-    #
-    # @param duration [nil, Duration, #to_nanos]
-    # @return [Duration] the slept duration, if +#positive?+, else the overshot time
-    def sleep(duration = nil)
-      remaining = duration ? duration - elapsed : -elapsed
-
-      remaining.tap { |rem| rem.sleep if rem.positive? }
-    end
-
-    # Sleep for the given number of seconds past this +Instant+, if any.
-    #
-    # Equivalent to +#sleep(Duration.from_secs(secs))+
-    #
-    # @param secs [Numeric] number of seconds to sleep past this +Instant+
-    # @return [Duration] the slept duration, if +#positive?+, else the overshot time
-    # @see #sleep
-    def sleep_secs(secs)
-      sleep(Duration.from_secs(secs))
-    end
-
-    # Sleep for the given number of milliseconds past this +Instant+, if any.
-    #
-    # Equivalent to +#sleep(Duration.from_millis(millis))+
-    #
-    # @param millis [Numeric] number of milliseconds to sleep past this +Instant+
-    # @return [Duration] the slept duration, if +#positive?+, else the overshot time
-    # @see #sleep
-    def sleep_millis(millis)
-      sleep(Duration.from_millis(millis))
-    end
-
-    # Sugar for +#elapsed.to_s+.
-    #
-    # @see Duration#to_s
-    def to_s(*args)
-      elapsed.to_s(*args)
-    end
-
-    # Add a +Duration+ or +#to_nanos+-coercible object to this +Instant+, returning
-    # a new +Instant+.
-    #
-    # @example
-    #   (Instant.now + Duration.from_secs(1)).to_s # => "-999.983976ms"
-    #
-    # @param other [Duration, #to_nanos]
-    # @return [Instant]
-    def +(other)
-      return TypeError, 'Not one of: [Duration, #to_nanos]' unless other.respond_to?(:to_nanos)
-
-      Instant.new(@ns + other.to_nanos)
-    end
-
-    # Subtract another +Instant+ to generate a +Duration+ between the two,
-    # or a +Duration+ or +#to_nanos+-coercible object, to generate an +Instant+
-    # offset by it.
-    #
-    # @example
-    #   (Instant.now - Duration.from_secs(1)).to_s # => "1.000016597s"
-    #   (Instant.now - Instant.now).to_s           # => "-3.87μs"
-    #
-    # @param other [Instant, Duration, #to_nanos]
-    # @return [Duration, Instant]
-    def -(other)
-      if other.is_a?(Instant)
-        Duration.new(@ns - other.ns)
-      elsif other.respond_to?(:to_nanos)
-        Instant.new(@ns - other.to_nanos)
-      else
-        raise TypeError, 'Not one of: [Instant, Duration, #to_nanos]'
-      end
-    end
-
-    # Determine if the given +Instant+ is before, equal to or after this one.
-    # +nil+ if not passed an +Instant+.
-    #
-    # @return [-1, 0, 1, nil]
-    def <=>(other)
-      @ns <=> other.ns if other.is_a?(Instant)
-    end
-
-    # Determine if +other+'s value equals that of this +Instant+.
-    # Use +eql?+ if type checks are desired for future compatibility.
-    #
-    # @return [Boolean]
-    # @see #eql?
-    def ==(other)
-      other.is_a?(Instant) && @ns == other.ns
-    end
-
-    alias eql? ==
-
-    # Generate a hash for this type and value.
-    #
-    # @return [Integer]
-    def hash
-      self.class.hash ^ @ns.hash
-    end
-  end
-
-  # A type representing a span of time in nanoseconds.
-  class Duration
-    include Comparable
-
-    # Create a new +Duration+ of a specified number of nanoseconds, zero by
-    # default.
-    #
-    # Users are strongly advised to use +#from_nanos+ instead.
-    #
-    # @param nanos [Integer]
-    # @see #from_nanos
-    def initialize(nanos = 0)
-      @ns = Integer(nanos)
-    end
-
-    class << self
-      # Generate a new +Duration+ measuring the given number of seconds.
-      #
-      # @param secs [Numeric]
-      # @return [Duration]
-      def from_secs(secs)
-        new(Integer(secs * 1_000_000_000))
-      end
-
-      alias secs from_secs
-
-      # Generate a new +Duration+ measuring the given number of milliseconds.
-      #
-      # @param millis [Numeric]
-      # @return [Duration]
-      def from_millis(millis)
-        new(Integer(millis * 1_000_000))
-      end
-
-      alias millis from_millis
-
-      # Generate a new +Duration+ measuring the given number of microseconds.
-      #
-      # @param micros [Numeric]
-      # @return [Duration]
-      def from_micros(micros)
-        new(Integer(micros * 1_000))
-      end
-
-      alias micros from_micros
-
-      # Generate a new +Duration+ measuring the given number of nanoseconds.
-      #
-      # @param nanos [Numeric]
-      # @return [Duration]
-      def from_nanos(nanos)
-        new(Integer(nanos))
-      end
-
-      alias nanos from_nanos
-
-      # Return a +Duration+ measuring the elapsed time of the yielded block.
-      #
-      # @example
-      #   Duration.measure { sleep(0.5) }.to_s # => "512.226109ms"
-      #
-      # @return [Duration]
-      def measure
-        Instant.now.tap { yield }.elapsed
-      end
-    end
-
-    # Add another +Duration+ or +#to_nanos+-coercible object to this one,
-    # returning a new +Duration+.
-    #
-    # @example
-    #   (Duration.from_secs(10) + Duration.from_secs(5)).to_s # => "15s"
-    #
-    # @param [Duration, #to_nanos]
-    # @return [Duration]
-    def +(other)
-      raise TypeError, 'Not one of: [Duration, #to_nanos]' unless other.respond_to?(:to_nanos)
-
-      Duration.new(to_nanos + other.to_nanos)
-    end
-
-    # Subtract another +Duration+ or +#to_nanos+-coercible object from this one,
-    # returning a new +Duration+.
-    #
-    # @example
-    #   (Duration.from_secs(10) - Duration.from_secs(5)).to_s # => "5s"
-    #
-    # @param [Duration, #to_nanos]
-    # @return [Duration]
-    def -(other)
-      raise TypeError, 'Not one of: [Duration, #to_nanos]' unless other.respond_to?(:to_nanos)
-
-      Duration.new(to_nanos - other.to_nanos)
-    end
-
-    # Divide this duration by a +Numeric+.
-    #
-    # @example
-    #   (Duration.from_secs(10) / 2).to_s # => "5s"
-    #
-    # @param [Numeric]
-    # @return [Duration]
-    def /(other)
-      Duration.new(to_nanos / other)
-    end
-
-    # Multiply this duration by a +Numeric+.
-    #
-    # @example
-    #   (Duration.from_secs(10) * 2).to_s # => "20s"
-    #
-    # @param [Numeric]
-    # @return [Duration]
-    def *(other)
-      Duration.new(to_nanos * other)
-    end
-
-    # Unary minus: make a positive +Duration+ negative, and vice versa.
-    #
-    # @example
-    #   -Duration.from_secs(-1).to_s # => "1s"
-    #   -Duration.from_secs(1).to_s  # => "-1s"
-    #
-    # @return [Duration]
-    def -@
-      Duration.new(-to_nanos)
-    end
-
-    # Return a +Duration+ that's absolute (positive).
-    #
-    # @example
-    #   Duration.from_secs(-1).abs.to_s # => "1s"
-    #   Duration.from_secs(1).abs.to_s  # => "1s"
-    #
-    # @return [Duration]
-    def abs
-      return self if positive? || zero?
-      Duration.new(to_nanos.abs)
-    end
-
-    # Compare the *value* of this +Duration+ with another, or any +#to_nanos+-coercible
-    # object, or nil if not comparable.
-    #
-    # @param [Duration, #to_nanos, Object]
-    # @return [-1, 0, 1, nil]
-    def <=>(other)
-      to_nanos <=> other.to_nanos if other.respond_to?(:to_nanos)
-    end
-
-    # Compare the equality of the *value* of this +Duration+ with another, or
-    # any +#to_nanos+-coercible object, or nil if not comparable.
-    #
-    # @param [Duration, #to_nanos, Object]
-    # @return [Boolean]
-    def ==(other)
-      other.respond_to?(:to_nanos) && to_nanos == other.to_nanos
-    end
-
-    # Check equality of the value and type of this +Duration+ with another.
-    #
-    # @param [Duration, Object]
-    # @return [Boolean]
-    def eql?(other)
-      other.is_a?(Duration) && to_nanos == other.to_nanos
-    end
-
-    # Generate a hash for this type and value.
-    #
-    # @return [Integer]
-    def hash
-      self.class.hash ^ to_nanos.hash
-    end
-
-    # Return this +Duration+ in seconds.
-    #
-    # @return [Float]
-    def to_secs
-      to_nanos / 1_000_000_000.0
-    end
-
-    alias secs to_secs
-
-    # Return this +Duration+ in milliseconds.
-    #
-    # @return [Float]
-    def to_millis
-      to_nanos / 1_000_000.0
-    end
-
-    alias millis to_millis
-
-    # Return this +Duration+ in microseconds.
-    #
-    # @return [Float]
-    def to_micros
-      to_nanos / 1_000.0
-    end
-
-    alias micros to_micros
-
-    # Return this +Duration+ in nanoseconds.
-    #
-    # @return [Integer]
-    def to_nanos
-      @ns
-    end
-
-    alias nanos to_nanos
-
-    # Return true if this +Duration+ is positive.
-    #
-    # @return [Boolean]
-    def positive?
-      to_nanos.positive?
-    end
-
-    # Return true if this +Duration+ is negative.
-    #
-    # @return [Boolean]
-    def negative?
-      to_nanos.negative?
-    end
-
-    # Return true if this +Duration+ is zero.
-    #
-    # @return [Boolean]
-    def zero?
-      to_nanos.zero?
-    end
-
-    # Return true if this +Duration+ is non-zero.
-    #
-    # @return [Boolean]
-    def nonzero?
-      to_nanos.nonzero?
-    end
-
-    # Sleep for the duration of this +Duration+.  Equivalent to
-    # +Kernel.sleep(duration.to_secs)+.
-    #
-    # @example
-    #   Duration.from_secs(1).sleep  # => 1
-    #   Duration.from_secs(-1).sleep # => raises NotImplementedError
-    #
-    # @raise [NotImplementedError] negative +Duration+ sleeps are not yet supported.
-    # @return [Integer]
-    # @see Instant#sleep
-    def sleep
-      raise NotImplementedError, 'time travel module missing' if negative?
-      Kernel.sleep(to_secs)
-    end
-
-    DIVISORS = [
-      [1_000_000_000.0, 's'],
-      [1_000_000.0, 'ms'],
-      [1_000.0, 'μs'],
-      [0, 'ns']
-    ].map(&:freeze).freeze
-
-    private_constant :DIVISORS
-
-    # 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.
-    #
-    # @example
-    #   Duration.from_nanos(100).to_s  # => "100ns"
-    #   Duration.from_micros(100).to_s # => "100μs"
-    #   Duration.from_millis(100).to_s # => "100ms"
-    #   Duration.from_secs(100).to_s   # => "100s"
-    #   Duration.from_nanos(1234567).to_s # => "1.234567ms"
-    #   Duration.from_nanos(1234567).to_s(2) # => "1.23ms"
-    #
-    # @param precision [Integer] the maximum number of decimal places
-    # @return [String]
-    def to_s(precision = 9)
-      precision = Integer(precision).abs
-      div, unit = DIVISORS.find { |d, _| to_nanos.abs >= d }
-
-      if div.zero?
-        format('%d%s', to_nanos, unit)
-      else
-        format("%#.#{precision}f", to_nanos / div).sub(/\.?0*\z/, '') << unit
-      end
-    end
-  end
-end
+require_relative 'monotime/version'
+require_relative 'monotime/duration'
+require_relative 'monotime/instant'

data/lib/monotime/duration.rb

@@ -0,0 +1,306 @@
+# frozen_string_literal: true
+
+module Monotime
+  # A type representing a span of time in nanoseconds.
+  class Duration
+    include Comparable
+
+    # Create a new +Duration+ of a specified number of nanoseconds, zero by
+    # default.
+    #
+    # Users are strongly advised to use +#from_nanos+ instead.
+    #
+    # @param nanos [Integer]
+    # @see #from_nanos
+    def initialize(nanos = 0)
+      @ns = Integer(nanos)
+    end
+
+    class << self
+      # Generate a new +Duration+ measuring the given number of seconds.
+      #
+      # @param secs [Numeric]
+      # @return [Duration]
+      def from_secs(secs)
+        new(Integer(secs * 1_000_000_000))
+      end
+
+      alias secs from_secs
+
+      # Generate a new +Duration+ measuring the given number of milliseconds.
+      #
+      # @param millis [Numeric]
+      # @return [Duration]
+      def from_millis(millis)
+        new(Integer(millis * 1_000_000))
+      end
+
+      alias millis from_millis
+
+      # Generate a new +Duration+ measuring the given number of microseconds.
+      #
+      # @param micros [Numeric]
+      # @return [Duration]
+      def from_micros(micros)
+        new(Integer(micros * 1_000))
+      end
+
+      alias micros from_micros
+
+      # Generate a new +Duration+ measuring the given number of nanoseconds.
+      #
+      # @param nanos [Numeric]
+      # @return [Duration]
+      def from_nanos(nanos)
+        new(Integer(nanos))
+      end
+
+      alias nanos from_nanos
+
+      # Return a +Duration+ measuring the elapsed time of the yielded block.
+      #
+      # @example
+      #   Duration.measure { sleep(0.5) }.to_s # => "512.226109ms"
+      #
+      # @return [Duration]
+      def measure
+        Instant.now.tap { yield }.elapsed
+      end
+
+      # Return the result of the yielded block alongside a +Duration+.
+      #
+      # @example
+      #   Duration.with_measure { "bloop" } # => ["bloop", #<Monotime::Duration: ...>]
+      #
+      # @return [Object, Duration]
+      def with_measure
+        start = Instant.now
+        ret = yield
+        [ret, start.elapsed]
+      end
+    end
+
+    # Add another +Duration+ or +#to_nanos+-coercible object to this one,
+    # returning a new +Duration+.
+    #
+    # @example
+    #   (Duration.from_secs(10) + Duration.from_secs(5)).to_s # => "15s"
+    #
+    # @param [Duration, #to_nanos]
+    # @return [Duration]
+    def +(other)
+      raise TypeError, 'Not one of: [Duration, #to_nanos]' unless other.respond_to?(:to_nanos)
+
+      Duration.new(to_nanos + other.to_nanos)
+    end
+
+    # Subtract another +Duration+ or +#to_nanos+-coercible object from this one,
+    # returning a new +Duration+.
+    #
+    # @example
+    #   (Duration.from_secs(10) - Duration.from_secs(5)).to_s # => "5s"
+    #
+    # @param [Duration, #to_nanos]
+    # @return [Duration]
+    def -(other)
+      raise TypeError, 'Not one of: [Duration, #to_nanos]' unless other.respond_to?(:to_nanos)
+
+      Duration.new(to_nanos - other.to_nanos)
+    end
+
+    # Divide this duration by a +Numeric+.
+    #
+    # @example
+    #   (Duration.from_secs(10) / 2).to_s # => "5s"
+    #
+    # @param [Numeric]
+    # @return [Duration]
+    def /(other)
+      Duration.new(to_nanos / other)
+    end
+
+    # Multiply this duration by a +Numeric+.
+    #
+    # @example
+    #   (Duration.from_secs(10) * 2).to_s # => "20s"
+    #
+    # @param [Numeric]
+    # @return [Duration]
+    def *(other)
+      Duration.new(to_nanos * other)
+    end
+
+    # Unary minus: make a positive +Duration+ negative, and vice versa.
+    #
+    # @example
+    #   -Duration.from_secs(-1).to_s # => "1s"
+    #   -Duration.from_secs(1).to_s  # => "-1s"
+    #
+    # @return [Duration]
+    def -@
+      Duration.new(-to_nanos)
+    end
+
+    # Return a +Duration+ that's absolute (positive).
+    #
+    # @example
+    #   Duration.from_secs(-1).abs.to_s # => "1s"
+    #   Duration.from_secs(1).abs.to_s  # => "1s"
+    #
+    # @return [Duration]
+    def abs
+      return self if positive? || zero?
+
+      Duration.new(to_nanos.abs)
+    end
+
+    # Compare the *value* of this +Duration+ with another, or any +#to_nanos+-coercible
+    # object, or nil if not comparable.
+    #
+    # @param [Duration, #to_nanos, Object]
+    # @return [-1, 0, 1, nil]
+    def <=>(other)
+      to_nanos <=> other.to_nanos if other.respond_to?(:to_nanos)
+    end
+
+    # Compare the equality of the *value* of this +Duration+ with another, or
+    # any +#to_nanos+-coercible object, or nil if not comparable.
+    #
+    # @param [Duration, #to_nanos, Object]
+    # @return [Boolean]
+    def ==(other)
+      other.respond_to?(:to_nanos) && to_nanos == other.to_nanos
+    end
+
+    # Check equality of the value and type of this +Duration+ with another.
+    #
+    # @param [Duration, Object]
+    # @return [Boolean]
+    def eql?(other)
+      other.is_a?(Duration) && to_nanos == other.to_nanos
+    end
+
+    # Generate a hash for this type and value.
+    #
+    # @return [Integer]
+    def hash
+      self.class.hash ^ to_nanos.hash
+    end
+
+    # Return this +Duration+ in seconds.
+    #
+    # @return [Float]
+    def to_secs
+      to_nanos / 1_000_000_000.0
+    end
+
+    alias secs to_secs
+
+    # Return this +Duration+ in milliseconds.
+    #
+    # @return [Float]
+    def to_millis
+      to_nanos / 1_000_000.0
+    end
+
+    alias millis to_millis
+
+    # Return this +Duration+ in microseconds.
+    #
+    # @return [Float]
+    def to_micros
+      to_nanos / 1_000.0
+    end
+
+    alias micros to_micros
+
+    # Return this +Duration+ in nanoseconds.
+    #
+    # @return [Integer]
+    def to_nanos
+      @ns
+    end
+
+    alias nanos to_nanos
+
+    # Return true if this +Duration+ is positive.
+    #
+    # @return [Boolean]
+    def positive?
+      to_nanos.positive?
+    end
+
+    # Return true if this +Duration+ is negative.
+    #
+    # @return [Boolean]
+    def negative?
+      to_nanos.negative?
+    end
+
+    # Return true if this +Duration+ is zero.
+    #
+    # @return [Boolean]
+    def zero?
+      to_nanos.zero?
+    end
+
+    # Return true if this +Duration+ is non-zero.
+    #
+    # @return [Boolean]
+    def nonzero?
+      to_nanos.nonzero?
+    end
+
+    # Sleep for the duration of this +Duration+.  Equivalent to
+    # +Kernel.sleep(duration.to_secs)+.
+    #
+    # @example
+    #   Duration.from_secs(1).sleep  # => 1
+    #   Duration.from_secs(-1).sleep # => raises NotImplementedError
+    #
+    # @raise [NotImplementedError] negative +Duration+ sleeps are not yet supported.
+    # @return [Integer]
+    # @see Instant#sleep
+    def sleep
+      raise NotImplementedError, 'time travel module missing' if negative?
+
+      Kernel.sleep(to_secs)
+    end
+
+    DIVISORS = [
+      [1_000_000_000.0, 's'],
+      [1_000_000.0, 'ms'],
+      [1_000.0, 'μs'],
+      [0, 'ns']
+    ].map(&:freeze).freeze
+
+    private_constant :DIVISORS
+
+    # 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.
+    #
+    # @example
+    #   Duration.from_nanos(100).to_s  # => "100ns"
+    #   Duration.from_micros(100).to_s # => "100μs"
+    #   Duration.from_millis(100).to_s # => "100ms"
+    #   Duration.from_secs(100).to_s   # => "100s"
+    #   Duration.from_nanos(1234567).to_s # => "1.234567ms"
+    #   Duration.from_nanos(1234567).to_s(2) # => "1.23ms"
+    #
+    # @param precision [Integer] the maximum number of decimal places
+    # @return [String]
+    def to_s(precision = 9)
+      precision = Integer(precision).abs
+      div, unit = DIVISORS.find { |d, _| to_nanos.abs >= d }
+
+      if div.zero?
+        format('%d%s', to_nanos, unit)
+      else
+        format("%#.#{precision}f", to_nanos / div).sub(/\.?0*\z/, '') << unit
+      end
+    end
+  end
+end

data/lib/monotime/instant.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module Monotime
+  # A measurement from the operating system's monotonic clock, with up to
+  # nanosecond precision.
+  class Instant
+    # A measurement, in nanoseconds.  Should be considered opaque and
+    # non-portable outside the process that created it.
+    attr_reader :ns
+    protected :ns
+
+    include Comparable
+
+    # Create a new +Instant+ from an optional nanosecond measurement.
+    #
+    # Users should generally *not* pass anything to this function.
+    #
+    # @param nanos [Integer]
+    # @see #now
+    def initialize(nanos = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond))
+      @ns = Integer(nanos)
+    end
+
+    # An alias to +new+, and generally preferred over it.
+    #
+    # @return [Instant]
+    def self.now
+      new
+    end
+
+    # Return a +Duration+ between this +Instant+ and another.
+    #
+    # @param earlier [Instant]
+    # @return [Duration]
+    def duration_since(earlier)
+      raise TypeError, 'Not an Instant' unless earlier.is_a?(Instant)
+
+      earlier - self
+    end
+
+    # Return a +Duration+ since this +Instant+ and now.
+    #
+    # @return [Duration]
+    def elapsed
+      duration_since(self.class.now)
+    end
+
+    # Return whether this +Instant+ is in the past.
+    #
+    # @return [Boolean]
+    def in_past?
+      elapsed.positive?
+    end
+
+    alias past? in_past?
+
+    # Return whether this +Instant+ is in the future.
+    #
+    # @return [Boolean]
+    def in_future?
+      elapsed.negative?
+    end
+
+    alias future? in_future?
+
+    # Sleep until this +Instant+, plus an optional +Duration+, returning a +Duration+
+    # that's either positive if any time was slept, or negative if sleeping would
+    # require time travel.
+    #
+    # @example Sleeps for a second
+    #   start = Instant.now
+    #   sleep 0.5 # do stuff for half a second
+    #   start.sleep(Duration.from_secs(1)).to_s # => "490.088706ms" (slept)
+    #   start.sleep(Duration.from_secs(1)).to_s # => "-12.963502ms" (did not sleep)
+    #
+    # @example Also sleeps for a second.
+    #   one_second_in_the_future = Instant.now + Duration.from_secs(1)
+    #   one_second_in_the_future.sleep.to_s     # => "985.592712ms" (slept)
+    #   one_second_in_the_future.sleep.to_s     # => "-4.71217ms" (did not sleep)
+    #
+    # @param duration [nil, Duration, #to_nanos]
+    # @return [Duration] the slept duration, if +#positive?+, else the overshot time
+    def sleep(duration = nil)
+      remaining = duration ? duration - elapsed : -elapsed
+
+      remaining.tap { |rem| rem.sleep if rem.positive? }
+    end
+
+    # Sleep for the given number of seconds past this +Instant+, if any.
+    #
+    # Equivalent to +#sleep(Duration.from_secs(secs))+
+    #
+    # @param secs [Numeric] number of seconds to sleep past this +Instant+
+    # @return [Duration] the slept duration, if +#positive?+, else the overshot time
+    # @see #sleep
+    def sleep_secs(secs)
+      sleep(Duration.from_secs(secs))
+    end
+
+    # Sleep for the given number of milliseconds past this +Instant+, if any.
+    #
+    # Equivalent to +#sleep(Duration.from_millis(millis))+
+    #
+    # @param millis [Numeric] number of milliseconds to sleep past this +Instant+
+    # @return [Duration] the slept duration, if +#positive?+, else the overshot time
+    # @see #sleep
+    def sleep_millis(millis)
+      sleep(Duration.from_millis(millis))
+    end
+
+    # Sugar for +#elapsed.to_s+.
+    #
+    # @see Duration#to_s
+    def to_s(*args)
+      elapsed.to_s(*args)
+    end
+
+    # Add a +Duration+ or +#to_nanos+-coercible object to this +Instant+, returning
+    # a new +Instant+.
+    #
+    # @example
+    #   (Instant.now + Duration.from_secs(1)).to_s # => "-999.983976ms"
+    #
+    # @param other [Duration, #to_nanos]
+    # @return [Instant]
+    def +(other)
+      return TypeError, 'Not one of: [Duration, #to_nanos]' unless other.respond_to?(:to_nanos)
+
+      Instant.new(@ns + other.to_nanos)
+    end
+
+    # Subtract another +Instant+ to generate a +Duration+ between the two,
+    # or a +Duration+ or +#to_nanos+-coercible object, to generate an +Instant+
+    # offset by it.
+    #
+    # @example
+    #   (Instant.now - Duration.from_secs(1)).to_s # => "1.000016597s"
+    #   (Instant.now - Instant.now).to_s           # => "-3.87μs"
+    #
+    # @param other [Instant, Duration, #to_nanos]
+    # @return [Duration, Instant]
+    def -(other)
+      if other.is_a?(Instant)
+        Duration.new(@ns - other.ns)
+      elsif other.respond_to?(:to_nanos)
+        Instant.new(@ns - other.to_nanos)
+      else
+        raise TypeError, 'Not one of: [Instant, Duration, #to_nanos]'
+      end
+    end
+
+    # Determine if the given +Instant+ is before, equal to or after this one.
+    # +nil+ if not passed an +Instant+.
+    #
+    # @return [-1, 0, 1, nil]
+    def <=>(other)
+      @ns <=> other.ns if other.is_a?(Instant)
+    end
+
+    # Determine if +other+'s value equals that of this +Instant+.
+    # Use +eql?+ if type checks are desired for future compatibility.
+    #
+    # @return [Boolean]
+    # @see #eql?
+    def ==(other)
+      other.is_a?(Instant) && @ns == other.ns
+    end
+
+    alias eql? ==
+
+    # Generate a hash for this type and value.
+    #
+    # @return [Integer]
+    def hash
+      self.class.hash ^ @ns.hash
+    end
+  end
+end

data/lib/monotime/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Monotime
-  VERSION = '0.6.1'
+  # Try to avoid blatting existing VERSION constants when we're included.
+  MONOTIME_VERSION = '0.7.0'
 end

data/monotime.gemspec

@@ -5,7 +5,7 @@ require "monotime/version"
 
 Gem::Specification.new do |spec|
   spec.name          = "monotime"
-  spec.version       = Monotime::VERSION
+  spec.version       = Monotime::MONOTIME_VERSION
   spec.authors       = ["Thomas Hurst"]
   spec.email         = ["tom@hur.st"]
 
@@ -31,7 +31,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.16"
+  spec.add_development_dependency "bundler", "~> 2"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "minitest", "~> 5.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: monotime
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Thomas Hurst
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-10-26 00:00:00.000000000 Z
+date: 2019-04-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.16'
+        version: '2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.16'
+        version: '2'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -70,6 +70,8 @@ files:
 - bin/console
 - bin/setup
 - lib/monotime.rb
+- lib/monotime/duration.rb
+- lib/monotime/instant.rb
 - lib/monotime/version.rb
 - monotime.gemspec
 homepage: https://github.com/Freaky/monotime