philiprehberger-stopwatch

Precision stopwatch with lap timing, pause/resume, and formatted output

Requirements

• Ruby >= 3.1

Installation

Add to your Gemfile:

gem "philiprehberger-stopwatch"

Or install directly:

gem install philiprehberger-stopwatch

Usage

require "philiprehberger/stopwatch"

sw = Philiprehberger::Stopwatch.new
sw.start
# ... do work ...
sw.lap('phase 1')
# ... do more work ...
sw.lap('phase 2')
sw.stop

sw.elapsed  # => 1.234 (seconds)
sw.laps     # => [{name: "phase 1", elapsed: 0.5, split: 0.5}, {name: "phase 2", elapsed: 0.734, split: 1.234}]

Pause and Resume

sw = Philiprehberger::Stopwatch.new
sw.start
sleep(0.1)
sw.pause      # alias for #stop
sw.resume     # alias for #start
sleep(0.1)
sw.stop
sw.elapsed    # => ~0.2 (paused time not counted)

Restart

sw = Philiprehberger::Stopwatch.new
sw.start
sleep(0.1)
sw.lap('phase 1')
sw.restart    # equivalent to #reset followed by #start
sleep(0.05)
sw.elapsed    # => ~0.05 (prior state cleared)

Formatted Output

sw = Philiprehberger::Stopwatch.new
sw.start
sleep(0.5)
sw.formatted_elapsed  # => "500.12ms"

sleep(65)
sw.formatted_elapsed  # => "1m 5s"

Lap Statistics

sw = Philiprehberger::Stopwatch.new
sw.start
sw.lap('setup')
sw.lap('process')
sw.lap('teardown')

sw.lap_stats
# => { count: 3, total: 0.053, avg: 0.018, min: 0.005, max: 0.031 }

sw.formatted_laps
# => [{ name: "setup", elapsed: 0.005, formatted: "5.00ms" }, ...]

Serialization

sw = Philiprehberger::Stopwatch.new
sw.start
sw.lap('setup')
sw.lap('process')
sw.stop

sw.to_h
# => { running: false, paused: true, elapsed: 0.053,
#      formatted_elapsed: "53.00ms", laps: [...], lap_stats: {...} }

Named Checkpoints

sw = Philiprehberger::Stopwatch.new
sw.start
sleep(0.1)
sw.checkpoint('after_setup')
sleep(0.2)
sw.checkpoint('after_process')

sw.elapsed_at('after_setup')    # => ~0.1 (cumulative split at that moment)
sw.elapsed_at('after_process')  # => ~0.3

sw.since('after_setup')         # => ~0.2 (time elapsed since that checkpoint)
sw.since('after_process')       # => ~0.0

sw.checkpoints
# => { "after_setup" => 0.1003, "after_process" => 0.3007 }

Block Timing

result, elapsed = Philiprehberger::Stopwatch.measure { expensive_operation }
puts "Took #{elapsed} seconds"

formatted = Philiprehberger::Stopwatch.measure_formatted { expensive_operation }
puts "Took #{formatted}"  # => "Took 12.50ms"

Sequential Tick Timing

For ad-hoc per-iteration timing in loops where naming each lap is overkill:

sw = Philiprehberger::Stopwatch.new.start

items.each do |item|
  process(item)
  puts "step took #{sw.tick} seconds"
end

Each call to #tick returns the seconds elapsed since the previous tick (or since #start for the first call). A thinner #lap for unnamed sequential measurement.

API

Method	Description
Stopwatch.new	Create a new stopwatch
#start	Start or resume the stopwatch
#stop	Pause the stopwatch
#pause	Alias for #stop
#resume	Alias for #start (resumes a paused stopwatch)
#reset	Reset all state
#restart	Reset and start the stopwatch in one call
#lap(name)	Record a lap with optional name
#tick	Return seconds since the previous tick (or since start on the first call)
#elapsed	Total elapsed time in seconds
#elapsed_ms	Total elapsed time in milliseconds
#elapsed_us	Total elapsed time in microseconds
#laps	Array of recorded lap data
#running?	Whether the stopwatch is actively running
#paused?	Whether the stopwatch is paused
#checkpoint(name)	Record a named moment storing the current cumulative split time
#elapsed_at(name)	Cumulative split time at the named checkpoint
#since(name)	Elapsed time since the named checkpoint was recorded
#checkpoints	Hash of all recorded checkpoints
#lap_stats	Aggregate lap statistics (count, total, avg, min, max)
#formatted_elapsed	Human-readable elapsed time string
#formatted_laps	Array of laps with formatted times
#to_h	Serialize full stopwatch state to a hash
Stopwatch.measure { block }	Measure block execution time
Stopwatch.measure_formatted { block }	Measure block and return formatted string

Development

bundle install
bundle exec rspec
bundle exec rubocop

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT