<?php

/* Reminder: always indent with 4 spaces (no tabs). */

/**
 * Geeklog 2
 *
 * License details are yet to be determined.  
 *
 */

/**
 * This class is used to time program execution. This is particularly handy for
 * performance trouble shooting.
 *<code>
 *   // Instantiate new timer object
 *   $mytimer = new timerobject();
 *
 *   // Set percision of the results to 4 significant digits
 *   // NOTE: this call is optional, code defaults to 2 
 *   $mytimer->setPercision(4);
 *
 *  // Start the timer
 *  $mytimer->startTimer();
 *
 *  // Stop timer and print elapsed time
 *  echo $mytimer->endTimer();
 *</code>
 *
 * @author Tony Bibbs
 *
 */
class Geeklog_Timer {

    /**
     * @access protected
     */
    protected $startTime = null;
    
    /**
     * @access protected
     */
    protected $endTime = null;
    
    /**
     * @access protected
     */
    protected $elapsedTime = null;
    
    /**
     * @access protected
     */
    protected $percision = 2;

    /**
     * Set percision on timer results
     *
     * This sets how many significant digits get sent back when elapsedTime is called
     *
     * @author Tony Bibbbs <tony@geeklog.net>
     * @access public
     * @param int $numDecimalPlaces Number of significant digits
     *
     */
    public function setPercision($numDecimalPlaces)
    {
        $this->percision = $numDecimalPlaces;
    }

    /**
     * Starts the timer
     *
     * @author Tony Bibbs <tony@geeklog.net>
     * @access public
     *
     */
    public function startTimer()
    {
        $mTime = microtime();
        $mTime = explode(' ', $mTime);
        $mTime = $mTime[1] + $mTime[0];
        $this->startTime = $mTime;
    }

    /**
     * Stops the timer
     * 
     * @author Tony Bibbs <tony@geeklog.net>
     * @access public
     * @return float Elapsed time to degree of percision specified
     *
     */
    public function stopTimer()
    {
        $mTime = microtime();
        $mTime = explode(' ',$mTime);
        $mTime = $mTime[1] + $mTime[0];
        $this->endTime = $mTime;
        $this->setElapsedTime();

        // We are going to assume that when the timer is stopped
        // they will want the elapsed time immediately
        return $this->getElapsedTime();
    }

    /** 
     * Restarts the timer
     *
     * Same as starTimer excepts this clears everything out first
     *
     * @author Tony Bibbs <tony@geeklog.net>
     * @access public
     * 
     */
    public function restart()
    {
        $this->endTime = null;
        $this->elapsedTime = null;        
        $this->startTimer();      
    }

    /**
     * Gets the elapsed time
     *
     * This returns the elapsed time with the proper number of significant digits
     *
     * @author Tony Bibbs <tony@geeklog.net>
     * @access public
     * @return float Elasped time in seconds formatted to degree of percision specified
     *
     */
    public function getElapsedTime()
    {
        return sprintf("%.{$this->percision}f", $this->elapsedTime);
    }

    /**
     * Sets the elapsed time
     *
     * once stop timer is called this gets called to calculate the elapsed time for later retrieval
     *
     * @author Tony Bibbs <tony@geeklog.net>
     * @access protected
     *
     */
    protected function setElapsedTime()
    {
        $this->elapsedTime = $this->endTime - $this->startTime;
    }

}

?>