The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Venus-4.15
River stage two • 3 direct dependents • 56 total dependents
/ Venus::Date

NAME

Venus::Date - Date Class

ABSTRACT

Date Class for Perl 5

SYNOPSIS

package main;

use Venus::Date;

my $date = Venus::Date->new(570672000);

# $date->string;

# '1988-02-01T00:00:00Z'

DESCRIPTION

This package provides methods for formatting, parsing, and manipulating date and time data.

ATTRIBUTES

This package has the following attributes:

day

day(Int)

This attribute is read-write, accepts (Int) values, and is optional.

month

month(Int)

This attribute is read-write, accepts (Int) values, and is optional.

year

year(Int)

This attribute is read-write, accepts (Int) values, and is optional.

hour

hour(Int)

This attribute is read-write, accepts (Int) values, and is optional.

minute

minute(Int)

This attribute is read-write, accepts (Int) values, and is optional.

second

second(Int)

This attribute is read-write, accepts (Int) values, and is optional.

INHERITS

This package inherits behaviors from:

Venus::Kind::Utility

INTEGRATES

This package integrates behaviors from:

Venus::Role::Buildable

Venus::Role::Explainable

METHODS

This package provides the following methods:

add

add(hashref $data) (Venus::Date)

The add method increments the date and time attributes specified.

Since 0.01

add example 1
# given: synopsis;

$date = $date->add({
  days => 1,
  months => 1,
  years => 1,
});

# $date->string; # 1989-03-03T16:17:54Z

# $date->epoch; # 604945074
add example 2
# given: synopsis;

$date = $date->add({
  hours => 1,
  minutes => 1,
  seconds => 1,
});

# $date->string; # 1988-02-01T01:01:01Z

# $date->epoch; # 570675661

add_days

add_days(number $days) (any)

The add_days method increments the day attribute.

Since 0.01

add_days example 1
# given: synopsis;

$date = $date->add_days(1);

# $date->string; # 1988-02-02T00:00:00Z

# $date->epoch; # 570758400
add_days example 2
# given: synopsis;

$date = $date->add_days(40);

# $date->string; # 1988-03-12T00:00:00Z

# $date->epoch; # 574128000
add_days example 3
# given: synopsis;

$date = $date->add_days(-1);

# $date->string; # 1988-01-31T00:00:00Z

# $date->epoch; # 570585600

add_hms

add_hms(maybe[number] $hours, maybe[number] $minutes, maybe[number] $seconds) (Venus::Date)

The add_hms method increments the hour, minute, and second attributes.

Since 0.01

add_hms example 1
# given: synopsis;

$date = $date->add_hms(1, 0, 0);

# $date->string; # 1988-02-01T01:00:00Z

# $date->epoch; # 570675600
add_hms example 2
# given: synopsis;

$date = $date->add_hms(undef, 1, 1);

# $date->string; # 1988-02-01T00:01:01Z

# $date->epoch; # 570672061
add_hms example 3
# given: synopsis;

$date = $date->add_hms(1, 1);

# $date->string; # 1988-02-01T01:01:00Z

# $date->epoch; # 570675660

add_hours

add_hours(number $hours) (any)

The add_hours method increments the hour attribute.

Since 0.01

add_hours example 1
# given: synopsis;

$date = $date->add_hours(1);

# $date->string; # 1988-02-01T01:00:00Z

# $date->epoch; # 570675600
add_hours example 2
# given: synopsis;

$date = $date->add_hours(25);

# $date->string; # 1988-02-02T01:00:00Z

# $date->epoch; # 570762000
add_hours example 3
# given: synopsis;

$date = $date->add_hours(-1);

# $date->string; # 1988-01-31T23:00:00Z

# $date->epoch; # 570668400

add_mdy

add_mdy(maybe[number] $months, maybe[number] $days, maybe[number] $years) (Venus::Date)

The add_mdy method increments the month, day, and years attributes.

Since 0.01

add_mdy example 1
# given: synopsis;

$date = $date->add_mdy(1, 0, 0);

# $date->string; # 1988-03-02T10:29:04Z

# $date->epoch; # 573301744
add_mdy example 2
# given: synopsis;

$date = $date->add_mdy(undef, 1, 1);

# $date->string; # 1989-02-01T05:48:50Z

# $date->epoch; # 602315330
add_mdy example 3
# given: synopsis;

$date = $date->add_mdy(1, 1);

# $date->string; # 1988-03-03T10:29:04Z

# $date->epoch; # 573388144

add_minutes

add_minutes(number $minutes) (Venus::Date)

The add_minutes method increments the minute attribute.

Since 0.01

add_minutes example 1
# given: synopsis;

$date = $date->add_minutes(1);

# $date->string; # 1988-02-01T00:01:00Z

# $date->epoch; # 570672060
add_minutes example 2
# given: synopsis;

$date = $date->add_minutes(61);

# $date->string; # 1988-02-01T01:01:00Z

# $date->epoch; # 570675660
add_minutes example 3
# given: synopsis;

$date = $date->add_minutes(-1);

# $date->string; # 1988-01-31T23:59:00Z

# $date->epoch; # 570671940

add_months

add_months(number $months) (Venus::Date)

The add_months method increments the month attribute.

Since 0.01

add_months example 1
# given: synopsis;

$date = $date->add_months(1);

# $date->string; # 1988-03-02T10:29:04Z

# $date->epoch; # 573301744
add_months example 2
# given: synopsis;

$date = $date->add_months(13);

# $date->string; # 1989-03-02T16:17:52Z

# $date->epoch; # 604858672
add_months example 3
# given: synopsis;

$date = $date->add_months(-1);

# $date->string; # 1988-01-01T13:30:56Z

# $date->epoch; # 568042256

add_seconds

add_seconds(number $seconds) (Venus::Date)

The add_seconds method increments the second attribute.

Since 0.01

add_seconds example 1
# given: synopsis;

$date = $date->add_seconds(1);

# $date->string; # 1988-02-01T00:00:01Z

# $date->epoch; # 570672001
add_seconds example 2
# given: synopsis;

$date = $date->add_seconds(61);

# $date->string; # 1988-02-01T00:01:01Z

# $date->epoch; # 570672061
add_seconds example 3
# given: synopsis;

$date = $date->add_seconds(-1);

# $date->string; # 1988-01-31T23:59:59Z

# $date->epoch; # 570671999

add_years

add_years(number $years) (Venus::Date)

The add_years method increments the year attribute.

Since 0.01

add_years example 1
# given: synopsis;

$date = $date->add_years(1);

# $date->string; # 1989-01-31T05:48:50Z

# $date->epoch; # 602228930
add_years example 2
# given: synopsis;

$date = $date->add_years(50);

# $date->string; # 2038-01-31T02:41:40Z

# $date->epoch; # 2148518500
add_years example 3
# given: synopsis;

$date = $date->add_years(-1);

# $date->string; # 1987-01-31T18:11:10Z

# $date->epoch; # 539115070

epoch

epoch() (number)

The epoch method returns the epoch.

Since 0.01

epoch example 1
# given: synopsis;

my $epoch = $date->epoch;

# 570672000

explain

explain() (number)

The explain method returns the epoch and is used in stringification operations.

Since 0.01

explain example 1
# given: synopsis;

my $explain = $date->explain;

# 570672000

format

format(string $format) (string)

The format method returns the formatted date and time string. See strftime for formatting rules.

Since 0.01

format example 1
# given: synopsis;

my $format = $date->format('%A, %B %e, %Y');

# Monday, February  1, 1988
format example 2
# given: synopsis;

my $format = $date->format('%b %e %a');

# Feb  1 Mon

hms

hms() (string)

The hms method returns the time formatted as hh:mm:ss.

Since 0.01

hms example 1
# given: synopsis;

my $hms = $date->hms;

# 00:00:00

iso8601

iso8601() (string)

The iso8601 method returns the date and time formatted as an ISO8601 string.

Since 0.01

iso8601 example 1
# given: synopsis;

my $iso8601 = $date->iso8601;

# 1988-02-01T00:00:00

mdy

mdy() (string)

The mdy method returns the date formatted as mm-dd-yyyy.

Since 0.01

mdy example 1
# given: synopsis;

my $mdy = $date->mdy;

# 02-01-1988

parse

parse(any @data) (Venus::Date)

The parse method resets and returns a date object based on the parsed time provided. See strptime for parsing rules.

Since 0.01

parse example 1
# given: synopsis;

$date = $date->parse('Monday, February  1, 1988', '%A, %B %e, %Y');

# $date->string; # 1988-02-01T00:00:00Z

# $date->epoch; # 570672000

reset

reset(number $time) (Venus::Date)

The reset method resets all attributes to correspond with the epoch provided.

Since 0.01

reset example 1
# given: synopsis;

$date = $date->reset(631152000);

# $date->string; # 1990-01-01T00:00:00Z

# $date->epoch; # 631152000

restart

restart(string $interval) (Venus::Date)

The restart method truncates the date and time to the specified unit of time, e.g. year, quarter, month, day, hour, minute, second.

Since 0.01

restart example 1
# given: synopsis;

$date = $date->restart('year');

# $date->string; # 1988-01-01T00:00:00Z

# $date->epoch; # 567993600
restart example 2
# given: synopsis;

$date = $date->restart('quarter');

# $date->string; # 1988-01-01T00:00:00Z

# $date->epoch; # 567993600
restart example 3
# given: synopsis;

$date = $date->restart('month');

# $date->string; # 1988-02-01T00:00:00Z

# $date->epoch; # 570672000

restart_day

restart_day() (Venus::Date)

The restart_day method truncates the date and time to the day.

Since 1.02

restart_day example 1
# given: synopsis;

$date = $date->restart_day;

# $date->string; # 1988-02-01T00:00:00Z

# $date->epoch; # 570672000

restart_hour

restart_hour() (Venus::Date)

The restart_hour method truncates the date and time to the hour.

Since 1.02

restart_hour example 1
# given: synopsis;

$date = $date->restart_hour;

# $date->string; # 1988-02-01T00:00:00Z

# $date->epoch; # 570672000

restart_minute

restart_minute() (Venus::Date)

The restart_minute method truncates the date and time to the minute.

Since 1.02

restart_minute example 1
# given: synopsis;

$date = $date->restart_minute;

# $date->string; # 1988-02-01T00:00:00Z

# $date->epoch; # 570672000

restart_month

restart_month() (Venus::Date)

The restart_month method truncates the date and time to the month.

Since 1.02

restart_month example 1
# given: synopsis;

$date = $date->restart_month;

# $date->string; # 1988-02-01T00:00:00Z

# $date->epoch; # 570672000

restart_quarter

restart_quarter() (Venus::Date)

The restart_quarter method truncates the date and time to the quarter.

Since 1.02

restart_quarter example 1
# given: synopsis;

$date = $date->restart_quarter;

# $date->string; # 1988-01-01T00:00:00Z

# $date->epoch; # 567993600

restart_second

restart_second() (Venus::Date)

The restart_second method truncates the date and time to the second.

Since 1.02

restart_second example 1
# given: synopsis;

$date = $date->restart_second;

# $date->string; # 1988-02-01T00:00:00Z

# $date->epoch; # 570672000

restart_year

restart_year() (Venus::Date)

The restart_year method truncates the date and time to the year.

Since 1.02

restart_year example 1
# given: synopsis;

$date = $date->restart_year;

# $date->string; # 1988-01-01T00:00:00Z

# $date->epoch; # 567993600

rfc1123

rfc1123() (string)

The rfc1123 method returns the date and time formatted as an RFC1123 string.

Since 0.01

rfc1123 example 1
# given: synopsis;

my $rfc1123 = $date->rfc1123;

# Mon, 01 Feb 1988 00:00:00 GMT

rfc3339

rfc3339() (string)

The rfc3339 method returns the date and time formatted as an RFC3339 string.

Since 0.01

rfc3339 example 1
# given: synopsis;

my $rfc3339 = $date->rfc3339;

# 1988-02-01T00:00:00Z

rfc7231

rfc7231() (string)

The rfc7231 method returns the date and time formatted as an RFC7231 string.

Since 0.01

rfc7231 example 1
# given: synopsis;

my $rfc7231 = $date->rfc7231;

# Mon, 01 Feb 1988 00:00:00 UTC

rfc822

rfc822() (string)

The rfc822 method returns the date and time formatted as an RFC822 string.

Since 0.01

rfc822 example 1
# given: synopsis;

my $rfc822 = $date->rfc822;

# Mon, 01 Feb 1988 00:00:00 +0000

set

set(hashref $data) (Venus::Date)

The set method sets the date and time attributes specified.

Since 0.01

set example 1
# given: synopsis;

$date = $date->set({
  day => 1,
  month => 1,
  year => 2000,
});

# $date->string; # 2000-01-01T00:00:00Z

# $date->epoch; # 946684800
set example 2
# given: synopsis;

$date = $date->set({
  day => 1,
  month => 12,
});

# $date->string; # 1988-12-01T00:00:00Z

# $date->epoch; # 596937600
set example 3
# given: synopsis;

$date = $date->set({
  day => 1,
  month => 12,
  year => 1979,
});

# $date->string; # 1979-12-01T00:00:00Z

# $date->epoch; # 312854400

set_hms

set_hms(maybe[number] $hours, maybe[number] $minutes, maybe[number] $seconds) (Venus::Date)

The set_hms method sets the hour, minute, and second attributes.

Since 0.01

set_hms example 1
# given: synopsis;

$date = $date->set_hms(1, 0, 0);

# $date->string; # 1988-02-01T01:00:00Z

# $date->epoch; # 570675600
set_hms example 2
# given: synopsis;

$date = $date->set_hms(undef, 30, 30);

# $date->string; # 1988-02-01T00:30:30Z

# $date->epoch; # 570673830
set_hms example 3
# given: synopsis;

$date = $date->set_hms(0, 59, 59);

# $date->string; # 1988-02-01T00:59:59Z

# $date->epoch; # 570675599

set_mdy

set_mdy(maybe[number] $months, maybe[number] $days, maybe[number] $years) (Venus::Date)

The set_mdy method sets the month, day, and year attributes.

Since 0.01

set_mdy example 1
# given: synopsis;

$date = $date->set_mdy(4, 30, 1990);

# $date->string; # 1990-04-30T00:00:00Z

# $date->epoch; # 641433600
set_mdy example 2
# given: synopsis;

$date = $date->set_mdy(4, 30, undef);

# $date->string; # 1988-04-30T00:00:00Z

# $date->epoch; # 578361600
set_mdy example 3
# given: synopsis;

$date = $date->set_mdy(undef, 15, undef);

# $date->string; # 1988-02-15T00:00:00Z

# $date->epoch; # 571881600

string

string() (string)

The string method returns a date and time string, and is an alias for "rfc3339".

Since 0.01

string example 1
# given: synopsis;

my $string = $date->string;

# 1988-02-01T00:00:00Z

sub

sub(hashref $data) (Venus::Date)

The sub method method decrements the date and time attributes specified.

Since 0.01

sub example 1
# given: synopsis;

$date = $date->sub({
  days => 1,
  months => 1,
  years => 1,
});

# $date->string; # 1986-12-31T07:42:06Z

# $date->epoch; # 536398926
sub example 2
# given: synopsis;

$date = $date->sub({
  hours => 1,
  minutes => 1,
  seconds => 1,
});

# $date->string; # 1988-01-31T22:58:59Z

# $date->epoch; # 570668339

sub_days

sub_days(number $days) (Venus::Date)

The sub_days method decrements the day attribute.

Since 0.01

sub_days example 1
# given: synopsis;

$date = $date->sub_days(1);

# $date->string; # 1988-01-31T00:00:00Z

# $date->epoch; # 570585600
sub_days example 2
# given: synopsis;

$date = $date->sub_days(32);

# $date->string; # 1987-12-31T00:00:00Z

# $date->epoch; # 567907200
sub_days example 3
# given: synopsis;

$date = $date->sub_days(-1);

# $date->string; # 1988-02-02T00:00:00Z

# $date->epoch; # 570758400

sub_hms

sub_hms(maybe[number] $hours, maybe[number] $minutes, maybe[number] $seconds) (Venus::Date)

The sub_hms method decrements the hour, minute, and second attributes.

Since 0.01

sub_hms example 1
# given: synopsis;

$date = $date->sub_hms(1, 0, 0);

# $date->string; # 1988-01-31T23:00:00Z

# $date->epoch; # 570668400
sub_hms example 2
# given: synopsis;

$date = $date->sub_hms(undef, 1, 1);

# $date->string; # 1988-01-31T23:58:59Z

# $date->epoch; # 570671939
sub_hms example 3
# given: synopsis;

$date = $date->sub_hms(1, 1);

# $date->string; # 1988-01-31T22:59:00Z

# $date->epoch; # 570668340

sub_hours

sub_hours(number $hours) (any)

The sub_hours method decrements the hour attribute.

Since 0.01

sub_hours example 1
# given: synopsis;

$date = $date->sub_hours(1);

# $date->string; # 1988-01-31T23:00:00Z

# $date->epoch; # 570668400
sub_hours example 2
# given: synopsis;

$date = $date->sub_hours(25);

# $date->string; # 1988-01-30T23:00:00Z

# $date->epoch; # 570582000
sub_hours example 3
# given: synopsis;

$date = $date->sub_hours(-1);

# $date->string; # 1988-02-01T01:00:00Z

# $date->epoch; # 570675600

sub_mdy

sub_mdy(maybe[number] $months, maybe[number] $days, maybe[number] $years) (Venus::Date)

The sub_mdy method decrements the month, day, and year attributes.

Since 0.01

sub_mdy example 1
# given: synopsis;

$date = $date->sub_mdy(1, 1, 1);

# $date->string; # 1986-12-31T07:42:06Z

# $date->epoch; # 536398926
sub_mdy example 2
# given: synopsis;

$date = $date->sub_mdy(1, 1, undef);

# $date->string; # 1987-12-31T13:30:56Z

# $date->epoch; # 567955856
sub_mdy example 3
# given: synopsis;

$date = $date->sub_mdy(1, 1);

# $date->string; # 1987-12-31T13:30:56Z

# $date->epoch; # 567955856

sub_minutes

sub_minutes(number $minutes) (Venus::Date)

The sub_minutes method decrements the minute attribute.

Since 0.01

sub_minutes example 1
# given: synopsis;

$date = $date->sub_minutes(1);

# $date->string; # 1988-01-31T23:59:00Z

# $date->epoch; # 570671940
sub_minutes example 2
# given: synopsis;

$date = $date->sub_minutes(61);

# $date->string; # 1988-01-31T22:59:00Z

# $date->epoch; # 570668340
sub_minutes example 3
# given: synopsis;

$date = $date->sub_minutes(-1);

# $date->string; # 1988-02-01T00:01:00Z

# $date->epoch; # 570672060

sub_months

sub_months(number $months) (Venus::Date)

The sub_months method decrements the month attribute.

Since 0.01

sub_months example 1
# given: synopsis;

$date = $date->sub_months(1);

# $date->string; # 1988-01-01T13:30:56Z

# $date->epoch; # 568042256
sub_months example 2
# given: synopsis;

$date = $date->sub_months(13);

# $date->string; # 1987-01-01T07:42:08Z

# $date->epoch; # 536485328
sub_months example 3
# given: synopsis;

$date = $date->sub_months(-1);

# $date->string; # 1988-03-02T10:29:04Z

# $date->epoch; # 573301744

sub_seconds

sub_seconds(number $seconds) (Venus::Date)

The sub_seconds method decrements the second attribute.

Since 0.01

sub_seconds example 1
# given: synopsis;

$date = $date->sub_seconds(1);

# $date->string; # 1988-01-31T23:59:59Z

# $date->epoch; # 570671999
sub_seconds example 2
# given: synopsis;

$date = $date->sub_seconds(61);

# $date->string; # 1988-01-31T23:58:59Z

# $date->epoch; # 570671939
sub_seconds example 3
# given: synopsis;

$date = $date->sub_seconds(-1);

# $date->string; # 1988-02-01T00:00:01Z

# $date->epoch; # 570672001

sub_years

sub_years(number $years) (Venus::Date)

The sub_years method decrements the years attribute.

Since 0.01

sub_years example 1
# given: synopsis;

$date = $date->sub_years(1);

# $date->string; # 1987-01-31T18:11:10Z

# $date->epoch; # 539115070
sub_years example 2
# given: synopsis;

$date = $date->sub_years(25);

# $date->string; # 1963-01-31T22:39:10Z

# $date->epoch; # -218251250
sub_years example 3
# given: synopsis;

$date = $date->sub_years(-1);

# $date->string; # 1989-01-31T05:48:50Z

# $date->epoch; # 602228930

OPERATORS

This package overloads the following operators:

operation: (!=)

This package overloads the != operator.

example 1

# given: synopsis;

my $result = $date != 570672001;

# 1
operation: ("")

This package overloads the "" operator.

example 1

# given: synopsis;

my $result = "$date";

# "570672000"
operation: (+)

This package overloads the + operator.

example 1

# given: synopsis;

my $result = $date + 0;

# 570672000
operation: (-)

This package overloads the - operator.

example 1

# given: synopsis;

my $result = $date - 0;

# 570672000
operation: (0+)

This package overloads the 0+ operator.

example 1

# given: synopsis;

my $result = 0 + $date;

# 570672000
operation: (==)

This package overloads the == operator.

example 1

# given: synopsis;

my $result = $date == 570672000;

# 1
operation: (>)

This package overloads the > operator.

example 1

# given: synopsis;

my $result = $date > 570671999;

# 1
operation: (>=)

This package overloads the >= operator.

example 1

# given: synopsis;

my $result = $date >= 570672000;

# 1
operation: (<)

This package overloads the < operator.

example 1

# given: synopsis;

my $result = $date < 570672001;

# 1
operation: (<=)

This package overloads the <= operator.

example 1

# given: synopsis;

my $result = $date <= 570672000;

# 1
operation: (eq)

This package overloads the eq operator.

example 1

# given: synopsis;

my $result = $date eq '570672000';

# 1
operation: (ne)

This package overloads the ne operator.

example 1

# given: synopsis;

my $result = $date ne '560672000';

# 1
operation: (~~)

This package overloads the ~~ operator.

example 1

# given: synopsis;

my $result = $date ~~ '570672000';

# 1

AUTHORS

Awncorp, awncorp@cpan.org

LICENSE

Copyright (C) 2022, Awncorp, awncorp@cpan.org.

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