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

  my $tm = Time::FFI::tm->from_object(Time::Moment->now);
  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 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 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);

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

You may also specify Time::tm or Time::FFI::tm (or subclasses), in which case the $islocal parameter is ignored and the values are copied as-is.

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 wday, yday, isdst, and (if supported) gmtoff and 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)

SEE ALSO

Time::FFI, Time::tm