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.