Provided by: libbadger-perl_0.16-2_all 
NAME
Badger::Timestamp - object representation of a timestamp
SYNOPSIS
use Badger::Timestamp;
# timestamp defaults to date/time now
my $stamp = Badger::Timestamp->new();
my $stamp = Badger::Timestamp->now(); # alias to new()
# construct from seconds since epoch
my $stamp = Badger::Timestamp->new($epoch_seconds);
# or from ISO-8601 timestamp (or similar)
my $stamp = Badger::Timestamp->new('2006-03-19 04:20:42');
# or from individual arguments
my $stamp = Badger::Timestamp->new(
year => 2006,
month => 3,
day => 19
hours => 4
minutes => 20
seconds => 42
);
# overloaded stringification operator calls timestamp() method
print $stamp->timestamp; # 2006-03-19 04:20:42
print $stamp; # 2006-03-19 04:20:42
# format using strftime()
print $stamp->format('%d-%b-%y');
# methods to access parts of date and time - in both singular
# (month, year, etc) and plural (months, years, etc) forms
print $stamp->date; # 2006-03-19
print $stamp->year; # 2006
print $stamp->month; # 03
print $stamp->day; # 19
print $stamp->time; # 04:20:42
print $stamp->hours; # 04
print $stamp->minutes; # 20
print $stamp->seconds; # 42
# update parts of date/time
$stamp->year(2007);
print $stamp; # 2007-03-19 04:20:42
# adjust date/time
$stamp->adjust( months => 3 ); # 3 months time
$stamp->adjust( days => 60 ); # 60 days time
$stamp->adjust( hours => -3 ); # 3 hours ago
# comparisons
$stamp->compare($epoch_seconds); # returns -1/0/1
$stamp->compare($timestamp_string);
$stamp->compare($timestamp_object);
$stamp->compare( year => 2006, month => 03, ...etc... );
$stamp->compare($hash_ref_of_named_params);
$stamp->before($any_of_the_above); # returns 1/0
$stamp->after($any_of_the_above); # returns 1/0
DESCRIPTION
This module implements a small and simple object for representing a moment in time. Its
scope is intentionally limited to the kind of applications that require very basic date
and time functionality with minimal overhead. A typical example would be a CGI script or
library generating a timestamp for a cookie, printing out a "last modified" date at the
bottom of a web page, or adding a time stamp to a log file message without having the
remember the right incantation to pass to "strftime()".
For any non-trivial date manipulation you should almost certainly be using the most
excellent DateTime modules instead.
The goals of this implementation are:
• To provide an OO wrapper of convenience around the core date and time functions and
modules ("time()", "localtime()", "strftime()", etc).
• To parse timestamps in ISO-8601 format (and formats sufficiently similar to it), such
as those used to store timestamps in databases. e.g. 2009-04-20T04:20:00.
• To grok epoch times (seconds since lst January 1970) such as those used for file
modification times.
• To perform basic date manipulation, e.g adding or subtracting days, months, years,
etc., such as you might want to do when constructing expiry dates for web content,
cookies, etc.
• To perform simple date comparisons, e.g. so that you can see if one of the previously
mentioned expiry dates has lapsed.
The module is derived from the Template Toolkit date plugin. It was moved out into stand-
alone module in 2006 for use in various commercial projects. It was made fully generic and
moved into the Badger fold in January 2009.
Please note that this documentation may be incorrect or incomplete in places.
EXPORTABLE SUBROUTINES
TS / TIMESTAMP
These are shortcut aliases to "Badger::Timestamp".
use Badger::Timestamp 'TS';
my $ts = TS->new(); # same as Badger::Timestamp->new();
Timestamp()
This subroutine returns the name of the "Badger::Timestamp" class when called without
arguments. Thus it can be used as an alias for "Badger::Timestamp" as per TS.
use Badger::Timestamp 'Timestamp';
my $ts = Timestamp->new(); # same as Badger::Timestamp->new();
When called with arguments, it creates a new "Badger::Timestamp" object.
my $ts = Timestamp($date); # same as Badger::Timestamp->new($date);
Now()
Returns a "Badger::Timestamp" for the current time.
METHODS
new($timestamp)
Constructor method to create a new "Badger::Timestamp" object from a timestamp string or
seconds since the epoch.
The timestamp should be specified as a date and time separated by a single space or upper
case "T". The date should contain 4 digits for the year and two for each of the month and
day separated by any non-numerical characters. The time is comprised of two digits for
each of the hours, minutes and seconds, also separated by any non-numerical characters.
# examples of valid formats
my $stamp = Badger::Timestamp->new('2006-03-19 04:20:42');
my $stamp = Badger::Timestamp->new('2006-03-19T04:20:42');
my $stamp = Badger::Timestamp->new('2006/03/19 04:20:42');
my $stamp = Badger::Timestamp->new('2006/03/19T04:20:42');
The "Badger::Timestamp" module converts these to the canonical form of "YYYY-MM-DD
HH:MM:SS"
my $stamp = Badger::Timestamp->new('2006/03/19T04.20.42');
print $stamp; # 2006-03-19 04:20:42
You can also construct a "Badger::Timestamp" object by specifying the number of seconds
since the epoch. This is the value return by system functions like "time()" and used for
file creation/modification times.
my $stamp = Badger::Timestamp->new(time());
Or can can pass it an existing "Badger::Timestamp" object.
my $stamp2 = Badger::Timestamp->new($stamp);
If you don't specify any argument then you get the current system time as returned by
"time()".
my $now = Badger::Timestamp->new;
now()
Returns a "Badger::Timestamp" object representing the current date and time.
copy()
Returns a new "Badger::Timestamp" object creates as a copy of the current one.
my $copy = $stamp->copy;
This can be useful for making adjustments to a timestamp without affecting the original
object.
my $later = $stamp->copy->adjust( months => 3 );
timestamp()
Returns the complete timestamp in canonical form.
print $stamp->timestamp(); # 2006-03-19 04:20:42
This method is called automatically whenever the object is used as a string value.
print $stamp; # 2006-03-19 04:20:42
format($format)
Returns a formatted version of the timestamp, generated using the POSIX strftime function.
print $stamp->format('%d-%b-%y');
date()
Returns the date component of the timestamp.
print $stamp->date(); # 2006-03-19
year() / years()
Returns the year.
print $stamp->year(); # 2006
Can also be called with an argument to change the year.
$stamp->year(2007);
month() / months()
Returns the month.
print $stamp->month(); # 03
Can also be called with an argument to change the yonth.
$stamp->month(04);
day() / days()
Returns the day.
print $stamp->day(); # 19
Can also be called with an argument to change the day.
$stamp->day(20);
days_in_month()
Returns the number of days in the current month. Accounts correctly for leap years.
leap_year()
Returns a true value (1) if the year is a leap year, a false value (0) if not.
time()
Returns the time component of the timestamp.
print $stamp->time(); # 04:20:42
hour() / hours()
Returns the hours.
print $stamp->hours(); # 04
Can also be called with an argument to change the hours.
$stamp->hours(05);
minute() / minutes()
Returns the minutes.
print $stamp->minutes(); # 20
Can also be called with an argument to change the minutes.
$stamp->minutes(21);
second() / seconds()
Returns the seconds.
print $stamp->seconds(); # 42
Can also be called with an argument to change the seconds.
$stamp->seconds(42);
epoch_time()
Returns the timestamp object as the number of seconds since the epoch time.
compare($when)
This method is used to chronologically compare two timestamps to determine if one is
earlier, later, or exactly equal to another.
The method can be passed another "Badger::Timestamp" object to compare against or an
argument or arguments from which a "Badger::Timestamp" object can be constructed. If no
arguments are passed then it defaults to a comparison against the current time.
my $stamp = Badger::Timestamp->new('2009-01-10 04:20:00');
$stamp->before($another_timestamp_object);
$stamp->before('2009-04-20 04:20:00');
$stamp->before($epoch_seconds);
$stamp->before; # before now
The method returns -1 if the timestamp object represents a time before the timestamp
passed as an argument, 1 if it's after, or 0 if it's equal.
equal($when)
This is a method of convenience which uses compare() to test if two timestamps are equal.
You can pass it any of the arguments accepted by the compare() method.
if ($time1->equal($time2)) {
print "both timestamps are equal\n";
}
This method is overloaded onto the "==" operator, allowing you to perform more natural
comparisons.
if ($time1 == $time2) {
print "both timestamps are equal\n";
}
before($when)
This is a method of convenience which uses compare() to test if one timestamp occurs
before another. It returns a true value (1) if the first timestamp (the object) is before
the second (the argument), or a false value (0) otherwise.
if ($time1->before($time2)) {
print "time1 is before time2\n";
}
This method is overloaded onto the "<" operator.
if ($time1 < $time2) {
print "time1 is before time2\n";
}
after($when)
This is a method of convenience which uses compare() to test if one timestamp occurs after
another. It returns a true value (1) if the first timestamp (the object) is after the
second (the argument), or a false value (0) otherwise.
if ($time1->after($time2)) {
print "time1 is after time2\n";
}
This method is overloaded onto the ">" operator.
if ($time1 > $time2) {
print "time1 is after time2\n";
}
not_equal($when)
This is an alias to the compare() method. It returns a true value (-1 or +1, both of
which Perl considers to be true values) if the timestamps are not equal or false value (0)
if they are.
if ($time1->not_equal($time2)) {
print "time1 is not equal to time2\n";
}
This method is overloaded onto the "!=" operator.
if ($time1 != $time2) {
print "time1 is not equal to time2\n";
}
not_before($when)
This is a method of convenience which uses compare() to test if one timestamp does not
occur before another. It returns a true value (1) if the first timestamp (the object) is
equal to or after the second (the argument), or a false value (0) otherwise.
if ($time1->not_before($time2)) {
print "time1 is not before time2\n";
}
This method is overloaded onto the ">=" operator.
if ($time1 >= $time2) {
print "time1 is not before time2\n";
}
not_after($when)
This is a method of convenience which uses compare() to test if one timestamp does not
occur after another. It returns a true value (1) if the first timestamp (the object) is
equal to or before the second (the argument), or a false value (0) otherwise.
if ($time1->not_after($time2)) {
print "time1 is not after time2\n";
}
This method is overloaded onto the "<=" operator.
if ($time1 <= $time2) {
print "time1 is not after time2\n";
}
adjust(%adjustments)
Method to adjust the timestamp by a fixed amount or amounts.
# positive adjustment
$date->adjust( months => 6, years => 1 );
# negative adjustment
$date->adjust( months => -18, hours => -200 );
Named parameters can be passed as arguments or via a hash reference.
$date->adjust( months => -18, hours => -200 ); # naked
$date->adjust({ months => -18, hours => -200 }); # clothed
You can specify units using singular (second, hour, month, etc) or plural (seconds, hours,
minutes, etc) keys. The method will correctly handle values outside the usual ranges. For
example, you can specify a change of 18 months, -200 hours, -99 seconds, and so on.
A single non-reference argument is assumed to be a duration which is converted to a number
of seconds via the duration() method.
duration($duration)
Returns the number of seconds in a duration. A single numerical argument is assumed to be
a number of seconds and is returned unchanged.
$date->adjust(300); # 300 seconds
A single non-numerical argument should have a suffix indicating the units. In "compact
form" this is a single letter. We use lower case "m" for minutes and upper case "M" for
months.
$date->adjust("300s"); # or "300 seconds"
$date->adjust("90m"); # or "90 minutes"
$date->adjust("3h"); # or "3 hours"
$date->adjust("2d"); # or "2 days"
$date->adjust("6M"); # or "6 months"
$date->adjust("5y"); # or "5 years"
Alternately you can spell the units out in full as shown in the right column above.
However, we only look at the first character of the following word so you can write all
sorts of nonsense which we will dutifully accept without complaint.
$date->adjust("5 sheep"); # 5 seconds
$date->adjust("9 men"); # 9 minutes
$date->adjust("3 yaks"); # 3 years
For the sake of convenience, the method will automatically convert the word "month" into
"Month" so that the first letter is correctly capitalised.
INTERNAL METHODS
split_timestamp()
Splits a timestamp into its constituent parts.
join_timestamp()
Joins the constituent parts of a date back into a timestamp.
uncache()
Removes any internally cached items. This is called automatically whenever the timestamp
is modified.
AUTHOR
Andy Wardley <http://wardley.org>
COPYRIGHT
Copyright (C) 2001-2009 Andy Wardley. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it under the same
terms as Perl itself.