Badger::Date(3pm)

💖 Badger::Date 💖

okay bestie, welcome to Badger::Date — it's a manual page, it's from Badger::Date(3pm), and it is genuinely the most low-key iconic little date object you will ever meet. it's a simple object representation of a date. that's it. that's the whole vibe. ✨

---

🌸 SYNOPSIS 🌸

use Badger::Date;

# date defaults to today to date/time now
my $date = Badger::Date->new();
my $date = Badger::Date->today();

# or from ISO-8601 date (or similar)
my $stamp = Badger::Date->new('2015-03-19');

# or from individual arguments
my $date = Badger::Date->new(
    year    => 2015,
    month   => 3,
    day     => 19
);

---

🦋 DESCRIPTION 🦋

so this module implements a small and simple object for representing a date. its scope is intentionally limited — like, on purpose, bestie — to the kind of applications that need very basic date functionality with minimal overhead. it's giving "small but mighty." 🫶

for any non-trivial date manipulation you should almost certainly be using the most excellent DateTime modules instead. no cap. this one is not the main character for heavy lifting.

this code is derived from Badger::Timestamp. 💅

---

✨ EXPORTABLE SUBROUTINES ✨

🎀 DATE

this is a shortcut alias to Badger::Date. slay.

use Badger::Date 'DATE';

my $date = DATE->new();         # same as Badger::Date->new();

🎀 Date()

this subroutine returns the name of the Badger::Date class when you call it with no arguments. so it can just vibe as an alias for Badger::Date, same as DATE up there. 💖

use Badger::Date 'Date';

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

when you call it with arguments, it creates a new Badger::Date object. periodt.

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

🎀 Today()

returns a Badger::Date for the current date. it's literally today. 🌈

---

👑 METHODS 👑

🌟 new('YYYY-MM-DD')

constructor method to create a new Badger::Date object from a date string or seconds since the epoch.

the date should contain 4 digits for the year and two for each of the month and day, separated by any non-numerical characters. any. non-numerical. characters. we're flexible like that. 💅

# examples of valid formats
my $date = Badger::Date->new('2015-03-19');
my $date = Badger::Date->new('2015/03/19');

the Badger::Date module converts these to the canonical form of YYYY-MM-DD:

my $date = Badger::Date->new('2015/03/19');
print $date;       # 2015-03-19

you can also construct a Badger::Date object by specifying the number of seconds since the epoch. this is the value returned by system functions like time() and used for file creation/modification times. iykyk. ⭐

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

or can can pass it an existing Badger::Date object. (yes, the original says "can can". we respect the source material around here. 😭)

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

if you don't specify any argument then you get the current system time as returned by time(). no thoughts, just now. 🕐

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

🌟 today()

returns a Badger::Date object representing the current date. ✨

🌟 copy()

returns a new Badger::Date object created as a copy of the current one.

my $copy = $date->copy;

this can be useful for making adjustments to a date without affecting the original object. protect your peace, protect your original object. 🫶

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

🌟 date()

returns the complete date in canonical form.

print $date->date();  # 2015-03-19

this method is called automatically whenever the object is used as a string value. so it just does that. iconic behaviour. 💅

print $date;               # 2015-03-19

🌟 format($format)

returns a formatted version of the timestamp, generated using the POSIX strftime function.

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

🌟 year() / years()

returns the year.

print $date->year();       # 2015

can also be called with an argument to change the year.

$date->year(2016);

🌟 month() / months()

returns the month.

print $date->month();      # 03

can also be called with an argument to change the yonth. (yes. "yonth". the original says "yonth". we are not fixing it, we are cherishing it. 💀)

$date->month(04);

🌟 day() / days()

returns the day.

print $date->day();        # 19

can also be called with an argument to change the day.

$date->day(20);

🌟 days_in_month()

returns the number of days in the current month. accounts correctly for leap years. it knows things. 🔥

🌟 leap_year()

returns a true value (1) if the year is a leap year, a false value (0) if not. simple as that, bestie.

🌟 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 dates to determine if one is earlier, later, or exactly equal to another.

the method can be passed another Badger::Date object to compare against, or an argument or arguments from which a Badger::Date object can be constructed. if no arguments are passed then it defaults to a comparison against the current time. ✨

my $date    = Badger::Date->new('2015-01-10');
my $compare = Badger::Date->new('2015-03-19');

$date->before($compare);           # date object
$date->before('2015-03-19');       # literal date
$date->before($epoch_seconds);     # epoch seconds, e.g. from file time
$date->before;                     # before now

the method returns -1 if the date object represents a date before the date passed as an argument, 1 if it's after, or 0 if it's equal. three outcomes, one method, zero drama. 🍓

🌟 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 ($date1->equal($date2)) {
    print "both dates are equal\n";
}

this method is overloaded onto the == operator, allowing you to perform more natural comparisons. cute, right?

if ($date1 == $date2) {
    print "both date are equal\n";
}

🌟 before($when)

this is a method of convenience which uses compare() to test if one date 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 ($date1->before($date2)) {
    print "$date1 is before $date2\n";
}

this method is overloaded onto the < operator.

if ($date1 < $date2) {
    print "$date1 is before $date2\n";
}

🌟 after($when)

this is a method of convenience which uses compare() to test if one date occurs after another. it returns a true value (1) if the first date (the object) is after the second (the argument), or a false value (0) otherwise.

if ($date1->after($date2)) {
    print "$date1 is after $date2\n";
}

this method is overloaded onto the > operator.

if ($date1 > $date2) {
    print "$date1 is after $date2\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 dates are not equal, or a false value (0) if they are.

if ($date1->not_equal($date2)) {
    print "$date1 is not equal to $date2\n";
}

this method is overloaded onto the != operator.

if ($date1 != $date2) {
    print "$date1 is not equal to $date2\n";
}

🌟 not_before($when)

this is a method of convenience which uses compare() to test if one date does not occur before another. it returns a true value (1) if the first date (the object) is equal to or after the second (the argument), or a false value (0) otherwise.

if ($date1->not_before($date2)) {
    print "$date1 is not before $date2\n";
}

this method is overloaded onto the >= operator.

if ($date1 >= $date2) {
    print "$date1 is not before $date2\n";
}

🌟 not_after($when)

this is a method of convenience which uses compare() to test if one date does not occur after another. it returns a true value (1) if the first date (the object) is equal to or before the second (the argument), or a false value (0) otherwise.

if ($date1->not_after($date2)) {
    print "$date1 is not after $date2\n";
}

this method is overloaded onto the <= operator.

if ($date1 <= $date2) {
    print "$date1 is not after $date2\n";
}

🌟 adjust(%adjustments)

method to adjust the date by a fixed amount or amounts.

# positive adjustment
$date->adjust( months => 6, years => 1 );

# negative adjustment
$date->adjust( months => -18 );

named parameters can be passed as arguments or via a hash reference.

$date->adjust(  months => -18  );        # naked
$date->adjust({ months => -18 });        # clothed

you can specify units using singular (day, month, year) or plural (days, months, years) keys. the method will correctly handle values outside the usual ranges. for example, you can specify a change of 18 months, -2000 days, and so on. go wild, honestly. 🦋

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. yes, the case matters, bestie, don't mix them up. 💅

$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. 💀 we are not the grammar police, we are the date police.

$date->adjust("5 Monkeys"); # 5 months
$date->adjust("9 doobies"); # 9 days
$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. little glow-up, no effort required. ✨

---

💜 AUTHOR 💜

Andy Wardley <http://wardley.org> — the icon, the legend. 👑

---

💖 COPYRIGHT 💖

Copyright (C) 2001-2015 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 🫶 — signed off with perl v5.36.0, dated 2023-08-28, from Badger::Date(3pm) itself. go forth and format some dates. 💅✨🌸