add lap and peek

cormullion · cormullion · commit 78f54ecaf0ab · 2017-12-13T22:47:32.000Z
diff --git a/README.md b/README.md
@@ -1,41 +1,64 @@
 # TickTock
 
-This module provides `tick()`, `tock()`, and `tok()` functions.
-
-They're similar to the `tic()`, `toc()`, and `toq()` functions that you might find in MATLAB and
-similar software.
+This module provides `tick()`, `tock()`, and `tok()` functions. They're similar to the `tic()`, `toc()`, and `toq()` functions that you might find in MATLAB and
+similar software. There are also `lap()` and `peek()` functions that reveal the state of the current timer without stopping it.
 
 **Don't use these for timing code execution!** Julia provides much better facilities for
 measuring performance, ranging from the `@time` and `@elapsed` macros to packages such as [BenchmarkTools.jl](https://github.com/JuliaCI/BenchmarkTools.jl). (And remember, don't
-time Julia code running in global scope!)
+time Julia code running in global scope!) The [TimerOutputs.jl](https://github.com/KristofferC/TimerOutputs.jl) package provides tools for timing different sections of a program.
 
-This code used to live in Julia Base in the `tic()`, `toc()`, and `toq()` functions (in base/util.jl). They were deprecated in GitHub issue [17046](https://github.com/JuliaLang/julia/issues/17046).
+## Functions
 
-The [TimerOutputs.jl](https://github.com/KristofferC/TimerOutputs.jl) package provides tools for timing different sections of a program.
+- `tick()` start counting
+- `tock()` stop counting show total elapsed time
+- `tok()`  stop counting return seconds
+- `peek()` continue counting, return elapsed seconds
+- `lap()`  continue counting, show total elapsed time
 
-## Example
+## Suggestions for use  
 
-```julia
-julia-0.6> using TickTock
+You can:
 
-julia-0.6> tick()
-INFO: Started timer at 2017-12-12T09:33:00.363.
+- time how long a phone call takes without leaving the Julia REPL
 
+```
+julia-0.6> using TickTock
+julia-0.6> tick()
+INFO: Started timer: 2017-12-13T22:30:59.632.
 julia-0.6> tock()
-INFO: Time taken: 149.427977832
-INFO:             2 minutes, 29 seconds, 427 milliseconds
+INFO: 55.052638936 ms: 55 seconds, 52 milliseconds
 ```
 
-To return the elapsed time in seconds, use `tok()`:
+- see whether your cup of tea's brewed for the right length of time:
 
-```julia
+julia-0.6> tick()
+INFO: Started timer: 2017-12-13T22:34:03.78.
+julia-0.6> lap()
+INFO: 72.625839832 ms: 1 minute, 12 seconds, 625 milliseconds
+julia-0.6> lap()
+INFO: 266.053953749 ms: 4 minutes, 26 seconds, 53 milliseconds
+julia-0.6> lap()
+INFO: 285.314459174 ms: 4 minutes, 45 seconds, 314 milliseconds
+```
+
+- see how many seconds you held your breath for:
+
+```
 julia-0.6> tick()
 INFO: Started timer at 2017-12-12T09:17:45.504.
 
 julia-0.6> tok()
 287.841546621
 ```
 
+You should not:
+
+- measure performance of Julia code
+
+## Acknowledgements
+
+This code used to live in Julia Base in the `tic()`, `toc()`, and `toq()` functions (in base/util.jl). They were deprecated in GitHub issue [17046](https://github.com/JuliaLang/julia/issues/17046).
+
 [![Build Status](https://travis-ci.org/cormullion/TickTock.jl.svg?branch=master)](https://travis-ci.org/cormullion/TickTock.jl)
 
 [![Coverage Status](https://coveralls.io/repos/cormullion/TickTock.jl/badge.svg?branch=master&service=github)](https://coveralls.io/github/cormullion/TickTock.jl?branch=master)
diff --git a/src/TickTock.jl b/src/TickTock.jl
@@ -13,7 +13,7 @@ This code used to live in Julia Base in the `tic()`, `toc()`, and `toq()` functi
 
 module TickTock
 
-export tick, tock, tok
+export tick, tock, tok, peek, lap
 
 """
     tick()
@@ -23,36 +23,63 @@ Start counting.
 function tick()
     t0 = time_ns()
     task_local_storage(:TIMERS, (t0, get(task_local_storage(), :TIMERS, ())))
-    info("Started timer at $(now()).")
+    info("Started timer: $(now()).")
 end
 
 """
-    tok()
+    peek()
 
-Return the time since the previous `tick()`, in seconds, and then stop counting.
+Return the seconds counted by the current timer, without stopping it.
 """
-function tok()
+function peek()
     t1 = time_ns()
     timers = get(task_local_storage(), :TIMERS, ())
     if timers === ()
         error("You must first use `tick()`.")
     end
     t0 = timers[1]::UInt64
+    return (t1 - t0)/1e9
+end
+
+"""
+    tok()
+
+Return the seconds since the previous `tick()` then stop counting.
+"""
+function tok()
+    timers = get(task_local_storage(), :TIMERS, ())
+    if timers === ()
+        error("You must first use `tick()`.")
+    end
+    t = peek()
     task_local_storage(:TIMERS, timers[2])
-    return (t1-t0)/1e9 # seconds
+    return t
 end
 
 """
     tock()
 
 Print the elapsed time, in canonical form, since the previous `tick()`,
-and then stop counting.
+then stop counting.
 """
 function tock()
     t = tok()
     canondc = Dates.canonicalize(Dates.CompoundPeriod(Dates.Second(floor(t)), Dates.Millisecond(floor((t-floor(t)) * 1000))))
-    info("Time taken: $t")
-    info("            $canondc")
+    info("$(t)ms: ($canondc)")
+end
+
+"""
+    lap()
+
+Print the current elapsed time, in canonical form, since the previous `tick()`,
+and continue counting.
+"""
+function lap()
+    t = peek()
+    canondc = Dates.canonicalize(Dates.CompoundPeriod(Dates.Second(floor(t)), Dates.Millisecond(floor((t-floor(t)) * 1000))))
+    info("$(t)ms: ($canondc)")
 end
 
+
+
 end # module
diff --git a/test/runtests.jl b/test/runtests.jl
@@ -3,4 +3,8 @@ using Base.Test
 
 tick()
 sleep(1)
+@test typeof(peek()) == Float64
+@test typeof(lap()) == Void
 @test tok() > 1.0
+tick()
+@test typeof(tock()) == Void
