The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
SPVM-Time-Piece-0.003
River stage zero No dependents
/ SPVM::Time::Piece

Name

SPVM::Time::Piece - Dates and Times

Description

The Time::Piece class in SPVM has methods to manipulate dates and times.

Usage

  use Time::Piece;
  
  my $tp = Time::Piece->localtime;
  say "Time is " . $tp->cdate;
  say "Year is " . $tp->year;

Interfaces

Cloneable

Fields

is_localtime

has is_localtime : byte;

The flag if the "tm" field is interpreted as a local time.

tm

has tm : Sys::Time::Tm;

Time information.

epoch

has epoch : ro long;

Seconds from epoch time.

Class Methods

localtime

static method localtime : Time::Piece ($epoch : long = -1, $allow_minus : int = 0);

Creates a bew Time::Piece object given the epoch time, and returns it.

This instance represents the user's specified timezone.

If $allow_minus is 0 and $epoch is less than 0, $epoch is set to the current epoch time.

The "epoch", "tm", and "is_localtime" fields are set to appropriate values.

localtime_tp

static method localtime_tp : Time::Piece ($tp : Time::Piece);

Creates a new Time::Piece object by interpreting $tp as the user's specified timezone, and returns it.

This instance represents the user's specified timezone,

The "epoch", "tm", and "is_localtime" fields are set to appropriate values.

gmtime

static method gmtime : Time::Piece ($epoch : long = -1, $allow_minus : int = 0);

Creates a new Time::Piece object given the epoch time, and returns it.

This instance represents UTC timezone,

If $allow_minus is 0 and $epoch is less than 0, $epoch is set to the current epoch time.

The "epoch", "tm", and "is_localtime" fields are set to appropriate values.

gmtime_tp

static method gmtime_tp : Time::Piece ($tp : Time::Piece);

Creates a new Time::Piece object by interpreting $tp as UTC timezone, and returns it.

This instance represents UTC timezone,

The "epoch", "tm", and "is_localtime" fields are set to appropriate values.

strptime

static method strptime : Time::Piece ($string : string, $format : string);

Parses the string $string according to the format $format.

This method calls std::get_time in C++.

See the std::get_time function about input field descriptors such as %Y, %m, %d, %H, %M, %S.

Exceptions:

$string must be defined. Otherwise an exception is thrown.

$format must be defined. Otherwise an exception is thrown.

If std::get_time failed, an exception is thrown.

Instance Methods

sec

method sec : int ();

Returns the second. This is the value of tm_sec in the Sys::Time::Tm class.

second

method second : int ();

The same as the "sec" method.

min

method min : int ();

Returns the minute. This is the value of tm_min in the Sys::Time::Tm class.

minute

method minute : int ();

The same as the "min" method.

hour

method hour : int ();

Returns the hour. This is the value of tm_hour in the Sys::Time::Tm class.

mday

method mday : int ();

Returns the day of the month. This is the value of tm_mday in the Sys::Time::Tm class.

day_of_month

method day_of_month : int ();

mon

method mon : int ();

Returns the month. This is the value of tm_mon plus 1 in the Sys::Time::Tm class.

_mon

method _mon : int ();

Returns the value of tm_mon in the Sys::Time::Tm class.

monname

method monname : string ($mon_list : string[] = undef);

Returns the month name given $mon_list.

The default $mon_list:

  ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]

month

method month : string ($mon_list : string[] = undef);

The same as the "monname" method.

fullmonth

method fullmonth : string ($mon_list : string[] = undef);

Returns the full month name given $mon_list.

The default $mon_list:

  ["January", "February", "March", "April", "May", "June", "July", 
                      "August", "September", "October", "November", "December"]
=head2 year

method year : int ();

Returns the year. This is the value of tm_mday plus 1900 in the Sys::Time::Tm class.

_year

method _year : int ();

Returns the value of tm_year in the Sys::Time::Tm class.

yy

method yy : int ();

Returns the the last two digits of "year".

wday

method wday : int ();

Returns the week number, interpreting Sunday as 1. This is the value of tm_wday plus 1 in the Sys::Time::Tm class.

_wday

method _wday : int ();

The same as the "day_of_week" method.

day_of_week

method day_of_week : int ();

Returns the week number, interpreting Sunday as 0. This is the value of tm_wday in the Sys::Time::Tm class.

wdayname

method wdayname : string ($day_list : string[] = undef);

Returns the name of the day of the week given $day_list.

The default $day_list:

  ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]

day

method day : string ($day_list : string[] = undef);

The same as the "wdayname" method.

fullday

method fullday : string ($day_list : string[] = undef);

Returns the full name of the day of the week given $day_list.

The default $day_list:

  ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]

yday

method yday : int ();

Returns the day in the year. This is the value of tm_yday in the Sys::Time::Tm class.

day_of_year

method day_of_year : int ();

The same as the "yday" method.

isdst

method isdst : int ();

Returns the flag thats indicate daylight saving time. This is the value of tm_isdst in the Sys::Time::Tm class.

daylight_savings

method daylight_savings : int ();

The same as the "isdst" method.

hms

method hms : string ($sep : string = undef);

Formats the hour, the minute, and the second into a two-digit string respectively, and concatenates them with the given separator $sep, and returns it.

If $sep is not defined, $sep is set to :.

time

method time : string ($sep : string = undef);

The same as the "hms" method.

ymd

method ymd : string ($sep : string = undef);

Formats the year, the month, and the day of the month into a four-digit string, a two-digit string, a two-digit string respectively, and concatenates them with the given separator $sep, and returns it.

If $sep is not defined, $sep is set to -.

date

method date : string ($sep : string = undef);

The same as the "ymd" method.

mdy

method mdy : string ($sep : string = undef);

Formats the month, the day of the month, and the year into a two-digit string, a two-digit string, a four-digit string respectively, and concatenates them with the given separator $sep, and returns it.

If $sep is not defined, $sep is set to -.

dmy

method dmy : string ($sep : string = undef);

Formats the day of the month, the month, and the year into a two-digit string, a two-digit string, a four-digit string respectively, and concatenates them with the given separator $sep, and returns it.

If $sep is not defined, $sep is set to -.

datetime

method datetime : string ();

Formats the time information into ISO 8601 format like 2000-02-29T12:34:56, and returns it.

tzoffset

method tzoffset : Time::Seconds ();

Calculates the timezone offset, and returns it.

julian_day

method julian_day : double ();

Calculates the number of days since Julian period began, and returns it.

mjd

method mjd : double ();

Calculates the modified Julian date (JD minus 2400000.5 days).

week

method week : int ();

Calculate the week number (ISO 8601), and returns it.

is_leap_year

method is_leap_year : int ();

If the year is a leap year, returns 1, otherwise returns 0.

month_last_day

method month_last_day : int ();

Returns the last day of the month.

cdate

method cdate : string ();

Formats the time information into the string like Tue Feb 29 12:34:56 2000.

strftime

method method strftime : string ($format : string = undef);

Formats the time information into a string according to the format $format, and returns it.

See the strftime function about conversion specifications such as %Y, %m, %d, %H, %M, %S.

If $format is not defined, it is set to %a, %d %b %Y %H:%M:%S %Z.

Exceptions:

The length of $format must be greater than 1. Otherwise an exception is thrown.

If too many memory is allocated, an exception is thrown.

add

method add : Time::Piece ($tsec : Time::Seconds);

Creates a new Time::Piece object with the given seconds $tsec added, and returns it.

subtract

method subtract : Time::Piece ($tsec : Time::Seconds);

Creates a new Time::Piece object with the given seconds $tsec subtracted, and returns it.

subtract_tp

method subtract_tp : Time::Seconds ($tp : Time::Piece);

Creates a new Time::Seconds object given the seconds that is "seconds" fields to the "epoch" field of this instance munus the "epoch" field of $tp.

compare

method compare : int ($tp : Time::Piece);

If the "epoch" field of this instance is greater than the "epoch" field of $tp, returns 1.

If the "epoch" field of this instance is less than the "epoch" field of $tp, returns -1.

If the "epoch" field of this instance is equal to the "epoch" field of $tp, returns 0.

add_months

method add_months : Time::Piece ($num_months : int);

Returns a new Time::Piece object with the month added by $num_months.

add_years

method add_years : Time::Piece ($years : int);

Returns a new Time::Piece object with the year added by $years.

truncate

method truncate : Time::Piece ($options : object[]);

Calling the truncate method returns a copy of the object but with the time truncated to the start of the supplied unit to.

Options:

to : string

"year", "quarter", "month", "day", "hour", "minute", and "second".

Excamples:

  $tp = $tp->truncate({to => "day"});

clone

method clone : Time::Piece ();

Clones this instance, and returns it.

Repository

SPVM::Time::Piece - Github

Author

Yuki Kimoto method kimoto.yuki@gmail.com

Copyright & License

Copyright (c) 2023 Yuki Kimoto

MIT License