NAME
Time::FFI::tm - POSIX tm record structure
SYNOPSIS
use Time::FFI::tm;
my $tm = Time::FFI::tm->new(
year => 95, # years since 1900
mon => 0, # 0 == January
mday => 1,
hour => 13,
min => 25,
sec => 59,
isdst => -1, # allow DST status to be determined by the system
);
$tm->mday($tm->mday + 1); # add a day
my $in_local = $tm->normalized_as_local;
say $in_local->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_as_local;
my $tm = Time::FFI::tm->from_object(Time::Moment->now);
my $datetime = $tm->to_object_as_local('DateTime');
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 an actual datetime.
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 mday
value (often indicating the last day of the previous month), and isdst
should be set to a negative value if unknown, so these values should always be specified explicitly.
Each attribute also has a corresponding alias starting with tm_
to match the standard tm
struct member names.
sec
Seconds [0,60].
min
Minutes [0,59].
hour
Hour [0,23].
mday
Day of month [1,31].
mon
Month of year [0,11].
year
Years since 1900.
wday
Day of week [0,6] (Sunday =0).
yday
Day of year [0,365].
isdst
Daylight Savings flag. (0: off, positive: on, negative: unknown)
gmtoff
Seconds east of UTC. (May not be available on all systems)
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(year => $year, ...);
my $tm = Time::FFI::tm->new({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 time attributes, 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);
Current API since version 2.000.
Construct a new Time::FFI::tm object from the passed datetime object's local datetime components. Currently Time::Piece, Time::Moment, DateTime, Time::tm, and Time::FFI::tm objects (and subclasses) are recognized. 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 time attributes in the structure, in the same order returned by "localtime" in perlfunc.
to_object_as_local
to_object_as_utc
my $piece = $tm->to_object_as_local('Time::Piece');
my $moment = $tm->to_object_as_utc('Time::Moment');
Since version 2.002.
Return an object of the specified class. Currently Time::Piece, Time::Moment, and DateTime (or subclasses) are recognized. Depending on the method called, the time attributes are interpreted in the local time zone or in UTC.
When interpreted as a local time, values outside the standard ranges are accepted; this is not currently supported for UTC times.
You may also specify Time::tm or Time::FFI::tm (or subclasses), in which case to_object_as_local
and to_object_as_utc
produce the same result with the time attributes copied as-is.
epoch_as_local
epoch_as_utc
my $epoch = $tm->epoch_as_local;
my $epoch = $tm->epoch_as_utc
Since version 2.002.
Translate the time structure into a Unix epoch timestamp (seconds since 1970-01-01 UTC). Depending on the method called, the time attributes are interpreted in the local time zone or in UTC.
When interpreted as a local time, values outside the standard ranges are accepted; this is not currently supported for UTC times.
normalized_as_local
normalized_as_utc
my $new = $tm->normalized_as_local;
my $new = $tm->normalized_as_utc;
Since version 2.002.
Return a new Time::FFI::tm object representing the same time, but with wday
, yday
, isdst
, and (if supported) gmtoff
and zone
set appropriately. Depending on the method called, the time attributes are interpreted in the local time zone or in UTC.
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)