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.
Install Now
PNG Icons
Emojis
