time_up 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e94465307a2737c930d8dbd195c92fe315850abf8c7be4b1c6f88f1eec2d1bd
-  data.tar.gz: 82cac53d1b5c18acdeb7312da3cc929bed1590e707d8ac8edeb0480fff13af29
+  metadata.gz: 5b040cfa422a59cc1c7f2157e8f7261ed1bdc7c470da76fead75b026159f02c8
+  data.tar.gz: 4b817578713714392dd0ab8f2694bce78c6ddf93e9b5eea16f302a5d4549c559
 SHA512:
-  metadata.gz: b0a1395d51df9233140f9f7b7dd49d6cdc3bc1c50eea76425da7300a6b165230c17452ecaf7b1721c50a9b87f788775913b93ada281906ab681a19376976a34c
-  data.tar.gz: 12856340affc8a8a298986c8b56c01198256346c5cd0caf8f7fac2726ea742d43fc05e113c7f93960c34cae08318b5c5ac912b5b5adb716e03748bef56818b1a
+  metadata.gz: 3b4fe6bff25861a0b9b76b95684e25eed9056886091556f22b70820251ea3f41b08879b2628dd8b8bee74e03720b0f39d7af87af5664c0bcaa152f7e8b88d329
+  data.tar.gz: e0b0953129fc39ed079d3b6addebf579d8defbebcda484649a9826ff0a3e3b2383360d7d8269572746b5f5469cb076d4e6fa770ed36735f1c2fe55f319c91c5b

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+# 0.0.3
+
+- Change the return value of TimeUp.start when passed a block to be the
+  evaluated value of the block (for easier insertion into existing code without
+  adding a bunch of new assignment and returns)
+- Allow timer instances' `start` method to be called with a block
+- Add `timings`, `count`, `min`, `max`, and `mean` methods for basic stats
+  tracking
+- Add `TimeUp.all_stats` to roll up all these
+
 # 0.0.2
 
 - Switch from a module method to Thread.current variable

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    time_up (0.0.2)
+    time_up (0.0.3)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -65,10 +65,10 @@ sleep 5
 puts TimeUp.stop :eggs # => ~5.0
 ```
 
-`TimeUp.start` also returns an instance of the named timer, which has its own
-`start`, `stop`, `elaped`, and `reset` methods. If you want to find that
-instance later, you can also call `TimeUp.timer(:some_name)`. So the above
-example could be rewritten as:
+When passes without a block, `TimeUp.start` returns an instance of the timer,
+which has its own `start`, `stop`, `elaped`, and `reset` methods. If you want to
+find that instance later, you can also call `TimeUp.timer(:some_name)`. So the
+above example could be rewritten as:
 
 ```ruby
 egg_timer = TimeUp.start :eggs
@@ -124,18 +124,35 @@ straightforward, so I'd encourage you to [read the code](/lib/time_up.rb).
 
 ### `TimeUp` module
 
-`TimeUp.start(name, [&blk])` - Starts (or restarts) and returns a named `Timer`
+`TimeUp.timer(name)` - Returns the `Timer` instance named `name` (creating it,
+if it doesn't exist)
 
-`TimeUp.timer(name)` - Returns any a `Timer` instance named `name` or `nil`
+`TimeUp.start(name, [&blk])` - Starts (or restarts) a named
+[Timer](#timeuptimer-class). If passed with a block, will return whatever the
+block evaluates to. If passed without a block, it will return the timer object
 
 `TimeUp.stop(name)` - Stops the named timer or raises if it's not defined
 
+`TimeUp.reset(name)` - Resets the named timer's elapsed time to 0, effectively
+restarting it if it's currently running. Raises if the timer isn't defined.
+
 `TimeUp.elapsed(name)` - Returns a `Float` of the total elapsed seconds that the
 named timer has been running (and raises if no timer is defined with the given
 `name`)
 
-`TimeUp.reset(name)` - Resets the named timer's elapsed time to 0, effectively
-restarting it if it's currently running. Raises if the timer isn't defined.
+`TimeUp.timings(name)` - Returns an array of each recorded start-to-stop
+duration of the timer (including the current one, if active)
+
+`TimeUp.count(name)` - The number of times the timer has been started and
+stopped (including the current timing, if active)
+
+`TimeUp.min(name)` - The shortest recording of the timer (including the current
+one, if active)
+
+`TimeUp.max(name)` - The longest recording of the timer (including the current
+one, if active)
+
+`TimeUp.mean(name)` - The arithmetic mean of all recorded durations of the timer
 
 `TimeUp.total_elapsed` - Returns a `Float` of the sum of `elapsed` for all the
 timers you've created
@@ -144,12 +161,17 @@ timers you've created
 `elapsed` values. Handy for grabbing a snapshot of the state of things at a
 particular point in time without stopping all your timers
 
+`TimeUp.all_stats` - Returns a hash of timer name keys mapped to another
+hash of their basic statistics (elapsed time, number of recordings, min, max,
+and mean)
+
 `TimeUp.active_timers` - Returns an array of all timers that are currently
 running. Useful for detecting cases where you might be counting the same time in
 multiple places simultaneously
 
-`TimeUp.print_summary([IO])` - Pretty-prints a multi-line summary of all your
-timers to STDOUT (or the provided IO)
+`TimeUp.print_summary([io])` - Pretty-prints a multi-line summary of all your
+timers to standard output (or the provided
+[IO](https://ruby-doc.org/core-3.0.1/IO.html))
 
 `TimeUp.stop_all` - Stops all timers
 
@@ -166,6 +188,20 @@ reference to them
 
 `elapsed` - A `Float` of the total elapsed seconds the timer has been running
 
+`timings` - Returns an array of each recorded start-to-stop duration of the
+timer (including the current one, if active)
+
+`count` - The number of times the timer has been started and stopped (including
+the current timing, if active)
+
+`min` - The shortest recording of the timer (including the current one, if
+active)
+
+`max` - The longest recording of the timer (including the current one, if
+active)
+
+`mean` - The arithmetic mean of all recorded durations of the timer
+
 `active?` - Returns `true` if the timer is running
 
 `reset(force: false)` - Resets the timer to 0 elapsed seconds. If `force` is

data/lib/time_up.rb

@@ -5,35 +5,29 @@ module TimeUp
 
   Thread.current[:time_up_timers] = {}
 
-  def self.start(name, &blk)
-    raise Error.new("Timer name must be a String or Symbol") unless name.is_a?(Symbol) || name.is_a?(String)
-    timer = __timers[name] ||= Timer.new(name)
-    timer.start
-    if blk
-      blk.call
-      timer.stop
-    end
-    timer
-  end
-
-  # Delegate methods
   def self.timer(name)
-    __timers[name]
+    __timers[name] ||= Timer.new(name)
   end
 
-  def self.stop(name)
-    __ensure_timer(name)
-    __timers[name].stop
-  end
-
-  def self.elapsed(name)
-    __ensure_timer(name)
-    __timers[name].elapsed
+  # Delegate methods
+  def self.start(name, &blk)
+    timer(name).start(&blk)
   end
 
-  def self.reset(name)
-    __ensure_timer(name)
-    __timers[name].reset
+  [
+    :stop,
+    :reset,
+    :elapsed,
+    :timings,
+    :count,
+    :min,
+    :max,
+    :mean
+  ].each do |method_name|
+    define_singleton_method method_name do |name|
+      __ensure_timer(name)
+      __timers[name].send(method_name)
+    end
   end
 
   # Interrogative methods
@@ -47,6 +41,18 @@ module TimeUp
     }.to_h
   end
 
+  def self.all_stats
+    __timers.values.map { |timer|
+      [timer.name, {
+        elapsed: timer.elapsed,
+        count: timer.count,
+        min: timer.min,
+        max: timer.max,
+        mean: timer.mean
+      }]
+    }.to_h
+  end
+
   def self.active_timers
     __timers.values.select(&:active?)
   end
@@ -94,46 +100,91 @@ module TimeUp
     attr_reader :name
 
     def initialize(name)
+      validate!(name)
       @name = name
       @start_time = nil
-      @elapsed = 0.0
+      @total_elapsed = 0.0
+      @past_timings = []
     end
 
-    def start
+    def start(&blk)
       @start_time ||= now
+      if blk
+        blk.call.tap do
+          stop
+        end
+      else
+        self
+      end
     end
 
     def stop
       if @start_time
-        @elapsed += now - @start_time
+        duration = now - @start_time
+        @past_timings.push(duration)
+        @total_elapsed += duration
+
         @start_time = nil
       end
-      @elapsed
+      @total_elapsed
     end
 
     def elapsed
       if active?
-        @elapsed + (now - @start_time)
+        @total_elapsed + (now - @start_time)
       else
-        @elapsed
+        @total_elapsed
       end
     end
 
-    def active?
-      !!@start_time
-    end
-
     def reset(force: false)
       if force
         @start_time = nil
       elsif !@start_time.nil?
         @start_time = now
       end
-      @elapsed = 0.0
+      @total_elapsed = 0.0
+      @past_timings = []
+    end
+
+    def count
+      timings.size
+    end
+
+    def min
+      timings.min
+    end
+
+    def max
+      timings.max
+    end
+
+    def mean
+      times = timings
+      return if times.empty?
+      times.sum / times.size
+    end
+
+    def timings
+      if active?
+        @past_timings + [now - @start_time]
+      else
+        @past_timings
+      end
+    end
+
+    def active?
+      !!@start_time
     end
 
     private
 
+    def validate!(name)
+      unless name.is_a?(Symbol) || name.is_a?(String)
+        raise Error.new("Timer name must be a String or Symbol")
+      end
+    end
+
     def now
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end

data/lib/time_up/version.rb

@@ -1,3 +1,3 @@
 module TimeUp
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: time_up
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Justin Searls
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-07-15 00:00:00.000000000 Z
+date: 2021-07-17 00:00:00.000000000 Z
 dependencies: []
 description:
 email: