Badger...mestamp(3pm)

💖 Badger::Timestamp — the Badger...mestamp(3pm) page, bestie edition

okay so this is the manual page for Badger::Timestamp, and it's literally your new bestie for "what time is it and can I do math on it".

---

✨ NAME ✨

Badger::Timestamp — an 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 🦋

So. This module is a small and simple little object for representing a moment in time. Its scope is intentionally limited, okay? On purpose. It's for the kind of apps that need very basic date and time stuff with basically no overhead. Think: a CGI script or a library making a timestamp for a cookie 🍪, printing a "last modified" date at the bottom of a web page, or slapping a timestamp on a log file message — all without having to remember the right incantation to hand to strftime(). iykyk.

real talk: for any non-trivial date manipulation you should almost certainly be using the most excellent DateTime modules instead. no cap.

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), like the ones used to store timestamps in databases. e.g. 2009-04-20T04:20:00.
• To grok epoch times (seconds since 1st January 1970), like the ones used for file modification times.
• To perform basic date manipulation, e.g. adding or subtracting days, months, years, etc. — the exact vibe you want when you're constructing expiry dates for web content, cookies, etc. 🍪
• To perform simple date comparisons, e.g. so you can see if one of those previously mentioned expiry dates has already lapsed. 👀

Fun lore drop 🧚: this module is derived from the Template Toolkit date plugin. It got moved out into a stand-alone module in 2006 for use in various commercial projects. Then it was made fully generic and moved into the Badger fold in January 2009.

heads up bestie: the docs literally say this documentation may be incorrect or incomplete in places. so like. fair warning. 🙈

---

🎀 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()

When you call this subroutine with no arguments, it returns the name of the Badger::Timestamp class. Which means it works as an alias for Badger::Timestamp, exactly like TS does. 🫶

use Badger::Timestamp 'Timestamp';

my $ts = Timestamp->new();  # same as Badger::Timestamp->new();

When you call it 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. ⏰✨ main character energy, right now, this instant.

---

✨ METHODS ✨

🦋 new($timestamp)

Bestie, this is the constructor. It makes a fresh Badger::Timestamp object from a timestamp string or from seconds since the epoch.

Your timestamp should be a date and a time, separated by a single space or an upper case T. The date needs 4 digits for the year and two digits each for month and day, separated by any non-numerical characters. The time is two digits each for 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 those to the canonical form of YYYY-MM-DD HH:MM:SS, slay.

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 giving it the number of seconds since the epoch. That's the value returned by system functions like time() and the kind of thing used for file creation/modification times. Time math? Obsessed.

my $stamp = Badger::Timestamp->new(time());

Or you can pass it an existing Badger::Timestamp object. Copy era.

my $stamp2 = Badger::Timestamp->new($stamp);

If you don't specify any argument, you get the current system time as returned by time(). No thoughts, just now.

my $now = Badger::Timestamp->new;

🌸 now()

Returns a Badger::Timestamp object representing the current date and time. It's giving right now.

🎀 copy()

Returns a new Badger::Timestamp object created as a copy of the current one. Dupe it, bestie.

my $copy = $stamp->copy;

This is useful for making adjustments to a timestamp without affecting the original object. Protect the original's peace.

my $later = $stamp->copy->adjust( months => 3 );

💖 timestamp()

Returns the complete timestamp in canonical form. Main character formatting.

print $stamp->timestamp();  # 2006-03-19 04:20:42

This method is called automatically whenever the object is used as a string value. It just knows.

print $stamp;               # 2006-03-19 04:20:42

✨ format($format)

Returns a formatted version of the timestamp, generated using the POSIX strftime function. Cute little glow-up.

print $stamp->format('%d-%b-%y');

🦋 date()

Returns the date component of the timestamp. Just the date part, periodt.

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. Glow-up unlocked.

$stamp->year(2007);

🍓 month() / months()

Returns the month.

print $stamp->month();      # 03

Can also be called with an argument to change the yonth. (That's the original's typo, not mine, and I'm keeping every detail 💅)

$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. She did her calendar homework.

👑 leap_year()

Returns a true value (1) if the year is a leap year, a false value (0) if not. Leap year? Iconic.

💜 time()

Returns the time component of the timestamp. Just the time part.

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. Raw epoch energy.

💀 compare($when)

This method is used to chronologically compare two timestamps to determine if one is earlier, later, or exactly equal to another. Vibe check, but for time.

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. Bestie behavior.

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 a 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. Time travel, but make it legal.

# 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. She's flexible like that.

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. Case matters, bestie.

$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. No notes.

$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. Little dissection moment.

🦋 join_timestamp()

Joins the constituent parts of a date back into a timestamp. Reassembly era.

💅 uncache()

Removes any internally cached items. This is called automatically whenever the timestamp is modified. Clear the cache, clear the mind.

---

👑 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.

---

And that's the whole page, bestie. This lil time icon was made with perl v5.36.0, dated 2023-08-28, and it's Badger...mestamp(3pm). Periodt. 💅✨