Class: Philiprehberger::Stopwatch

Inherits:
Object
  • Object
show all
Defined in:
lib/philiprehberger/stopwatch.rb,
lib/philiprehberger/stopwatch/version.rb

Defined Under Namespace

Classes: Error

Constant Summary collapse

VERSION = 
'0.6.0'

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Stopwatch

Returns a new instance of Stopwatch.



9
10
11
12
13
14
15
16
17
18
 
# File 'lib/philiprehberger/stopwatch.rb', line 9

def initialize
  @laps = []
  @checkpoints = {}
  @running = false
  @paused = false
  @start_time = nil
  @elapsed_before_pause = 0.0
  @lap_start = nil
  @last_tick = nil
end

Class Method Details

.format_duration(seconds) ⇒ String

Format a duration in seconds as a human-readable string

Parameters:

  • seconds (Float)

Returns:

  • (String) 


276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
 
# File 'lib/philiprehberger/stopwatch.rb', line 276

def self.format_duration(seconds)
  if seconds < 0.001
    format('%.2fus', seconds * 1_000_000)
  elsif seconds < 1.0
    format('%.2fms', seconds * 1_000)
  elsif seconds < 60.0
    format('%.3fs', seconds)
  elsif seconds < 3600.0
    minutes = (seconds / 60).to_i
    secs = (seconds % 60).to_i
    "#{minutes}m #{secs}s"
  else
    hours = (seconds / 3600).to_i
    minutes = ((seconds % 3600) / 60).to_i
    secs = (seconds % 60).to_i
    "#{hours}h #{minutes}m #{secs}s"
  end
end

.measure { ... } ⇒ Array

Measure execution time of a block

Yields:

  • block to measure

Returns:

  • (Array) —

    [result, elapsed_seconds]



256
257
258
259
260
261
 
# File 'lib/philiprehberger/stopwatch.rb', line 256

def self.measure
  start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
  result = yield
  elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
  [result, elapsed]
end

.measure_formatted { ... } ⇒ String

Measure execution time and return formatted string

Yields:

  • block to measure

Returns:

  • (String) —

    formatted elapsed time



267
268
269
270
 
# File 'lib/philiprehberger/stopwatch.rb', line 267

def self.measure_formatted(&)
  _, elapsed = measure(&)
  format_duration(elapsed)
end

Instance Method Details

#checkpoint(name) ⇒ self

Record a named checkpoint at the current cumulative elapsed time

Parameters:

  • name (String, Symbol) —

    checkpoint name

Returns:

  • (self)

Raises:



147
148
149
150
151
152
153
154
 
# File 'lib/philiprehberger/stopwatch.rb', line 147

def checkpoint(name)
  raise Error, 'stopwatch is not running' unless @running

  current = now
  split = @elapsed_before_pause + (current - @start_time)
  @checkpoints[name] = split
  self
end

#checkpoints ⇒ Hash

Return a copy of all recorded checkpoints

Returns:

  • (Hash) 


179
180
181
 
# File 'lib/philiprehberger/stopwatch.rb', line 179

def checkpoints
  @checkpoints.dup
end

#elapsed ⇒ Float

Get total elapsed time in seconds

Returns:

  • (Float) 


128
129
130
131
132
133
134
 
# File 'lib/philiprehberger/stopwatch.rb', line 128

def elapsed
  if @running && !@paused
    @elapsed_before_pause + (now - @start_time)
  else
    @elapsed_before_pause
  end
end

#elapsed_at(name) ⇒ Float

Return the cumulative elapsed time recorded at a named checkpoint

Parameters:

  • name (String, Symbol) —

    checkpoint name

Returns:

  • (Float)

Raises:



160
161
162
163
164
 
# File 'lib/philiprehberger/stopwatch.rb', line 160

def elapsed_at(name)
  raise Error, "checkpoint '#{name}' not found" unless @checkpoints.key?(name)

  @checkpoints[name]
end

#elapsed_ms ⇒ Float

Get total elapsed time in milliseconds

Returns:

  • (Float) 


114
115
116
 
# File 'lib/philiprehberger/stopwatch.rb', line 114

def elapsed_ms
  elapsed * 1000.0
end

#elapsed_us ⇒ Float

Get total elapsed time in microseconds

Returns:

  • (Float) 


121
122
123
 
# File 'lib/philiprehberger/stopwatch.rb', line 121

def elapsed_us
  elapsed * 1_000_000.0
end

#formatted_elapsed ⇒ String

Format elapsed time as a human-readable string

Returns:

  • (String) 


205
206
207
 
# File 'lib/philiprehberger/stopwatch.rb', line 205

def formatted_elapsed
  self.class.format_duration(elapsed)
end

#formatted_laps ⇒ Array<Hash>

Get formatted lap data

Returns:

  • (Array<Hash>) —

    each with :name, :elapsed, :split, :formatted, :formatted_split



212
213
214
215
216
217
218
219
220
221
222
 
# File 'lib/philiprehberger/stopwatch.rb', line 212

def formatted_laps
  @laps.map do |lap|
    {
      name: lap[:name],
      elapsed: lap[:elapsed],
      split: lap[:split],
      formatted: self.class.format_duration(lap[:elapsed]),
      formatted_split: self.class.format_duration(lap[:split])
    }
  end
end

#lap(name = nil) ⇒ Hash

Record a lap

Parameters:

  • name (String, nil) (defaults to: nil) —

    optional lap name

Returns:

  • (Hash) —

    lap data with name, elapsed time, and cumulative split time

Raises:



80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/philiprehberger/stopwatch.rb', line 80

def lap(name = nil)
  raise Error, 'stopwatch is not running' unless @running

  current = now
  lap_elapsed = current - @lap_start
  split = @elapsed_before_pause + (current - @start_time)
  lap_data = { name: name, elapsed: lap_elapsed, split: split }
  @laps << lap_data
  @lap_start = current
  lap_data
end

#lap_stats ⇒ Hash

Get aggregate statistics across all recorded laps

Returns:

  • (Hash) —

    { count:, total:, avg:, min:, max: }



186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
 
# File 'lib/philiprehberger/stopwatch.rb', line 186

def lap_stats
  if @laps.empty?
    return { count: 0, total: 0.0, avg: 0.0, min: 0.0, max: 0.0 }
  end

  times = @laps.map { |l| l[:elapsed] }
  total = times.sum
  {
    count: times.length,
    total: total,
    avg: total / times.length,
    min: times.min,
    max: times.max
  }
end

#laps ⇒ Array<Hash>

Get all recorded laps

Returns:

  • (Array<Hash>) 


139
140
141
 
# File 'lib/philiprehberger/stopwatch.rb', line 139

def laps
  @laps.dup
end

#paused? ⇒ Boolean

Check if the stopwatch is paused

Returns:

  • (Boolean) 


241
242
243
 
# File 'lib/philiprehberger/stopwatch.rb', line 241

def paused?
  @paused
end

#reset ⇒ self

Reset the stopwatch

Returns:

  • (self) 


53
54
55
56
57
58
59
60
61
62
63
 
# File 'lib/philiprehberger/stopwatch.rb', line 53

def reset
  @laps = []
  @checkpoints = {}
  @running = false
  @paused = false
  @start_time = nil
  @elapsed_before_pause = 0.0
  @lap_start = nil
  @last_tick = nil
  self
end

#restart ⇒ self

Reset and start the stopwatch in one call

Returns:

  • (self) 


68
69
70
71
 
# File 'lib/philiprehberger/stopwatch.rb', line 68

def restart
  reset
  start
end

#running? ⇒ Boolean

Check if the stopwatch is running (and not paused)

Returns:

  • (Boolean) 


248
249
250
 
# File 'lib/philiprehberger/stopwatch.rb', line 248

def running?
  @running && !@paused
end

#since(name) ⇒ Float

Return the elapsed time since a named checkpoint was recorded

Parameters:

  • name (String, Symbol) —

    checkpoint name

Returns:

  • (Float)

Raises:



170
171
172
173
174
 
# File 'lib/philiprehberger/stopwatch.rb', line 170

def since(name)
  raise Error, "checkpoint '#{name}' not found" unless @checkpoints.key?(name)

  elapsed - @checkpoints[name]
end

#start ⇒ self Also known as: resume

Start the stopwatch

Returns:

  • (self)

Raises:



23
24
25
26
27
28
29
30
31
32
33
34
35
36
 
# File 'lib/philiprehberger/stopwatch.rb', line 23

def start
  raise Error, 'stopwatch is already running' if @running && !@paused

  @start_time = now
  if @paused
    @paused = false
  else
    @elapsed_before_pause = 0.0
    @lap_start = @start_time
    @laps = []
  end
  @running = true
  self
end

#stop ⇒ self Also known as: pause

Stop (pause) the stopwatch

Returns:

  • (self)

Raises:



41
42
43
44
45
46
47
48
 
# File 'lib/philiprehberger/stopwatch.rb', line 41

def stop
  raise Error, 'stopwatch is not running' unless @running
  raise Error, 'stopwatch is already paused' if @paused

  @elapsed_before_pause += now - @start_time
  @paused = true
  self
end

#tick ⇒ Float

Record an unnamed tick and return the seconds since the previous tick

On the first call after start, returns the seconds elapsed since the stopwatch began. Subsequent calls return the seconds since the previous tick. Useful for sequential timing in loops where naming each lap is noise — a thinner lap for ad-hoc measurement.

Returns:

  • (Float) —

    seconds since the previous tick (or since start)

Raises:

  • (Error) —

    if the stopwatch is not running



101
102
103
104
105
106
107
108
109
 
# File 'lib/philiprehberger/stopwatch.rb', line 101

def tick
  raise Error, 'stopwatch is not running' unless running?

  current = now
  previous = @last_tick || @start_time
  delta = current - previous
  @last_tick = current
  delta
end

#to_h ⇒ Hash

Serialize the stopwatch state to a hash

Returns:

  • (Hash) 


227
228
229
230
231
232
233
234
235
236
 
# File 'lib/philiprehberger/stopwatch.rb', line 227

def to_h
  {
    running: running?,
    paused: paused?,
    elapsed: elapsed,
    formatted_elapsed: formatted_elapsed,
    laps: laps,
    lap_stats: lap_stats
  }
end