NAME

Time::Simple - A simple, light-weight ISO 8601 time object.

SYNOPSIS

use Time::Simple;
my $time   = Time::Simple->new('23:24:59');
my $hour   = $time->hours;
my $minute = $time->minutes;
my $second = $time->seconds;

my $time2  = Time::Simple->new($hour, $minute, $second);

my $now = Time::Simple->new;
my $nexthour = $now + 60;
print "An hour from now is $nexthour.\n";

if ($nexthour->hour > 23) {
	print "It'll be tomorrow within the next hour!\n";
}

# You can also do this:
($time cmp "23:24:25")
# ...and this:
($time <=> [23, 24, 25])

$time++; # Add a minute
$time--; # Subtract a minute

my $now  = Time::Simple->new;
# A minute from now:
my $then = Time::Simple->new( $now + 60 );
# Or:
my $soon = Time::Simple->new( '00:01:00' );

DESCRIPTION

A simple, light-weight time object.

This version should be considered alpha: stable, but not yet thourghly tested.

FATAL ERRORS

Attempting to create an invalid time with this module will return undef rather than an object.

Some operations can produce fatal errors: these can be replaced by warnings and the return of undef by switching the value of $FATALS:

$Time::Simple::FATALS = undef;

You will then only get warnings to STDERR, and even then only if you asked perl for warnings with use warnings or by setting $^W either directly or with the -w command-line switch.

EXPORT

None by default.

CONSTRUCTOR (new)

$_ = Time::Simple->new('21:10:09');
$_ = Time::Simple->new( 11,10, 9 );
$_ = Time::Simple->new( time() );

The constructor new returns a Time::Simple object if the supplied values specify a valid time, otherwise returns undef.

Valid times are either as supplied by the time, or in ISO 8601 format. In the latter case, the values may be supplied as a colon-delimited scalar, as a list, or as an anonymous array.

If nothing is supplied to the constructor, the current local time will be used.

INSTANCE METHODS

METHOD next

my $will_be_by_one_second = $now->next;

Returns the next time by incrementing the caller's time by one second.

METHOD prev

my $was_by_one_second = $now->prev;

Returns the last time by decrementing the caller's time by one second.

METHOD hour

my $hr = $time->hour;

The hour. Alias: hours.

METHOD minute

my $min = $time->minute;

The minutes. Alias: minutes.

METHOD second

my $sec = $time->second;

The seconds. Alias: seconds.

format

Returns a string representing the time, in the format specified. If you don't pass a parameter, an ISO 8601 formatted time is returned.

$date->format;
$date->format("%H hours, %M minutes, and %S seconds");
$date->format("%H-%M-%S");

The formatting parameter is as you would pass to strftime(3): "strftime" in POSIX.

OPERATORS

Some operators can be used with Time::Simple objects:

+= -=

You can increment or decrement a time by a number of seconds using the += and -= operators

+ -

You can construct new times offset by a number of seconds using the + and - operators.

-

You can subtract two times ($t1 - $t2) to find the number of seconds between them.

comparison

You can compare two times using the arithmetic and/or string comparison operators: lt le ge gt < <= >= >.

*

You can interpolate a time instance directly into a string, in the format specified by ISO 8601 (eg: 23:24:25).

DIAGNOSTICS

Illegal octal digit ....

You probably used an anonymous array and prefixed a number with a leading zero, as you would if you supplied a scalar string: [11,10,09].

TODO

Suggestions welcome. How should operators not mentioend behave? Can one verbar times?

SEE ALSO

Time::HiRes, Date::Time, Date::Simple, "localtime" in perlfunc, "time" in perlfunc. "strftime" in POSIX, "mktime" in POSIX.

CREDITS

This module is a rewrite of Marty Pauley's excellent and very useful Date::Simple object. If you're reading, Marty: many thanks. For support, though, please contact Lee Goddard (lgoddard -at- cpan -dot- org) or use rt.cpan.org.

Thanks to Zsolt for testing.

AUTHOR

Lee Goddard (lgoddard -at- cpan -dot- org) after Marty Pauley.

COPYRIGHT AND LICENSE

Copyright (C) 2006 Lee Goddard. Parts Copyright (C) 2001, Kasei.

This program is free software; you can redistribute it and/or modify it under the terms of either: a) the GNU General Public License; either version 2 of the License, or (at your option) any later version. b) the Perl Artistic License.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

cpanm Time::Simple

perl -MCPAN -e shell
install Time::Simple