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 . SOURCE Source repository is at . BUGS Please report any bugs or feature requests on the bugtracker website 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 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.