Source for file Timer.class.php

Documentation is available at Timer.class.php

  1. <?php
  2. /**
  3.  * Gumbo Library Framework
  4.  *
  5.  * LICENSE
  6.  * This library is being released under the terms of the New BSD License.  A
  7.  * copy of the license is packaged with the software (LICENSE.txt).  If no
  8.  * copy is found, a copy of the license template can be found at:
  9.  * http://www.opensource.org/licenses/bsd-license.php
  10.  * 
  11.  * @category Gumbo
  12.  * @package Timer
  13.  * @copyright Copyright (c) 2007, iBayou, Michael Luster
  14.  * @license http://www.opensource.org/licenses/bsd-license.php New BSD License
  15.  * @author Michael Luster <mluster79@yahoo.com>
  16.  * @link http://sourceforge.net/projects/phpgumbo
  17.  * @version 0.0.1
  18.  */
  19.  
  20. /**
  21.  * Timer Class
  22.  *
  23.  * @category Gumbo
  24.  * @package Timer
  25.  * @copyright Copyright (c) 2007, iBayou, Michael Luster
  26.  * @license http://www.opensource.org/licenses/bsd-license.php New BSD License
  27.  * @author Michael Luster <mluster79@yahoo.com>
  28.  * @link http://sourceforge.net/projects/phpgumbo
  29.  * @desc Timer Class
  30.  * @version 0.0.1
  31.  */
  32.  
  33. gumbo_load ("Interface_Timer");
  34.  
  35. class Gumbo_Timer implements Gumbo_Interface_Timer {
  36.     
  37.     /** @var array $_times list of record Times (or Laps) */
  38.     private $_times = array ();
  39.     
  40.     /** @var bool $_running */
  41.     private $_running = false;
  42.     /** @var bool $_stopped */
  43.     private $_stopped = true;
  44.     
  45.     
  46.     
  47.     /**
  48.      * Constructor
  49.      * @param bool $start starts the Timer
  50.      */
  51.     public function __construct ($start=false) {
  52.         if ($start) {
  53.             $this->start (true);
  54.         }
  55.     }
  56.     
  57.     /** ACTION METHODS **/
  58.     /**
  59.      * Starts the Timer by recording the current time stamp
  60.      * @precondition !isRunning()
  61.      * @postcondition isStarted()
  62.      * @param bool $reset resets timer
  63.      */
  64.     public function start ($reset=false) {
  65.         try {
  66.             // verify precondition
  67.             if (!is_bool ($reset)) {
  68.                 throw new Gumbo_Exception ("Invalid Argument 'reset:bool' => {$reset}:" . gettype ($reset));
  69.             }
  70.         } catch (Gumbo_Exception $e) {
  71.             $e->setFunction (__METHOD__);
  72.             gumbo_trigger ($e);
  73.             $reset = false;
  74.         }
  75.         if ($reset) {
  76.             $this->reset ();
  77.         }
  78.         
  79.         // checks if the Timer is running
  80.         if ($this->isRunning ()) {
  81.             return;
  82.         }
  83.         
  84.         $this->_times [] = microtime (true);
  85.         $this->_running = true;
  86.         $this->_stopped = false;
  87.     }
  88.     
  89.     /**
  90.      * Saves the Mark (or Lap)
  91.      * @precondition isRunning()
  92.      */
  93.     public function lap () {
  94.         if (!$this->isRunning ()) {
  95.             return;
  96.         }
  97.         $this->_times [] = microtime (true);
  98.     }
  99.     
  100.     /**
  101.      * Stops the Timer by recording the current time stamp
  102.      * @precondition isRunning()
  103.      * @postcondition isStopped()
  104.      */
  105.     public function stop () {
  106.         if (!$this->isRunning ()) { return; }
  107.         
  108.         $this->_times [] = microtime (true);
  109.         $this->_running = false;
  110.         $this->_stopped = true;
  111.     }
  112.     
  113.     /**
  114.      * Resets the Timer
  115.      * @postcondition !isRunning()
  116.      * @postcondition isStopped()
  117.      */
  118.     public function reset () {
  119.         $this->_running = false;
  120.         $this->_stopped = true;
  121.         $this->_times = array ();
  122.     }
  123.     
  124.     
  125.     
  126.     /** ACCESSOR METHODS **/
  127.     /**
  128.      * Returns the actual microtime value of the given lap (0 => start time)
  129.      * @param int $lap (0 returns start time, if > laps() or negative, returns stop time)
  130.      * @return num 
  131.      */
  132.     public function stamp ($lap=null) {
  133.         try {
  134.             // verify precondition
  135.             if (!is_null ($lap) && !is_int ($lap)) {
  136.                 throw new Gumbo_Exception ("Invalid Argument 'lap:int|null' => {$lap}:" . gettype ($lap));
  137.             }
  138.             if (is_null ($lap)) { $lap = 0; }
  139.             if ($lap <= -1 || $lap >= $this->laps ()) { $lap = $this->laps () - 1; }
  140.             
  141.             if (!isset ($this->_times [$lap])) {
  142.                 throw new Gumbo_Exception ("Lap Undefined: {$lap}");
  143.             }
  144.             
  145.             return $this->_times [$lap];
  146.         } catch (Gumbo_Exception $e) {
  147.             $e->setFunction (__METHOD__);
  148.             gumbo_trigger ($e);
  149.         }
  150.         return 0;
  151.     }
  152.     
  153.     /**
  154.      * Returns the time difference from the given lap to the previous lap
  155.      * 
  156.      * If the parameter is null or 0, it will return the total time from
  157.      * start to stop recorded by the Timer.  If parameter greater than total
  158.      * laps, it will return the difference from the Stop time to the previous
  159.      * lap.
  160.      * 
  161.      * @precondition laps() > 2
  162.      * @param int $lap lap number (if > laps(), returns last time)
  163.      * @param int $precision rounds the number to the given precision
  164.      * @return num 
  165.      */
  166.     public function time ($lap=null, $precision=null) {
  167.         try {
  168.             // verify precondition
  169.             if ($this->laps () < 2) {
  170.                 throw new Gumbo_Exception ("Not Enough Laps Recorded");
  171.             }
  172.             if (!is_null ($lap) && !is_int ($lap)) {
  173.                 throw new Gumbo_Exception ("Invalid Argument 'lap:int|null' => {$lap}:" . gettype ($lap));
  174.             }
  175.             
  176.             try {
  177.                 // verify precondition
  178.                 if (!is_null ($precision) && !is_int ($precision)) {
  179.                     throw new Gumbo_Exception ("Invalid Argument 'precision:int|null' => {$precision}:" . gettype ($precision));
  180.                 }
  181.                 if (!is_null ($precision) && $precision < 0) {
  182.                     throw new Gumbo_Exception ("Out Of Range 'precision >= 0' => {$precision}");
  183.                 }
  184.             } catch (Gumbo_Exception $e) {
  185.                 $e->setFunction (__METHOD__);
  186.                 gumbo_trigger ($e);
  187.                 $precision = null;
  188.             }
  189.             
  190.             if (is_null ($lap) || $lap <= 0) {
  191.                 $lap = $this->laps () - 1;
  192.                 $prev = 0;
  193.             } else {
  194.                 if ($lap >= $this->laps ()) {
  195.                     $lap = $this->laps () - 1;
  196.                 }
  197.                 $prev = $lap - 1;
  198.             }
  199.             
  200.             return round (abs ($this->_times [$lap] - $this->_times [$prev]), $precision);
  201.         } catch (Gumbo_Exception $e) {
  202.             $e->setFunction (__METHOD__);
  203.             gumbo_trigger ($e);
  204.         }
  205.         return 0;
  206.     }
  207.     
  208.     /**
  209.      * Returns the average time between Laps
  210.      * @precondition laps() >= 2
  211.      * @param int $precision rounds the number to the given precision
  212.      * @return num 
  213.      */
  214.     public function average ($precision=null) {
  215.         try {
  216.             // verify precondition
  217.             if ($this->laps () < 2) {
  218.                 throw new Gumbo_Exception ("Not Enough Laps Records");
  219.             }
  220.             
  221.             try {
  222.                 // verify precondition
  223.                 if (!is_null ($precision) && !is_int ($precision)) {
  224.                     throw new Gumbo_Exception ("Invalid Argument 'precision:int|null' => {$precision}:" . gettype ($precision));
  225.                 }
  226.                 if (!is_null ($precision) && $precision < 0) {
  227.                     throw new Gumbo_Exception ("Out Of Range 'precision >= 0' => {$precision}");
  228.                 }
  229.             } catch (Gumbo_Exception $e) {
  230.                 $e->setFunction (__METHOD__);
  231.                 gumbo_trigger ($e);
  232.                 $precision = null;
  233.             }
  234.             
  235.             $total = 0;
  236.             $count = 0;
  237.             for ($x = 1;$x < $this->laps ();$x++) {
  238.                 $total += $this->time ($x);
  239.                 $count++;
  240.             }
  241.             
  242.             return round (($total / $count), $precision);
  243.         } catch (Gumbo_Exception $e) {
  244.             $e->setFunction (__METHOD__);
  245.             gumbo_trigger ($e);
  246.         }
  247.         return 0;
  248.     }
  249.     
  250.     /**
  251.      * Returns the number of Laps
  252.      * @return int 
  253.      */
  254.     public function laps () {
  255.         return count ($this->_times);
  256.     }
  257.     
  258.     /**
  259.      * Returns the start time
  260.      * @return num 
  261.      */
  262.     public function startTime () {
  263.         return $this->stamp ();
  264.     }
  265.     
  266.     /**
  267.      * Returns the stop time
  268.      * @return num 
  269.      */
  270.     public function stopTime () {
  271.         return $this->stamp (-1);
  272.     }
  273.     
  274.     /**
  275.      * Returns if the Timer is running (or has been started)
  276.      * @return bool 
  277.      */
  278.     public function isRunning () {
  279.         return $this->_running;
  280.     }
  281.     
  282.     /**
  283.      * Returns if the Timer is stopped
  284.      * @return bool 
  285.      */
  286.     public function isStopped () {
  287.         return $this->_stopped;
  288.     }
  289.     
  290. }
  291.  
  292. ?>