Time-Simple version 0.04
========================

INSTALLATION

To install this module type the following:

   perl Makefile.PL
   make
   make test
   make install

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.


