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

This documentation refers to Date::Components version 0.2.1

  use Carp              qw(croak);
  use Date::Components  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 );

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.

Subroutines is_valid_date, format_date and get_numeric_day_of_week 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.

  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.

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

date_offset_in_weekdays

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_month_from_string

get_dayofmonth_from_string

get_year_from_string

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

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.

None by default.

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'

date_offset_in_weekdays

Usage:

 my $offset_date = date_offset_in_weekdays( $date, $num_days );

Purpose:

 Find a WEEKDAY date in the future or past offset by the number of weekdays from the given starting WEEKDAY date

Returns:

 Date of the weekday offset from the given weekday date

Parameter(s):

 - Weekday date string in any format
 - Integer number of weekdays, positive or negative

Throws:

 Throws exception for any invalid input INCLUDING weekend dates

Comments:

 This effectively functions as if ALL weekend dates were removed
 from the calendar.  This function accepts ONLY weekday dates and
 outputs ONLY weekday dates

Examples:

 date_offset_in_weekdays('Mon Jul 11 08:50:51 1977', -7);  # Returns '06/30/1977'
 date_offset_in_weekdays('Tue Jul 12 08:50:51 1977', -3);  # Returns '07/07/1977'
 date_offset_in_weekdays('Wed Jul 13 08:50:51 1977',  0);  # Returns '07/13/1977'
 date_offset_in_weekdays('Thu Jul 14 08:50:51 1977',  3);  # Returns '07/19/1977'
 date_offset_in_weekdays('Fri Jul 15 08:50:51 1977',  7);  # Returns '07/26/1977'

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:

 Function is overloaded to accept one of two date input types
 1) Date string
     my $day_of_week = get_numeric_day_of_week( SCALAR );
 2) Month, dayofmonth, year
     my $day_of_week = get_numeric_day_of_week( SCALAR, SCALAR, SCALAR );

Purpose:

 Get numeric day of week (1-7) for given date

Returns:

 Numeric day of week

Parameter(s):

 - ( date string in any format )
           OR
 - ( month, day of month, 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_numeric_day_of_week('Sep  23, 1541');      # Returns 2
 get_numeric_day_of_week('June  6, 2001');      # Returns 3

get_month_from_string

Usage:

 my $month_number = get_month_from_string( SCALAR );

Purpose:

 Extract month from given date string

Returns:

 Month number

Parameter(s):

 Date string in any format

Throws:

 Throws exception for any invalid input

Comments:

 - Handles all years, even negative years (aka BC)
 - <1 for Jan ... 12 for Dec>

Examples:

 get_month_from_string('12/31/1795');               # Returns  12
 get_month_from_string('Sat Oct 22 08:50:51 1577'); # Returns  10
 get_month_from_string('June  6, 2001');            # Returns   6
 get_month_from_string('February  28, 1995');       # Returns   2
 get_month_from_string('-1755-08-15');              # Returns   8
 get_month_from_string('19 May, 227');              # Returns   5

get_dayofmonth_from_string

Usage:

 my $day_of_month = get_dayofmonth_from_string( SCALAR );

Purpose:

 Extract day of month from given date string

Returns:

 Day of month

Parameter(s):

 Date string in any format

Throws:

 Throws exception for any invalid input

Comments:

 - Handles all years, even negative years (aka BC)

Examples:

 get_dayofmonth_from_string('12/31/1795');               # Returns  31
 get_dayofmonth_from_string('Sat Oct 22 08:50:51 1577'); # Returns  22
 get_dayofmonth_from_string('June  6, 2001');            # Returns   6
 get_dayofmonth_from_string('February  28, 1995');       # Returns  28
 get_dayofmonth_from_string('-1755-08-15');              # Returns  15
 get_dayofmonth_from_string('19 May, 227');              # Returns  19

get_year_from_string

Usage:

 my $year = get_year_from_string( SCALAR );

Purpose:

 Extract year from given date string

Returns:

 Year

Parameter(s):

 Date string in any format

Throws:

 Throws exception for any invalid input

Comments:

 - Handles all years, even negative years (aka BC)

Examples:

 get_year_from_string('Sat Oct 22 08:50:51 1577'); # Returns  1577
 get_year_from_string('June  6, 2001');            # Returns  2001
 get_year_from_string('February  28, 1995');       # Returns  1995
 get_year_from_string('-1755-08-15');              # Returns -1755
 get_year_from_string('19 May, 227');              # Returns   227
 get_year_from_string('04/27/0');                  # Returns     0

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

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.

   warnings              1.05
   version               0.74
   Carp                  1.04
   Readonly              1.03
   Readonly::XS          1.04
   Test::More            0.74
   Test::Manifest        1.22
   Test::Pod             1.26
   Test::Pod::Coverage   1.08

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.

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

For many others search for date in CPAN

David McAllister, <perldave@gmail.com>

Copyright (C) 2008 by David McAllister

Date::Components version 0.2.1

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.

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

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.

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.

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.