  ------------------------------------------------------------------------
  Timers unit                               by Sebastian Groeneveld (2000)
  ------------------------------------------------------------------------

  Usage
  =====

  Add the following line to your program:

  $INCLUDE "Timers.inc"


  Public routines
  ===============

  Most of the following routines expect a number Nr. There are 20 timers
  available, ranging from nr. 1 to 20.

  -----
  SUB StartTimer( BYVAL Nr AS INTEGER )

  Start timer Nr. If it is already running, no action is taken.

  -----
  SUB StopTimer( BYVAL Nr AS INTEGER )

  Stop timer Nr. If it was not running, no action is taken. The timer's
  internal value is updated.

  -----
  SUB UpdateTimer( BYVAL Nr AS INTEGER )

  Update timer Nr. If it was not running, no action is taken. The timer's
  internal value is updated, and the timer is restarted. Calling this
  routine continuously will decrease the accuracy of the timer.

  -----
  SUB ResetTimer( BYVAL Nr AS INTEGER )

  Reset timer Nr. The timer will be stopped if it was running and its
  internal value will be set to zero.

  -----
  SUB AdjustTimer( BYVAL Nr AS INTEGER, BYVAL Seconds AS SINGLE )

  Adjust timer Nr. If you specify a negative value for Seconds, the timer
  value is decreased.

  -----
  FUNCTION TimerValue( BYVAL Nr AS INTEGER ) AS SINGLE

  Returns the total running-time value of timer Nr. If it is not running,
  then just the internal value is returned, otherwise the running-time since
  last update is added. However, the value always represents the time the
  timer has been running, and is never lower than zero.

  -----
  FUNCTION RunTimerValue( BYVAL Nr AS INTEGER ) AS SINGLE

  Calculates the time elapsed since last update. Accounts for a midnight
  rollover.

  -----
  FUNCTION TimeString( BYVAL Seconds AS SINGLE ) AS STRING

  Converts a time to a string. The format depends on the specified value:
    If Seconds <  60    "##.# s"     (SS.F s)
    If Seconds <  3600  "##:##"      (MM:SS)
    If Seconds >= 3600  "##:##:##"   (HH:MM:SS)


  Example
  =======

  $INCLUDE "Timers.inc"

  CLS

  StartTimer 1

  '----------->
  DELAY 1.5

  PRINT "After 1.5 seconds pause: "; TimerValue( 1 )

  DELAY 1.5
  '<-----------

  StopTimer 1

  PRINT "After 3.0 seconds pause: "; TimerValue( 1 )

  AdjustTimer 1, +2.0

  PRINT "Adjusted value (+2.0)  : "; TimeString( TimerValue( 1 ) )


