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.

cpanm Mojar::Cron

perl -MCPAN -e shell
install Mojar::Cron