monotime 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d77cca7907b76e8276296abc382f10612e7879605f7472ab46e4b26c9594426d
-  data.tar.gz: d4d1284f11de89438125a3e28e4686bdde6a78cf02a431d3eb57e861e7345613
+  metadata.gz: 54cec038f8a6e79cbfaf1364c22a2733b9c155d15562ac6c4181568e254ce3f2
+  data.tar.gz: f2fb3122d163d62cbfe6c148a547af7917efad19a30032695a34949bdf5758e4
 SHA512:
-  metadata.gz: 4975756b4d469b02437d7ad45216eef58d5e20b3675f6c725c64d1b8d1da3518c5eec89fc98cbc1d9d0e6238665232e837415783726132b757cf2e19ab2ef4fc
-  data.tar.gz: cfe8ffd03b80d308d512f5df277e5b9d82c6c88f47cb048390245dd8b34f598e03c41ad9286576add9f75dfdd1cbb2230101b60dc6bed844f85de9fab1247a76
+  metadata.gz: 708d7018fc1d90987b00074545ff351ab31ba60a37e3808092f85d48f0dce660380895c8fd0fa3e9f1038deb958a2274e730e2119d73f582377c72ef9aebe6a4
+  data.tar.gz: 0a5cd0b6f7ffb5a50f6d31efd21d4887e9130dec54551bb1e04642c7ada69532b12c4f4bf432b97ada9b4ba5be6d9e0f1ced6c307c6488df7dbb87199fec7853

data/.travis.yml

@@ -4,4 +4,5 @@ language: ruby
 cache: bundler
 rvm:
   - 2.5.1
+  - jruby
 before_install: gem install bundler -v 1.16.3

data/README.md

@@ -1,3 +1,6 @@
+[![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)
+
 # Monotime
 
 A sensible interface to Ruby's monotonic clock, inspired by Rust.
@@ -62,6 +65,8 @@ And how to do basic maths on itself:
 ```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"
 ```
 
 `Instant` does some simple maths too:
@@ -77,6 +82,53 @@ And how to do basic maths on itself:
 `Duration` and `Instant` are also `Comparable` with other instances of their
 type, and support `#hash` for use in, er, hashes.
 
+## Sleeping
+
+`Duration` can be used to sleep a thread, assuming it's positive (time travel
+is not yet implemented):
+
+```ruby
+# Equivalent
+sleep(Duration.from_secs(1).to_secs)  # => 1
+
+Duration.from_secs(1).sleep           # => 1
+```
+
+So can `Instant`, taking a `Duration` and sleeping until the given `Duration`
+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)
+loop do
+  start = Instant.now
+  poke_my_api(api_to_poke, what_to_poke_it_with)
+  start.sleep(poke_duration) # sleeps 60 seconds minus how long poke_my_api took
+  # alternative: start.sleep_secs(60)
+end
+```
+
+`Instant#sleep` returns a `Duration` which was slept, or a negative `Duration` if
+the desired sleep period has passed.
+
+## Duration duck typing
+
+Operations taking a `Duration` can also accept any type which implements
+`#to_nanos`, returning an (Integer) number of nanoseconds the value represents.
+
+For example, to treat built-in numeric types as second durations, you could do:
+
+```ruby
+class Numeric
+  def to_nanos
+    Integer(self * 1_000_000_000)
+  end
+end
+
+(Duration.from_secs(1) + 41).to_s  # => "42s"
+(Instant.now - 42).to_s            # => "42.000010545s"
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/monotime/version.rb

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

data/lib/monotime.rb

@@ -45,14 +45,54 @@ module Monotime
       duration_since(self.class.now)
     end
 
-    # Sugar for +elapsed.to_s+.
+    # Sleep for the given `Duration` past this +Instant+, if any.
+    #
+    # @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)
+    #
+    # @param duration [Duration, #to_nanos]
+    # @return [Duration] the slept duration, if +#positive?+, else the overshot time
+    def sleep(duration)
+      remaining = duration - elapsed
+
+      return remaining unless remaining.positive?
+      remaining.tap(&:sleep)
+    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(secs)
+      sleep(Duration.from_millis(secs))
+    end
+
+    # Sugar for +#elapsed.to_s+.
     #
     # @see Duration#to_s
     def to_s(*args)
       elapsed.to_s(*args)
     end
 
-    # Add a +Duration+ to this +Instant+, returning a new +Instant+.
+    # Add a +Duration+ or +#to_nanos+-coercible object to this +Instant+, returning
+    # a new +Instant+.
     #
     # @param other [Duration, #to_nanos]
     # @return [Instant]
@@ -63,7 +103,8 @@ module Monotime
     end
 
     # Subtract another +Instant+ to generate a +Duration+ between the two,
-    # or a +Duration+, to generate an +Instant+ offset by it.
+    # or a +Duration+ or +#to_nanos+-coercible object, to generate an +Instant+
+    # offset by it.
     #
     # @param other [Instant, Duration, #to_nanos]
     # @return [Duration, Instant]
@@ -77,17 +118,28 @@ module Monotime
       end
     end
 
-    # Compare this +Instant+ with another.
+    # 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 [Fixnum]
     def hash
       self.class.hash ^ @ns.hash
     end
@@ -146,7 +198,8 @@ module Monotime
       end
     end
 
-    # Add another +Duration+ to this one, returning a new +Duration+.
+    # Add another +Duration+ or +#to_nanos+-coercible object to this one,
+    # returning a new +Duration+.
     #
     # @param [Duration, #to_nanos]
     #
@@ -157,7 +210,8 @@ module Monotime
       Duration.new(to_nanos + other.to_nanos)
     end
 
-    # Subtract another +Duration+ from this one, returning a new +Duration+.
+    # Subtract another +Duration+ or +#to_nanos+-coercible object from this one,
+    # returning a new +Duration+.
     #
     # @param [Duration, #to_nanos]
     # @return [Duration]
@@ -167,17 +221,51 @@ module Monotime
       Duration.new(to_nanos - other.to_nanos)
     end
 
-    # Compare this +Duration+ with another.
+    # Divide this duration by a +Numeric+.
+    #
+    # @param [Numeric]
+    # @return [Duration]
+    def /(other)
+      Duration.new(to_nanos / other)
+    end
+
+    # Multiply this duration by a +Numeric+.
+    #
+    # @param [Numeric]
+    # @return [Duration]
+    def *(other)
+      Duration.new(to_nanos * other)
+    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.is_a? Duration
+      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.is_a?(Duration) && to_nanos == other.to_nanos
+      other.respond_to?(:to_nanos) && to_nanos == other.to_nanos
     end
 
-    alias eql? ==
+    # 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 [Fixnum]
     def hash
       self.class.hash ^ to_nanos.hash
     end
@@ -210,6 +298,38 @@ module Monotime
       @ns
     end
 
+    # 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
+
+    # Sleep for the duration of this +Duration+.  Equivalent to
+    # +Kernel.sleep(duration.to_secs)+.
+    #
+    # @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'],
@@ -232,7 +352,7 @@ module Monotime
       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 = format("#{'-' if negative?}%.#{precision}f", ns)
       num.sub!(/\.?0*$/, '') if precision.nonzero?
       num << unit
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: monotime
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Thomas Hurst
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-10-04 00:00:00.000000000 Z
+date: 2018-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler