File Coverage

blib/lib/Misc/Stopwatch.pm

Criterion	Covered	Total	%
statement	28	30	93.3
branch	4	8	50.0
condition	2	6	33.3
subroutine	10	10	100.0
pod	7	7	100.0
total	51	61	83.6

package Misc::Stopwatch;
use strict;
our $VERSION = 0.1;
use Time::HiRes qw(gettimeofday tv_interval);

# ------------------------------------------------------------------------------
# new - Construct a new Misc::Stopwatch
# new
# ------------------------------------------------------------------------------
#|test(!abort) use Misc::Stopwatch;
#|test(true) my $sw = Misc::Stopwatch->new();
# ------------------------------------------------------------------------------

sub new {
  bless [], (ref($_[0]) || $_[0]);
}

# ------------------------------------------------------------------------------
# start - Reset and Start the stopwatch
# start
# Returns C<$self>.
#
# Note that calling this on an already-running instance will reset it.
# ------------------------------------------------------------------------------
#|test(!abort) my $sw = Misc::Stopwatch->new()->start();
# ------------------------------------------------------------------------------

sub start {
  $_[0]->reset();
  $_[0]->_capture();
}

# ------------------------------------------------------------------------------
# lap - Preserve the elapsed time without stopping
# lap
#
# Returns C<$self>.
#
# This is is a no-op unless the stopwatch is running.
# ------------------------------------------------------------------------------
#|test(!abort) my $sw = Misc::Stopwatch->new()->start()->lap();
# ------------------------------------------------------------------------------

sub lap {
  return $_[0] unless $_[0]->is_running;
  $_[0]->_capture();
}

# ------------------------------------------------------------------------------
# stop - Stop
# stop
# Returns C<$self>.
# ------------------------------------------------------------------------------
#|test(!abort) my $sw = Misc::Stopwatch->new()->start()->stop();
# ------------------------------------------------------------------------------

sub stop {
  $_[0]->lap();
  push @{$_[0]}, undef;
  $_[0];
}

# ------------------------------------------------------------------------------
# elapsed - Return the elapsed time
# elapsed $lap
# elapsed
# In its second form, elapsed will return the time from L to now (or when
# L was called).
#
# C is returned when:
#
# 1.) C<$lap> is provided but no such lap exists
#
# 2.) L returns a false value
# ------------------------------------------------------------------------------
#|test(true) Misc::Stopwatch->new()->start()->elapsed();
# ------------------------------------------------------------------------------

sub elapsed {
  my ($self, $lap) = @_;
  my ($b, $e) = ($$self[0], undef);
  if (defined $lap) {
    $e = $$self[$lap];
  } elsif ($self->is_running) {
    $e = [gettimeofday];
  } else {
    $e = $$self[-2];
  }
  defined ($b && $e) ? tv_interval($b, $e) : 0;
}

# ------------------------------------------------------------------------------
# reset - Stop and clear data
# reset
# Returns C<$self>.
# ------------------------------------------------------------------------------
#|test(!abort) my $sw = Misc::Stopwatch->new()->reset();
# ------------------------------------------------------------------------------

sub reset {
  @{$_[0]} = ();
  $_[0];
}

# ------------------------------------------------------------------------------
# is_running - Boolean logic
# is_running
# Returns a true value if the stopwatch has been started and has not been
# stopped.
# ------------------------------------------------------------------------------
#|test(false) Misc::Stopwatch->new()->is_running();
#|test(true) Misc::Stopwatch->new()->start()->is_running();
# ------------------------------------------------------------------------------

sub is_running {
  defined $_[0][$#{$_[0]}];
}

# ------------------------------------------------------------------------------
# _capture - Capture the moment
# _capture
# ------------------------------------------------------------------------------

sub _capture {
  push @{$_[0]}, [gettimeofday];
  $_[0];
}

1;

__END__