/ 
Date-Components-v0.0.2
River stage zero No dependents
/ Date::Components

NAME

Date::Components - Parses, processes and formats ONLY dates and date components (time parameters are ignored).

VERSION

This documentation refers to Date::Components version 0.0.2

SYNOPSIS

use Carp              1.04   qw(croak);
use Date::Components  0.0.2  qw(
                                date_only_parse
                                is_valid_year
                                set_day_to_day_name_abbrev
                                format_date
                               );

# Parse a $date string and extract its components
my $date = 'Mon Sep 17 08:50:51 2007';
my ($month, $day, $year, $dayofweek) = date_only_parse($date);

# Test if $year is valid
( is_valid_year( $year ) ) or croak "   Input year, '$year', is not a valid input.\n";

# Set $dayofweek, whether alpha or numeric, to alpha.
my $alpha_day = set_day_to_day_name_abbrev( $dayofweek );

# Re-formats $date to one of several user choices
my $formatted_date = format_date( $date );

DESCRIPTION

Date::Components parses dates into components on the front end, formats them on the back end and enables many operations on whole dates and date components in between.

This unique module was created to combine a parser, formatter, component operators and time independence into a single unit. Independence of time also enables the widest date range possible (limited by integer size). Applications include portfolio management where only dates are relevant. With the variety of supported date formats, it can be used as an in-line date re-formatter. Subroutines providing operations specific to the standard 400 year cycle are included also.

The module is not object oriented. Rather, it supplies a variety of useful functions to analyze, process and format complete dates and the four date components of month, day-of-month, year and day-of-week. ALL representations of time and related parameters are ignored, including hours, minutes, seconds, time zones, daylight savings time, etc.

Leap year standard is used. According to the Royal Greenwich Observatory, the calendar year is 365 days long, unless the year is exactly divisible by four, then an extra day is added to February so the year is 366 days long. If the year is the last year of a century, e.g., 2000, 2100, 2200, 2300, 2400, then it is only a leap year if it is exactly divisible by 400. So, 2100 won't be a leap year but 2000 is. The next century year, exactly divisible by 400, won't occur until 2400--400 years away.

Two subroutines, is_valid_date and format_date, are overloaded to accept either a list of date components or a single SCALAR date string to enable more flexible usage.

Date strings returned by subroutines are always in default format.

Conventions

To make the code correspond to standard date representations, day of the week
and month numbers both start at 1.

Day numbers are represented as 1-7 corresponding to Mon through Sun.

Month numbers are represented as 1-12 corresponding to Jan through Dec.

Subroutine List

Frontend / Backend
date_only_parse
format_date
Validity Check
is_valid_date
is_valid_month
is_valid_day_of_month
is_valid_day_of_week
is_valid_year
is_valid_400_year_cycle
Component Formatting
set_day_to_day_name_abbrev
set_day_to_day_name_full
set_day_to_day_number
set_month_to_month_name_abbrev
set_month_to_month_name_full
set_month_to_month_number
day_name_to_day_number
day_number_to_day_name
month_name_to_month_number
month_number_to_month_name
Date Operations
compare_date1_and_date2
date1_to_date2_delta
date_offset_in_days
compare_year1_and_year2
year1_to_year2_delta
date_offset_in_years
number_of_weekdays_in_range
Inquiries
is_leap_year
get_year_phase
number_of_day_within_year
day_number_within_year_to_date
day_number_within_400_year_cycle_to_date
get_number_of_day_within_400yr_cycle
get_days_remaining_in_400yr_cycle
get_num_days_in_year
get_days_remaining_in_year
get_numeric_day_of_week
get_number_of_days_in_month
get_days_remaining_in_month
get_first_of_month_day_of_week
calculate_day_of_week_for_first_of_month_in_next_year
get_global_year_cycle

Parsing and Formatting

Refer to the documentation of the date_only_parse and format_date routines for specifics. If other formats are desired, please contact the author. Note that ALL years, even negative, are accepted.

EXPORT

None by default.

SUBROUTINES

date_only_parse
Usage:
my ($month, $dayofmonth, $year, $dayofweek = date_only_parse( <date string> );
Purpose:
Converts variety of date strings into components for processing
Returns:
- if parse is unsuccessful it returns a list:
        (
          month_integer<1-12>,
          day_of_month_integer<1-N>,
          year_integer,
          numeric_day_of_week<1 for Mon ... 7 for Sun>
        )
- '' if parameter is a valid string from which a VALID date is NOT recognized
Parameters:
Text string containing date in various formats
Throws:
Throws exception for any invalid input
Comments:
Handles all years, even negative years (aka BC)
Formats Parsed (case insensitive)
  - 'month_num/day_num/year'
      Single digits for month and day are allowed for parsing.
  - 'Mon Sep 17 08:50:51 2007'
  - 'September 17, 2007'
  - '17 September, 2007'
  - 'YYYY-MM-DD' (ex: 2007-09-01 <Sep 1, 2007>)
Examples:
date_only_parse('2/29/2005');                 # Returns  ''
date_only_parse('Mon Feb 27 08:50:51 2005');  # Returns  ''
date_only_parse('13/9/1619');                 # Returns  ''
date_only_parse('2/29/2004');                 # Returns  (  2, 29,  2004, 7 )
date_only_parse('Mon Jul 31 08:50:51 1865');  # Returns  (  7, 31,  1865, 1 )
date_only_parse('2/29/2000');                 # Returns  (  2, 29,  2000, 2 )
date_only_parse('1876-12-18');                # Returns  ( 12, 18,  1876, 1 )
date_only_parse('-407-06-03');                # Returns  (  6,  3,  -407, 4 )
date_only_parse('July 9, 2089');              # Returns  (  7,  9,  2089, 6 )
date_only_parse('23 March, 30004');           # Returns  (  3, 23, 30004, 2 )
format_date
Usage:
Function is overloaded to accept EITHER a date string OR a date component.
  1) Date string, <OPTIONAL date format>
     my $date = format_date( SCALAR, <SCALAR> );
  2) Month, dayofmonth, year, <OPTIONAL date format>
     my $date = format_date( SCALAR, SCALAR, SCALAR, <SCALAR> );
Purpose:
Formats dates
Returns:
Date string
Parameter(s):
- ( date_string in any format, <optional date format> )
                 OR
- ( month, day of month, year, <optional date format> )
Throws:
Throws exception for any invalid input
Comments:
- Handles all years, even negative years (aka BC)
- It does NOT output time, time zone or any other time parameter
  other than a CONSTANT 12noon time when a time component is
  included in the format.
- Format options
   <Default> ->  'mm/dd/yyyy'
   'A'       ->  'Mon Sep 17 12:00:00 2007' (time component is ALWAYS 12 noon)
   'B'       ->  'September 17, 2007'
   'C'       ->  '17 September, 2007'
   'D'       ->  'YYYY-MM-DD'
Examples:
format_date(7, 4, 1599,  'A');           # Returns  'Sun Jul  4 12:00:00 1599'
format_date('Mon Sep 17 08:50:51 2007'); # Returns  '09/17/2007'
format_date('12/31/-401');               # Returns  '12/31/-401'
format_date('1/4/2001');                 # Returns  '01/04/2001'
format_date( 2, 29, 1604,  'B');         # Returns  'February 29, 1604'
format_date( 2, 29, 1604,  'C');         # Returns  '29 February, 1604'
format_date( 3,  7, 1604,  'D');         # Returns  '1604-03-07'
format_date('15 January,  -87', 'D');    # Returns  '-87-01-15'
is_valid_date
Usage:
Function is overloaded to accept one of three date input types
1) Date string
    my $status = is_valid_date( SCALAR );
2) Month, dayofmonth, year
    my $status = is_valid_date( SCALAR, SCALAR, SCALAR );
3) Month, dayofmonth, year, dayofweek
    my $status = is_valid_date( SCALAR, SCALAR, SCALAR, SCALAR );
Purpose:
Checks if date is valid
Returns:
- '1' if date is valid
- ''  otherwise
Parameter(s):
- ( date_string in any format )
          OR
- ( month, day of month, year )
          OR
- ( month, day of month, year, dayofweek )
Throws:
No exceptions
Comments:
- Handles all years, even negative years (aka BC)
- Month can be any of numeric, three character abbreviation or full
- Day of week can be any of numeric, three character abbreviation or full
- <1 for Jan ... 12 for Dec>
- <1 for Mon ... 7 for Sun>
Examples:
is_valid_date   (2, 29, 2005, 7);              # Returns ''
is_valid_date   ('Jan,  15, 2005, Sat');       # Returns ''
is_valid_date   ('0/14/1988');                 # Returns ''
is_valid_date   (6,'0', 47);                   # Returns ''
is_valid_date   (2, 0, 2005, 7);               # Returns ''
is_valid_date   ('Jan', 15, 2005, 'Sat');      # Returns  1
is_valid_date   (8, 15, 1964);                 # Returns  1
is_valid_date   (3, 5, 2000, 'Sun');           # Returns  1
is_valid_date   (6, 3, 47);                    # Returns  1
is_valid_date   ('5/14/1988');                 # Returns  1
is_valid_date   ('Sun Feb 29 12:00:00 1604');  # Returns  1
is_valid_month
Usage:
my $status = is_valid_month( $month );
Purpose:
Checks if month is valid
Returns:
- '1' if month is valid
- ''  otherwise
Parameter(s):
Month in one of three formats ( numeric <1-12>, full name or three character abbreviated )
Throws:
No exceptions
Comments:
<1 for Jan ... 12 for Dec>
Examples:
is_valid_month(' 11 ');        # Returns  ''
is_valid_month('Feb', 'Mar');  # Returns  ''
is_valid_month(4);             # Returns   1
is_valid_month('July');        # Returns   1
is_valid_month('JAN');         # Returns   1
is_valid_day_of_month
Usage:
my $status = is_valid_day_of_month( $month, $dayofmonth, $year );
Purpose:
Checks if day of month is valid
Returns:
- '1' if day of month is valid
- ''  otherwise
Parameter(s):
- Month in one of three formats ( numeric <1-12>, full name or three character abbreviated )
- Day of month (1-31)
- Year
Throws:
No exceptions
Comments:
Handles all years, even negative years (aka BC)
Examples:
is_valid_day_of_month( 2,       30,   1555);  # Returns  ''
is_valid_day_of_month( 8,      '0',   1555);  # Returns  ''
is_valid_day_of_month( 2,       29,   1559);  # Returns  ''
is_valid_day_of_month( 2,       28,   1559);  # Returns   1
is_valid_day_of_month('May',    31,     -3);  # Returns   1
is_valid_day_of_month('Jul',    31,  50032);  # Returns   1
is_valid_day_of_month('August', 31,   1888);  # Returns   1
is_valid_day_of_week
Usage:
my $status = is_valid_day_of_week( $dayofweek );
Purpose:
Checks if day of week is valid
Returns:
- '1' if day of week is valid
- ''  otherwise
Parameter(s):
Day of week
Throws:
No exceptions
Comments:
<1 for Mon ... 7 for Sun>
Examples:
is_valid_day_of_week('0');       # Returns  ''
is_valid_day_of_week(' 7');      # Returns  ''
is_valid_day_of_week('Sat ');    # Returns  ''
is_valid_day_of_week(7);         # Returns   1
is_valid_day_of_week('Mon');     # Returns   1
is_valid_day_of_week('Friday');  # Returns   1
is_valid_day_of_week('TUE');     # Returns   1
is_valid_year
Usage:
my $status = is_valid_year( $year );
Purpose:
Checks if year is valid
Returns:
- '1' if year is valid
- ''  otherwise
Parameter(s):
Year
Throws:
No exceptions
Comments:
Handles all years, even negative years (aka BC)
Examples:
is_valid_year('-1600 BC');      # Returns  ''
is_valid_year(' 1962 ');        # Returns  ''
is_valid_year(' 2005');         # Returns  ''
is_valid_year('2007', '2008');  # Returns  ''
is_valid_year('-33');           # Returns   1
is_valid_year(1999);            # Returns   1
is_valid_year('2642');          # Returns   1
is_valid_400_year_cycle
Usage:
my $status = is_valid_400_year_cycle( $year_400_cycle );
Purpose:
Checks if year is valid 400 year cycle phase
Returns:
- '1' if year is valid 400 year cycle phase number
- ''  otherwise
Parameter(s):
400 year cycle
Throws:
No exceptions
Comments:
valid inputs (years) are multiples of 400
 (i.e.  ... -400, 0, 400, ... 1600, 2000, 2400, ...)
Examples:
is_valid_400_year_cycle( -900);  # Returns  ''
is_valid_400_year_cycle( 1924);  # Returns  ''
is_valid_400_year_cycle(-1200);  # Returns   1
is_valid_400_year_cycle(    0);  # Returns   1
is_valid_400_year_cycle(64000);  # Returns   1
set_day_to_day_name_abbrev
Usage:
my $dayofweek_alpha = set_day_to_day_name_abbrev( $dayofweek );
Purpose:
Set the incoming day of week to three letter abbreviation
Returns:
Day of week as three character abbreviation
Parameter(s):
Day of week in one of three formats ( numeric <1-7>, full name or three character abbreviated )
Throws:
Throws exception for any invalid input
Comments:
1 for Mon, ..., 7 for Sun
Examples:
set_day_to_day_name_abbrev('Wednesday'); # Returns 'Wed'
set_day_to_day_name_abbrev('Sat');       # Returns 'Sat'
set_day_to_day_name_abbrev(5);           # Returns 'Fri'
set_day_to_day_name_full
Usage:
my $dayofweek_fullname = set_day_to_day_name_full( $dayofweek );
Purpose:
Set the day of week to full name
Returns:
Day of week full name
Parameter(s):
Day of week in one of three formats ( numeric<1-7>, full name or three character abbreviated )
Throws:
Throws exception for any invalid input
Comments:
<1 for Monday ... 7 for Sunday>
Examples:
set_day_to_day_name_full(5);          # Returns  'Friday'
set_day_to_day_name_full('Tuesday');  # Returns  'Tuesday'
set_day_to_day_name_full('Sun');      # Returns  'Sunday'
set_day_to_day_number
Usage:
my $dayofweek_number = set_day_to_day_number( $dayofweek );
Purpose:
Set the incoming day of week to day of week number
Returns:
Numeric day of week (1-7)
Parameter(s):
Day of week in one of three formats ( numeric <1-7>, full name or three character abbreviated )
Throws:
Throws exception for any invalid input
Comments:
1 for Mon, ..., 7 for Sun
Examples:
set_day_to_day_number('Sunday'); # Returns 7
set_day_to_day_number('Tue');    # Returns 2
set_day_to_day_number(1);        # Returns 1
set_month_to_month_name_abbrev
Usage:
my $month_alpha = set_month_to_month_name_abbrev( $month );
Purpose:
Set the incoming month to three letter abbreviation
Returns:
Three character month abbreviation
Parameter(s):
Month in one of three formats ( numeric <1-12>, full name or three character abbreviated )
Throws:
Throws exception for any invalid input
Comments:
Again, the standard three character abbreviation for the month is returned.
Examples:
set_month_to_month_name_abbrev(11);      # Returns 'Nov'
set_month_to_month_name_abbrev('Dec');   # Returns 'Dec'
set_month_to_month_name_abbrev('April'); # Returns 'Apr'
set_month_to_month_name_full
Usage:
my $month_fullname = set_month_to_month_name_full( $month );
Purpose:
Set the incoming month to full name
Returns:
Month full name
Parameter(s):
Month in one of three formats ( numeric<1-12>, full name or three character abbreviated )
Throws:
Throws exception for any invalid input
Comments:
<1 for Jan ... 12 for Dec>
Examples:
set_month_to_month_name_full(11);        # Returns  'November'
set_month_to_month_name_full('Apr');     # Returns  'April'
set_month_to_month_name_full('August');  # Returns  'August'
set_month_to_month_number
Usage:
my $month_num = set_month_to_month_number( $month );
Purpose:
Set the incoming month to month number
Returns:
Numeric month (1-12)
Parameter(s):
Month in one of three formats ( numeric <1-12>, full name or three character abbreviated )
Throws:
Throws exception for any invalid input
Examples:
set_month_to_month_number(3);      # Returns 3
set_month_to_month_number('Jan');  # Returns 1
set_month_to_month_number('July'); # Returns 7
day_name_to_day_number
Usage:
my $numeric_dayofweek = day_name_to_day_number( $day_name );
Purpose:
Convert alpha day of week name to numeric day of week
Returns:
Numeric day of week (1-7)
Parameter(s):
Day of week, full name or three letter abbreviation
Throws:
Throws exception for any invalid input
Comments:
<1 for Mon ... 7 for Sun>
Examples:
day_name_to_day_number('Tue'     ); # Returns 2
day_name_to_day_number('Thursday'); # Returns 4
day_name_to_day_number('Sunday'  ); # Returns 7
day_number_to_day_name
Usage:
my $dayofweek_abbreviated = day_number_to_day_name( $numeric_dayofweek );
Purpose:
Convert numeric number to three letter abbreviation for day of week
Returns:
Abbreviated day of week
Parameter(s):
Numeric day of week (1-7)
Throws:
Throws exception for any invalid input
Comments:
<1 for Mon ... 7 for Sun>
Examples:
day_number_to_day_name(1); # Returns 'Mon'
day_number_to_day_name(3); # Returns 'Wed'
day_number_to_day_name(7); # Returns 'Sun'
month_name_to_month_number
Usage:
my $month_number = month_name_to_month_number( $month_alpha );
Purpose:
Convert alpha month name to month number
Returns:
Numeric month (1-12)
Parameter(s):
Month in alpha format ( full name or three character abbreviated )
Throws:
Throws exception for any invalid input
Comments:
Input month MUST be in alpha format, full or abbreviated
Examples:
month_name_to_month_number('Nov');      # Returns 11
month_name_to_month_number('February'); # Returns 2
month_number_to_month_name
Usage:
my $month_alpha = month_number_to_month_name( $month_num );
Purpose:
Convert month number to month alpha
Returns:
Three character month abbreviation
Parameter(s):
Month in numeric format
Throws:
Throws exception for any invalid input
Comments:
Input month MUST be in numeric format (1-12)
Examples:
month_number_to_month_name(9); # Returns 'Sep'
compare_date1_and_date2
Usage:
my $compare_result = compare_date1_and_date2( $date_1, date_2 );
Purpose:
Compares two dates to find which one is later
Returns:
-  '1' if the FIRST date is LATER   than the second
- '-1' if the FIRST date is EARLIER than the second
-  '0' if both dates are the same
Parameter(s):
- Date string one in any format
- Date string two in any format
Throws:
Throws exception for any invalid input
date1_to_date2_delta
Usage:
my $date_difference = date1_to_date2_delta( $date_1, date_2 );
Purpose:
Finds the difference in days between the two dates by subtracting the second from the first
Returns:
Number of days difference
Parameter(s):
- Date string one in any format
- Date string two in any format
Throws:
Throws exception for any invalid input
Comments:
If day ONE is EARLIER than date TWO, a negative number is returned.
Examples:
date1_to_date2_delta('Sat Jan  7 08:50:51   1995', '1/8/1996'); # Returns -366
date1_to_date2_delta('4/11/2002',                  '4/9/2002'); # Returns 2
date1_to_date2_delta('12/11/1544',               '12/11/1544'); # Returns 0
date_offset_in_days
Usage:
my $offset_date = date_offset_in_days( $date, $num_days );
Purpose:
Find a date in the future or past offset by the number of days from the given date
Returns:
Date of the day offset from the given date
Parameter(s):
- Date string in any format
- Integer number of days, positive or negative
Throws:
Throws exception for any invalid input
Comments:
Positive offset is future date, negative is past date, zero is current date (no offset)
Examples:
date_offset_in_days('1/1/2000',    1);  # Returns '1/2/2000'
date_offset_in_days('1/21/2000',  -5);  # Returns '1/16/2000'
compare_year1_and_year2
Usage:
my $compare_result = compare_year1_and_year2( $date_1, date_2 );
Purpose:
Compares two dates to find which one is the later year, months and days are ignored
Returns:
-  '1' if the FIRST year is LATER   than the second
- '-1' if the FIRST year is EARLIER than the second
-  '0' if both years are the same
Parameter(s):
- Date string one in any format
- Date string two in any format
Throws:
Throws exception for any invalid input
Comments:
Again, the month and day-of-month fields in the input parameters are COMPLETELY ignored.
Examples:
# Returns '0',   The years in both dates, 9/23/1967 and 4/7/1967, are the same
compare_year1_and_year2('9/23/1967',  '4/7/1967');

# Returns '1',   Year 2004 is greater than year 2003
compare_year1_and_year2('1/7/2004',   '12/19/2003');

# Returns '-1',  Year 1387 is less than year 1555
compare_year1_and_year2('Fri May 18 08:50:51 1387',  'Wed Feb 23 08:50:51 1555');
year1_to_year2_delta
Usage:
my $years_difference = year1_to_year2_delta( $date_1, date_2 );
Purpose:
Calculates the difference in WHOLE years between two dates (basically it
truncates the date difference to whole years)
Returns:
Integer year difference
Parameter(s):
- Date string one in any format
- Date string two in any format
Throws:
Throws exception for any invalid input
Comments:
- Difference is positive if date1 > date2
- Difference is negative if date1 < date2
Examples:
year1_to_year2_delta('12/25/2007', '4/11/2002'); # Returns 5
year1_to_year2_delta('6/07/1999',  '6/06/1998'); # Returns 1
year1_to_year2_delta('2/28/1992',  '2/28/1996'); # Returns -4
year1_to_year2_delta('2/29/1992',  '2/28/1996'); # Returns -3
date_offset_in_years
Usage:
my $offset_date = date_offset_in_years( $date, $num_years );
Purpose:
Find a date in the future or past offset by the number of YEARS from the given date
Returns:
Date offset by the number of years
Parameter(s):
- Date string in any format
- Integer number of years, positive or negative
Throws:
Throws exception for any invalid input
Comments:
There are two exceptions where the new month/dayofmonth do NOT match the original
  - Feb 29 in a leap year maps to Feb 28 in a NON leap year
  - Feb 28 in a NON leap year maps to Feb 29 in a leap year
Examples:
date_offset_in_years('1/4/1841', -2003); # returns  '01/04/-162'

- Case where leap year day maps to non leap year
date_offset_in_years('2/29/1604', 107); # returns  '02/28/1711'
date_offset_in_years('2/29/2096', -53); # returns  '02/28/2043'
date_offset_in_years('2/29/-8',     0); # returns  '02/29/-8'

- Case where NON leap year day maps to leap year
date_offset_in_years('2/28/1781', 443); # returns  '02/29/2224'
date_offset_in_years('2/28/1919', -91); # returns  '02/29/1828'
date_offset_in_years('2/28/-77',  173); # returns  '02/29/96'
number_of_weekdays_in_range
Usage:
my $num_weekdays = number_of_weekdays_in_range( $date_1, date_2 );
Purpose:
Calculates the number of weekdays in the range of the two dates
Returns:
Number of weekdays the range
Parameter(s):
- Date string one in any format
- Date string two in any format
Throws:
Throws exception for any invalid input
Comments:
- Difference is positive if date1 > date2
- Difference is negative if date1 < date2
- Friday to Saturday counts as ZERO days
- Friday to Sunday   counts as ZERO days
- Friday to Monday   counts as one  day
- Tuesday to previous Wednesday counts as NEGATIVE four days
Examples:
number_of_weekdays_in_range('10/22/2007', '10/31/2007'); # Returns -7
number_of_weekdays_in_range('1/1/-399',   '12/31/-400'); # Returns 1
is_leap_year
Usage:
my $status = is_leap_year( $year );
Purpose:
Determine if year is a leap year or not
Returns:
- '1' if leap year
- ''  if NON leap year
Parameter(s):
Year
Throws:
Throws exception for any invalid input
Comments:
Handles all years, even negative years (aka BC)
Examples:
is_leap_year(1900);  # Returns    ''
is_leap_year(2099);  # Returns    ''
is_leap_year(  -4);  # Returns 'yes'
is_leap_year(2004);  # Returns 'yes'
get_year_phase
Usage:
my $year_phase = get_year_phase( $year );
Purpose:
Get the phase (0-399) of the current year within the standard 400 year cycle
Returns:
Year phase (0-399) for the given year
Parameter(s):
Year
Throws:
Throws exception for any invalid input
Comments:
- Handles all years, even negative years (aka BC)
- years repeat in a standard 400 year cycle where year 2000 is defined by
  this program to be phase '0' and year 2399 is then phase '399'
Examples:
get_year_phase(1900);  # Returns  300
get_year_phase(2000);  # Returns    0
get_year_phase(2001);  # Returns    1
get_year_phase(  -3);  # Returns  397
get_year_phase(1999);  # Returns  399
number_of_day_within_year
Usage:
my $day_number = number_of_day_within_year( $date_string );
Purpose:
Get the day number within the year
Returns:
Day number within year
Parameter(s):
Date string which will be parsed
Throws:
Throws exception for any invalid input
Comments:
Jan 31 ALWAYS returns '31' and Dec 31 returns either '365' or '366' depending upon leap year
Examples:
number_of_day_within_year('3/1/0');      # Returns    61
number_of_day_within_year('1/1/2000');   # Returns     1
number_of_day_within_year('12/31/2000'); # Returns   366
number_of_day_within_year('1/28/2007');  # Returns    28
number_of_day_within_year('3/1/2007');   # Returns    60
day_number_within_year_to_date
Usage:
my $date = day_number_within_year_to_date( $year, $day_number );
Purpose:
Converts the number of the day within the year to a date
Returns:
Date
Parameter(s):
- Year
- Number of day in year <1-365/6>
Throws:
Throws exception for any invalid input
Comments:
Handles all years, even negative years (aka BC)
Examples:
day_number_within_year_to_date(2001, 151); # Returns  5/31/2001
day_number_within_year_to_date(1443,  60); # Returns   3/1/1443
day_number_within_year_to_date(  -4, 244); # Returns    8/31/-4
day_number_within_year_to_date(   0, 306); # Returns     11/1/0
day_number_within_400_year_cycle_to_date
Usage:
my $date = day_number_within_400_year_cycle_to_date( $year_400_cycle, $number_of_day );
Purpose:
Converts the number of the day within the standard 400 year cycle to a date
Returns:
Date
Parameter(s):
- 400 year cycle, (i.e.  ... -400, 0, 400, ... 1600, 2000, 2400, ...)
- number of day in the standard 400 year cycle <1-146097>
Throws:
Throws exception for any invalid input
Comments:
- Handles all years, even negative years (aka BC)
- Years repeat in a standard 400 year cycle where year 2000 is defined by
  this program to be phase '0' and year 2399 is then phase '399'
Examples:
day_number_within_400_year_cycle_to_date(2000, 146097); # Returns  12/31/2399
day_number_within_400_year_cycle_to_date(2000,      1); # Returns    1/1/2000
day_number_within_400_year_cycle_to_date(   0,      1); # Returns       1/1/0
day_number_within_400_year_cycle_to_date(-400, 146097); # Returns    12/31/-1
day_number_within_400_year_cycle_to_date(2000,  36527); # Returns    1/2/2100
day_number_within_400_year_cycle_to_date(1600, 130416); # Returns   1/24/1957
get_number_of_day_within_400yr_cycle
Usage:
my $day_number = get_number_of_day_within_400yr_cycle( $month, $dayofmonth, $year );
Purpose:
Get the number of the day within the standard 400 year cycle
Returns:
Day number within the standard 400 year cycle
Parameter(s):
- Month in one of three formats ( numeric <1-12>, full name or three character abbreviated )
- Day of month (1-31)
- Year
Throws:
Throws exception for any invalid input
Comments:
- Handles all years, even negative years (aka BC)
- Years repeat in a standard 400 year cycle where year 2000 is defined by
  this program to be phase '0' and year 2399 is then phase '399'.
- This would be a very LARGE integer for the 1990's
- Jan 1, 2000 would return '1'
Examples:
get_number_of_day_within_400yr_cycle( 2,    1, 2000); # Returns        32
get_number_of_day_within_400yr_cycle( 1,    1,    0); # Returns         1
get_number_of_day_within_400yr_cycle(12,   31, -201); # Returns     73049
get_number_of_day_within_400yr_cycle('Feb', 1, 1999); # Returns    145764
get_days_remaining_in_400yr_cycle
Usage:
my $num_days = get_days_remaining_in_400yr_cycle( $month, $dayofmonth, $year );
Purpose:
Get the number of days remaining from the given date to the end of
the current standard 400 year cycle
Returns:
Number of days remaining in 400 year cycle
Parameter(s):
- Month in one of three formats ( numeric <1-12>, full name or three character abbreviated )
- Day of month (1-31)
- Year
Throws:
Throws exception for any invalid input
Comments:
- Handles all years, even negative years (aka BC)
- Years repeat in a standard 400 year cycle where year 2000 is defined by
  this program to be phase '0' and year 2399 is then phase '399'
- This would be a very SMALL integer for the 1990's
- Jan 1, 2000 would return '146096'.  There are a total of 146,097 days in
  the standard 400 year cycle.
Examples:
get_days_remaining_in_400yr_cycle('Jan',  1, -400); # Returns  146096
get_days_remaining_in_400yr_cycle(12,    31, -401); # Returns       0
get_days_remaining_in_400yr_cycle(12,    30, 1999); # Returns       1
get_days_remaining_in_400yr_cycle(1,      1, 2000); # Returns  146096
get_days_remaining_in_400yr_cycle('May',  1, 2100); # Returns  109451
get_num_days_in_year
Usage:
my $num_days_in_year = get_num_days_in_year( $year );
Purpose:
Get number of days in given year
Returns:
Number of days in given year
Parameter(s):
Year
Throws:
Throws exception for any invalid input
Comments:
Handles all years, even negative years (aka BC)
Examples:
get_num_days_in_year(  -5); # Returns 365
get_num_days_in_year( 300); # Returns 365
get_num_days_in_year(1904); # Returns 366
get_num_days_in_year(2301); # Returns 365
get_days_remaining_in_year
Usage:
my $num_days = get_days_remaining_in_year( $month, $dayofmonth, $year );
Purpose:
Get the number of days remaining in the year from the given date
Returns:
Number of days remaining in year
Parameter(s):
- Month in one of three formats ( numeric <1-12>, full name or three character abbreviated )
- Day of month (1-31)
- Year
Throws:
Throws exception for any invalid input
Comments:
- Handles all years, even negative years (aka BC)
- if the last day of the year is given, 0 is returned
- <1 for Jan ... 12 for Dec>
- <1 for Mon ... 7 for Sun>
Examples:
get_days_remaining_in_year(12,         31,  -88); # Returns    0
get_days_remaining_in_year('Sep',       2, 1401); # Returns  120
get_days_remaining_in_year('February',  7, 1865); # Returns  327
get_numeric_day_of_week
Usage:
my $day_of_week = get_numeric_day_of_week( $month, $dayofmonth, $year );
Purpose:
Get numeric day of week (1-7) for given date
Returns:
Numeric day of week
Parameter(s):
- Month in one of three formats ( numeric <1-12>, full name or three character abbreviated )
- Day of month (1-31)
- Year
Throws:
Throws exception for any invalid input
Comments:
- Handles all years, even negative years (aka BC)
- <1 for Jan ... 12 for Dec>
- <1 for Mon ... 7 for Sun>
Examples:
get_numeric_day_of_week(    2,     29, -2000); # Returns 2
get_numeric_day_of_week('Dec',     31,  1795); # Returns 4
get_numeric_day_of_week('January',  1,  2000); # Returns 6
get_number_of_days_in_month
Usage:
my $num_days = get_number_of_days_in_month( $month, $year );
Purpose:
Get the number of days in a specific month
Returns:
Number of days
Parameter(s):
- Month in one of three formats ( numeric <1-12>, full name or three character abbreviated )
- Year
Throws:
Throws exception for any invalid input
Comments:
Handles all years, even negative years (aka BC)
Examples:
get_number_of_days_in_month('Apr',1996); # Returns 30
get_number_of_days_in_month('1',  1011); # Returns 31
get_days_remaining_in_month
Usage:
my $num_days = get_days_remaining_in_month( $month, $dayofmonth, $year );
Purpose:
Find out how many days are remaining in the month from the given date
Returns:
Number of days left in month
Parameter(s):
- Month in one of three formats ( numeric <1-12>, full name or three character abbreviated )
- Day of month (1-31)
- Year
Throws:
Throws exception for any invalid input
Comments:
- Handles all years, even negative years (aka BC)
- If the last day of the month is given, 0 is returned
Examples:
get_days_remaining_in_month(12,   31,  -88); # Returns  0
get_days_remaining_in_month('Sep', 2, 1401); # Returns 28
get_first_of_month_day_of_week
Usage:
my $dayofweek = get_first_of_month_day_of_week( $month, $year );
Purpose:
Get the day of the week for the first of the month for a specified month/year combination
Returns:
Day of week in numeric format
Parameter(s):
- Month in one of three formats ( numeric <1-12>, full name or three character abbreviated )
- Year
Throws:
Throws exception for any invalid input
Comments:
1 for Mon, ..., 7 for Sun
Examples:
get_first_of_month_day_of_week('Feb',1996); # Returns 4
get_first_of_month_day_of_week('2',   -57); # Returns 1
calculate_day_of_week_for_first_of_month_in_next_year
Usage:
my $dayofweek = calculate_day_of_week_for_first_of_month_in_next_year( $number_of_days_in_year_offset, $day_of_week_this_month );
Purpose:
Calculates the day of the week on the first of the month twelve months from the current month
Returns:
The day of week on the first of the month one year from current month if successful.
Parameter(s):
- Number of days from the first of the current month to the first of the month one year ahead

- Day of the week for the first of the current month
Throws:
Throws exception for any invalid input
Examples:
# Returns '5' representing Friday, where leap year (Feb 29) is in the range

my $dayofweek_0 = (calculate_day_of_week_for_first_of_month_in_next_year(366, 3);

# Returns '2' representing Tuesday, where NO leap year is in the range

my $dayofweek_1 = (calculate_day_of_week_for_first_of_month_in_next_year(365, 'Monday');
get_global_year_cycle
Usage:
my $cycle_year = get_global_year_cycle( $year );
Purpose:
Get the phase zero year for the given year.
Returns:
The phase zero year containing the given year if successful.
Parameter(s):
Integer representing year, positive or negative
Throws:
Throws exception for any invalid input
Comments:
- Handles all years, even negative years (aka BC)
- Years repeat in a standard 400 year cycle.  This function
  truncates the incoming year to the nearest multiple of 400 which
  is defined by this program to be phase '0' of the 400 year cycle.
  Thus, all values returned by this function are multiples of 400.
Examples:
get_global_year_cycle( -17); # returns   -400
get_global_year_cycle(-801); # returns  -1200
get_global_year_cycle(   1); # returns      0
get_global_year_cycle(1899); # returns   1600
get_global_year_cycle(1999); # returns   1600
get_global_year_cycle(2000); # returns   2000
get_global_year_cycle(2001); # returns   2000

DIAGNOSTICS

All functions comprehensively test input parameters BEFORE proceeding. Functions of the is_valid_ type generally return an empty string, '', for invalid. Other functions first trap errors due to invalid input, report the problem and then stop running.

A comprehensive set of tests is included in the distribution. Devel::Cover was used to achieve near complete code coverage. The only code not covered by the tests, by design, are several else statements to trap unexpected else conditions. Use the standard make test to run.

DEPENDENCIES

- Carp                  1.04  qw(croak);
- Readonly              1.03;
- Readonly::XS          1.04;
- Test::Manifest        1.22;
- Test::Pod             1.26;
- Test::Pod::Coverage   1.08;

BUGS AND LIMITATIONS

All years, positive (AD) and negative (BC) are acceptable up to the integer size on the host system. However, this range is NOT historically accurate before 1582AD. Thus, even though one can find the day of the week, for example May 17, -273BC, by projecting backwards from today's standard, the date is NOT historically valid. Refer to the the Date::Calc module for further explanation.

Date strings with truncated years such as '04' for '2004' will NOT parse correctly.

Note the correct fields within date strings of the various formats. For example, the date string '4/8/2005' is interpreted as 'April 8, 2005', NOT 'August 4, 2005'.

Startup is slow due to the one-time creation of a small hash table to speed up subsequent look-ups.

SEE ALSO

Date::Calc, Date::Simple, Date::Manip, Class::Date

For many others search for date in CPAN

AUTHOR

David McAllister, <perldave@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2007 by David McAllister

Date::Components version 0.0.2

This program is free (or copyleft) software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This software may be used in any state or jurisdiction which does not prohibit the limitation or exclusion of liability for loss or damage caused by negligence, breach of contract or breach of implied terms, or incidental or consequential damages.

DISCLAIMER OF WARRANTY

This Program of Date::Components is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

DISCLAIMER OF LIABILITY

THIS PROGRAM AND SOFTWARE IS PROVIDED TO YOU FOR FREE AND ON AN "AS IS" AND "WITH ALL FAULTS" BASIS. YOU EXPRESSLY UNDERSTAND AND AGREE THAT THE AUTHOR OF THIS PROGRAM AND SOFTWARE (AND ANY VERSION THEREOF) SHALL NOT BE LIABLE TO YOU FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL OR EXEMPLARY DAMAGES, INCLUDING BUT NOT LIMITED TO, DAMAGES FOR LOSS OF PROFITS, GOODWILL, USE, DATA OR OTHER INTANGIBLE LOSSES (EVEN IF THE AUTHOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES) RESULTING FROM: (I) THE USE OR THE INABILITY TO USE THE PROGRAM OR SOFTWARE; (II) THE INABILITY TO USE THE PROGRAM OR SOFTWARE TO ACCESS CONTENT OR DATA; (III) THE COST OF PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; (IV) UNAUTHORIZED ACCESS TO OR ALTERATION OF YOUR TRANSMISSIONS OR DATA; OR (V) ANY OTHER MATTER RELATING TO THE PROGRAM OR SOFTWARE. THE FOREGOING LIMITATIONS SHALL APPLY NOTWITHSTANDING A FAILURE OF ESSENTIAL PURPOSE OF ANY LIMITED REMEDY AND TO THE FULLEST EXTENT PERMITTED BY LAW.

NOTHING IN THIS AGREEMENT IS INTENDED TO EXCLUDE OR LIMIT ANY CONDITION, WARRANTY, RIGHT OR LIABILITY WHICH MAY NOT BE LAWFULLY EXCLUDED OR LIMITED. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF CERTAIN WARRANTIES OR CONDITIONS OR THE LIMITATION OR EXCLUSION OF LIABILITY FOR LOSS OR DAMAGE CAUSED BY NEGLIGENCE, BREACH OF CONTRACT OR BREACH OF IMPLIED TERMS, OR INCIDENTAL OR CONSEQUENTIAL DAMAGES. ACCORDINGLY, ONLY THE ABOVE LIMITATIONS IN THAT ARE LAWFUL IN YOUR JURISDICTION WILL APPLY TO YOU AND THE AUTHOR'S LIABILITY WILL BE LIMITED TO THE MAXIMUM EXTENT PERMITTED BY LAW.

LIMITATION OF LIABILITY

Notwithstanding any damages that you might incur for any reason whatsoever (including, without limitation, all damages referenced above and all direct or general damages), your sole and entire remedy for any defect, damage or loss arising from a failure of the Program and Software to perform is to stop using it. The foregoing limitations, exclusions, and disclaimers shall apply to the maximum extent permitted by applicable law, even if any remedy fails its essential purpose.

ACKNOWLEDGMENTS

This module is only possible due to the many countless and selfless people in the PERL community who have created a robust and thorough foundation to enable smooth module development.

In particular, the Date::Calc routine was used to validate the leap year exceptions of century years which are not a multiple of 400.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 5031:

Non-ASCII character seen before =encoding in 'SOFTWARE. '. Assuming CP1252