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

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)

SEE ALSO

Time::FFI, Time::tm