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

 / 
qbit-2.8
River stage two • 32 direct dependents • 33 total dependents
/ qbit::Date

Name

qbit::Array - Functions to manipulate dates.

Functions

trdate

Arguments:

  • $iformat - string, input format;

  • $oformat - string, output format. One of:

    • norm - array ref, ['year', 'month (1-12)', 'day (1-31)', 'hour (0-23)', 'minute (0-59)', 'second (0-59)'];

    • db_time - string, 'YYYY-MM-DD hh:mm:ss';

    • sec - number, seconds like in localtime;

    • days_in_month - number, days in month. Cannot convert from this type to other.

  • $date - scalar, date in input format.

Return value: scalar, date in output format. undef if conversion has errors.

Convert date from iformat to oformat.


            

              
              
trdate(db => sec => '2000-01-01');

curdate

Arguments as hash:

  • oformat - string, output format, see "trdate".

Return value: scalar, current date in output format.


            

              
              
curdate(oformat => 'db');

date_add

Arguments:

  • $date - scalar, date;

  • %opts - hash, additional arguments:

    • iformat - string, input format, default - 'norm';

    • oformat - string, output format, default - 'norm';

    • second - number, quantity of seconds to add;

    • minute - number, quantity of minutes to add;

    • hour - number, quantity of hours to add;

    • day - number, quantity of days to add;

    • week - number, quantity of weeks to add;

    • month - number, quantity of months to add;

    • year - number, quantity of years to add;

Return value: scalar, date in output format.


            

              
              
date_add('2000-01-01', day => 12, hour => 5, iformat => 'db', oformat => 'db');

date_sub

See "date_add"

name2date

Arguments:

  • $name - string, date caption. Available values:

      lastyesterday

      lasttoday

      daybeforeyesterday

      yesterday

      today or day

      tomorrow

      dayaftertomorrow;

  • %opts - hash, additional arguments:

    • oformat: string, output format, default - 'norm'.

Return value: scalar, date in output format. undef unless known name.


            

              
              
name2date('yesterday', oformat => 'db');

name2dates

Arguments:

  • $name - string, period caption. One of:

    • Any from "name2date";

    • week, sevendays, last7days: last 7 days, including today;

    • thisweek: current week, from Monday to today;

    • lastweek, pastweek: past week, from Monday to Sunday;

    • tendays: last 10 days, including today;

    • lastmonth, pastmonth: past month, from 1th to (28|29|30|31)th;

    • month: current month, from 1th to (28|29|30|31)th;

    • thismonth: current month, from 1th to today;

    • year, thisyear: current year, from January 1th to December 31th;

    • {N}days: last {N} days, including today, {N} - numer, quantity of days;

    • pastpastweek: week before past week, from Monday to Sunday;

    • past{N}days: last {N} days before {N} days, {N} - number of days;

    • pastpastmonth: month before past month, from 1th to (28|29|30|31)th;

    • pastyear: past year, from January 1th to December 31th;

    • twoyearsago: year before past year, from January 1th to December 31th;

  • $fd - scalar, start date. Return if unknown period name;

  • $td - scalar, end date. Return if unknown period name;

  • %opts - hash, additional arguments:

    • iformat: string, input format for $fd and $td, default - 'norm';

    • oformat: string, output format, default - 'norm'.

Return value: array, (start_date, end_date).


            

              
              
($fd, $td) = name2date('pastyear', [], [], oformat => 'db'); # ('2012-01-01', '2012-12-31')
($fd, $td) = name2date('other', '2000-01-01', '2000-01-03', iformat => 'db', oformat => 'db'); # ('2000-01-01', '2000-01-03')

dates2array

Arguments:

  • $fd - scalar, start date;

  • $td - scalar, end date;

  • %opts - hash, additional arguments:

    • iformat: string, input format, default - 'norm';

    • oformat: string, output format, default - 'norm';

    • interval: string, step size: day, week, month, year. Default day.

Return value: array of scalars.


            

              
              
my @dates = dates2array('2001-01-01', '2001-01-04', iformat => 'db', oformat => 'db');

dates_delta

Arguments:

  • $fd - scalar, start date;

  • $td - scalar, end date;

  • %opts - hash, additional arguments:

    • iformat: string, input format, default - 'norm'.

Return value: array ref, [years, months, days, hours, minutes, seconds].

dates_delta_days

Arguments: See "dates_delta"

Return value: number, days from $fd to $td.

compare_dates

Arguments:

  • $dt1 - scalar, first date;

  • $dt2 - scalar, second date;

  • %opts - hash, additional arguments:

    • iformat1: string, input format for first date, default - 'norm'.

    • iformat2: string, input format for second date, default - 'norm'.

Return value:

  • -1: $dt1 < $dt2;

  • 0: $dt1 = $dt2;

  • 1: $dt1 > $dt2.


            

              
              
compare_dates($dt1, $dt2, iformat1 => 'db', iformat2 => 'norm')

format_date

Arguments:

  • $date - scalar, date;

  • $format - string, output format;

  • %opts - hash, additional arguments:

    • iformat: string, input format for date, default - 'norm'.

Formaters:


            

              
              
%a  Abbreviated weekday name                                                Thu
%A  Full weekday name                                                       Thursday
%b  Abbreviated month name                                                  Aug
%B  Full month name                                                         August
%c  Date and time representation                                            Thu Aug 23 14:55:02 2001
%d  Day of the month (01-31)                                                23
%H  Hour in 24h format (00-23)                                              14
%I  Hour in 12h format (01-12)                                              02
%j  Day of the year (001-366)                                               235
%m  Month as a decimal number (01-12)                                       08
%M  Minute (00-59)                                                          55
%p  AM or PM designation                                                    PM
%S  Second (00-61)                                                          02
%U  Week number with the first Sunday as the first day of week one (00-53)  33
%w  Weekday as a decimal number with Sunday as 0 (0-6)                      4
%W  Week number with the first Monday as the first day of week one (00-53)  34
%x  Date representation                                                     08/23/01
%X  Time representation                                                     14:55:02
%y  Year, last two digits (00-99)                                           01
%Y  Year                                                                    2001
%Z  Timezone name or abbreviation                                           CDT
%%  A % sign    %

Return value: string


            

              
              
format_date('2001-01-01', '%Y %B', iformat => 'db');

is_date_in_future

Arguments:

  • $date - scalar, date;

  • %opts - hash, additional arguments:

    • iformat: string, input format for date, default - 'norm'.

Return value: boolean.


            

              
              
is_date_in_future($date, iformat => 'db')

is_date_in_past

See "is_date_in_future"

check_date

Arguments:

  • $date - scalar, date;

  • %opts - hash, additional arguments:

    iformat: string, input format for date, default - 'norm'.

Return value: boolean.


            

              
              
check_date($date, iformat => 'db');

Extending trdate


            

              
              
local $qbit::Date::TR_HS{'new_type'} = {
    '>' => sub {my $dt_norm = shift;     ...Convert $dt_norm to new_type code...},
    '<' => sub {my $dt_new_type = shift; ...Convert $dt_new_type to norm code...};
};