Commit cfb4b81b authored by Benjamin Summerton's avatar Benjamin Summerton

Added a ton of documentation

parent 049f7f86
...@@ -8,6 +8,7 @@ proc msecs*(nsecs: int64): int64 {.inline.} ...@@ -8,6 +8,7 @@ proc msecs*(nsecs: int64): int64 {.inline.}
proc secs*(nsecs: int64): float {.inline.} proc secs*(nsecs: int64): float {.inline.}
# The stopwatch object
type type
Stopwatch* = object Stopwatch* = object
running: bool running: bool
...@@ -15,7 +16,7 @@ type ...@@ -15,7 +16,7 @@ type
laps: seq[Nanos] laps: seq[Nanos]
# Function prototypes # Basic stopwatch functionality
proc newStopwatch*(): Stopwatch proc newStopwatch*(): Stopwatch
proc clone*(sw: var Stopwatch): Stopwatch proc clone*(sw: var Stopwatch): Stopwatch
proc running*(sw: var Stopwatch): bool {.inline.} proc running*(sw: var Stopwatch): bool {.inline.}
...@@ -31,7 +32,7 @@ proc laps*(sw: var Stopwatch; incCur: bool = false): seq[int64] {.inline.} ...@@ -31,7 +32,7 @@ proc laps*(sw: var Stopwatch; incCur: bool = false): seq[int64] {.inline.}
proc rmLap*(sw: var Stopwatch; num: int) {.inline.} proc rmLap*(sw: var Stopwatch; num: int) {.inline.}
proc clearLaps(sw: var Stopwatch) {.inline.} proc clearLaps(sw: var Stopwatch) {.inline.}
# These functions are for the current lap (or previous one if not running) # Getting the time of the current lap (or previously ran one, if the stopwatch is stopped)
proc nsecs*(sw: var Stopwatch): int64 {.inline.} proc nsecs*(sw: var Stopwatch): int64 {.inline.}
proc usecs*(sw: var Stopwatch): int64 {.inline.} proc usecs*(sw: var Stopwatch): int64 {.inline.}
proc msecs*(sw: var Stopwatch): int64 {.inline.} proc msecs*(sw: var Stopwatch): int64 {.inline.}
...@@ -50,7 +51,34 @@ proc totalSecs*(sw: var Stopwatch): float {.inline.} ...@@ -50,7 +51,34 @@ proc totalSecs*(sw: var Stopwatch): float {.inline.}
{.deprecated: [seconds: secs].} {.deprecated: [seconds: secs].}
# TODO document
#===============================#
#== Time Conversion Functions ==#
#===============================#
## Converts nanoseconds to microseconds
proc usecs*(nsecs: int64): int64 =
return (nsecs div 1_000).int64
## Converts nanoseconds to microseconds
proc msecs*(nsecs: int64): int64 =
return (nsecs div 1_000_000).int64
## Converts nanoseconds to seconds (represented as a float)
proc secs*(nsecs: int64): float =
return nsecs.float / 1_000_000_000.0
#=====================#
#== Stopwatch procs ==#
#=====================#
## Creates a new Stopwatch. It has no laps and isn't running
proc newStopwatch*(): Stopwatch = proc newStopwatch*(): Stopwatch =
result = Stopwatch( result = Stopwatch(
running: false, running: false,
...@@ -59,6 +87,8 @@ proc newStopwatch*(): Stopwatch = ...@@ -59,6 +87,8 @@ proc newStopwatch*(): Stopwatch =
) )
## Clones the state of an existing Stopwatch. Will copy over it's laps and if
## it is currently running or not.
proc clone*(sw: var Stopwatch): Stopwatch = proc clone*(sw: var Stopwatch): Stopwatch =
result = Stopwatch( result = Stopwatch(
running: sw.running, running: sw.running,
...@@ -67,10 +97,13 @@ proc clone*(sw: var Stopwatch): Stopwatch = ...@@ -67,10 +97,13 @@ proc clone*(sw: var Stopwatch): Stopwatch =
) )
## Checks to see if the Stopwatch is measuring time.
proc running*(sw: var Stopwatch): bool = proc running*(sw: var Stopwatch): bool =
return sw.running return sw.running
## Makes the Stopwatch measure time. Will do nothing if the Stopwatch is
## already doing that.
proc start*(sw: var Stopwatch) = proc start*(sw: var Stopwatch) =
# If we are already running, ignore # If we are already running, ignore
if sw.running: if sw.running:
...@@ -81,6 +114,8 @@ proc start*(sw: var Stopwatch) = ...@@ -81,6 +114,8 @@ proc start*(sw: var Stopwatch) =
sw.startTicks = getTicks().Nanos sw.startTicks = getTicks().Nanos
## Makes the Stopwatch stop measuring time. It will record the lap it has
## taken. If the Stopwatch wasn't running before, nothing will happen
proc stop*(sw: var Stopwatch) = proc stop*(sw: var Stopwatch) =
# First thing, measure the time # First thing, measure the time
let stopTicks = getTicks().Nanos let stopTicks = getTicks().Nanos
...@@ -97,23 +132,35 @@ proc stop*(sw: var Stopwatch) = ...@@ -97,23 +132,35 @@ proc stop*(sw: var Stopwatch) =
sw.startTicks = 0 sw.startTicks = 0
# TODO document ## Clears out the state of the Stopwatch. This deletes all of the lap data and
## will make it stop measuring time.
proc reset*(sw: var Stopwatch) = proc reset*(sw: var Stopwatch) =
sw.running = false sw.running = false
sw.startTicks = 0 sw.startTicks = 0
sw.laps.setLen(0) # Clear the laps sw.laps.setLen(0) # Clear the laps
# TODO document ## This function will clear out the state of the Stopwatch and tell it to start
## recording time. It is the same as calling reset() then start().
proc restart*(sw: var Stopwatch) = proc restart*(sw: var Stopwatch) =
sw.reset() sw.reset()
sw.start() sw.start()
## Returns the number of laps the Stopwatch has recorded so far. If `incCur` is
## set to `true`, it will include the current lap in the count. By default it
## set to `false`.
proc numLaps*(sw: var Stopwatch; incCur: bool = false): int = proc numLaps*(sw: var Stopwatch; incCur: bool = false): int =
return sw.laps.len + (if incCur and sw.running: 1 else: 0) return sw.laps.len + (if incCur and sw.running: 1 else: 0)
## Returns the time (in nanoseconds) of a lap with the provided index of `num`.
## If `incCur` is set to `true`, it will include the current lap in the range
## (as the last lap). By default it is set to `false`. This function can raise
## an `IndexError` if `num` isn't a valid lap index.
##
## If you want to convert the returned value to a different time measurement,
## use one of the functions: `msecs()`, `usecs()` or `secs()`.
proc lap*(sw: var Stopwatch; num: int; incCur: bool = false): int64 = proc lap*(sw: var Stopwatch; num: int; incCur: bool = false): int64 =
if incCur and sw.running: if incCur and sw.running:
# Check if the index is good or not # Check if the index is good or not
...@@ -130,43 +177,82 @@ proc lap*(sw: var Stopwatch; num: int; incCur: bool = false): int64 = ...@@ -130,43 +177,82 @@ proc lap*(sw: var Stopwatch; num: int; incCur: bool = false): int64 =
# only look at completed laps # only look at completed laps
return sw.laps[num] return sw.laps[num]
## Returns a list of all the recorded laps (in nanoseconds). If `incCur` is set
## `true`, then it will include the current lap in the result. By default it is
## `false`.
##
## If you want to convert the returned value to a different time measurement,
## use one of the functions: `msecs()`, `usecs()` or `secs()` in conjunction
## with the `map()` function from the `sequtils` module. Example:
##
## .. code-block:: nim
## var sw = newStopwatch()
##
## # some time measurements later...
##
## var lapsSecs = sw2.laps.map(proc(x: int64): float = secs(x))
## echo lapsSecs
## # --> @[1.000117, 0.500115, 0.200212]
proc laps*(sw: var Stopwatch; incCur: bool = false): seq[int64] = proc laps*(sw: var Stopwatch; incCur: bool = false): seq[int64] =
# TODO need to include the current lap too!
return sw.laps return sw.laps
## Removes a lap from the Stopwatch's record with the given index of `num`.
## This function has the possibility of raising an `IndexError`.
proc rmLap*(sw: var Stopwatch; num: int) = proc rmLap*(sw: var Stopwatch; num: int) =
sw.laps.delete(num) sw.laps.delete(num)
## This clears out all of the lap records from a Stopwatch. This will not
## effect the current lap (if one is being measured).
proc clearLaps(sw: var Stopwatch) = proc clearLaps(sw: var Stopwatch) =
sw.laps.setLen(0) sw.laps.setLen(0)
## This will return either the length of the current lap (if `stop()` has not
## been called, or the time of the previously measured lap. The return value is
## in nanoseconds. If no laps have been run yet, then this will return 0.
##
## See also: `usecs()`, `msecs()`, `secs()`
proc nsecs*(sw: var Stopwatch): int64 = proc nsecs*(sw: var Stopwatch): int64 =
let curTicks = getTicks().Nanos let curTicks = getTicks().Nanos
if sw.running: if sw.running:
# Return current lap # Return current lap
return (curTicks - sw.startTicks).int64 return (curTicks - sw.startTicks).int64
else: elif sw.laps.len != 0:
# Return previous lap # Return previous lap
return sw.laps[high(sw.laps)].int64 return sw.laps[high(sw.laps)].int64
else:
# No laps yet
return 0
## The same as `nsecs()`, except the return value is in microseconds.
##
## See also: `nsecs()`, `msecs()`, `secs()`
proc usecs*(sw: var Stopwatch): int64 = proc usecs*(sw: var Stopwatch): int64 =
return usecs(sw.nsecs) return usecs(sw.nsecs)
## The same as `nsecs()`, except the return value is in milliseconds.
##
## See also: `nsecs()`, `usecs()`, `secs()`
proc msecs*(sw: var Stopwatch): int64 = proc msecs*(sw: var Stopwatch): int64 =
return msecs(sw.nsecs) return msecs(sw.nsecs)
## The same as `nsecs()`, except the return value is in seconds (as floats).
##
## See also: `nsecs()`, `usecs()`, `msecs()`
proc secs*(sw: var Stopwatch): float = proc secs*(sw: var Stopwatch): float =
return secs(sw.nsecs) return secs(sw.nsecs)
# These functions include the time for all laps (plus the current lap, if there is one) ## This returns the time of all laps combined, plus the current lap (if
## Stopwatch is running). The return value is in nanoseconds.
##
## See also: `totalUsecs()`, `totalMsecs()`, `totalSecs()`
proc totalNsecs*(sw: var Stopwatch): int64 = proc totalNsecs*(sw: var Stopwatch): int64 =
let curTicks = getTicks().Nanos let curTicks = getTicks().Nanos
let total = if sw.laps.len != 0: foldl(sw.laps, a + b) else: 0 let total = if sw.laps.len != 0: foldl(sw.laps, a + b) else: 0
...@@ -178,28 +264,24 @@ proc totalNsecs*(sw: var Stopwatch): int64 = ...@@ -178,28 +264,24 @@ proc totalNsecs*(sw: var Stopwatch): int64 =
return total.int64 return total.int64
## The same as `totalNsecs()`, except the return value is in microseconds.
##
## See also: `totalNsecs()`, `totalMsecs()`, `totalSecs()`
proc totalUsecs*(sw: var Stopwatch): int64 = proc totalUsecs*(sw: var Stopwatch): int64 =
return usecs(sw.totalNsecs) return usecs(sw.totalNsecs)
## The same as `totalNsecs()`, except the return value is in milliseconds.
##
## See also: `totalNsecs()`, `totalUsecs()`,`totalSecs()`
proc totalMsecs*(sw: var Stopwatch): int64 = proc totalMsecs*(sw: var Stopwatch): int64 =
return msecs(sw.totalNsecs) return msecs(sw.totalNsecs)
## The same as `totalNsecs()`, except the return value is in seconds (as a
## float).
##
## See also: `totalNsecs()`, `totalUsecs()`, `totalMsecs()`
proc totalSecs*(sw: var Stopwatch): float = proc totalSecs*(sw: var Stopwatch): float =
return secs(sw.totalNsecs) return secs(sw.totalNsecs)
proc usecs*(nsecs: int64): int64 =
return (nsecs div 1_000).int64
proc msecs*(nsecs: int64): int64 =
return (nsecs div 1_000_000).int64
proc secs*(nsecs: int64): float =
return nsecs.float / 1_000_000_000.0
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment