DATE

    use Badger::Date 'DATE';

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

Date()

    use Badger::Date 'Date';

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

When called with arguments, it creates a new "Badger::Date" object.

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

Today()

new('YYYY-MM-DD')

The date should contain 4 digits for the year and two for each of the month and day separated by any non-numerical characters.

    # 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 return by system functions like "time()" and used for file creation/modification times.

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

Or can can pass it an existing "Badger::Date" object.

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

If you don't specify any argument then you get the current system time as returned by "time()".

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

today()

copy()

    my $copy = $date->copy;

This can be useful for making adjustments to a date without affecting the original object.

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

date()

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

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

    print $date;               # 2015-03-19

format($format)

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

year() / years()

    print $date->year();       # 2015

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

    $date->year(2016);

month() / months()

    print $date->month();      # 03

Can also be called with an argument to change the yonth.

    $date->month(04);

day() / days()

    print $date->day();        # 19

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

    $date->day(20);

days_in_month()

leap_year()

epoch_time()

compare($when)

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.

equal($when)

    if ($date1->equal($date2)) {
        print "both dates are equal\n";
    }

This method is overloaded onto the "==" operator, allowing you to perform more natural comparisons.

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

before($when)

    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)

    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)

    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)

    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)

    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)

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

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)

    $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("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 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.