pretty_stopwatch 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6c38e209a9aed274b4b020c88f62f806d627b7f4f52b1bf6ac25c8d4ef90ca1
-  data.tar.gz: cbf674f15bd8ba525a3a22ed957f7de8eab06fe228c2dc749b9e56811cf97116
+  metadata.gz: 9a6ceb7faaa5c8fb188e743dbe175e30eeb1036beed7127163d35f087f78acf2
+  data.tar.gz: c8bc70a9c8ca23a056d99a4cda1f6a3006ac708f199552160793214efb840772
 SHA512:
-  metadata.gz: 6eea6338238a1def7bb6421e0183c9f19d7f5f22eb2909b293e8bdcda3809c32bd5f7cd9b9fb9bbd68e8c999ddcef423a59c5abb284b051766de4b5dc4ee19c4
-  data.tar.gz: 1caa1fd00ec324547fe0074deb304ebc3240abe4b314299a76440f8efadc823bb495c145c2cdfbd114ce9e1a62472b2ba4e829a62146eece0d7f25bd2770a475
+  metadata.gz: 3760e63b88048882ebbfe8592972b132556c3a426eeaf3473cc017458b2a930d0f6b9bb1e74bc6f0e7a24c8315820eb309736da5e53f59a7879efaf5044b1dfc
+  data.tar.gz: eac0582afb63bc7aff999bfaf83ae599e9ad72f2248f85a94dedfa8fc52db9c9f03f5e49c4977ad015200681d77bfd4e406e3abf628b50821e422c5e65250cd2

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+### 0.1.4
+* Documentation (YARD)
+
+### 0.1.3
+* Documentation / GEM configuration
+
+### 0.1.0
+* Initial Release

data/lib/pretty_stopwatch/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PrettyStopwatch
-  VERSION = "0.1.3"
+  VERSION = "0.1.4"
 end

data/lib/pretty_stopwatch.rb

@@ -1,43 +1,36 @@
 # frozen_string_literal: true
 
-require_relative "pretty_stopwatch/version"
-
-#
-# Based on the Guava Stopwatch com.google.common.base.Stopwatch
-# Credit: The Guava Authors
-#
-# = Basic Example:
-#   stopwatch = Stopwatch::create_started
-#   sleep(0.1)
-#   stopwatch.stop # optional
-#   puts "slept for #{stopwatch}" # to_s optional
-#   Output: "slept for 0.1014ms"
+# A simple Stopwatch with nanosecond precision and readable formatting.
 #
-# = Named Example:
-#   stopwatch = Stopwatch::create_started(:foo)
-#   sleep(0.1)
-#   puts "slept for #{stopwatch.get(:foo)}"
-#   Output: "slept for 0.1014ms"
+# Uses: Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond) to measure elapsed time.
 #
-# = Block Example:
-#   stopwatch = Stopwatch::time{sleep 0.1}
+# "The state-changing methods are not idempotent; it is an error to start or stop a stopwatch
+# that is already in the desired state."
 #
-# = Lambda Example:
-#   lambda = -> {sleep 0.15}
-#   stopwatch = Stopwatch::time(lambda)
-#
-# = Proc Example:
-#   proc = Proc.new {sleep 0.15}
-#   stopwatch = Stopwatch::time(proc)
-
-#   stopwatch = Stopwatch::create_started(:foo)
-#   sleep(0.1)
-#   puts "slept for #{stopwatch.get(:foo)}"
-#   Output: "slept for 0.1014ms"
+# Implementation based on the Guava Stopwatch class: 'com.google.common.base.Stopwatch' Credit: The Guava Authors
+# @example Basic Usage
+#     stopwatch = Stopwatch::create_started
+#     sleep(0.1)
+#     stopwatch.stop # optional
+#     puts "slept for #{stopwatch}" # to_s optional
+#     # slept for 100.02 ms
+# @example Named Example:
+#     stopwatch = Stopwatch::create_started(:foo)
+#     sleep(0.2)
+#     puts "#{stopwatch}"
+#     # 'foo' elapsed: 200.235 ms
+# @example Block:
+#     stopwatch = Stopwatch::time{sleep 0.1}
+# @example Lambda:
+#     lambda = -> {sleep 0.15}
+#     stopwatch = Stopwatch::time(lambda)
+# @example Proc:
+#     proc = Proc.new {sleep 0.15}
+#     stopwatch = Stopwatch::time(proc)
 class Stopwatch
-  # Stopwatch methods are not idempotent; it is an error to start or stop a stopwatch that is already in the desired state.
   class IllegalStateError < StandardError
   end
+
   attr_reader :name
   attr_reader :running
 
@@ -48,10 +41,12 @@ class Stopwatch
     @elapsed_nanos = elapsed_nanos
   end
 
+  # @return [Boolean]
   def running?
     @running
   end
 
+  # @return [Boolean]
   def stopped?
     !@running
   end
@@ -59,14 +54,29 @@ class Stopwatch
   private_class_method :new # private constructor
 
   class << self
+    # Creates a new Stopwatch, and starts it.
+    #
+    # @param name [String] (optional) the name of the Stopwatch
+    # @param elapsed_nanos [Integer] (optional) elapsed_nanos (use for testing)
+    # @return [Stopwatch]
     def create_started(name = nil, elapsed_nanos: 0)
       new(name, elapsed_nanos).start
     end
 
+    # Creates a new Stopwatch, but does not start it.
+    #
+    # @param name [String] (optional) the name of the Stopwatch
+    # @param elapsed_nanos [Integer] (optional) elapsed_nanos (use for testing)
+    # @return [Stopwatch]
     def create_unstarted(name = nil, elapsed_nanos: 0)
       new(name, elapsed_nanos)
     end
 
+    # Times the execution of the given callable/block using a new Stopwatch.
+    #
+    # @param callable [Callable] callable to execute and time
+    # @param block [Block] block to execute and time
+    # @return [Stopwatch] Stopped Stopwatch
     def time(callable = nil, &block)
       stopwatch = create_started
       if callable
@@ -80,6 +90,8 @@ class Stopwatch
     end
   end
 
+  # Starts the Stopwatch
+  # @return [Stopwatch]
   def start
     raise IllegalStateError, "Stopwatch is already running" if @running
     @running = true
@@ -87,6 +99,8 @@ class Stopwatch
     self
   end
 
+  # Stops the Stopwatch
+  # @return [Stopwatch]
   def stop
     raise IllegalStateError, "Stopwatch is already stopped" unless @running
     @elapsed_nanos += Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond) - @start_nanos
@@ -94,12 +108,15 @@ class Stopwatch
     self
   end
 
-  # reset the elapsed time and stop the stopwatch
+  # Stops the Stopwatch and resets the elapsed time
+  # @return [Stopwatch]
   def reset
     @running = false
     @elapsed_nanos = 0
+    self
   end
 
+  # @return [Integer]
   def elapsed_nanos
     if running?
       now = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
@@ -108,10 +125,12 @@ class Stopwatch
     @elapsed_nanos
   end
 
+  # @return [Integer]
   def elapsed_millis
     elapsed_nanos / 1_000_000
   end
 
+  # @return [String]
   def to_s
     value_with_unit = PrettyUnitFormatter.scale_nanos_with_unit(elapsed_nanos)
     return "'#{@name}' elapsed: #{value_with_unit}" if @name
@@ -137,13 +156,13 @@ class Stopwatch
       end
 
       def scale_nanos_with_unit(nanos)
-        return "0 ns" if nanos.zero?
+        return "0 ns" if nanos < 1
         unit = get_unit(nanos)
         value = nanos / unit[:divisor].to_f
         "#{format_float(value)} #{unit[:name]}"
       end
 
-      # format float to 3dp & remove trailing zeros
+      # @return [String] Rounded to 3dp and with trailing zeros removed
       private def format_float(float)
         sprintf("%f", float.round(3)).sub(/\.?0*$/, "")
       end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pretty_stopwatch
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Ben Mcfadyen
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-29 00:00:00.000000000 Z
+date: 2024-10-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -33,6 +33,7 @@ extra_rdoc_files: []
 files:
 - ".rspec"
 - ".standard.yml"
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
 - Rakefile