NAME
TimeDate - A time and date object for Perl
SYNOPSIS
use TimeDate;
my $t = TimeDate->new("2015-09-14 17:44");
print $t->strftime("%Y-%m-%d %H:%M:%S") . "\n";
my $s = TimeDate->now;
print "That was " . ($s - $t) . " seconds ago";DESCRIPTION
TimeDate 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 = TimeDate->new("2015-09-14 11:44 am");
$ENV{TZ} = "Pacific/Rarotonga";
print "$t";Use TimeDate::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
TimeDate->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 TimeDate->new("2005-10") is the same as TimeDate->new("2005-10-01 00:00:00"). It also works fine with dates formatted as ISO8601 TimeDate->new("2005-10-01T03:04:05").
TimeDate->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.
TimeDate->now()
Returns an object representing the current time (now).
TimeDate->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 = TimeDate->mktime(115, 2, 0);METHODS
$t->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"$t->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"$t->natural()
Prints the date in a natural format such as "25 seconds ago" or "in 5 days".
CLASS SUBROUTINES
TimeDate::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 = TimeDate::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;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.