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.
is_valid_date
format_date
get_numeric_day_of_week
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.
date_only_parse
is_valid_month
is_valid_day_of_month
is_valid_day_of_week
is_valid_year
is_valid_400_year_cycle
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
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
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_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.
my ($month, $dayofmonth, $year, $dayofweek = date_only_parse( <date string> );
Converts variety of date strings into components for processing
- 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
Text string containing date in various formats
Throws exception for any invalid input
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>)
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 )
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> );
Formats dates
Date string
- ( date string in any format, <optional date format> ) OR - ( month, day of month, year, <optional date format> )
- 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'
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'
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 );
Checks if date is valid
- '1' if date is valid - '' otherwise
- ( date string in any format ) OR - ( month, day of month, year ) OR - ( month, day of month, year, dayofweek )
No exceptions
- 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>
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
my $status = is_valid_month( $month );
Checks if month is valid
- '1' if month is valid - '' otherwise
Month in one of three formats ( numeric <1-12>, full name or three character abbreviated )
<1 for Jan ... 12 for Dec>
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
my $status = is_valid_day_of_month( $month, $dayofmonth, $year );
Checks if day of month is valid
- '1' if day of month is valid - '' otherwise
- Month in one of three formats ( numeric <1-12>, full name or three character abbreviated ) - Day of month (1-31) - Year
Handles all years, even negative years (aka BC)
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
my $status = is_valid_day_of_week( $dayofweek );
Checks if day of week is valid
- '1' if day of week is valid - '' otherwise
Day of week
<1 for Mon ... 7 for Sun>
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
my $status = is_valid_year( $year );
Checks if year is valid
- '1' if year is valid - '' otherwise
Year
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
my $status = is_valid_400_year_cycle( $year_400_cycle );
Checks if year is valid 400 year cycle phase
- '1' if year is valid 400 year cycle phase number - '' otherwise
400 year cycle
valid inputs (years) are multiples of 400 (i.e. ... -400, 0, 400, ... 1600, 2000, 2400, ...)
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
my $dayofweek_alpha = set_day_to_day_name_abbrev( $dayofweek );
Set the incoming day of week to three letter abbreviation
Day of week as three character abbreviation
Day of week in one of three formats ( numeric <1-7>, full name or three character abbreviated )
1 for Mon, ..., 7 for Sun
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'
my $dayofweek_fullname = set_day_to_day_name_full( $dayofweek );
Set the day of week to full name
Day of week full name
Day of week in one of three formats ( numeric<1-7>, full name or three character abbreviated )
<1 for Monday ... 7 for Sunday>
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'
my $dayofweek_number = set_day_to_day_number( $dayofweek );
Set the incoming day of week to day of week number
Numeric day of week (1-7)
set_day_to_day_number('Sunday'); # Returns 7 set_day_to_day_number('Tue'); # Returns 2 set_day_to_day_number(1); # Returns 1
my $month_alpha = set_month_to_month_name_abbrev( $month );
Set the incoming month to three letter abbreviation
Three character month abbreviation
Again, the standard three character abbreviation for the month is returned.
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'
my $month_fullname = set_month_to_month_name_full( $month );
Set the incoming month to full name
Month full name
Month in one of three formats ( numeric<1-12>, full name or three character abbreviated )
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'
my $month_num = set_month_to_month_number( $month );
Set the incoming month to month number
Numeric month (1-12)
set_month_to_month_number(3); # Returns 3 set_month_to_month_number('Jan'); # Returns 1 set_month_to_month_number('July'); # Returns 7
my $numeric_dayofweek = day_name_to_day_number( $day_name );
Convert alpha day of week name to numeric day of week
Day of week, full name or three letter abbreviation
day_name_to_day_number('Tue' ); # Returns 2 day_name_to_day_number('Thursday'); # Returns 4 day_name_to_day_number('Sunday' ); # Returns 7
my $dayofweek_abbreviated = day_number_to_day_name( $numeric_dayofweek );
Convert numeric number to three letter abbreviation for day of week
Abbreviated day of week
day_number_to_day_name(1); # Returns 'Mon' day_number_to_day_name(3); # Returns 'Wed' day_number_to_day_name(7); # Returns 'Sun'
my $month_number = month_name_to_month_number( $month_alpha );
Convert alpha month name to month number
Month in alpha format ( full name or three character abbreviated )
Input month MUST be in alpha format, full or abbreviated
month_name_to_month_number('Nov'); # Returns 11 month_name_to_month_number('February'); # Returns 2
my $month_alpha = month_number_to_month_name( $month_num );
Convert month number to month alpha
Month in numeric format
Input month MUST be in numeric format (1-12)
month_number_to_month_name(9); # Returns 'Sep'
my $compare_result = compare_date1_and_date2( $date_1, date_2 );
Compares two dates to find which one is later
- '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
- Date string one in any format - Date string two in any format
my $date_difference = date1_to_date2_delta( $date_1, date_2 );
Finds the difference in days between the two dates by subtracting the second from the first
Number of days difference
If day ONE is EARLIER than date TWO, a negative number is returned.
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
my $offset_date = date_offset_in_days( $date, $num_days );
Find a date in the future or past offset by the number of days from the given date
Date of the day offset from the given date
- Date string in any format - Integer number of days, positive or negative
Positive offset is future date, negative is past date, zero is current date (no offset)
date_offset_in_days('1/1/2000', 1); # Returns '1/2/2000' date_offset_in_days('1/21/2000', -5); # Returns '1/16/2000'
my $offset_date = date_offset_in_weekdays( $date, $num_days );
Find a WEEKDAY date in the future or past offset by the number of weekdays from the given starting WEEKDAY date
Date of the weekday offset from the given weekday date
- Weekday date string in any format - Integer number of weekdays, positive or negative
Throws exception for any invalid input INCLUDING weekend dates
This effectively functions as if ALL weekend dates were removed from the calendar. This function accepts ONLY weekday dates and outputs ONLY weekday dates
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'
my $compare_result = compare_year1_and_year2( $date_1, date_2 );
Compares two dates to find which one is the later year, months and days are ignored
- '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
Again, the month and day-of-month fields in the input parameters are COMPLETELY ignored.
# 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');
my $years_difference = year1_to_year2_delta( $date_1, date_2 );
Calculates the difference in WHOLE years between two dates (basically it truncates the date difference to whole years)
Integer year difference
- Difference is positive if date1 > date2 - Difference is negative if date1 < date2
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
my $offset_date = date_offset_in_years( $date, $num_years );
Find a date in the future or past offset by the number of YEARS from the given date
Date offset by the number of years
- Date string in any format - Integer number of years, positive or negative
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
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'
my $num_weekdays = number_of_weekdays_in_range( $date_1, date_2 );
Calculates the number of weekdays in the range of the two dates
Number of weekdays the range
- 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
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
my $status = is_leap_year( $year );
Determine if year is a leap year or not
- '1' if leap year - '' if NON leap year
is_leap_year(1900); # Returns '' is_leap_year(2099); # Returns '' is_leap_year( -4); # Returns 'yes' is_leap_year(2004); # Returns 'yes'
my $year_phase = get_year_phase( $year );
Get the phase (0-399) of the current year within the standard 400 year cycle
Year phase (0-399) for the given year
- 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'
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
my $day_number = number_of_day_within_year( $date_string );
Get the day number within the year
Day number within year
Date string which will be parsed
Jan 31 ALWAYS returns '31' and Dec 31 returns either '365' or '366' depending upon leap year
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
my $date = day_number_within_year_to_date( $year, $day_number );
Converts the number of the day within the year to a date
Date
- Year - Number of day in year <1-365/6>
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
my $date = day_number_within_400_year_cycle_to_date( $year_400_cycle, $number_of_day );
Converts the number of the day within the standard 400 year cycle to a date
- 400 year cycle, (i.e. ... -400, 0, 400, ... 1600, 2000, 2400, ...) - number of day in the standard 400 year cycle <1-146097>
- 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'
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
my $day_number = get_number_of_day_within_400yr_cycle( $month, $dayofmonth, $year );
Get the number of the day within the standard 400 year cycle
Day number within the standard 400 year cycle
- 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'
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
my $num_days = get_days_remaining_in_400yr_cycle( $month, $dayofmonth, $year );
Get the number of days remaining from the given date to the end of the current standard 400 year cycle
Number of days remaining in 400 year cycle
- 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.
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
my $num_days_in_year = get_num_days_in_year( $year );
Get number of days in given year
Number of days in given year
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
my $num_days = get_days_remaining_in_year( $month, $dayofmonth, $year );
Get the number of days remaining in the year from the given date
Number of days remaining in year
- 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>
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
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 );
Get numeric day of week (1-7) for given date
Numeric day of week
- ( date string in any format ) OR - ( month, day of month, year )
- Handles all years, even negative years (aka BC) - <1 for Jan ... 12 for Dec> - <1 for Mon ... 7 for Sun>
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
my $month_number = get_month_from_string( SCALAR );
Extract month from given date string
Month number
Date string in any format
- Handles all years, even negative years (aka BC) - <1 for Jan ... 12 for Dec>
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
my $day_of_month = get_dayofmonth_from_string( SCALAR );
Extract day of month from given date string
Day of month
- Handles all years, even negative years (aka BC)
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
my $year = get_year_from_string( SCALAR );
Extract year from given date string
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
my $num_days = get_number_of_days_in_month( $month, $year );
Get the number of days in a specific month
Number of days
- Month in one of three formats ( numeric <1-12>, full name or three character abbreviated ) - Year
get_number_of_days_in_month('Apr',1996); # Returns 30 get_number_of_days_in_month('1', 1011); # Returns 31
my $num_days = get_days_remaining_in_month( $month, $dayofmonth, $year );
Find out how many days are remaining in the month from the given date
Number of days left in month
- Handles all years, even negative years (aka BC) - If the last day of the month is given, 0 is returned
get_days_remaining_in_month(12, 31, -88); # Returns 0 get_days_remaining_in_month('Sep', 2, 1401); # Returns 28
my $dayofweek = get_first_of_month_day_of_week( $month, $year );
Get the day of the week for the first of the month for a specified month/year combination
Day of week in numeric format
get_first_of_month_day_of_week('Feb',1996); # Returns 4 get_first_of_month_day_of_week('2', -57); # Returns 1
my $dayofweek = calculate_day_of_week_for_first_of_month_in_next_year( $number_of_days_in_year_offset, $day_of_week_this_month );
Calculates the day of the week on the first of the month twelve months from the current month
The day of week on the first of the month one year from current month if successful.
- 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
# 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');
my $cycle_year = get_global_year_cycle( $year );
Get the phase zero year for the given year.
The phase zero year containing the given year if successful.
Integer representing year, positive or negative
- 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.
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.
is_valid_
''
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.
Devel::Cover
make test
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.
1 POD Error
The following errors were encountered while parsing the POD:
Non-ASCII character seen before =encoding in 'SOFTWARE. '. Assuming CP1252
To install Date::Components, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Date::Components
CPAN shell
perl -MCPAN -e shell install Date::Components
For more information on module installation, please visit the detailed CPAN module installation guide.