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-Local-More-0.002
River stage one • 2 direct dependents • 2 total dependents
++
/ Time::Local::More

NAME

Time::Local::More - More functions for producing Unix epoch timestamp or localtime/gmtime tuple

VERSION

This document describes version 0.002 of Time::Local::More (from Perl distribution Time-Local-More), released on 2021-06-17.

SYNOPSIS

 use Time::Local::More qw(
                       time_startofminute_local
                       time_startofminute_utc
                       localtime_startofminute
                       gmtime_startofminute

                       time_startofhour_local
                       time_startofhour_utc
                       localtime_startofhour
                       gmtime_startofhour

                       time_startofday_local
                       time_startofday_utc
                       localtime_startofday
                       gmtime_startofday

                       time_startofsaturday_local
                       time_startofsaturday_utc
                       localtime_startofsaturday
                       gmtime_startofsaturday

                       time_startofsunday_local
                       time_startofsunday_utc
                       localtime_startofsunday
                       gmtime_startofsunday

                       time_startofmonday_local
                       time_startofmonday_utc
                       localtime_startofmonday
                       gmtime_startofmonday

                       time_startofmonth_local
                       time_startofmonth_utc
                       localtime_startofmonth
                       gmtime_startofmonth

                       time_startoflastdayofmonth_local
                       time_startoflastdayofmonth_utc
                       localtime_startlastdayofofmonth
                       gmtime_startlastdayofofmonth

                       time_startoflastdayoflastmonth_local
                       time_startoflastdayoflastmonth_utc
                       localtime_startoflastdayoflastmonth
                       gmtime_startoflastdayoflastmonth

                       time_startofyear_local
                       time_startofyear_utc
                       localtime_startofyear
                       gmtime_startofyear
                    );
 # you can import all using :all tag

 my $epoch1 = 1623894635; # Thu Jun 17 08:50:35 2021 Asia/Jakarta
                          # Thu Jun 17 01:50:35 2021 UTC

 # assuming we are in Asia/Jakarta
 say time_startofday_local($epoch1); # => 1623862800
                                     # = Thu Jun 17 00:00:00 2021 Asia/Jakarta
 say time_startofday_utc($epoch1);   # => 1623888000
                                     # = Thu Jun 17 00:00:00 2021 UTC

DESCRIPTION

EARLY RELEASE: API MIGHT CHANGE.

Overview of the module:

  • The *startof* functions

    These functions basically "round" the time to the start of minute, hour, day, or so on. For example, "time_startofday_local" is basically equivalent to:

     my @t = localtime(); # e.g. 1623894635 (Thu Jun 17 08:50:35 2021 Asia/Jakarta)
 $t[0] = 0; # zero the second
 $t[1] = 0; # zero the minute
 $t[2] = 0; # zero the hour
 Time::Local::timelocal_nocheck(@t); # convert back to epoch. result is 1623862800 (Thu Jun 17 00:00:00 2021 Asia/Jakarta)

    or alternatively:

     my $t = time();
 my @t = localtime($t);
 $t - $t[0] - $t[1]*60 - $t[2]*3600;

Keywords: start of period, time rounding, truncating timestamp.

FUNCTIONS

time_startofminute_local

Usage:

 my $time = time_startofminute_local( [ $time0 ] );

Return Unix epoch timestamp for start of minute at local timezone. If $time0 is not specified, will default to current timestamp (time()).

time_startofminute_utc

Usage:

 my $time = time_startofminute_utc( [ $time0 ] );

Return Unix epoch timestamp for start of minute at UTC. If $time0 is not specified, will default to current timestamp (time()).

localtime_startofminute

Usage:

 localtime_startofminute( [ $time0 ] ); # like output of localtime()

Return localtime() output for start of minute. If $time0 is not specified, will default to current timestamp (time()).

gmtime_startofminute

Usage:

 gmtime_startofminute( [ $time0 ] ); # like output of gmtime()

Return gmtime() output for start of minute. If $time0 is not specified, will default to current timestamp (time()).

time_startofhour_local

Usage:

 my $time = time_startofhour_local( [ $time0 ] );

Return Unix epoch timestamp for start of hour at local timezone. If $time0 is not specified, will default to current timestamp (time()).

time_startofhour_utc

Usage:

 my $time = time_startofhour_utc( [ $time0 ] );

Return Unix epoch timestamp for start of hour at UTC. If $time0 is not specified, will default to current timestamp (time()).

localtime_startofhour

Usage:

 localtime_startofhour( [ $time0 ] ); # like output of localtime()

Return localtime() output for start of hour. If $time0 is not specified, will default to current timestamp (time()).

gmtime_startofhour

Usage:

 gmtime_startofhour( [ $time0 ] ); # like output of gmtime()

Return gmtime() output for start of hour. If $time0 is not specified, will default to current timestamp (time()).

time_startofday_local

Usage:

 my $time = time_startofday_local( [ $time0 ] );

Return Unix epoch timestamp for start of day at local timezone. If $time0 is not specified, will default to current timestamp (time()).

time_startofday_utc

Usage:

 my $time = time_startofday_utc( [ $time0 ] );

Return Unix epoch timestamp for start of day at UTC. If $time0 is not specified, will default to current timestamp (time()).

localtime_startofday

Usage:

 localtime_startofday( [ $time0 ] ); # like output of localtime()

Return localtime() output for start of day. If $time0 is not specified, will default to current timestamp (time()).

gmtime_startofday

Usage:

 gmtime_startofday( [ $time0 ] ); # like output of gmtime()

Return gmtime() output for start of day. If $time0 is not specified, will default to current timestamp (time()).

time_startofsaturday_local

Usage:

 my $time = time_startofsaturday_local( [ $time0 ] );

Return Unix epoch timestamp for start of most recent past Saturday at local timezone. If $time0 is not specified, will default to current timestamp (time()).

time_startofsaturday_utc

Usage:

 my $time = time_startofsaturday_utc( [ $time0 ] );

Return Unix epoch timestamp for start of most recent past Saturday at UTC. If $time0 is not specified, will default to current timestamp (time()).

localtime_startofsaturday

Usage:

 localtime_startofsaturday( [ $time0 ] ); # like output of localtime()

Return localtime() output for start of most recent past Saturday. If $time0 is not specified, will default to current timestamp (time()).

gmtime_startofsaturday

Usage:

 gmtime_startofsaturday( [ $time0 ] ); # like output of gmtime()

Return gmtime() output for start of most recent past Saturday. If $time0 is not specified, will default to current timestamp (time()).

time_startofsunday_local

Usage:

 my $time = time_startofsunday_local( [ $time0 ] );

Return Unix epoch timestamp for start of most recent past Sunday at local timezone. If $time0 is not specified, will default to current timestamp (time()).

time_startofsunday_utc

Usage:

 my $time = time_startofsunday_utc( [ $time0 ] );

Return Unix epoch timestamp for start of most recent past Sunday at UTC. If $time0 is not specified, will default to current timestamp (time()).

localtime_startofsunday

Usage:

 localtime_startofsunday( [ $time0 ] ); # like output of localtime()

Return localtime() output for start of sunday. If $time0 is not specified, will default to current timestamp (time()).

gmtime_startofsunday

Usage:

 gmtime_startofsunday( [ $time0 ] ); # like output of gmtime()

Return gmtime() output for start of most recent past Sunday. If $time0 is not specified, will default to current timestamp (time()).

time_startofmonday_local

Usage:

 my $time = time_startofmonday_local( [ $time0 ] );

Return Unix epoch timestamp for start of most recent past Monday at local timezone. If $time0 is not specified, will default to current timestamp (time()).

time_startofmonday_utc

Usage:

 my $time = time_startofmonday_utc( [ $time0 ] );

Return Unix epoch timestamp for start of most recent past Monday at UTC. If $time0 is not specified, will default to current timestamp (time()).

localtime_startofmonday

Usage:

 localtime_startofmonday( [ $time0 ] ); # like output of localtime()

Return localtime() output for start of most recent past Monday. If $time0 is not specified, will default to current timestamp (time()).

gmtime_startofmonday

Usage:

 gmtime_startofmonday( [ $time0 ] ); # like output of gmtime()

Return gmtime() output for start of most recent past Monday. If $time0 is not specified, will default to current timestamp (time()).

time_startofmonth_local

Usage:

 my $time = time_startofmonth_local( [ $time0 ] );

Return Unix epoch timestamp for start of month at local timezone. If $time0 is not specified, will default to current timestamp (time()).

time_startofmonth_utc

Usage:

 my $time = time_startofmonth_utc( [ $time0 ] );

Return Unix epoch timestamp for start of month at UTC. If $time0 is not specified, will default to current timestamp (time()).

localtime_startofmonth

Usage:

 localtime_startofmonth( [ $time0 ] ); # like output of localtime()

Return localtime() output for start of month. If $time0 is not specified, will default to current timestamp (time()).

gmtime_startofmonth

Usage:

 gmtime_startofmonth( [ $time0 ] ); # like output of gmtime()

Return gmtime() output for start of month. If $time0 is not specified, will default to current timestamp (time()).

time_startoflastdayofmonth_local

Usage:

 my $time = time_startoflastdayofmonth_local( [ $time0 ] );

Return Unix epoch timestamp for start of last day of month at local timezone. If $time0 is not specified, will default to current timestamp (time()).

time_startoflastdayofmonth_utc

Usage:

 my $time = time_startoflastdayofmonth_utc( [ $time0 ] );

Return Unix epoch timestamp for start of last day of month at UTC. If $time0 is not specified, will default to current timestamp (time()).

localtime_startoflastdayofmonth

Usage:

 localtime_startoflastdayofmonth( [ $time0 ] ); # like output of localtime()

Return localtime() output for start of last day of month. If $time0 is not specified, will default to current timestamp (time()).

gmtime_startoflastdayofmonth

Usage:

 gmtime_startoflastdayofmonth( [ $time0 ] ); # like output of gmtime()

Return gmtime() output for start of last day of month. If $time0 is not specified, will default to current timestamp (time()).

time_startoflastdayoflastmonth_local

Usage:

 my $time = time_startoflastdayoflastmonth_local( [ $time0 ] );

Return Unix epoch timestamp for start of last day of last month at local timezone. If $time0 is not specified, will default to current timestamp (time()).

time_startoflastdayoflastmonth_utc

Usage:

 my $time = time_startoflastdayoflastmonth_utc( [ $time0 ] );

Return Unix epoch timestamp for start of last day of last month at UTC. If $time0 is not specified, will default to current timestamp (time()).

localtime_startoflastdayoflastmonth

Usage:

 localtime_startoflastdayoflastmonth( [ $time0 ] ); # like output of localtime()

Return localtime() output for start of last day of last month. If $time0 is not specified, will default to current timestamp (time()).

gmtime_startoflastdayoflastmonth

Usage:

 gmtime_startoflastdayoflastmonth( [ $time0 ] ); # like output of gmtime()

Return gmtime() output for start of last day of last month. If $time0 is not specified, will default to current timestamp (time()).

time_startofyear_local

Usage:

 my $time = time_startofyear_local( [ $time0 ] );

Return Unix epoch timestamp for start of year at local timezone. If $time0 is not specified, will default to current timestamp (time()).

time_startofyear_utc

Usage:

 my $time = time_startofyear_utc( [ $time0 ] );

Return Unix epoch timestamp for start of year at UTC. If $time0 is not specified, will default to current timestamp (time()).

localtime_startofyear

Usage:

 localtime_startofyear( [ $time0 ] ); # like output of localtime()

Return localtime() output for start of year. If $time0 is not specified, will default to current timestamp (time()).

gmtime_startofyear

Usage:

 gmtime_startofyear( [ $time0 ] ); # like output of gmtime()

Return gmtime() output for start of year. If $time0 is not specified, will default to current timestamp (time()).

FAQ

Where are "startofweek" functions?

Use the "startofsunday" or "startofmonday" functions; since some people use Sunday as start of the week and some people use Monday.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Time-Local-More.

SOURCE

Source repository is at https://github.com/perlancar/perl-Time-Local-More.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Time-Local-More

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

SEE ALSO

Time::Local

localtime() and gmtime() in perlfunc.

You can also use DateTime to calculate these "start of period" epochs. For example, to get start of month epoch: DateTime->now->set(day => 1)->epoch. Note that DateTime has a significantly larger footprint than Time::Local.

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2021 by perlancar@cpan.org.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.