Improve util.profiling.Timer class

. Add ability to provide intermediate results with `elapsedTime()` without
  prior cal top `stop()`
. Add fluent interface to the start() and stop() methods

Author: thekid

ChangeLog.md

@@ -110,6 +110,9 @@ XP Framework Core ChangeLog
 
 ### Features
 
+* Changed util.profiling.Timer to be able to provide intermediate results
+  with `elapsedTime()` without prior call to `stop()`, and added fluent
+  interface to util.profiling.Timer's start() and stop() methods - (@thekid)
 * Implemented taking exceptions from tearDown() into account for test failure / 
   success in the unittest package, see xp-framework/core#32 - (@thekid)
 * Implemented pushing back bytes to buffered stream (see xp-framework/core#16)

src/main/php/util/profiling/Timer.class.php

@@ -15,24 +15,27 @@
  * @purpose  Provide a simple profiling timer
  */
 class Timer extends \lang\Object {
-  public
-    $start = 0.0,
-    $stop  = 0.0;
+  protected $start= null;
+  protected $stop= null;
 
   /**
    * Start the timer
    *
+   * @return  self
    */
   public function start() {
     $this->start= microtime(true);
+    return $this;
   }
 
   /**
    * Stop the timer
    *
+   * @return  self
    */
   public function stop() {
     $this->stop= microtime(true);
+    return $this;
   }
 
   /**
@@ -61,6 +64,12 @@ public static function measure($block) {
    * @return  float seconds elapsed
    */
   public function elapsedTime() {
-    return $this->stop - $this->start;
+    if (null === $this->start) {
+      return 0.0;
+    } else if (null === $this->stop) {
+      return microtime(true) - $this->start;
+    } else {
+      return $this->stop - $this->start;
+    }
   }
 }

src/test/php/net/xp_framework/unittest/util/TimerTest.class.php

@@ -4,56 +4,68 @@
 use util\profiling\Timer;
 use util\Comparator;
 
-
 /**
  * Tests Timer class
  *
  * @see      xp://util.profiling.Timer
  */
 class TimerTest extends TestCase {
-  
-  /**
-   * Tests elapsed time is zero if not started yet
-   *
-   */
+
+  #[@test]
+  public function can_create() {
+    new Timer();
+  }
+
   #[@test]
-  public function initiallyZero() {
+  public function elapsed_time_is_zero_before_timer_is_started() {
     $this->assertEquals(0.0, (new Timer())->elapsedTime());
   }
 
-  /**
-   * Tests elapsed time after 100 milliseconds
-   *
-   */
   #[@test]
-  public function elapsedTimeGreaterThanZeroUsingStartAndStop() {
-    $fixture= new Timer();
-    $fixture->start();
-    usleep(100 * 1000);
-    $fixture->stop();
+  public function start_returns_timer() {
+    $t= new Timer();
+    $this->assertEquals($t, $t->start());
+  }
+
+  #[@test]
+  public function stop_returns_timer() {
+    $t= new Timer();
+    $t->start();
+    $this->assertEquals($t, $t->stop());
+  }
+
+  #[@test]
+  public function calling_stop_before_start_does_not_raise_exception() {
+    (new Timer())->stop();
+  }
+
+  #[@test]
+  public function elapsed_time_after_50_milliseconds() {
+    $fixture= (new Timer())->start();
+    usleep(50 * 1000);
+    $elapsed= $fixture->stop()->elapsedTime();
+    $this->assertTrue($elapsed > 0.0, 'Elapsed time '.$elapsed.' should be greater than zero');
+  }
+
+  #[@test]
+  public function elapsed_time_without_stop_after_50_milliseconds() {
+    $fixture= (new Timer())->start();
+    usleep(50 * 1000);
     $elapsed= $fixture->elapsedTime();
-    $this->assertTrue($elapsed > 0.0, 'Elapsed time should be greater than zero');
+    $this->assertTrue($elapsed > 0.0, 'Elapsed time '.$elapsed.' should be greater than zero');
   }
 
-  /**
-   * Tests elapsed time after 100 milliseconds
-   *
-   */
   #[@test]
-  public function elapsedTimeGreaterThanZeroUsingMeasure() {
+  public function elapsed_time_measured_after_50_milliseconds() {
     $fixture= Timer::measure(function() {
       usleep(100 * 1000);
     });
     $elapsed= $fixture->elapsedTime();
-    $this->assertTrue($elapsed > 0.0, 'Elapsed time should be greater than zero');
+    $this->assertTrue($elapsed > 0.0, 'Elapsed time '.$elapsed.' should be greater than zero');
   }
 
-  /**
-   * Tests measure()
-   *
-   */
   #[@test, @expect('lang.IllegalArgumentException')]
-  public function notCallable() {
+  public function not_callable_argument_passed_to_measure() {
     Timer::measure('@not-callable@');
   }
 }