StopWatch
Date: 2017-02-08

org.apache.commons.lang3.time

## Class StopWatch

- java.lang.Object
- - org.apache.commons.lang3.time.StopWatch

-     public class StopWatch
      extends java.lang.Object

  `StopWatch` provides a convenient API for timings.

  To start the watch, call `start()` or `createStarted()`. At this point you can:

  - `split()` the watch to get the time whilst the watch continues in the background. `unsplit()` will remove the effect of the split. At this point, these three options are available again.
  - `suspend()` the watch to pause it. `resume()` allows the watch to continue. Any time between the suspend and resume will not be counted in the total. At this point, these three options are available again.
  - `stop()` the watch to complete the timing session.

  It is intended that the output methods `toString()` and `getTime()` should only be called after stop, split or suspend, however a suitable result will be returned at other points.

  NOTE: As from v2.1, the methods protect against inappropriate calls. Thus you cannot now call stop before start, resume before suspend or unsplit before split.

  1. split(), suspend(), or stop() cannot be invoked twice
  2. unsplit() may only be called if the watch has been split()
  3. resume() may only be called if the watch has been suspend()
  4. start() cannot be called twice without calling reset()

  This class is not thread-safe

  Since:
    2.0

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `StopWatch()` Constructor.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static StopWatch` | `createStarted()` Provides a started stopwatch for convenience.
    `long` | `getNanoTime()` Get the time on the stopwatch in nanoseconds.
    `long` | `getSplitNanoTime()` Get the split time on the stopwatch in nanoseconds.
    `long` | `getSplitTime()` Get the split time on the stopwatch.
    `long` | `getStartTime()` Returns the time this stopwatch was started.
    `long` | `getTime()` Get the time on the stopwatch.
    `long` | `getTime(java.util.concurrent.TimeUnit timeUnit)` Get the time on the stopwatch in the specified TimeUnit.
    `boolean` | `isStarted()` The method is used to find out if the StopWatch is started.
    `boolean` | `isStopped()` This method is used to find out whether the StopWatch is stopped.
    `boolean` | `isSuspended()` This method is used to find out whether the StopWatch is suspended.
    `void` | `reset()` Resets the stopwatch.
    `void` | `resume()` Resume the stopwatch after a suspend.
    `void` | `split()` Split the time.
    `void` | `start()` Start the stopwatch.
    `void` | `stop()` Stop the stopwatch.
    `void` | `suspend()` Suspend the stopwatch for later resumption.
    `java.lang.String` | `toSplitString()` Gets a summary of the split time that the stopwatch recorded as a string.
    `java.lang.String` | `toString()` Gets a summary of the time that the stopwatch recorded as a string.
    `void` | `unsplit()` Remove a split.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### StopWatch

          public StopWatch()

      Constructor.

  - ### Method Detail

    - #### createStarted

          public static StopWatch createStarted()

      Provides a started stopwatch for convenience.
      Returns:
        StopWatch a stopwatch that's already been started.
      Since:
        3.5

    - #### start

          public void start()

      Start the stopwatch.

      This method starts a new timing session, clearing any previous values.

      Throws:
        `java.lang.IllegalStateException` - if the StopWatch is already running.

    - #### stop

          public void stop()

      Stop the stopwatch.

      This method ends a new timing session, allowing the time to be retrieved.

      Throws:
        `java.lang.IllegalStateException` - if the StopWatch is not running.

    - #### reset

          public void reset()

      Resets the stopwatch. Stops it if need be.

      This method clears the internal values to allow the object to be reused.

    - #### split

          public void split()

      Split the time.

      This method sets the stop time of the watch to allow a time to be extracted. The start time is unaffected, enabling `unsplit()` to continue the timing from the original start point.

      Throws:
        `java.lang.IllegalStateException` - if the StopWatch is not running.

    - #### unsplit

          public void unsplit()

      Remove a split.

      This method clears the stop time. The start time is unaffected, enabling timing from the original start point to continue.

      Throws:
        `java.lang.IllegalStateException` - if the StopWatch has not been split.

    - #### suspend

          public void suspend()

      Suspend the stopwatch for later resumption.

      This method suspends the watch until it is resumed. The watch will not include time between the suspend and resume calls in the total time.

      Throws:
        `java.lang.IllegalStateException` - if the StopWatch is not currently running.

    - #### resume

          public void resume()

      Resume the stopwatch after a suspend.

      This method resumes the watch after it was suspended. The watch will not include time between the suspend and resume calls in the total time.

      Throws:
        `java.lang.IllegalStateException` - if the StopWatch has not been suspended.

    - #### getTime

          public long getTime()

      Get the time on the stopwatch.

      This is either the time between the start and the moment this method is called, or the amount of time between start and stop.

      Returns:
        the time in milliseconds

    - #### getTime

          public long getTime(java.util.concurrent.TimeUnit timeUnit)

      Get the time on the stopwatch in the specified TimeUnit.

      This is either the time between the start and the moment this method is called, or the amount of time between start and stop. The resulting time will be expressed in the desired TimeUnit with any remainder rounded down. For example, if the specified unit is `TimeUnit.HOURS` and the stopwatch time is 59 minutes, then the result returned will be `0`.

      Parameters:
        `timeUnit` - the unit of time, not null
      Returns:
        the time in the specified TimeUnit, rounded down
      Since:
        3.5

    - #### getNanoTime

          public long getNanoTime()

      Get the time on the stopwatch in nanoseconds.

      This is either the time between the start and the moment this method is called, or the amount of time between start and stop.

      Returns:
        the time in nanoseconds
      Since:
        3.0

    - #### getSplitTime

          public long getSplitTime()

      Get the split time on the stopwatch.

      This is the time between start and latest split.

      Returns:
        the split time in milliseconds
      Throws:
        `java.lang.IllegalStateException` - if the StopWatch has not yet been split.
      Since:
        2.1

    - #### getSplitNanoTime

          public long getSplitNanoTime()

      Get the split time on the stopwatch in nanoseconds.

      This is the time between start and latest split.

      Returns:
        the split time in nanoseconds
      Throws:
        `java.lang.IllegalStateException` - if the StopWatch has not yet been split.
      Since:
        3.0

    - #### getStartTime

          public long getStartTime()

      Returns the time this stopwatch was started.
      Returns:
        the time this stopwatch was started
      Throws:
        `java.lang.IllegalStateException` - if this StopWatch has not been started
      Since:
        2.4

    - #### toString

          public java.lang.String toString()

      Gets a summary of the time that the stopwatch recorded as a string.

      The format used is ISO 8601-like, hours:minutes:seconds.milliseconds.

      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        the time as a String

    - #### toSplitString

          public java.lang.String toSplitString()

      Gets a summary of the split time that the stopwatch recorded as a string.

      The format used is ISO 8601-like, hours:minutes:seconds.milliseconds.

      Returns:
        the split time as a String
      Since:
        2.1

    - #### isStarted

          public boolean isStarted()

      The method is used to find out if the StopWatch is started. A suspended StopWatch is also started watch.

      Returns:
        boolean If the StopWatch is started.
      Since:
        3.2

    - #### isSuspended

          public boolean isSuspended()

      This method is used to find out whether the StopWatch is suspended.

      Returns:
        boolean If the StopWatch is suspended.
      Since:
        3.2

    - #### isStopped

          public boolean isStopped()

      This method is used to find out whether the StopWatch is stopped. The stopwatch which's not yet started and explicitly stopped stopwatch is considered as stopped.

      Returns:
        boolean If the StopWatch is stopped.
      Since:
        3.2