monotime 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54cec038f8a6e79cbfaf1364c22a2733b9c155d15562ac6c4181568e254ce3f2
-  data.tar.gz: f2fb3122d163d62cbfe6c148a547af7917efad19a30032695a34949bdf5758e4
+  metadata.gz: bbb84fdd4db4d629ca5d4cc847c47d9003f4553f010b575364f7ad562c16bb4d
+  data.tar.gz: 40729463ba3970e77110c2ae92620f4d6ca08b6d9997776272a3d0a05a03b595
 SHA512:
-  metadata.gz: 708d7018fc1d90987b00074545ff351ab31ba60a37e3808092f85d48f0dce660380895c8fd0fa3e9f1038deb958a2274e730e2119d73f582377c72ef9aebe6a4
-  data.tar.gz: 0a5cd0b6f7ffb5a50f6d31efd21d4887e9130dec54551bb1e04642c7ada69532b12c4f4bf432b97ada9b4ba5be6d9e0f1ced6c307c6488df7dbb87199fec7853
+  metadata.gz: 2916513d7d5dada28d18855d7644055cf82ddd6d2ad66ebd27c7a73d9ae2c88cde94887e7769d007372768c7acbcac32d8210308f9bc2ba2256b150126f29d9b
+  data.tar.gz: cff3a4bd7be443460f7dfc65432da3f3d30fef62433e5caa73c932497d490fdc5641b34659f18d8790bb0797449d93b9019f46678c0489b3aa9756c871222bd1

data/.rubocop.yml

@@ -1,2 +1,11 @@
 Metrics/LineLength:
   Max: 96
+
+Style/AsciiComments:
+  Enabled: false
+
+Style/AccessModifierDeclarations:
+  Enabled: false
+
+Style/FormatStringToken:
+  Enabled: false

data/README.md

@@ -108,6 +108,14 @@ loop do
 end
 ```
 
+Or you can declare a future `Instant` and ask to sleep until it passes:
+
+```ruby
+next_minute = Instant.now + Duration.from_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.
 

data/lib/monotime.rb

@@ -8,7 +8,8 @@ module Monotime
   class Instant
     # A measurement, in nanoseconds.  Should be considered opaque and
     # non-portable outside the process that created it.
-    protected def ns() @ns end
+    attr_reader :ns
+    protected :ns
 
     include Comparable
 
@@ -17,6 +18,7 @@ module Monotime
     # 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
@@ -45,7 +47,9 @@ module Monotime
       duration_since(self.class.now)
     end
 
-    # Sleep for the given `Duration` past this +Instant+, if any.
+    # 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
@@ -53,13 +57,17 @@ module Monotime
     #   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]
+    # @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)
-      remaining = duration - elapsed
+    def sleep(duration = nil)
+      remaining = duration ? duration - elapsed : -elapsed
 
-      return remaining unless remaining.positive?
-      remaining.tap(&:sleep)
+      remaining.tap { |rem| rem.sleep if rem.positive? }
     end
 
     # Sleep for the given number of seconds past this +Instant+, if any.
@@ -80,8 +88,8 @@ module Monotime
     # @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))
+    def sleep_millis(millis)
+      sleep(Duration.from_millis(millis))
     end
 
     # Sugar for +#elapsed.to_s+.
@@ -94,6 +102,9 @@ module Monotime
     # 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)
@@ -106,6 +117,10 @@ module Monotime
     # 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)
@@ -152,7 +167,10 @@ module Monotime
     # 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
@@ -163,7 +181,7 @@ module Monotime
       # @param secs [Numeric]
       # @return [Duration]
       def from_secs(secs)
-        new(Integer(Float(secs) * 1_000_000_000))
+        new(Integer(secs * 1_000_000_000))
       end
 
       # Generate a new +Duration+ measuring the given number of milliseconds.
@@ -171,7 +189,7 @@ module Monotime
       # @param millis [Numeric]
       # @return [Duration]
       def from_millis(millis)
-        new(Integer(Float(millis) * 1_000_000))
+        new(Integer(millis * 1_000_000))
       end
 
       # Generate a new +Duration+ measuring the given number of microseconds.
@@ -179,7 +197,7 @@ module Monotime
       # @param micros [Numeric]
       # @return [Duration]
       def from_micros(micros)
-        new(Integer(Float(micros) * 1_000))
+        new(Integer(micros * 1_000))
       end
 
       # Generate a new +Duration+ measuring the given number of nanoseconds.
@@ -192,6 +210,9 @@ module Monotime
 
       # 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
@@ -201,8 +222,10 @@ module Monotime
     # Add another +Duration+ or +#to_nanos+-coercible object to this one,
     # returning a new +Duration+.
     #
-    # @param [Duration, #to_nanos]
+    # @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)
@@ -213,6 +236,9 @@ module Monotime
     # 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)
@@ -223,6 +249,9 @@ module Monotime
 
     # Divide this duration by a +Numeric+.
     #
+    # @example
+    #   (Duration.from_secs(10) / 2).to_s # => "5s"
+    #
     # @param [Numeric]
     # @return [Duration]
     def /(other)
@@ -231,12 +260,38 @@ module Monotime
 
     # 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.
     #
@@ -322,6 +377,10 @@ module Monotime
     # 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
@@ -345,16 +404,66 @@ module Monotime
     # 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
-      ns = to_nanos.abs
-      div, unit = DIVISORS.find { |d, _| ns >= d }
-      ns /= div if div.nonzero?
-      num = format("#{'-' if negative?}%.#{precision}f", ns)
-      num.sub!(/\.?0*$/, '') if precision.nonzero?
-      num << unit
+      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
+
+    # def to_s_bigdecimal(precision = 9)
+    #   require 'bigdecimal'
+    #   precision = Integer(precision).abs
+    #   div, unit = DIVISORS.find { |d, _| to_nanos.abs >= d }
+
+    #   if div.zero?
+    #     format('%d%s', to_nanos, unit)
+    #   else
+    #     num = (BigDecimal(to_nanos) / div.to_i)
+    #       .round(precision, :banker).to_s('F').sub(/\.?0*$/, '')
+    #     format('%s%s', num, unit)
+    #   end
+    # end
+
+    # def to_s_divmod(precision = 9)
+    #   precision = Integer(precision).abs
+
+    #   ns = to_nanos.abs
+    #   div, unit = DIVISORS.find { |d, _| ns >= d }
+
+    #   return format('%dns', to_nanos) if div.zero?
+
+    #   whole, frac = to_nanos.divmod(div.to_i)
+
+    #   if precision.zero? || frac.zero?
+    #     whole += 1 if frac > div / 2
+    #     return format('%d%s', whole, unit)
+    #   end
+
+    #   # XXX: still need to round: Duration.from_nanos(99999999999).to_s_divmod 7 # => 99.1s
+    #   p frac
+    #   frac = ((frac / div.to_f) * (10 ** precision)).round
+    #   if frac.to_s =~ /\A10*\z/ # erm...
+    #     whole += 1
+    #     frac = 0
+    #   end
+    #   num = format('%d.%d', whole, frac)
+    #   num.sub!(/\.?0*\z/, '') if precision.nonzero?
+    #   num << unit
+    # end
   end
 end

data/lib/monotime/version.rb

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

metadata

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