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