NAME
Time::FFI::tm - POSIX tm record structure
SYNOPSIS
use Time::FFI::tm;
my $tm = Time::FFI::tm->new(
tm_year => 95, # years since 1900
tm_mon => 0, # 0 == January
tm_mday => 1,
tm_hour => 13,
tm_min => 25,
tm_sec => 59,
tm_isdst => -1, # allow DST status to be determined by the system
);
$tm->tm_mday($tm->tm_mday + 1); # add a day
my $in_local = $tm->normalized(1);
say $in_local->tm_isdst; # now knows if DST is active
my $tm = Time::FFI::tm->from_list(CORE::localtime(time));
my $epoch = POSIX::mktime($tm->to_list);
my $epoch = $tm->epoch(1);
my $tm = Time::FFI::tm->from_object(Time::Moment->now, 1);
my $datetime = $tm->to_object('DateTime', 1);DESCRIPTION
This FFI::Platypus::Record class represents the tm struct defined by time.h and used by functions such as mktime(3) and strptime(3). This is used by Time::FFI to provide access to such structures.
The structure does not store an explicit time zone, so you must specify whether to interpret it as local or UTC time whenever rendering it to or from an actual date/time.
ATTRIBUTES
The integer components of the tm struct are stored as settable attributes that default to 0. Note that 0 is out of the standard range for the tm_mday value (often indicating the last day of the previous month), and tm_isdst should be set to a negative value if unknown, so these values should always be specified explicitly.
tm_sec
Seconds [0,60].
tm_min
Minutes [0,59].
tm_hour
Hour [0,23].
tm_mday
Day of month [1,31].
tm_mon
Month of year [0,11].
tm_year
Years since 1900.
tm_wday
Day of week [0,6] (Sunday =0).
tm_yday
Day of year [0,365].
tm_isdst
Daylight Savings flag. (0: off, positive: on, negative: unknown)
tm_gmtoff
Seconds east of UTC. (May not be available on all systems)
tm_zone
Timezone abbreviation. (Read only string, may not be available on all systems)
METHODS
new
my $tm = Time::FFI::tm->new;
my $tm = Time::FFI::tm->new(tm_year => $year, ...);
my $tm = Time::FFI::tm->new({tm_year => $year, ...});Construct a new Time::FFI::tm object representing a tm struct.
from_list
my $tm = Time::FFI::tm->from_list($sec, $min, $hour, $mday, $mon, $year, $wday, $yday, $isdst);Construct a new Time::FFI::tm object from the passed list of values, in the same order returned by "localtime" in perlfunc. Missing or undefined values will be interpreted as the default of 0, but see "ATTRIBUTES".
from_object
my $tm = Time::FFI::tm->from_object($obj, $islocal);Since version 1.001
Construct a new Time::FFI::tm object from the passed datetime object, which may be any object that implements an epoch method returning the Unix epoch timestamp. If a true value is passed as the second argument, the resulting structure will represent the local time at that instant; otherwise it will represent UTC. The original time zone and any fractional seconds will not be represented in the resulting structure.
to_list
my ($sec, $min, $hour, $mday, $mon, $year, $wday, $yday, $isdst) = $tm->to_list;Return the list of values in the structure, in the same order returned by "localtime" in perlfunc.
to_object
my $piece = $tm->to_object('Time::Piece', $islocal);
my $moment = $tm->to_object('Time::Moment', $islocal);
my $datetime = $tm->to_object('DateTime', $islocal);Return an object of the specified class. If a true value is passed as the second argument, the object will represent the time as interpreted in the local time zone; otherwise it will be interpreted as UTC. Currently Time::Piece, Time::Moment, and DateTime (or subclasses) are recognized.
When interpreted as a local time, values outside the standard ranges are accepted; this is not currently supported for UTC times.
epoch
my $epoch = $tm->epoch($islocal);Since version 1.000
Translate the time structure into a Unix epoch timestamp (seconds since 1970-01-01 UTC). If a true value is passed, the timestamp will represent the time as interpreted in the local time zone; otherwise it will be interpreted as UTC.
When interpreted as a local time, values outside the standard ranges are accepted; this is not currently supported for UTC times.
normalized
my $new = $tm->normalized($islocal);Since version 1.003
Return a new Time::FFI::tm object representing the same time, but with tm_wday, tm_yday, tm_isdst, and (if supported) tm_gmtoff and tm_zone set appropriately. If a true value is passed, these values will be set according to the time as interpreted in the local time zone; otherwise they will be set according to the time as interpreted in UTC. Note that this does not replace the need to pass $islocal for future conversions.
When interpreted as a local time, values outside the standard ranges will also be normalized; this is not currently supported for UTC times.
BUGS
Report any issues on the public bugtracker.
AUTHOR
Dan Book <dbook@cpan.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2019 by Dan Book.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)