The Perl Toolchain Summit 2025 Needs You: You can help 🙏 Learn more

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