/ 
Time-FFI-1.000
River stage zero No dependents
/ Time::FFI::tm

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
);

my $in_local = $tm->with_extra(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 $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 an actual time.

ATTRIBUTES

tm_sec

tm_min

tm_hour

tm_mday

tm_mon

tm_year

tm_wday

tm_yday

tm_isdst

tm_gmtoff

tm_zone

The integer components of the tm struct are stored as settable attributes that default to 0. Note that 0 is out of range for the tm_mday value, and tm_isdst should be set to a negative value if unknown, so these values should always be specified explicitly. The tm_gmtoff and tm_zone attributes may not be available on all systems. The tm_zone attribute is a read-only string.

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.

epoch

my $epoch = $tm->epoch($islocal);

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.

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".

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.

with_extra

my $new = $tm->with_extra($islocal);

Return a new Time::FFI::tm object with the same time components, 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.

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)

SEE ALSO

Time::FFI