File Coverage

blib/lib/Timer/Simple.pm

Criterion	Covered	Total	%
statement	62	66	93.9
branch	36	40	90.0
condition	11	20	55.0
subroutine	16	16	100.0
pod	11	11	100.0
total	136	153	88.8

# vim: set sw=2 sts=2 ts=2 expandtab smarttab:
#
# This file is part of Timer-Simple
#
# This software is copyright (c) 2011 by Randy Stauner.
#
# This is free software; you can redistribute it and/or modify it under
# the same terms as the Perl 5 programming language system itself.
#
use strict;
use warnings;

package Timer::Simple;
# git description: v1.005-3-gd10352e

our $AUTHORITY = 'cpan:RWSTAUNER';
# ABSTRACT: Small, simple timer (stopwatch) object
$Timer::Simple::VERSION = '1.006';
use Carp qw(croak carp); # core
use overload # core
  '""' => \&string,
  '0+' => \&elapsed,
  fallback => 1;


sub new {
  my $class = shift;
  my $self = {
    start => 1,
    string => 'short',
    hires => HIRES(),
    @_ == 1 ? %{$_[0]} : @_,
  };

  if( $self->{format} ){
    carp("$class option 'format' is deprecated.  Use 'hms' (or 'string')");
    $self->{hms} ||= delete $self->{format};
  }
  $self->{hms} ||= default_format_spec($self->{hires});

  bless $self, $class;

  $self->start
    if $self->{start};

  return $self;
}


sub elapsed {
  my ($self) = @_;

  if( !defined($self->{started}) ){
    croak("Timer never started!");
  }

  # if stop() was called, use that time, otherwise "now"
  my $elapsed = defined($self->{stopped})
    ? $self->{stopped}
    : $self->time;

  return $self->{hires}
    ? Time::HiRes::tv_interval($self->{started}, $elapsed)
    : $elapsed - $self->{started};
}


sub hms {
  my ($self, $format) = @_;

  my ($h, $m, $s) = separate_hms($self->elapsed);

  return wantarray
    ? ($h, $m, $s)
    : sprintf(($format || $self->{hms}), $h, $m, $s);
}


sub start {
  my ($self) = @_;

  # don't use an old stopped time if we're restarting
  delete $self->{stopped};

  $self->{started} = $self->time;
}


sub stop {
  my ($self) = @_;
  $self->{stopped} = $self->time
    # don't change the clock if it's already stopped
    if !defined($self->{stopped});
  # natural return value would be elapsed() but don't compute it in void context
  return $self->elapsed
    if defined wantarray;
}


sub string {
  my ($self, $format) = @_;
  $format ||= $self->{string};

  # if it's a method name or a coderef delegate to it
  return scalar $self->$format()
    if $self->can($format)
      || ref($format) eq 'CODE'
      || overload::Method($format, '&{}');

  # cache the time so that all formats show the same (in case it isn't stopped)
  my $seconds = $self->elapsed;

  my $string;
  if( $format eq 'short' ){
    $string = sprintf('%ss (' . $self->{hms} . ')', $seconds, separate_hms($seconds));
  }
  elsif( $format eq 'rps' ){
    my $elapsed = sprintf '%f', $seconds;
    my $rps     = $elapsed == 0 ? '??' : sprintf '%.3f', 1 / $elapsed;
    $string = "${elapsed}s ($rps/s)";
  }
  elsif( $format =~ /human|full/ ){
    # human
    $string = sprintf('%d hours %d minutes %s seconds', separate_hms($seconds));
    $string = $seconds . ' seconds (' . $string . ')'
      if $format eq 'full';
  }
  else {
    croak("Unknown format: $format");
  }
  return $string;
}


sub time {
  return $_[0]->{hires}
    ? [ Time::HiRes::gettimeofday() ]
    : time;
}

{
  # aliases
  no warnings 'once';
  *restart = \&start;
}

# package functions


{
  # only perform the check once, but don't perform the check until required
  my $HIRES;
  sub HIRES () {  ## no critic Prototypes
    $HIRES = (do { local $@; eval { require Time::HiRes; 1; } } || '')
      if !defined($HIRES);
    return $HIRES;
  }
}


sub default_format_spec {
  my ($fractional) = @_ ? @_ : HIRES();
  # float: 9 (width) - 6 (precision) - 1 (dot) == 2 digits before decimal point
  return '%02d:%02d:' . ($fractional ? '%09.6f' : '%02d');
}


sub format_hms {
  # if only one argument was provided assume its seconds and split it
  my ($h, $m, $s) = (@_ == 1 ? separate_hms(@_) : @_);

  return sprintf(default_format_spec(int($s) != $s), $h, $m, $s);
}


sub separate_hms {
  my ($s)  = @_;

  # find the number of whole hours, then subtract them
  my $h  = int($s / 3600);
     $s -=     $h * 3600;
  # find the number of whole minutes, then subtract them
  my $m  = int($s / 60);
     $s -=     $m * 60;

  return ($h, $m, $s);
}

1;

__END__