NAME

Time::Date - A time and date object for Perl

SYNOPSIS

    use Time::Date;
    my $t = Time::Date->new("2015-09-14 17:44");
    print $t->strftime("%Y-%m-%d %H:%M:%S") . "\n";
    my $s = Time::Date->now;
    print "That was " . ($s->{epoch} - $t->{epoch}) . " seconds ago";

DESCRIPTION

Time::Date is a class that can be used to represent a date as an object. Unlike other modules, this one just stores a Unix epoch within the object and relies heavily on the underlying operating system so it's very fast. It provides functionality for working with common representations of dates, displaying dates naturally (like "5 minutes ago"), and for listing timezones. Also, it will stringify automatically if you use the object in a string.

TIME ZONES

If you want to use a different timezone, you have to set the TZ environment variable as is the standard on most operating systems. This takes effect when parsing and displaying dates. For example, if you want to parse a date from Ashgabat and display it for a user in Rarotonga, you have to write it like this:

    $ENV{TZ} = "Asia/Ashgabat";
    my $t = Time::Date->new("2015-09-14 11:44 am");
    $ENV{TZ} = "Pacific/Rarotonga";
    print "$t";

Use time_zones subroutine to get a list of valid timezones.

DATE MATH

You can add or subtract time by adding or subtracting a number of seconds from the "epoch" field in the object. For example, to add a day you would write:

    $t->{epoch} += 60 * 60 * 24;

CONSTRUCTORS

new($str)

Takes a date in string form and parses it into Unix timestamp. The format is meant to work well with MySQL date strings, and you can leave any part out after the year and it will fill in the rest for you. for example Time::Date->new("2005-10") is the same as Time::Date->new("2005-10-01 00:00:00"). It also works fine with dates formatted as ISO8601 Time::Date->new("2005-10-01T03:04:05").

new_epoch($epoch)

Takes a epoch as an argument and returns an object. It does no parsing. Just wraps the Unix timestamp (epoch) into an object.

now()

Returns an object representing the current time (now).

mktime($year, $mon, $mday, $hour, $min, $sec, $wday, $yday, $isdst)

Returns an object from mktime arguments. See mktime(3) man page for how to use mktime. http://linux.die.net/man/3/mktime. mktime is very useful for finding the last day of the month since it handles overflow and negative numbers nicely. For example, this is the last day of Febuary:

    my $t = Time::Date->mktime(115, 2, 0);

METHODS

strftime($format)

Returns a string of the date represented by $t. See the strftime(3) man page for info on the format options. http://man7.org/linux/man-pages/man3/strftime.3.html. For example, you can use:

    print $t->strftime("%B %d, %Y") . "\n";
    # prints "September 14, 2015"

str()

Prints the date as a string. The format is the same as if you used $t->strftime("%Y-%m-%d %H:%M:%S"). You can always pass this string back into new(), if you need to recreate the object later. This is the default stringification when you use the object in a string. for example:

    print "$t\n";
    # prints "2015-09-14 14:23:31"

natural()

Prints the date in a natural format such as "25 seconds ago" or "in 5 days".

epoch()

Returns the Unix timestamp (epoch) of the date.

CLASS SUBROUTINES

time_zones()

Returns a list of time zone names from the Olson database on your system. Could be useful if you need to display a list of them. For example, if you wanted an HTML select tag:

    my $zones = Time::Date::time_zones;
    my $output = "<select name=\"timezone\">\n";
    for my $zone (@$zones) {
        if ($zone->{region}) {
            $output .= "</optgroup>\n" if $zone->{i};
            $output .= "<optgroup label=\"$zone->{region}\">\n";
        }
        else {
            $output .= "    <option value=\"$zone->{zone}\">$zone->{name}</option>\n";
        }
    }
    $output .= "</optgroup>\n</select>\n";
    print $output;

METACPAN

https://metacpan.org/pod/Time::Date

REPOSITORY

https://github.com/zorgnax/timedate

AUTHOR

Jacob Gelbman, <gelbman@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2015 by Jacob Gelbman

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.18.2 or, at your option, any later version of Perl 5 you may have available.

cpanm Time::Date

perl -MCPAN -e shell
install Time::Date