Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/grinnz/time-ffi

Time::FFI - libffi interface to POSIX date and time functions
https://github.com/grinnz/time-ffi

Last synced: 5 days ago
JSON representation

Time::FFI - libffi interface to POSIX date and time functions

Awesome Lists containing this project

README 

        
=pod



=head1 NAME



Time::FFI - libffi interface to POSIX date and time functions



=head1 SYNOPSIS



  use Time::FFI qw(localtime mktime strptime strftime);



  my $tm = strptime '1995-01-02 13:15:39', '%Y-%m-%d %H:%M:%S';

  my $epoch = mktime $tm;

  print "$epoch: ", strftime('%I:%M:%S %p on %B %e, %Y', $tm);



  my $tm = localtime time;

  my $datetime = $tm->to_object_as_local('DateTime');



  my $tm = gmtime time;

  my $moment = $tm->to_object_as_utc('Time::Moment');



  use Time::FFI::tm;

  my $tm = Time::FFI::tm->from_object(DateTime->now);

  my $epoch = $tm->epoch_as_local;

  my $piece = $tm->to_object_as_local('Time::Piece');



=head1 DESCRIPTION



B provides a L interface to POSIX date and

time functions found in F.



The L and L functions behave very differently from the

core functions of the same name, as well as those exported by L,

so you may wish to call them as e.g. C rather than importing

them.



All functions will throw an exception in the event of an error. For functions

other than L and L, this exception will contain the

syscall error message, and L will also have been set by the

syscall, so you could check it after trapping the exception for finer exception

handling.



=head1 FUNCTIONS



All functions are exported individually, or with the C<:all> export tag.



=head2 asctime



  my $str = asctime $tm;



Returns a string in the format C representing the

passed L record. The thread-safe L function is

used if available.



=head2 ctime



  my $str = ctime $epoch;

  my $str = ctime;



Returns a string in the format C representing the

passed epoch timestamp (defaulting to the current time) in the local time zone.

This is equivalent to L but uses the thread-safe L

function if available.



=head2 gmtime



  my $tm = gmtime $epoch;

  my $tm = gmtime;



Returns a L record representing the passed epoch timestamp

(defaulting to the current time) in UTC. The thread-safe L

function is used if available.



=head2 localtime



  my $tm = localtime $epoch;

  my $tm = localtime;



Returns a L record representing the passed epoch timestamp

(defaulting to the current time) in the local time zone. The thread-safe

L function is used if available.



=head2 mktime



  my $epoch = mktime $tm;



Returns the epoch timestamp representing the passed L record

interpreted in the local time zone. The time is interpreted from the C,

C, C, C, C, C, and C members of the record,

ignoring the rest. DST status will be automatically determined if C is a

negative value. The record will also be updated to normalize any out-of-range

values and populate the C, C, and C values, as well as

C and C if supported.



=head2 strftime



  my $str = strftime $format, $tm;



Returns a string formatted according to the passed format string, representing

the passed L record. Consult your system's L manual

for available format descriptors.



=head2 strptime



  my $tm = strptime $str, $format;

     $tm = strptime $str, $format, $tm;

  my $tm = strptime $str, $format, undef, \my $remaining;

     $tm = strptime $str, $format, $tm, \my $remaining;



Returns a L record representing the passed string, parsed

according to the passed format. Consult your system's L manual for

available format descriptors. The C value will be set to -1; all other

unspecified values will default to 0. Note that the default C value of 0

is outside of the standard range [1,31] and may cause an error or be

interpreted as the last day of the previous month.



A L record may be passed as the third argument, in which case it

will be modified in place to (on most systems) update only the date/time

elements which were parsed from the string. Additionally, an optional scalar

reference may be passed as the fourth argument, in which case it will be set to

the remaining unprocessed characters of the input string if any.



This function is usually not available on Windows.



=head2 timegm



  my $epoch = timegm $tm;



I



Like L, but interprets the passed L record as UTC. This

function is not always available.



=head2 timelocal



  my $epoch = timelocal $tm;



I



The same as L, but not always available.



=head1 BUGS



Report any issues on the public bugtracker.



=head1 AUTHOR



Dan Book 



=head1 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)



=head1 SEE ALSO



L, L, L, L, L



=cut