view release on metacpan or  search on metacpan

lib/Badger/Date.pm  view on Meta::CPAN

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

=head2 equal($when)

This is a method of convenience which uses L<compare()> to test if two
timestamps are equal.  You can pass it any of the arguments accepted by the
L<compare()> method.

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

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

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

=head2 before($when)

This is a method of convenience which uses L<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 C<E<lt>> operator.

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

=head2 after($when)

This is a method of convenience which uses L<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 C<E<gt>> operator.

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

=head2 not_equal($when)

This is an alias to the L<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 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 C<!=> operator.

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

=head2 not_before($when)

This is a method of convenience which uses L<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 C<E<gt>=> operator.

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

=head2 not_after($when)

This is a method of convenience which uses L<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 C<E<lt>=> operator.

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

=head2 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.

A single non-reference argument is assumed to be a duration which is
converted to a number of seconds via the L<duration()> method.

=head2 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 C<m> for
minutes and upper case C<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 C<month> into C<Month> so that the first letter is correctly capitalised.

=head1 AUTHOR