/ 
Mojar-Cron-0.501
River stage one • 1 direct dependent • 1 total dependent
/ Mojar::Cron::Date

NAME

Mojar::Cron::Date - Integer arithmetic for ISO dates

SYNOPSIS

say Mojar::Cron::Date->$_ for qw(yesterday today tomorrow);

DESCRIPTION

Methods for manipulating simple dates.

First, make a date. That should either be using your machine's local timezone:

$local_date = Mojar::Cron::Date->yesterday;
$local_date = Mojar::Cron::Date->today;
$local_date = Mojar::Cron::Date->tomorrow;

or using UTC:

$utc_date = Mojar::Cron::Date->current->previous;
$utc_date = Mojar::Cron::Date->current;
$utc_date = Mojar::Cron::Date->current->next;

or via a literal value:

$date = Mojar::Cron::Date->new('2005-02-14');

or by copying:

$copied_date = $date->new;

Then once you have a date, it is timezone-neutral -- you simply roll forwards or backwards.

$date->roll(1);
$date->roll_back(1);
$date->roll_back(7);
$date->roll(-7);
$date->roll_to(0);

Or you can go non-mutating by creating fresh dates equal to those values.

$future_date = $date->next;
$past_date = $date->previous;
$past_date = $date->before(7);
$past_date = $date->after(-7);
$soon_date = $date->new->roll_to(0);

PORTABILITY CAVEAT

This module makes heavy use of POSIX::strftime and is not expected to work on platforms where that is missing or faulty. It is tested regularly on linux.

CONSTRUCTORS

current

The date of the current UTC time.

$utc_date = Mojar::Cron::Date->current;

today

The date of the current local time.

$local_date = Mojar::Cron::Date->today;

tomorrow

The date after today.

$local_date = Mojar::Cron::Date->tomorrow;

yesterday

The date before today.

$local_date = Mojar::Cron::Date->yesterday;

METHODS

after

A non-mutating generator for a fresh date that is this many nights after the source (invoker) date.

$future_date = $date->after(28);

before

A non-mutating generator for a fresh date that is this many nights before the source (invoker) date.

$past_date = $date->before(28);

dow

The numeric weekday of this date.

$date->roll_to(1);  # Now on a Monday
my $dow_id = $date->dow;  # 1 : Mon

The answer will a number from 0 to 6, with 0 indicating Sunday and 6 Saturday.

format

$epoch_seconds = $date->format('%s')
$month_name = $date->format('%B')

Format the date to a string.

is_weekend

next

previous

roll

Roll date forwards by a number of nights.

$date->roll(1);  # next day
$date->roll(7);  # week later

roll_back

Roll date backwards by a number of nights.

$date->roll_back(1);  # previous day
$date->roll_back(7);  # week earlier

which are equivalent to

$date->roll(-1);
$date->roll(-7);

roll_to

Roll date forwards by the least amount to make it the specified weekday. The most it can roll forwards is 6 nights.

$date->roll_to(0);  # 0 : Sun
$date->roll_to(1);  # 1 : Mon
...
$date->roll_to(6);  # 6 : Sat

If $date is a Monday, then $date-roll_to(1)> will make no change since it is already on a Monday. On the other hand, $date-roll_to(0)> will make it roll forwards 6 nights to get to the following Sunday.

Like the other roll* methods, roll_to is also a mutator. For the non-mutating equivalent, first copy with new.

$soon = $date->new->roll_to(0);

sleeps (*linux only*)

How many sleeps till the specified date? The answer will be positive if given a future date, negative if given a past date.

$sleeps = $date->sleeps($my_next_birthday);

FUNCTIONS

sort

@sorted  = sort {$a cmp $b} @dates
@reverse = sort {$b cmp $a} @dates
@sorted  = sort {$a <=> $b} @dates
@reverse = sort {$b <=> $a} @dates

Built-in forward and reverse sorting works, giving the same result with either operator.

COPYRIGHT AND LICENCE

Copyright (C) 2016--2022, Nic Sandfield.

This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.