The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
DateTimeX-Start-v1.6.0
River stage zero No dependents
++
/ DateTimeX::Start

NAME

DateTimeX::Start - Find the time at which a day starts.

VERSION

Version 1.6.0

SYNOPSIS

    use DateTimeX::Start qw( :ALL );

    my $dt = start_of_date([2013, 10, 20], 'America/Sao_Paulo');
    print("$dt\n");  # 2013-10-20T01:00:00
    $dt->subtract( seconds => 1 );
    print("$dt\n");  # 2013-10-19T23:59:59

    # These three are equivalent.
    my $dt = start_of_today();
    my $dt = start_of_today('local');
    my $dt = start_of_date( DateTime->now( time_zone => 'local' ) );

    # These three are equivalent.
    my $dt = start_of_date([2014, 1, 1]);
    my $dt = start_of_date([2014, 1]);
    my $dt = start_of_date([2014]);

    my $dt = start_of_date(  DateTime->now( time_zone => 'local' ) );
    my $dt = start_of_month( DateTime->now( time_zone => 'local' ) );
    my $dt = start_of_year(  DateTime->now( time_zone => 'local' ) );

DESCRIPTION

In Sao Paulo, in the night of Oct 19th, 2013, the clocks went from 23:59:59 to 01:00:00. That's just one example of the fact that not all days have a midnight hour. This module provides a mean of determining when a particular day (or month or year) starts.

FUNCTIONS

start_of_date / date

    my $dt = start_of_date($date);
    my $dt = start_of_date($date, $tz_or_tz_name);
    my $dt = date($date);
    my $dt = date($date, $tz_or_tz_name);

Returns a DateTime object representing the earliest time of the specified date.

$date must be one of the following:

  • A DateTime object (to find the first time of $date->strftime('%Y-%m-%d')),

  • A reference to an array containing a year, a month and a day ([$y,$m,$d], to find the first time of the specified date),

  • A reference to an array containing a year and month ([$y,$m], to find the first time of the specified month), or

  • A reference to an array containing a year ([$y], to find the first time of the specified year).

$tz_or_tz_name must be either a time zone name supported by DateTime::TimeZone or a DateTime::TimeZone object. It defaults to $dt->time_zone if $date is a DateTime object, and 'local' otherwise.

start_of_month / month

    my $dt = start_of_month($date);
    my $dt = start_of_month($date, $tz_or_tz_name);
    my $dt = month($date);
    my $dt = month($date, $tz_or_tz_name);

Returns a DateTime object representing the earliest time of the specified month.

$date must be one of the following:

  • A DateTime object (to find the first time of the month given by $date->strftime('%Y-%m')),

  • A reference to an array containing a year and month ([$y,$m], to find the first time of the specified month), or

  • A reference to an array containing a year ([$y], to find the first time of the specified year).

$tz_or_tz_name must be either a time zone name supported by DateTime::TimeZone or a DateTime::TimeZone object. It defaults to $dt->time_zone if $date is a DateTime object, and 'local' otherwise.

start_of_year / year

   my $dt = start_of_year($date);
   my $dt = start_of_year($date, $tz_or_tz_name);
   my $dt = year($date);
   my $dt = year($date, $tz_or_tz_name);

Returns a DateTime object representing the earliest time of the specified year.

$date must be one of the following:

  • A DateTime object (to find the first time of the month given by $date->year), or

  • A reference to an array containing a year ([$y], to find the first time of the specified year).

$tz_or_tz_name must be either a time zone name supported by DateTime::TimeZone or a DateTime::TimeZone object. It defaults to $dt->time_zone if $date is a DateTime object, and 'local' otherwise.

start_of_today / today

   my $dt = start_of_today();
   my $dt = start_of_today($tz_or_tz_name);
   my $dt = today();
   my $dt = today($tz_or_tz_name);

Returns a DateTime object representing the earliest time of the current day.

$tz_or_tz_name must be either a time zone name supported by DateTime::TimeZone or a DateTime::TimeZone object. It defaults to 'local'.

EXPORTS

Nothing is exported by default. The following are exported on demand:

  • start_of_date

  • start_of_month

  • start_of_year

  • start_of_today

  • date

  • month

  • year

  • today

  • :ALL

    For all of the above.

  • :long

    For start_of_date, start_of_month, start_of_year and start_of_today.

  • :short

    For date, month, year and today.

NOTES

  • This purpose of the functions of this module is to find the earliest time of the specified date. As such, if a day has two midnights, the earlier of two will be returned.

  • Arguments passed to the functions of this module aren't modified.

ASSUMPTIONS

The code makes the following assumptions about time zones:

  • There is no dt to which one can add time to obtain a dt with an earlier date.

  • In no time zone does a date starts more than 24*60*60 seconds before the same date starts in UTC.

  • In no time zone does a date starts more than 24*60*60 seconds after the same date starts in UTC.

  • There is no year without a January.

  • There is no month without a 1st.

  • Jumps in time zones only occur on times with zero seconds. (Optimization)

BUGS

Please report any bugs or feature requests to bug-DateTimeX-Start at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=DateTimeX-Start. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

DOCUMENTATION AND SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc DateTimeX::Start

You can also find it online at these locations:

If you need help, the following are great resources:

Bugs and improvements can be reported using any of the following systems:

Using CPAN's request tracker by emailing bug-DateTimeX-Start at rt.cpan.org
Using CPAN's request tracker at http://rt.cpan.org/NoAuth/Bugs.html?Dist=DateTimeX-Start
Using GitHub's issue tracker at https://github.com/ikegami/perl-DateTimeX-Start/issues

REPOSITORY

AUTHOR

Eric Brine <ikegami@adaelis.com>

COPYRIGHT AND LICENSE

No rights reserved.

The author has dedicated the work to the Commons by waiving all of his or her rights to the work worldwide under copyright law and all related or neighboring legal rights he or she had in the work, to the extent allowable by law.

Works under CC0 do not require attribution. When citing the work, you should not imply endorsement by the author.