Resumable timers for accurate timing of short running operations

See also xolox/vim-easytags#80 where I suggested
to add accurate timing to the vim-easytags plug-in. This change will
facilitate that.

Author: xolox

README.md

@@ -37,8 +37,8 @@ from the source code of the miscellaneous scripts using the Python module
 
 <!-- Start of generated documentation -->
 
-The documentation of the 93 functions below was extracted from
-19 Vim scripts on July 19, 2014 at 12:32.
+The documentation of the 94 functions below was extracted from
+19 Vim scripts on July 19, 2014 at 13:11.
 
 ### Asynchronous Vim script evaluation
 
@@ -911,6 +911,33 @@ Test comparison of version strings with `xolox#misc#version#at_least()`.
 
 ### Timing of long during operations
 
+#### The `xolox#misc#timer#resumable()` function
+
+Create a resumable timer object. This returns an object (a dictionary with
+functions) with the following "methods":
+
+ - `start()` instructs the timer object to start counting elapsed time
+   (when a timer object is created it is not automatically started).
+
+ - `stop()` instructs the timer object to stop counting elapsed time.
+   This adds the time elapsed since `start()` was last called to the
+   total elapsed time. This method will raise an error if called out of
+   sequence.
+
+ - `format()` takes the total elapsed time and reports it as a string
+   containing a formatted floating point number.
+
+Timer objects are meant to accurately time short running operations so
+they're dependent on Vim's [reltime()][] and [reltimestr()][] functions.
+In order to make it possible to use timer objects in my Vim plug-ins
+unconditionally there's a fall back to [localtime()][] when [reltime()][]
+is not available. In this mode the timer objects are not very useful but
+at least they shouldn't raise errors.
+
+[localtime()]: http://vimdoc.sourceforge.net/htmldoc/eval.html#localtime()
+[reltime()]: http://vimdoc.sourceforge.net/htmldoc/eval.html#reltime()
+[reltimestr()]: http://vimdoc.sourceforge.net/htmldoc/eval.html#reltimestr()
+
 #### The `xolox#misc#timer#start()` function
 
 Start a timer. This returns a list which can later be passed to

autoload/xolox/misc.vim

@@ -4,4 +4,4 @@
 " Last Change: July 19, 2014
 " URL: http://peterodding.com/code/vim/misc/
 
-let g:xolox#misc#version = '1.14.2'
+let g:xolox#misc#version = '1.15'

autoload/xolox/misc/timer.vim

@@ -1,7 +1,7 @@
 " Timing of long during operations.
 "
 " Author: Peter Odding <peter@peterodding.com>
-" Last Change: June 21, 2014
+" Last Change: July 19, 2014
 " URL: http://peterodding.com/code/vim/misc/
 
 if !exists('g:timer_enabled')
@@ -15,6 +15,69 @@ endif
 let s:has_reltime = has('reltime')
 let s:unique_marker = 'xolox#misc#timer#value'
 
+function! xolox#misc#timer#resumable() " {{{1
+  " Create a resumable timer object. This returns an object (a dictionary with
+  " functions) with the following "methods":
+  "
+  "  - `start()` instructs the timer object to start counting elapsed time
+  "    (when a timer object is created it is not automatically started).
+  "
+  "  - `stop()` instructs the timer object to stop counting elapsed time.
+  "    This adds the time elapsed since `start()` was last called to the
+  "    total elapsed time. This method will raise an error if called out of
+  "    sequence.
+  "
+  "  - `format()` takes the total elapsed time and reports it as a string
+  "    containing a formatted floating point number.
+  "
+  " Timer objects are meant to accurately time short running operations so
+  " they're dependent on Vim's [reltime()][] and [reltimestr()][] functions.
+  " In order to make it possible to use timer objects in my Vim plug-ins
+  " unconditionally there's a fall back to [localtime()][] when [reltime()][]
+  " is not available. In this mode the timer objects are not very useful but
+  " at least they shouldn't raise errors.
+  "
+  " [localtime()]: http://vimdoc.sourceforge.net/htmldoc/eval.html#localtime()
+  " [reltime()]: http://vimdoc.sourceforge.net/htmldoc/eval.html#reltime()
+  " [reltimestr()]: http://vimdoc.sourceforge.net/htmldoc/eval.html#reltimestr()
+  let object = {'total': [0, 0]}
+  function object.start() dict
+    if s:has_reltime
+      let self.current = reltime()
+    else
+      let self.current = localtime()
+    endif
+  endfunction
+  function object.stop() dict
+    if empty(get(self, 'current'))
+      throw "timer.stop() called on a timer that was never started!"
+    endif
+    if s:has_reltime
+      let elapsed_time_string = xolox#misc#str#trim(reltimestr(reltime(self.current)))
+      " This is a bit silly (converting to a string and then parsing that) but
+      " the value of reltime() is documented as being platform specific...
+      let [seconds, microseconds] = split(elapsed_time_string, '\.')
+      let self.total[0] += substitute(seconds, '^0*', '', '')
+      let self.total[1] += substitute(microseconds, '^0*', '', '')
+      let self.current = []
+    else
+      let self.total[0] += localtime() - self.current
+      let self.current = 0
+    endif
+  endfunction
+  function object.format() dict
+    let seconds = self.total[0]
+    let microseconds = self.total[1]
+    if microseconds >= 1000000
+      let additional_seconds = microseconds / 1000000
+      let seconds += additional_seconds
+      let microseconds -= additional_seconds * 1000000
+    endif
+    return printf('%i.%06i', seconds, microseconds)
+  endfunction
+  return object
+endfunction
+
 function! xolox#misc#timer#start() " {{{1
   " Start a timer. This returns a list which can later be passed to
   " `xolox#misc#timer#stop()`.

doc/misc.txt

@@ -113,10 +113,11 @@ function
    20. The |xolox#misc#tests#version_string_parsing()| function
    21. The |xolox#misc#tests#version_string_comparison()| function
   18. Timing of long during operations  |misc-timing-of-long-during-operations|
-   1. The |xolox#misc#timer#start()| function
-   2. The |xolox#misc#timer#stop()| function
-   3. The |xolox#misc#timer#force()| function
-   4. The |xolox#misc#timer#convert()| function
+   1. The |xolox#misc#timer#resumable()| function
+   2. The |xolox#misc#timer#start()| function
+   3. The |xolox#misc#timer#stop()| function
+   4. The |xolox#misc#timer#force()| function
+   5. The |xolox#misc#timer#convert()| function
   19. Version string handling                    |misc-version-string-handling|
    1. The |xolox#misc#version#parse()| function
    2. The |xolox#misc#version#at_least()| function
@@ -167,8 +168,8 @@ For those who are curious: The function descriptions given below were extracted
 from the source code of the miscellaneous scripts using the Python module
 'vimdoctool.py' included in vim-tools [5].
 
-The documentation of the 93 functions below was extracted from 19 Vim scripts
-on July 19, 2014 at 12:32.
+The documentation of the 94 functions below was extracted from 19 Vim scripts
+on July 19, 2014 at 13:11.
 
 -------------------------------------------------------------------------------
                                       *misc-asynchronous-vim-script-evaluation*
@@ -1087,6 +1088,28 @@ Test comparison of version strings with |xolox#misc#version#at_least()|.
                                         *misc-timing-of-long-during-operations*
 Timing of long during operations ~
 
+-------------------------------------------------------------------------------
+The *xolox#misc#timer#resumable()* function
+
+Create a resumable timer object. This returns an object (a dictionary with
+functions) with the following "methods":
+
+- 'start()' instructs the timer object to start counting elapsed time (when a
+  timer object is created it is not automatically started).
+
+- 'stop()' instructs the timer object to stop counting elapsed time. This
+  adds the time elapsed since 'start()' was last called to the total elapsed
+  time. This method will raise an error if called out of sequence.
+
+- 'format()' takes the total elapsed time and reports it as a string
+  containing a formatted floating point number.
+
+Timer objects are meant to accurately time short running operations so they're
+dependent on Vim's |reltime()| and |reltimestr()| functions. In order to make
+it possible to use timer objects in my Vim plug-ins unconditionally there's a
+fall back to |localtime()| when |reltime()| is not available. In this mode the
+timer objects are not very useful but at least they shouldn't raise errors.
+
 -------------------------------------------------------------------------------
 The *xolox#misc#timer#start()* function