File Coverage

blib/lib/Date/Components.pm

Criterion	Covered	Total	%
statement	1304	1369	95.2
branch	972	974	99.7
condition	207	213	97.1
subroutine	50	50	100.0
pod	44	44	100.0
total	2577	2650	97.2

{
package Date::Components;

use 5.008008;
use strict;
use warnings;

require Exporter;

our @ISA = qw(Exporter);

eval {use Carp   qw(croak)};
eval {use Readonly};

our @EXPORT = qw();

# Items to export into callers namespace by default. Note: do not export
# names by default without a very good reason. Use EXPORT_OK instead.
# Do not simply export all your public functions/methods/constants.
our @EXPORT_OK = ( qw(
                      date_only_parse
                      is_valid_date
                      format_date
                      is_leap_year
                      is_valid_month
                      is_valid_day_of_month
                      is_valid_day_of_week
                      is_valid_year
                      is_valid_400_year_cycle
                      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
                      day_name_to_day_number
                      day_number_to_day_name
                      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
                      month_name_to_month_number
                      month_number_to_month_name
                      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
                      date1_to_date2_delta
                      number_of_weekdays_in_range
                      compare_date1_and_date2
                      year1_to_year2_delta
                      compare_year1_and_year2
                      date_offset_in_days
                      date_offset_in_weekdays
                      date_offset_in_years
                      calculate_day_of_week_for_first_of_month_in_next_year
                      get_global_year_cycle
                     ),
                 );

# This allows declaration use Date::Components ':all';
# If you do not need this, moving things directly into @EXPORT or @EXPORT_OK
# will save memory.
our %EXPORT_TAGS = (
                    'all' => [ @EXPORT_OK, @EXPORT ],
                   );

use version; our $VERSION = qv('0.2.1');


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







Readonly my $DATE_BASELINE_YEAR_2000       => '2000';
#Readonly my $DATE_BASELINE_MONTHNUM        => '1';
#Readonly my $DATE_BASELINE_MONTHNAME       => 'January';
#Readonly my $DATE_BASELINE_DAYNUM          => '6';
#Readonly my $DATE_BASELINE_DAYNAME         => 'Saturday';
Readonly my $NUMBER_OF_YEAR_PHASES         => 400;
#Readonly my $MIN_NUMBER_OF_DAYS_IN_YEAR    => 365;
#Readonly my $MAX_NUMBER_OF_DAYS_IN_YEAR    => 366;
#Readonly my $MIN_NUMBER_OF_DAYS_IN_A_MONTH => 28;
#Readonly my $NUMBER_OF_MONTHS_IN_YEAR      => 12;

Readonly my $NUMBER_OF_DAYS_IN_400_YEAR_CYCLE => (300 * 365) + (100 * 366) - 3; # three is subtracted for the three of the four century years which are NOT leap years
Readonly my $BASELINE_DAY_OF_WEEK_ON_JAN_1_2000 => 6;



# Create READ ONLY hash to hold day of week on Jan 1 for each year phase
my %hash_intermediate_00;
$hash_intermediate_00{'0'} = $BASELINE_DAY_OF_WEEK_ON_JAN_1_2000;
for ( my $iii_003=1; $iii_003<$NUMBER_OF_YEAR_PHASES; $iii_003++ )
   {
   my $num_days_in_year_05 = get_num_days_in_year($iii_003 - 1);
   $hash_intermediate_00{$iii_003} = calculate_day_of_week_for_first_of_month_in_next_year( $num_days_in_year_05, $hash_intermediate_00{$iii_003 - 1} );
   }
Readonly my %DAY_OF_WEEK_ON_FIRST_OF_YEAR => %hash_intermediate_00;


# Create READ ONLY hash to hold day of week on each first of month for each year phase
my %hash_intermediate_01;
for ( my $iii_007=0; $iii_007<$NUMBER_OF_YEAR_PHASES; $iii_007++ )
   {
   $hash_intermediate_01{$iii_007}{1}  = get_first_of_month_day_of_week(  1, $iii_007 );
   $hash_intermediate_01{$iii_007}{2}  = get_first_of_month_day_of_week(  2, $iii_007 );
   $hash_intermediate_01{$iii_007}{3}  = get_first_of_month_day_of_week(  3, $iii_007 );
   $hash_intermediate_01{$iii_007}{4}  = get_first_of_month_day_of_week(  4, $iii_007 );
   $hash_intermediate_01{$iii_007}{5}  = get_first_of_month_day_of_week(  5, $iii_007 );
   $hash_intermediate_01{$iii_007}{6}  = get_first_of_month_day_of_week(  6, $iii_007 );
   $hash_intermediate_01{$iii_007}{7}  = get_first_of_month_day_of_week(  7, $iii_007 );
   $hash_intermediate_01{$iii_007}{8}  = get_first_of_month_day_of_week(  8, $iii_007 );
   $hash_intermediate_01{$iii_007}{9}  = get_first_of_month_day_of_week(  9, $iii_007 );
   $hash_intermediate_01{$iii_007}{10} = get_first_of_month_day_of_week( 10, $iii_007 );
   $hash_intermediate_01{$iii_007}{11} = get_first_of_month_day_of_week( 11, $iii_007 );
   $hash_intermediate_01{$iii_007}{12} = get_first_of_month_day_of_week( 12, $iii_007 );
   }

Readonly my %NUMERIC_DAY_OF_WEEK_ON_FIRST_OF_MONTH => %hash_intermediate_01;


# Preloaded methods go here.

###############################################################################
# Usage      : date_only_parse( SCALAR )
# Purpose    : converts variety of date strings into components for processing
# Returns    : - if parse is successful 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>
#            :         )
#            : - '' otherwise
# 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
#            :   - 'month_num/day_num/year'
#            :   - 'Mon Sep 17 08:50:51 2007'
#            :   - 'September 17, 2007'
#            :   - '17 September, 2007'
#            :   - 'YYYY-MM-DD' (ex: 2007-09-01 )
# See Also   : N/A
###############################################################################
sub date_only_parse
   {
   my (
       $date_string_in_00,
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_03 = 1;
   ( @_ ==  $num_input_params_03 ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly $num_input_params_03 parameter(s), a date string in any format.   '@_'.\n\n\n";
   ( ref(\$_[0]) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the date string    '$_[0]'.\n\n\n";
   ( $_[0]  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the date string    '$_[0]'.\n\n\n";


   foreach ($date_string_in_00)
      {
      SWITCH:
         {
         if ( ( /^(\d{1,2})\/(\d{1,2})\/(\-{0,1}\d{1,})$/ )                                        &&  ( is_valid_date( $1, $2, $3 ) ) )        { return ( int($1), int($2), $3, get_numeric_day_of_week( $1, $2, $3 ) );                   last SWITCH; } # 'month_num/day_num/year'
         if ( ( /^([a-z]{3,3})\s+([a-z]{3,3})\s+(\d{1,2})\s+\d\d:\d\d:\d\d\s+(\-{0,1}\d{1,})$/i )  &&  ( is_valid_date( $2, $3, $4, $1 ) ) )    { return ( set_month_to_month_number($2), $3, $4, get_numeric_day_of_week( $2, $3, $4 ) );  last SWITCH; } # 'Mon Sep 17 08:50:51 2007'
         if ( ( /^([a-z]{3,})\s+(\d{1,2}),\s+(\-{0,1}\d{1,})$/i )                                  &&  ( is_valid_date( $1, $2, $3 ) ) )        { return ( set_month_to_month_number($1), $2, $3, get_numeric_day_of_week( $1, $2, $3 ) );  last SWITCH; } # 'September 17, 2007'
         if ( ( /^(\d{1,2})\s+([a-z]{3,}),\s+(\-{0,1}\d{1,})$/i )                                  &&  ( is_valid_date( $2, $1, $3 ) ) )        { return ( set_month_to_month_number($2), $1, $3, get_numeric_day_of_week( $2, $1, $3 ) );  last SWITCH; } # '17 September, 2007'
         if ( ( /^(\-{0,1}\d{1,})\-(\d{2,2})\-(\d{2,2})$/ )                                        &&  ( is_valid_date( $2, $3, $1 ) ) )        { return ( int($2), int($3), $1, get_numeric_day_of_week( $2, $3, $1 ) );                   last SWITCH; } # YYYY-MM-DD (ex: 2007-09-01 )
#         if (  )    { $whatever = 1; last SWITCH; }
         return ( '' );
         }
      }


# TBD possibly add more formats
#   Dates parsed by Date::Parse
#    1995:01:24T09:08:17.1823213           ISO-8601
#    1995-01-24T09:08:17.1823213
#    Wed, 16 Jun 94 07:29:35 CST           Comma and day name are optional
#    Thu, 13 Oct 94 10:13:13 -0700
#    Wed, 9 Nov 1994 09:50:32 -0500 (EST)  Text in ()'s will be ignored.
#    21/dec/93 17:05
   }




###############################################################################
# Usage      : Function is overloaded to accept one of three date input types
#            :    1) Date string
#            :       is_valid_date( SCALAR )
#            :    2) Month, dayofmonth, year
#            :       is_valid_date( SCALAR, SCALAR, SCALAR )
#            :    3) Month, dayofmonth, year, dayofweek
#            :       is_valid_date( SCALAR, SCALAR, SCALAR, SCALAR )
# Purpose    : checks if date is valid
# Returns    : - '1' if date is valid
#            : - ''  otherwise
# Parameters : 1) ( date string in any format )
#            :           OR
#            : 2) ( month, day of month, year )
#            :           OR
#            : 3) ( 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>
# See Also   : N/A
###############################################################################
sub is_valid_date
   {


   # Incoming Inspection
   if ( ( @_  !=  1 )  &&  ( @_  !=  3 )  &&  ( @_  !=  4 ) )
      {
      return ( '' );
      }


   my ( $month_input_00, $day_of_month_in_00, $year_in_00, $day_of_week_in_00 );
   my $month_num_00;
   if ( @_ ==  1 ) # recursive and back into 'is_valid_date' one time just to get date string parsed
      {
      my $date_in_04 = $_[0];
      if ( ref(\$date_in_04)  ne 'SCALAR' )
         {
         return ( '' );
         }

      if ( $date_in_04  eq  '' )
         {
         return ( '' );
         }

      if ( date_only_parse($date_in_04)  eq  '' )
         {
         return ( '' );
         }
      else
         {
         return ( '1' );
         }
      }
   elsif ( @_ ==  3 ) # day of week is NOT given by user
      {
      ( $month_input_00, $day_of_month_in_00, $year_in_00 ) = @_;
      if ( !(is_valid_month($month_input_00)) )
         {
         return ( '' );
         }

      if ( !(is_valid_year($year_in_00)) )
         {
         return ( '' );
         }

      if ( !(is_valid_day_of_month($month_input_00, $day_of_month_in_00, $year_in_00)) )
         {
         return ( '' );
         }
      }
   else # day of week IS given by user
      {
      ( $month_input_00, $day_of_month_in_00, $year_in_00, $day_of_week_in_00 ) = @_;
      if ( !(is_valid_month($month_input_00)) )
         {
         return ( '' );
         }

      if ( !(is_valid_year($year_in_00)) )
         {
         return ( '' );
         }

      if ( !(is_valid_day_of_month($month_input_00, $day_of_month_in_00, $year_in_00)) )
         {
         return ( '' );
         }

      if ( !(is_valid_day_of_week($day_of_week_in_00)) )
         {
         return ( '' );
         }
      }


   # Set to numeric forms
   $month_num_00 = set_month_to_month_number($month_input_00);

   my $day_of_week_on_day_n_00 = get_numeric_day_of_week(
                                                         $month_num_00,       # month in digits or alpha
                                                         $day_of_month_in_00, # day of month in digits
                                                         $year_in_00,         # year in digits
                                                        );

   # Check calculated day of week matches the input from user
   if ( $day_of_week_in_00 )
      {
      if ( set_day_to_day_number($day_of_week_in_00) != $day_of_week_on_day_n_00 )
         {
         return ( '' );
         }
      }

   return ( '1' );
   }




###############################################################################
# Usage      : calculate_day_of_week_for_first_of_month_in_next_year( SCALAR, SCALAR )
# Purpose    : calculates the day of the week on the first of the month twelve months from the current month
# Returns    : numeric day of week if successful
# Parameters : (
#            :  number of days between the first of the current month and the first of the month twelve months later,
#            :  alpha or numeric_day_of_week for first of current month <1 for Mon ... 7 for Sun>
#            : )
# Throws     : Throws exception for any invalid input
# Comments   : N/A
# See Also   : N/A
###############################################################################
sub calculate_day_of_week_for_first_of_month_in_next_year
   {
   my (
       $num_days_in_year_02,
       $day_of_week_on_first_of_month_00,
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_15 = 2;
   ( @_ ==  $num_input_params_15) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly $num_input_params_15 parameter(s), the number of days in a calender year (either 365 or 366).   '@_'.\n\n\n";
   ( ref(\$num_days_in_year_02) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the number of days in a calender year (either 365 or 366)    '$num_days_in_year_02'.\n\n\n";
   ( $num_days_in_year_02  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the number of days in a calender year (either 365 or 366)    '$num_days_in_year_02'.\n\n\n";
   ( ( $num_days_in_year_02  eq '365' )  ||  ( $num_days_in_year_02  eq '366' ) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a number (1-7) for the number of days in a calender year (either 365 or 366)    '$num_days_in_year_02'.\n\n\n";

   ( ref(\$day_of_week_on_first_of_month_00) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the day of the week for the first of a month    '$day_of_week_on_first_of_month_00'.\n\n\n";
   ( $day_of_week_on_first_of_month_00  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the day of the week for the first of a month    '$day_of_week_on_first_of_month_00'.\n\n\n";
   ( is_valid_day_of_week($day_of_week_on_first_of_month_00)  =~ m/^\d$/ ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a number (1-7) for the day of the week for the first of a month    '$day_of_week_on_first_of_month_00'.\n\n\n";

   $day_of_week_on_first_of_month_00 = set_day_to_day_number($day_of_week_on_first_of_month_00);


   $day_of_week_on_first_of_month_00 += ($num_days_in_year_02) % 7;
   if ( $day_of_week_on_first_of_month_00 > 7 )
      {
      $day_of_week_on_first_of_month_00 -=  7;
      }

   return ( $day_of_week_on_first_of_month_00 );
   }




###############################################################################
# Usage      : is_leap_year( SCALAR )
# Purpose    : determine if year is a leap year or not
# Returns    : - 'yes' if the input is a leap year
#            : - '' if the input is a NON leap year
# Parameters : (
#            :  year in integer form
#            : )
# Throws     : Throws exception for any invalid input
# Comments   : Handles all years, even negative years (aka BC)
# See Also   : N/A
###############################################################################
sub is_leap_year
   {
   my (
       $year_in_01,
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_01 = 1;
   ( @_ ==  $num_input_params_01) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly one parameter, a year number.   '@_'.\n\n\n";
   ( ref(\$year_in_01) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the year    '$year_in_01'.\n\n\n";
   ( $year_in_01  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the year    '$year_in_01'.\n\n\n";
   ( $year_in_01  =~ m/^\-{0,1}\d+$/ ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a number for the year    '$year_in_01'.\n\n\n";


   my $leap_year_status_01 = 'yes';
   if ( $year_in_01 % 4 > 0 )
      {
      $leap_year_status_01 = '';
      }
   if ( ( $year_in_01 % 100 == 0 )  &&  ( $year_in_01 % 400 > 0 ) )
      {
      $leap_year_status_01 = '';
      }

   return ( $leap_year_status_01 );
   }




###############################################################################
# Usage      : get_year_phase( SCALAR )
# Purpose    : determine the phase of the current year within the standard 400 year cycle
# Returns    : - year phase (0-399) for the given year if input is valid
# Parameters : (
#            :  year in integer form
#            : )
# 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:  years -1, 399 and 1999 are all phase 399
#            :              years -400, 0, 1600 and 2000 are all phase 0
#            :              year  1946 is phase 346
# See Also   : N/A
###############################################################################
sub get_year_phase
   {
   my (
       $year_in_02,
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_02 = 1;
   ( @_ ==  $num_input_params_02) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly one parameter, a year number.   '@_'.\n\n\n";
   ( ref(\$year_in_02) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the year    '$year_in_02'.\n\n\n";
   ( $year_in_02  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the year    '$year_in_02'.\n\n\n";
   ( $year_in_02  =~ m/^\-{0,1}\d+$/ ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a number for the year    '$year_in_02'.\n\n\n";

   my $year_offset_00 = $year_in_02 - $DATE_BASELINE_YEAR_2000;
   my $year_phase_00;

   if ( $year_offset_00 > 0 )
      {
      $year_phase_00 = $year_offset_00 % $NUMBER_OF_YEAR_PHASES;
      }
   elsif ( $year_offset_00 < 0 )
      {
      $year_phase_00 = $NUMBER_OF_YEAR_PHASES - ( (-$year_offset_00) % $NUMBER_OF_YEAR_PHASES);
      if ( $year_phase_00  ==  400 )
         {
         $year_phase_00 = '0';
         }
      }
   else
      {
      $year_phase_00 = '';
      }

   if ( $year_phase_00 eq '')
      {
      $year_phase_00 = '0';
      }

   return ( $year_phase_00 );
   }




###############################################################################
# Usage      : number_of_day_within_year( SCALAR )
# Purpose    : get the day number within the year
# Returns    : integer day number if successful
# Parameters : (
#            :  text string containing date in various formats which are 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
# See Also   : N/A
###############################################################################
sub number_of_day_within_year
   {
   my (
       $date_in_00,
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_00 = 1;
   ( @_ ==  $num_input_params_00) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly one parameter, a date string.   '@_'.\n\n\n";
   ( ref(\$date_in_00) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the date string    '$date_in_00'.\n\n\n";
   ( $date_in_00  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the date string    '$date_in_00'.\n\n\n";
   ( date_only_parse($date_in_00) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Cannot extract the date from the input date string    '$date_in_00'.\n\n\n";

   my ( $month_num_01, $day_of_month_01, $year_num_01, $day_of_week_01 ) = date_only_parse($date_in_00);

   my $month_num_05 = set_month_to_month_number($month_num_01);


   my $number_of_day_in_year = $day_of_month_01;
   for ( my $iii_001=0; $iii_001<($month_num_05-1); $iii_001++ )
      {
      if ( $iii_001  ==  1 )
         {
         if ( is_leap_year($year_num_01) )
            {
            $number_of_day_in_year += get_number_of_days_in_month($iii_001+1, $year_num_01);
            }
         else
            {
            $number_of_day_in_year += get_number_of_days_in_month($iii_001+1, $year_num_01);
            }
         }
      else
         {
         $number_of_day_in_year += get_number_of_days_in_month($iii_001+1, $year_num_01);
         }
      }

   return ( $number_of_day_in_year ) ;
   }




###############################################################################
# Usage      : month_name_to_month_number( SCALAR )
# Purpose    : convert alpha month name to month number
# Returns    : integer month number (1-12) if successful
# Parameters : full or three character abbreviated month name
# Throws     : Throws exception for any invalid input
# Comments   : N/A
# See Also   : N/A
###############################################################################
sub month_name_to_month_number
   {
   my (
       $month_in_02,
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_14 = 1;
   ( @_ ==  $num_input_params_14) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly $num_input_params_14 parameter(s), a month string.   '@_'.\n\n\n";
   ( ref(\$month_in_02) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the month string    '$month_in_02'.\n\n\n";
   ( $month_in_02  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the month string    '$month_in_02'.\n\n\n";


   # Check for expected strings
   ( is_valid_month($month_in_02) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Cannot extract the month from the input month string    '$month_in_02'.\n\n\n";
   $month_in_02  =~  m/^(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec|January|February|March|April|May|June|July|August|September|October|November|December)$/i;


   foreach ( uc($1) )
      {
      SWITCH:
         {
         if ( /^(JAN|JANUARY)$/   )    { return (  1 ); last SWITCH; }
         if ( /^(FEB|FEBRUARY)$/  )    { return (  2 ); last SWITCH; }
         if ( /^(MAR|MARCH)$/     )    { return (  3 ); last SWITCH; }
         if ( /^(APR|APRIL)$/     )    { return (  4 ); last SWITCH; }
         if ( /^(MAY|MAY)$/       )    { return (  5 ); last SWITCH; }
         if ( /^(JUN|JUNE)$/      )    { return (  6 ); last SWITCH; }
         if ( /^(JUL|JULY)$/      )    { return (  7 ); last SWITCH; }
         if ( /^(AUG|AUGUST)$/    )    { return (  8 ); last SWITCH; }
         if ( /^(SEP|SEPTEMBER)$/ )    { return (  9 ); last SWITCH; }
         if ( /^(OCT|OCTOBER)$/   )    { return ( 10 ); last SWITCH; }
         if ( /^(NOV|NOVEMBER)$/  )    { return ( 11 ); last SWITCH; }
         if ( /^(DEC|DECEMBER)$/  )    { return ( 12 ); last SWITCH; }
         croak "\n\n   ($0)   '${\(caller(0))[3]}' This month of year condition, '$month_in_02', must be in alpha form.  Something is amiss.\n\n\n";
         }
      }
   }




###############################################################################
# Usage      : day_name_to_day_number( SCALAR )
# Purpose    : convert alpha day of week name to day of week number
# Returns    : integer day of week number (1-7) if successful
# Parameters : full or three character abbreviated day of week name
# Throws     : Throws exception for any invalid input
# Comments   : <1 for Mon ... 7 for Sun>
# See Also   : N/A
###############################################################################
sub day_name_to_day_number
   {
   my (
       $day_in_02,
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_05 = 1;
   ( @_ ==  $num_input_params_05) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly one parameter, a day string.   '@_'.\n\n\n";
   ( ref(\$day_in_02) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the day string    '$day_in_02'.\n\n\n";
   ( $day_in_02  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the day string    '$day_in_02'.\n\n\n";


   # Check for expected strings
   ( is_valid_day_of_week($day_in_02)  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Cannot extract the day from the input day string    '$day_in_02'.\n\n\n";
   $day_in_02  =~  m/^(\d|Mon|Tue|Wed|Thu|Fri|Sat|Sun|Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday)$/i;

   foreach ( uc($1) )
      {
      SWITCH:
         {
         if ( /^(MON|MONDAY)$/    )    { return (  1 ); last SWITCH; }
         if ( /^(TUE|TUESDAY)$/   )    { return (  2 ); last SWITCH; }
         if ( /^(WED|WEDNESDAY)$/ )    { return (  3 ); last SWITCH; }
         if ( /^(THU|THURSDAY)$/  )    { return (  4 ); last SWITCH; }
         if ( /^(FRI|FRIDAY)$/    )    { return (  5 ); last SWITCH; }
         if ( /^(SAT|SATURDAY)$/  )    { return (  6 ); last SWITCH; }
         if ( /^(SUN|SUNDAY)$/    )    { return (  7 ); last SWITCH; }
         croak "\n\n   ($0)   '${\(caller(0))[3]}' This day of week value, '$day_in_02', should not occur.  Something is amiss.\n\n\n";
         }
      }
   }




###############################################################################
# Usage      : month_number_to_month_name( SCALAR )
# Purpose    : convert month number to month alpha
# Returns    : three character abbreviated month name if successful
# Parameters : month number (1-12)
# Throws     : Throws exception for any invalid input
# Comments   : N/A
# See Also   : N/A
###############################################################################
sub month_number_to_month_name
   {
   my (
       $month_in_03,
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_06 = 1;
   ( @_ ==  $num_input_params_06) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly one parameter, a month number.   '@_'.\n\n\n";
   ( ref(\$month_in_03) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the month number    '$month_in_03'.\n\n\n";
   ( $month_in_03  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the month number    '$month_in_03'.\n\n\n";

   # Check for expected strings
   ( $month_in_03  =~  m/^(\d{1,2})$/i ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Cannot extract the month from the input month number    '$month_in_03'.\n\n\n";


   foreach ($1)
      {
      SWITCH:
         {
         if ( $_ ==  1 )    { return ( 'Jan' ); last SWITCH; }
         if ( $_ ==  2 )    { return ( 'Feb' ); last SWITCH; }
         if ( $_ ==  3 )    { return ( 'Mar' ); last SWITCH; }
         if ( $_ ==  4 )    { return ( 'Apr' ); last SWITCH; }
         if ( $_ ==  5 )    { return ( 'May' ); last SWITCH; }
         if ( $_ ==  6 )    { return ( 'Jun' ); last SWITCH; }
         if ( $_ ==  7 )    { return ( 'Jul' ); last SWITCH; }
         if ( $_ ==  8 )    { return ( 'Aug' ); last SWITCH; }
         if ( $_ ==  9 )    { return ( 'Sep' ); last SWITCH; }
         if ( $_ == 10 )    { return ( 'Oct' ); last SWITCH; }
         if ( $_ == 11 )    { return ( 'Nov' ); last SWITCH; }
         if ( $_ == 12 )    { return ( 'Dec' ); last SWITCH; }
         croak "\n\n   ($0)   '${\(caller(0))[3]}' This month of year value, '$month_in_03', should not occur.  Something is amiss.\n\n\n";
         }
      }
   }




###############################################################################
# Usage      : day_number_to_day_name( SCALAR )
# Purpose    : convert day of week number to day of week alpha
# Returns    : three character abbreviated day of week name if successful
# Parameters : day of week number (1-7)
# Throws     : Throws exception for any invalid input
# Comments   : <1 for Mon ... 7 for Sun>
# See Also   : N/A
###############################################################################
sub day_number_to_day_name
   {
   my (
       $day_in_03,
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_07 = 1;
   ( @_ ==  $num_input_params_07) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly one parameter, a day number.   '@_'.\n\n\n";
   ( ref(\$day_in_03) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the day number    '$day_in_03'.\n\n\n";
   ( $day_in_03  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the day number    '$day_in_03'.\n\n\n";


   # Check for expected strings
   ( $day_in_03  =~  m/^(\d{1,2})$/i ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Cannot extract the day from the input day number    '$day_in_03'.\n\n\n";


   foreach ($1)
      {
      SWITCH:
         {
         if ( $_ ==  1 )    { return ( 'Mon' ); last SWITCH; }
         if ( $_ ==  2 )    { return ( 'Tue' ); last SWITCH; }
         if ( $_ ==  3 )    { return ( 'Wed' ); last SWITCH; }
         if ( $_ ==  4 )    { return ( 'Thu' ); last SWITCH; }
         if ( $_ ==  5 )    { return ( 'Fri' ); last SWITCH; }
         if ( $_ ==  6 )    { return ( 'Sat' ); last SWITCH; }
         if ( $_ ==  7 )    { return ( 'Sun' ); last SWITCH; }
         croak "\n\n   ($0)   '${\(caller(0))[3]}' This day of week value, '$day_in_03', should not occur.  Something is amiss.\n\n\n";
         }
      }
   }




###############################################################################
# Usage      : set_day_to_day_name_abbrev( SCALAR )
# Purpose    : set the incoming day of week to three letter abbreviation
# Returns    : three character abbreviated day of week name if successful
# Parameters : 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>
# See Also   : N/A
###############################################################################
sub set_day_to_day_name_abbrev
   {
   my (
       $day_in_04,
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_08 = 1;
   ( @_ ==  $num_input_params_08) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly one parameter, a day number or day alpha.   '@_'.\n\n\n";
   ( ref(\$day_in_04) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the day number or day alpha    '$day_in_04'.\n\n\n";
   ( $day_in_04  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the day number or day alpha    '$day_in_04'.\n\n\n";

   if ( $day_in_04  =~  m/^(\d{1,2})$/i )
      {
      return ( day_number_to_day_name($day_in_04) );
      }
   else
      {
      return ( day_number_to_day_name(day_name_to_day_number($day_in_04)) );
      }
   }




###############################################################################
# Usage      : set_day_to_day_name_full( SCALAR )
# Purpose    : set the incoming day of week to full name
# Returns    : day of week FULL name if successful
# Parameters : 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>
# See Also   : N/A
###############################################################################
sub set_day_to_day_name_full
   {
   my (
       $day_in_06,
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_35 = 1;
   ( @_ ==  $num_input_params_35) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly ${num_input_params_35} parameter, a day number or day alpha.   '@_'.\n\n\n";
   ( ref(\$day_in_06) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the day number or day alpha    '$day_in_06'.\n\n\n";
   ( $day_in_06  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the day number or day alpha    '$day_in_06'.\n\n\n";
   ( is_valid_day_of_week($day_in_06) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a valid the day of the week in either alpha or numeric format    '$day_in_06'.\n\n\n";


   my $day_of_week_10 = set_day_to_day_number($day_in_06);
   foreach ($day_of_week_10)
      {
      SWITCH:
         {
         if ( $_ ==  1 )    { return ( 'Monday'    ); last SWITCH; }
         if ( $_ ==  2 )    { return ( 'Tuesday'   ); last SWITCH; }
         if ( $_ ==  3 )    { return ( 'Wednesday' ); last SWITCH; }
         if ( $_ ==  4 )    { return ( 'Thursday'  ); last SWITCH; }
         if ( $_ ==  5 )    { return ( 'Friday'    ); last SWITCH; }
         if ( $_ ==  6 )    { return ( 'Saturday'  ); last SWITCH; }
                              return ( 'Sunday'    );
         }
      }
   }




###############################################################################
# Usage      : set_month_to_month_name_abbrev( SCALAR )
# Purpose    : set the incoming month to three letter abbreviation
# Returns    : three character abbreviated month name if successful
# Parameters : month in one of three formats ( numeric<1-12>, full name or three character abbreviated )
# Throws     : Throws exception for any invalid input
# Comments   : N/A
# See Also   : N/A
###############################################################################
sub set_month_to_month_name_abbrev
   {
   my (
       $month_in_04,
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_09 = 1;
   ( @_ ==  $num_input_params_09) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly one parameter, a month number or month alpha.   '@_'.\n\n\n";
   ( ref(\$month_in_04) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the month number or month alpha    '$month_in_04'.\n\n\n";
   ( $month_in_04  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the month number or month alpha    '$month_in_04'.\n\n\n";

   if ( $month_in_04  =~  m/^(\d{1,2})$/i )
      {
      return ( month_number_to_month_name($month_in_04) );
      }
   else
      {
      return ( month_number_to_month_name(month_name_to_month_number($month_in_04)) );
      }
   }




###############################################################################
# Usage      : set_month_to_month_name_full( SCALAR )
# Purpose    : set the incoming month to full name
# Returns    : month FULL name if successful
# Parameters : month in one of three formats ( numeric<1-12>, full name or three character abbreviated )
# Throws     : Throws exception for any invalid input
# Comments   : N/A
# See Also   : N/A
###############################################################################
sub set_month_to_month_name_full
   {
   my (
       $month_in_07,
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_34 = 1;
   ( @_ ==  $num_input_params_34) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly ${num_input_params_34} parameter, a month number or month alpha.   '@_'.\n\n\n";
   ( ref(\$month_in_07) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the month number or month alpha    '$month_in_07'.\n\n\n";
   ( $month_in_07  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the month number or month alpha    '$month_in_07'.\n\n\n";
   ( is_valid_month($month_in_07) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Cannot extract the month from the input month string    '$month_in_07'.\n\n\n";


   my $month_num_15 = set_month_to_month_number($month_in_07);
   foreach ($month_num_15)
      {
      SWITCH:
         {
         if ( $_ ==  1 )    { return ( 'January'   ); last SWITCH; }
         if ( $_ ==  2 )    { return ( 'February'  ); last SWITCH; }
         if ( $_ ==  3 )    { return ( 'March'     ); last SWITCH; }
         if ( $_ ==  4 )    { return ( 'April'     ); last SWITCH; }
         if ( $_ ==  5 )    { return ( 'May'       ); last SWITCH; }
         if ( $_ ==  6 )    { return ( 'June'      ); last SWITCH; }
         if ( $_ ==  7 )    { return ( 'July'      ); last SWITCH; }
         if ( $_ ==  8 )    { return ( 'August'    ); last SWITCH; }
         if ( $_ ==  9 )    { return ( 'September' ); last SWITCH; }
         if ( $_ == 10 )    { return ( 'October'   ); last SWITCH; }
         if ( $_ == 11 )    { return ( 'November'  ); last SWITCH; }
                              return ( 'December'  );
         }
      }
   }




###############################################################################
# Usage      : set_day_to_day_number( SCALAR )
# Purpose    : set the incoming day of week to day of week number
# Returns    : numeric<1-7> if successful
# Parameters : 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>
# See Also   : N/A
###############################################################################
sub set_day_to_day_number
   {
   my (
       $day_in_05,
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_10 = 1;
   ( @_ ==  $num_input_params_10) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly one parameter, a day number or day alpha.   '@_'.\n\n\n";
   ( ref(\$day_in_05) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the day number or day alpha    '$day_in_05'.\n\n\n";
   ( $day_in_05  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the day number or day alpha    '$day_in_05'.\n\n\n";

   if ( !( $day_in_05  =~  m/^(\d{1,2})$/i ) )
      {
      return ( day_name_to_day_number($day_in_05) );
      }
   else
      {
      return ( day_name_to_day_number(day_number_to_day_name($day_in_05)) );
      }
   }




###############################################################################
# Usage      : set_month_to_month_number( SCALAR )
# Purpose    : set the incoming month to month number
# Returns    : numeric month <1-12> if successful
# Parameters : month in one of three formats ( numeric<1-12>, full name or three character abbreviated )
# Throws     : Throws exception for any invalid input
# Comments   : N/A
# See Also   : N/A
###############################################################################
sub set_month_to_month_number
   {
   my (
       $month_in_06,
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_11 = 1;
   ( @_ ==  $num_input_params_11) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly one parameter, a month number or month alpha.   '@_'.\n\n\n";
   ( ref(\$month_in_06) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the month number or month alpha    '$month_in_06'.\n\n\n";
   ( $month_in_06  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the month number or month alpha    '$month_in_06'.\n\n\n";

   if ( !( $month_in_06  =~  m/^(\d{1,2})$/i ) )
      {
      return ( month_name_to_month_number($month_in_06) );
      }
   else
      {
      return ( month_name_to_month_number(month_number_to_month_name($month_in_06)) );
      }
   }




###############################################################################
# Usage      : get_num_days_in_year( SCALAR )
# Purpose    : determine number of days in given year
# Returns    : - '366' if the input is a leap year
#            : - '365' if the input is a NON leap year
# Parameters : (
#            :  year in integer form
#            : )
# Throws     : Throws exception for any invalid input
# Comments   : Handles all years, even negative years (aka BC)
# See Also   : N/A
###############################################################################
sub get_num_days_in_year
   {
   my (
       $year_in_03,
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_04 = 1;
   ( @_ ==  $num_input_params_04) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly one parameter, a year number.   '@_'.\n\n\n";
   ( ref(\$year_in_03) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the year    '$year_in_03'.\n\n\n";
   ( $year_in_03  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the year    '$year_in_03'.\n\n\n";
   ( $year_in_03  =~ m/^\-{0,1}\d+$/ ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a number for the year    '$year_in_03'.\n\n\n";

   if ( is_leap_year($year_in_03) ne '' )
      {
      return ( 366 );
      }
   else
      {
      return ( 365 );
      }
   }




###############################################################################
# Usage      : date1_to_date2_delta( SCALAR, SCALAR )
# Purpose    : finds the difference in days between the two dates by subtracting the second from the first
# Returns    : integer day count if successful
# Parameters : (
#            :   date ONE in any format,
#            :   date 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
# See Also   : N/A
###############################################################################
sub date1_to_date2_delta
   {
   my (
       $date_one_00,
       $date_two_00
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_12 = 2;
   ( @_ ==  $num_input_params_12) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly $num_input_params_12 parameters ('date1' and date2).   '@_'.\n\n\n";

   ( ref(\$date_one_00) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR first parameter for the first date    '$date_one_00'.\n\n\n";
   ( ref(\$date_two_00) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR second parameter for the second date    '$date_two_00'.\n\n\n";

   ( $date_one_00  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the first date    '$date_one_00'.\n\n\n";
   ( $date_two_00  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the second date    '$date_two_00'.\n\n\n";

   ( date_only_parse($date_one_00) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Cannot extract the date from the input date1 string    '$date_one_00'.\n\n\n";
   ( date_only_parse($date_two_00) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Cannot extract the date from the input date2 string    '$date_two_00'.\n\n\n";

   my $date_one_02;
   my $date_two_02;
   my $date_compare_00 = compare_date1_and_date2($date_one_00, $date_two_00);

   if ( ( $date_compare_00  ne  '0' )  &&  ( $date_compare_00  ne  '-1' )  &&  ( $date_compare_00  ne  '1' ) )
      {
      croak "\n\n   ($0)   '${\(caller(0))[3]}' This condition should NOT occur.  date_compare_00 has a value of '$date_compare_00' and only one of '1', '-1' or '0' is expected.\n\n\n";
      }


   if ( $date_compare_00  eq  '0' )
      {
      return ('0');
      }
   if ( $date_compare_00  eq  '-1' )
      {
      $date_one_02 = $date_two_00;
      $date_two_02 = $date_one_00;
      }
   if ( $date_compare_00  eq  '1' )
      {
      $date_one_02 = $date_one_00;
      $date_two_02 = $date_two_00;
      }


   my ( $date1_month_num_02, $date1_day_of_month_02, $date1_year_num_02, $date1_day_of_week_02 ) = date_only_parse($date_one_02);
   my ( $date2_month_num_02, $date2_day_of_month_02, $date2_year_num_02, $date2_day_of_week_02 ) = date_only_parse($date_two_02);


   my $year_phase_date_one_00;
   my $which_400yr_cycle_occurrence_for_date_one_02;
   if ( $date1_year_num_02 >= 0 )
      {
      $which_400yr_cycle_occurrence_for_date_one_02 = int( $date1_year_num_02  /  $NUMBER_OF_YEAR_PHASES );
      $year_phase_date_one_00 = get_year_phase( $date1_year_num_02 );
      }
   else
      {
      $which_400yr_cycle_occurrence_for_date_one_02 = int( ($date1_year_num_02+1)  /  $NUMBER_OF_YEAR_PHASES ) - 1;
      $year_phase_date_one_00 =  $NUMBER_OF_YEAR_PHASES - ( -$date1_year_num_02 % $NUMBER_OF_YEAR_PHASES );
      if ( $year_phase_date_one_00  >=  $NUMBER_OF_YEAR_PHASES )
         {
         $year_phase_date_one_00  -=  $NUMBER_OF_YEAR_PHASES;
         }
      }

   my $year_phase_date_two;
   my $which_400yr_cycle_occurrence_for_date_two_02;
   if ( $date2_year_num_02 >= 0 )
      {
      $which_400yr_cycle_occurrence_for_date_two_02 = int( $date2_year_num_02  /  $NUMBER_OF_YEAR_PHASES );
      $year_phase_date_two = get_year_phase( $date2_year_num_02 );
      }
   else
      {
      $which_400yr_cycle_occurrence_for_date_two_02 = int( ($date2_year_num_02+1)  /  $NUMBER_OF_YEAR_PHASES ) - 1;
      $year_phase_date_two =  $NUMBER_OF_YEAR_PHASES - ( -$date2_year_num_02 % $NUMBER_OF_YEAR_PHASES );
      if ( $year_phase_date_two  >=  $NUMBER_OF_YEAR_PHASES )
         {
         $year_phase_date_two  -=  $NUMBER_OF_YEAR_PHASES;
         }
      }


   my $num_days_in_year1_phases_00 = 0;
   for ( my $iii_005=0; $iii_005<$year_phase_date_one_00; $iii_005++ )
      {
      $num_days_in_year1_phases_00 += get_num_days_in_year( 2000 + $iii_005 );  # sum the days of whole years
      }
   $num_days_in_year1_phases_00 += number_of_day_within_year( $date_one_02 );  # sum the days of the year up to the given day


   my $num_days_in_year2_phases = 0;
   for ( my $iii_006=0; $iii_006<$year_phase_date_two; $iii_006++ )
      {
      $num_days_in_year2_phases += get_num_days_in_year( 2000 + $iii_006 );  # sum the days of whole years
      }
   $num_days_in_year2_phases += number_of_day_within_year( $date_two_02 );  # sum the days of the year up to the given day


   my $date_diff_00 = '';
   if ( $which_400yr_cycle_occurrence_for_date_one_02  ==  $which_400yr_cycle_occurrence_for_date_two_02 )
      {
      $date_diff_00 = $num_days_in_year1_phases_00 - $num_days_in_year2_phases;
      }
   elsif ( $which_400yr_cycle_occurrence_for_date_one_02  ==  ( $which_400yr_cycle_occurrence_for_date_two_02 + 1 ) )
      {
      $date_diff_00 = $num_days_in_year1_phases_00 + ( $NUMBER_OF_DAYS_IN_400_YEAR_CYCLE - $num_days_in_year2_phases );
      }
#   elsif ( $which_400yr_cycle_occurrence_for_date_one_02  >  ( $which_400yr_cycle_occurrence_for_date_two_02 + 1 ) )
   else
      {
      $date_diff_00  = ($which_400yr_cycle_occurrence_for_date_one_02  - ($which_400yr_cycle_occurrence_for_date_two_02 + 1 )) * ( $NUMBER_OF_DAYS_IN_400_YEAR_CYCLE);
      $date_diff_00 += $num_days_in_year1_phases_00 + ( $NUMBER_OF_DAYS_IN_400_YEAR_CYCLE - $num_days_in_year2_phases );
      }


   if ( $date_compare_00  ==  1 )
      {
      return ( $date_diff_00 );
      }
   else
      {
      return ( -$date_diff_00 );
      }
   }




###############################################################################
# Usage      : is_valid_month( SCALAR )
# Purpose    : checks if month is valid
# Returns    : - '1' if month is valid
#            : - ''  otherwise
# Parameters : (
#            :  alpha or month integer<1-12>,
#            : )
# Throws     : No Exceptions
# Comments   : N/A
# See Also   : N/A
###############################################################################
sub is_valid_month
   {
   my (
       $month_input_01,
      )
       = @_;


   # Incoming Inspection
   if ( @_  !=  1 )
      {
      return ( '' );
      }

   if ( ref(\$month_input_01)  ne 'SCALAR' )
      {
      return ( '' );
      }

   if ( $month_input_01  eq  '' )
      {
      return ( '' );
      }


   # Check for expected strings
   if ( !( $month_input_01  =~  m/^(\d{1,2}|Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec|January|February|March|April|May|June|July|August|September|October|November|December)$/i ) )
      {
      return ( '' );
      }


   # Check numeric form of Month of Year for acceptable value
   if ( $month_input_01 =~ m/^(\d{1,2})$/ )
      {
      if ( ( $1 < 1 )  ||  ( $1 > 12 ) )
         {
         return ( '' );
         }
      }

   return ( 1 );
   }




###############################################################################
# Usage      : is_valid_day_of_month( SCALAR, SCALAR, SCALAR )
# Purpose    : checks if day of month is valid
# Returns    : - '1' if day of month is valid
#            : - ''  otherwise
# Parameters : (
#            :  alpha or month integer<1-12>,
#            :  day of month integer<1-N>,
#            :  year integer,
#            : )
# Throws     : No Exceptions
# Comments   : Handles all years, even negative years (aka BC)
# See Also   : N/A
###############################################################################
sub is_valid_day_of_month
   {
   my (
       $month_input_02,
       $day_of_month_input_00,
       $year_input_01,
      )
       = @_;


   # Incoming Inspection
   if ( @_  !=  3 )
      {
      return ( '' );
      }

   if ( ref(\$day_of_month_input_00)  ne 'SCALAR' )
      {
      return ( '' );
      }

   if ( $day_of_month_input_00  eq  '' )
      {
      return ( '' );
      }

   if ( !(is_valid_month($month_input_02)) )
      {
      return ( '' );
      }
   my $month_num_03 = set_month_to_month_number($month_input_02);

   if ( !(is_valid_year($year_input_01)) )
      {
      return ( '' );
      }


   if ( !( ( $day_of_month_input_00 =~ m/^(\d{1,2})$/ )  &&  ( $1 > 0 )  &&  ( $1 < 32 ) ) )
      {
      return ( '' );
      }


   # Check for out of range day_of_month numbers
   # Months with 30 days ( April June September November )
   if ( ( ( $month_num_03 == 4 )  ||  ( $month_num_03 == 6 )  ||  ( $month_num_03 == 9 )  ||  ( $month_num_03 == 11 ) )  &&  ( $day_of_month_input_00 > 30 ) )
      {
      return ( '' );
      }
   # February (NON leap year)
#   elsif ( ( $month_num_03 == 2 )  &&  (!( is_leap_year($year_input_01) ))  &&  ( $day_of_month_input_00  >  28 ) )
   if ( ( $month_num_03 == 2 )  &&  (!( is_leap_year($year_input_01) ))  &&  ( $day_of_month_input_00  >  28 ) )
      {
      return ( '' );
      }
   # February (leap year)
#   elsif ( ( $month_num_03 == 2 )  &&    ( is_leap_year($year_input_01) )   &&  ( $day_of_month_input_00  >  29 ) )
   if ( ( $month_num_03 == 2 )  &&  ( is_leap_year($year_input_01) )   &&  ( $day_of_month_input_00  >  29 ) )
      {
      return ( '' );
      }
   # Months with 31 days
#   elsif ( ( $month_num_03 > 0 )  &&  ( $month_num_03 < 13 )  &&  ( $day_of_month_input_00 > 31 ) )
#      {
#      return ( '' );
#      }


   return ( 1 );
   }




###############################################################################
# Usage      : is_valid_day_of_week( SCALAR )
# Purpose    : checks if day of week is valid
# Returns    : - '1' if day of week is valid
#            : - ''  otherwise
# Parameters : (
#            :  day of week in one of three formats ( numeric<1-7>, full name or three character abbreviated )
#            : )
# Throws     : No Exceptions
# Comments   : <1 for Mon ... 7 for Sun>
# See Also   : N/A
###############################################################################
sub is_valid_day_of_week
   {
   my (
       $day_of_week_input_00,
      )
       = @_;


   # Incoming Inspection
   if ( @_  !=  1 )
      {
      return ( '' );
      }

   if ( ref(\$day_of_week_input_00)  ne 'SCALAR' )
      {
      return ( '' );
      }

   if ( $day_of_week_input_00  eq  '' )
      {
      return ( '' );
      }


   if ( !( $day_of_week_input_00  =~  m/^(\d|Mon|Tue|Wed|Thu|Fri|Sat|Sun|Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday)$/i ) )
      {
      return ( '' );
      }


   # Check numeric form of day of week for valid value
   if ( $day_of_week_input_00 =~ m/^(\d)$/ )
      {
      if (  ( $1 < 1 )  ||  ( $1 > 7 )  )
         {
         return ( '' );
         }
      }

   return ( 1 );
   }




###############################################################################
# Usage      : is_valid_year( SCALAR )
# Purpose    : checks if year is valid
# Returns    : - '1' if year is valid
#            : - ''  otherwise
# Parameters : (
#            :  year in integer format
#            : )
# Throws     : No Exceptions
# Comments   : Handles all years, even negative years (aka BC)
# See Also   : N/A
###############################################################################
sub is_valid_year
   {
   my (
       $year_input_00,
      )
       = @_;


   # Incoming Inspection
   if ( @_  !=  1 )
      {
      return ( '' );
      }

   if ( ref(\$year_input_00)  ne 'SCALAR' )
      {
      return ( '' );
      }

   if ( $year_input_00  eq  '' )
      {
      return ( '' );
      }

   if ( !( $year_input_00  =~  m/^\-{0,1}\d{1,}$/ ) )
      {
      return ( '' );
      }

   return ( 1 );
   }




###############################################################################
# Usage      : is_valid_400_year_cycle( SCALAR )
# Purpose    : checks if year is valid 400 year cycle phase number
# Returns    : - '1' if year is valid 400 year cycle phase number
#            : - ''  otherwise
# Parameters : (
#            :  year in integer format
#            : )
# Throws     : No Exceptions
# Comments   : valid years are multiples of 400 (i.e.  ... -400, 0, 400, ... 1600, 2000, 2400, ...)
# See Also   : N/A
###############################################################################
sub is_valid_400_year_cycle
   {
   my (
       $four_hundred_year_cycle_01,
      )
       = @_;


   # Incoming Inspection
   if ( @_  !=  1 )
      {
      return ( '' );
      }

   if ( ref(\$four_hundred_year_cycle_01)  ne 'SCALAR' )
      {
      return ( '' );
      }

   if ( $four_hundred_year_cycle_01  eq  '' )
      {
      return ( '' );
      }

   if ( !( ( $four_hundred_year_cycle_01  =~  m/^\-{0,1}(\d+)$/ )  &&  ( ( $1 % $NUMBER_OF_YEAR_PHASES )  ==  0 ) ) )
      {
      return ( '' );
      }

   return ( 1 );
   }




###############################################################################
# Usage      : compare_date1_and_date2( SCALAR, SCALAR )
# 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
# Parameters : (
#            :   date ONE in any format,
#            :   date TWO in any format
#            : )
# Throws     : Throws exception for any invalid input
# Comments   : N/A
# See Also   : N/A
###############################################################################
sub compare_date1_and_date2
   {
   my (
       $date_one_01,
       $date_two_01
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_18 = 2;
   ( @_ ==  $num_input_params_18) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly $num_input_params_18 parameter(s), two date strings.   '@_'.\n\n\n";

   ( ref(\$date_one_01) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the first date string    '$date_one_01'.\n\n\n";
   ( $date_one_01  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the first date string    '$date_one_01'.\n\n\n";
   ( date_only_parse($date_one_01) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Cannot parse the date from the first input date string    '$date_one_01'.\n\n\n";

   ( ref(\$date_two_01) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the second date string    '$date_two_01'.\n\n\n";
   ( $date_two_01  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the second date string    '$date_two_01'.\n\n\n";
   ( date_only_parse($date_two_01) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Cannot parse the date from the second input date string    '$date_two_01'.\n\n\n";



   my ( $date1_month_num_03, $date1_day_of_month_03, $date1_year_num_03, $date1_day_of_week_03 ) = date_only_parse($date_one_01);
   my ( $date2_month_num_03, $date2_day_of_month_03, $date2_year_num_03, $date2_day_of_week_03 ) = date_only_parse($date_two_01);


   my $date1_month_num_04 = set_month_to_month_number($date1_month_num_03);
   my $date2_month_num_04 = set_month_to_month_number($date2_month_num_03);

   my $compare_date_1_and_date_2_00 = '';
   if ( $date1_year_num_03  >  $date2_year_num_03 )
      {
      $compare_date_1_and_date_2_00 = '1';
      }
   elsif ( ( $date1_year_num_03  ==  $date2_year_num_03 )  &&  ( $date1_month_num_04  >  $date2_month_num_04 ) )
      {
      $compare_date_1_and_date_2_00 = '1';
      }
   elsif ( ( $date1_year_num_03  ==  $date2_year_num_03 )  &&  ( $date1_month_num_04  ==  $date2_month_num_04 )  &&  ( $date1_day_of_month_03  >  $date2_day_of_month_03 ) )
      {
      $compare_date_1_and_date_2_00 = '1';
      }
   elsif ( ( $date1_year_num_03  ==  $date2_year_num_03 )  &&  ( $date1_month_num_04  ==  $date2_month_num_04 )  &&  ( $date1_day_of_month_03  ==  $date2_day_of_month_03 ) )
      {
      $compare_date_1_and_date_2_00 = '0';
      }
   else
      {
      $compare_date_1_and_date_2_00 = '-1';
      }

   return ( $compare_date_1_and_date_2_00 );
   }




###############################################################################
# Usage      : date_offset_in_days( SCALAR, SCALAR )
# 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 if successful
# Parameters : (
#            :   date in any format,
#            :   number of days offset, positive is future date, negative is past date, zero is current date (no offset)
#            : )
# Throws     : Throws exception for any invalid input
# Comments   : N/A
# See Also   : N/A
###############################################################################
sub date_offset_in_days
   {
   my (
       $date_in_01,
       $date_delta_00
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_19 = 2;
   ( @_ ==  $num_input_params_19) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly $num_input_params_19 parameter(s), a date string followed by the number of offset days.   '@_'.\n\n\n";

   ( ref(\$date_in_01) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the date string    '$date_in_01'.\n\n\n";
   ( $date_in_01  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the date string    '$date_in_01'.\n\n\n";
   ( date_only_parse($date_in_01) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Cannot parse the date from the input date string    '$date_in_01'.\n\n\n";

   ( ref(\$date_delta_00) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the number of offset days    '$date_delta_00'.\n\n\n";
   ( $date_delta_00  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty value for the number of offset days    '$date_delta_00'.\n\n\n";
   ( $date_delta_00  =~ m/^\-{0,1}\d+$/ ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects an integer value, positive, negative or zero, for the number of offset days    '$date_delta_00'.\n\n\n";


   if ( $date_delta_00  ==  0 )
      {
      return ( format_date( $date_in_01 ) );
      }


   my ( $date1_month_num_05, $date1_day_of_month_05, $date1_year_num_05, $date1_day_of_week_05 ) = date_only_parse($date_in_01);

   # Total the number of 400 year cycles included in the offset day count
   my $number_of_complete_year_cycles_00 = int( abs($date_delta_00) / $NUMBER_OF_DAYS_IN_400_YEAR_CYCLE );

   # Day offset by multiples of COMPLETE four hundred year cycles
   my $offset_year_00;
   if (  $date_delta_00  >=  0  )
      {
      $offset_year_00 = $date1_year_num_05 + ( $number_of_complete_year_cycles_00 * $NUMBER_OF_YEAR_PHASES );
      }
   else
      {
      $offset_year_00 = $date1_year_num_05 - ( $number_of_complete_year_cycles_00 * $NUMBER_OF_YEAR_PHASES );
      }
   my $offset_month_00        = $date1_month_num_05;
   my $offset_day_of_month_00 = $date1_day_of_month_05;

   my $days_left_00;
   my $days_left_in_offset_400_year_cycle = get_days_remaining_in_400yr_cycle( $date1_month_num_05, $date1_day_of_month_05, $offset_year_00 );
   my $days_used_in_offset_400_year_cycle = get_number_of_day_within_400yr_cycle( $date1_month_num_05, $date1_day_of_month_05, $offset_year_00 );
   my $day_num_in_400_year_cycle_01;
   if (  $date_delta_00  >=  0  )
      {
      $days_left_00 = int( $date_delta_00 % $NUMBER_OF_DAYS_IN_400_YEAR_CYCLE );


      if ( $days_left_in_offset_400_year_cycle  >=  $days_left_00 )
         {
         $day_num_in_400_year_cycle_01 = $days_used_in_offset_400_year_cycle + $days_left_00;
         }
      else
         {
         $day_num_in_400_year_cycle_01 = $days_left_00 - $days_left_in_offset_400_year_cycle;
         $offset_year_00 += $NUMBER_OF_YEAR_PHASES;
         }
      }
   else
      {
      $days_left_00 = int( abs($date_delta_00) % $NUMBER_OF_DAYS_IN_400_YEAR_CYCLE );


      if ( $days_used_in_offset_400_year_cycle  >  $days_left_00 )
         {
         $day_num_in_400_year_cycle_01 = $days_used_in_offset_400_year_cycle - $days_left_00;
         }
      else
         {
         $day_num_in_400_year_cycle_01 = $NUMBER_OF_DAYS_IN_400_YEAR_CYCLE - ($days_left_00 - $days_used_in_offset_400_year_cycle);
         $offset_year_00 -= $NUMBER_OF_YEAR_PHASES;
         }
      }

   my $which_400_year_cycle_00 = get_global_year_cycle($offset_year_00);

   $day_num_in_400_year_cycle_01 = day_number_within_400_year_cycle_to_date( $which_400_year_cycle_00, $day_num_in_400_year_cycle_01 );

   return ( format_date( $day_num_in_400_year_cycle_01 ) );
   }




###############################################################################
# Usage      : get_global_year_cycle( SCALAR )
# Purpose    : get the phase zero year for the given year
# Returns    : - the phase zero year containing the given year if input is valid
# Parameters : (
#            :  year in integer format
#            : )
# 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
#            :        years 1600 through 1999 return the phase zero year 1600
#            :        year 2007  returns the phase zero year 2000
# See Also   : N/A
###############################################################################
sub get_global_year_cycle
   {
   my (
       $year_input_08
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_20 = 1;
   ( @_ ==  $num_input_params_20) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly $num_input_params_20 parameter(s), a date string followed by the number of offset days.   '@_'.\n\n\n";

   ( ref(\$year_input_08) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the year number    '$year_input_08'.\n\n\n";
   ( $year_input_08  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty value for the year number    '$year_input_08'.\n\n\n";
   ( is_valid_year($year_input_08) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects an integer value, positive, negative or zero, for the year number    '$year_input_08'.\n\n\n";


  my $which_400_year_cycle_01;
  if (  $year_input_08  >=  0  )
     {
     $which_400_year_cycle_01 = int( $year_input_08 / $NUMBER_OF_YEAR_PHASES ) * $NUMBER_OF_YEAR_PHASES;
     }
  else
     {
     if ( ( abs($year_input_08) % $NUMBER_OF_YEAR_PHASES )  ==  0 )
        {
        $which_400_year_cycle_01 = int( $year_input_08 / $NUMBER_OF_YEAR_PHASES ) * $NUMBER_OF_YEAR_PHASES;
        }
     else
        {
        $which_400_year_cycle_01 = int( $year_input_08 / $NUMBER_OF_YEAR_PHASES ) * $NUMBER_OF_YEAR_PHASES - $NUMBER_OF_YEAR_PHASES;
        }
     }

   return ( $which_400_year_cycle_01 );
   }




###############################################################################
# Usage      : get_number_of_days_in_month( SCALAR, SCALAR )
# Purpose    : get the number of days in a specific month
# Returns    : - number of days in the month if successful
# Parameters : (
#            :  alpha or month integer<1-12>,
#            :  year integer,
#            : )
# Throws     : Throws exception for any invalid input
# Comments   : Handles all years, even negative years (aka BC)
# See Also   : N/A
###############################################################################
sub get_number_of_days_in_month
   {
   my (
       $month_input_04,
       $year_input_02,
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_21 = 2;
   ( @_ ==  $num_input_params_21) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly $num_input_params_21 parameter(s), (month, year).   '@_'.\n\n\n";

   ( ref(\$month_input_04) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the month    '$month_input_04'.\n\n\n";
   ( $month_input_04  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty value for the month    '$month_input_04'.\n\n\n";
   ( is_valid_month($month_input_04) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a valid month    '$month_input_04'.\n\n\n";

   ( ref(\$year_input_02) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the year number    '$year_input_02'.\n\n\n";
   ( $year_input_02  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty value for the year number    '$year_input_02'.\n\n\n";
   ( is_valid_year($year_input_02) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects an integer value, positive, negative or zero, for the year number    '$year_input_02'.\n\n\n";


   my $month_num_06 = set_month_to_month_number($month_input_04);

   # Months with 30 days ( April June September November )
   if ( ( $month_num_06 == 4 )  ||  ( $month_num_06 == 6 )  ||  ( $month_num_06 == 9 )  ||  ( $month_num_06 == 11 ) )
      {
      return ( 30 );
      }
   # February (NON leap year)
   elsif ( ( $month_num_06 == 2 )  &&  (!( is_leap_year($year_input_02) ) )   )
      {
      return ( 28 );
      }
   # February (leap year)
#   elsif ( ( $month_num_06 == 2 )  &&    ( is_leap_year($year_input_02) ) )
   elsif ( $month_num_06 == 2 )
      {
      return ( 29 );
      }
   # Months with 31 days
   else
      {
      return ( 31 );
      }

   }




###############################################################################
# Usage      : get_days_remaining_in_month( SCALAR, SCALAR, SCALAR )
# Purpose    : find out how many days are remaining in the month from the given date
# Returns    : number of days left if successful
# Parameters : (
#            :  alpha or month integer<1-12>,
#            :  day of month integer<1-N>,
#            :  year integer,
#            : )
# 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
# See Also   : N/A
###############################################################################
sub get_days_remaining_in_month
   {
   my (
       $month_input_05,
       $day_of_month_input_01,
       $year_input_03,
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_22 = 3;
   ( @_ ==  $num_input_params_22) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly $num_input_params_22 parameter(s), (month, day_of_month, year).   '@_'.\n\n\n";


   ( ref(\$month_input_05) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the month    '$month_input_05'.\n\n\n";
   ( $month_input_05  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty value for the month    '$month_input_05'.\n\n\n";
   ( is_valid_month($month_input_05) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a valid month    '$month_input_05'.\n\n\n";

   ( ref(\$year_input_03) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the year number    '$year_input_03'.\n\n\n";
   ( $year_input_03  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty value for the year number    '$year_input_03'.\n\n\n";
   ( is_valid_year($year_input_03) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects an integer value, positive, negative or zero, for the year number    '$year_input_03'.\n\n\n";

   ( ref(\$day_of_month_input_01) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the day of month    '$day_of_month_input_01'.\n\n\n";
   ( $day_of_month_input_01  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty value for the day of month    '$day_of_month_input_01'.\n\n\n";
   ( is_valid_day_of_month($month_input_05, $day_of_month_input_01, $year_input_03) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects an integer value for the day of month (1-31)    '$day_of_month_input_01'.\n\n\n";


   my $month_num_07 = set_month_to_month_number($month_input_05);

   # Months with 30 days ( April June September November )
   if ( ( $month_num_07 == 4 )  ||  ( $month_num_07 == 6 )  ||  ( $month_num_07 == 9 )  ||  ( $month_num_07 == 11 ) )
      {
      return ( 30 - $day_of_month_input_01 );
      }
   # February (NON leap year)
   elsif ( ( $month_num_07 == 2 )  &&  (!( is_leap_year($year_input_03) ) )   )
      {
      return ( 28 - $day_of_month_input_01 );
      }
   # February (leap year)
#   elsif ( ( $month_num_07 == 2 )  &&    ( is_leap_year($year_input_03) ) )
   elsif ( $month_num_07 == 2 )
      {
      return ( 29 - $day_of_month_input_01 );
      }
   # Months with 31 days
   else
      {
      return ( 31 - $day_of_month_input_01 );
      }

   }




###############################################################################
# Usage      : get_days_remaining_in_year( SCALAR, SCALAR, SCALAR )
# Purpose    : find out how many days are remaining in the year from the given date
# Returns    : number of days left if successful
# Parameters : (
#            :  alpha or month integer<1-12>,
#            :  day of month integer<1-N>,
#            :  year integer,
#            : )
# 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
# See Also   : N/A
###############################################################################
sub get_days_remaining_in_year
   {
   my (
       $month_input_06,
       $day_of_month_input_02,
       $year_input_04,
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_23 = 3;
   ( @_ ==  $num_input_params_23) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly $num_input_params_23 parameter(s), (month, day_of_month, year).   '@_'.\n\n\n";


   ( ref(\$month_input_06) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the month    '$month_input_06'.\n\n\n";
   ( $month_input_06  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty value for the month    '$month_input_06'.\n\n\n";
   ( is_valid_month($month_input_06) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a valid month    '$month_input_06'.\n\n\n";

   ( ref(\$year_input_04) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the year number    '$year_input_04'.\n\n\n";
   ( $year_input_04  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty value for the year number    '$year_input_04'.\n\n\n";
   ( is_valid_year($year_input_04) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects an integer value, positive, negative or zero, for the year number    '$year_input_04'.\n\n\n";

   ( ref(\$day_of_month_input_02) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the day of month    '$day_of_month_input_02'.\n\n\n";
   ( $day_of_month_input_02  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty value for the day of month    '$day_of_month_input_02'.\n\n\n";
   ( is_valid_day_of_month($month_input_06, $day_of_month_input_02, $year_input_04) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects an integer value for the day of month (1-31)    '$day_of_month_input_02'.\n\n\n";


   my $month_num_08 = set_month_to_month_number($month_input_06);

   return ( get_num_days_in_year( $year_input_04 ) - number_of_day_within_year( "${month_num_08}/${day_of_month_input_02}/${year_input_04}" ) );
   }




###############################################################################
# Usage      : get_number_of_day_within_400yr_cycle( SCALAR, SCALAR, SCALAR )
# Purpose    : find the number of the day within the standard 400 year cycle
# Returns    : day number if successful
# Parameters : (
#            :  alpha or month integer<1-12>,
#            :  day of month integer<1-N>,
#            :  year integer,
#            : )
# 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'
# See Also   : N/A
###############################################################################
sub get_number_of_day_within_400yr_cycle
   {
   my (
       $month_input_07,
       $day_of_month_input_03,
       $year_input_05,
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_24 = 3;
   ( @_ ==  $num_input_params_24) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly $num_input_params_24 parameter(s), (month, day_of_month, year).   '@_'.\n\n\n";


   ( ref(\$month_input_07) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the month    '$month_input_07'.\n\n\n";
   ( $month_input_07  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty value for the month    '$month_input_07'.\n\n\n";
   ( is_valid_month($month_input_07) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a valid month    '$month_input_07'.\n\n\n";

   ( ref(\$year_input_05) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the year number    '$year_input_05'.\n\n\n";
   ( $year_input_05  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty value for the year number    '$year_input_05'.\n\n\n";
   ( is_valid_year($year_input_05) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects an integer value, positive, negative or zero, for the year number    '$year_input_05'.\n\n\n";

   ( ref(\$day_of_month_input_03) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the day of month    '$day_of_month_input_03'.\n\n\n";
   ( $day_of_month_input_03  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty value for the day of month    '$day_of_month_input_03'.\n\n\n";
   ( is_valid_day_of_month($month_input_07, $day_of_month_input_03, $year_input_05) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects an integer value for the day of month (1-31)    '$day_of_month_input_03'.\n\n\n";


   my $month_num_09 = set_month_to_month_number($month_input_07);

   my $year_phase_01 = get_year_phase($year_input_05);
   my $day_num_in_400_year_cycle_00 = 0;
   my $iii_000 = 0;
   for ( $iii_000=0; $iii_000<$year_phase_01; $iii_000++ )
      {
      $day_num_in_400_year_cycle_00 += get_num_days_in_year($iii_000);
      }
   $day_num_in_400_year_cycle_00 += number_of_day_within_year( "${month_num_09}/${day_of_month_input_03}/${iii_000}" );

   return ( $day_num_in_400_year_cycle_00 );

   }




###############################################################################
# Usage      : get_days_remaining_in_400yr_cycle( SCALAR, SCALAR, SCALAR )
# Purpose    : find the number of days remaining from the given date to the end of the current standard 400 year cycle
# Returns    : number of days left if successful
# Parameters : (
#            :  alpha or month integer<1-12>,
#            :  day of month integer<1-N>,
#            :  year integer,
#            : )
# 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.
# See Also   : N/A
###############################################################################
sub get_days_remaining_in_400yr_cycle
   {
   my (
       $month_input_08,
       $day_of_month_input_04,
       $year_input_06,
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_25 = 3;
   ( @_ ==  $num_input_params_25) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly $num_input_params_25 parameter(s), (month, day_of_month, year).   '@_'.\n\n\n";


   ( ref(\$month_input_08) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the month    '$month_input_08'.\n\n\n";
   ( $month_input_08  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty value for the month    '$month_input_08'.\n\n\n";
   ( is_valid_month($month_input_08) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a valid month    '$month_input_08'.\n\n\n";

   ( ref(\$year_input_06) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the year number    '$year_input_06'.\n\n\n";
   ( $year_input_06  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty value for the year number    '$year_input_06'.\n\n\n";
   ( is_valid_year($year_input_06) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects an integer value, positive, negative or zero, for the year number    '$year_input_06'.\n\n\n";

   ( ref(\$day_of_month_input_04) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the day of month    '$day_of_month_input_04'.\n\n\n";
   ( $day_of_month_input_04  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty value for the day of month    '$day_of_month_input_04'.\n\n\n";
   ( is_valid_day_of_month($month_input_08, $day_of_month_input_04, $year_input_06) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects an integer value for the day of month (1-31)    '$day_of_month_input_04'.\n\n\n";


   my $month_num_10 = set_month_to_month_number($month_input_08);

   return ( $NUMBER_OF_DAYS_IN_400_YEAR_CYCLE - get_number_of_day_within_400yr_cycle( $month_num_10, $day_of_month_input_04, $year_input_06 ) );
   }




###############################################################################
# Usage      : day_number_within_year_to_date( SCALAR, SCALAR )
# Purpose    : converts the number of the day within the year to a date
# Returns    : date if successful
# Parameters : (
#            :  year integer,
#            :  number of day in year <1-365/6>,
#            : )
# Throws     : Throws exception for any invalid input
# Comments   : Handles all years, even negative years (aka BC)
# See Also   : N/A
###############################################################################
sub day_number_within_year_to_date
   {
   my (
       $year_input_07,
       $day_number_in_year_00,
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_26 = 2;
   ( @_ ==  $num_input_params_26) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly $num_input_params_26 parameter(s), (month, day_of_month, year).   '@_'.\n\n\n";

   ( ref(\$year_input_07) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the year number    '$year_input_07'.\n\n\n";
   ( $year_input_07  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty value for the year number    '$year_input_07'.\n\n\n";
   ( is_valid_year($year_input_07) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects an integer value, positive, negative or zero, for the year number    '$year_input_07'.\n\n\n";

   ( ref(\$day_number_in_year_00) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the day number within the year    '$day_number_in_year_00'.\n\n\n";
   ( $day_number_in_year_00  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty value for the day number within the year    '$day_number_in_year_00'.\n\n\n";


   if ( !(is_leap_year($year_input_07)) )
      {
      ( ( $day_number_in_year_00 =~ m/^(\d{1,3})$/ )  &&  ( $1 > 0 )  &&  ( $1 < 366 ) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' The number of the day within a NON leap must be in the range of 1-365    '$day_number_in_year_00'.\n\n\n";
      }
   else
      {
      ( ( $day_number_in_year_00 =~ m/^(\d{1,3})$/ )  &&  ( $1 > 0 )  &&  ( $1 < 367 ) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' The number of the day within a LEAP must be in the range of 1-366    '$day_number_in_year_00'.\n\n\n";
      }


   my $date_from_num_00;

   if ( $day_number_in_year_00 < 32 )
      {
      $date_from_num_00 = "1/" . $day_number_in_year_00 . "/$year_input_07";
      }
   elsif ( !( is_leap_year($year_input_07) ) )
      {
      foreach ($day_number_in_year_00)
         {
         SWITCH:
            {
            if ( $_ <  60 )    { $date_from_num_00 =  "2/" . ($_ -  31) . "/$year_input_07"; last SWITCH; } #      if    ( $_ < (31 + 29) )
            if ( $_ <  91 )    { $date_from_num_00 =  "3/" . ($_ -  59) . "/$year_input_07"; last SWITCH; } #      elsif ( $_ < (31 + 28 + 32) )                                                      $date_from_num_00 = "3/" . ($_ - (31 + 28)) . "/$year_input_07";
            if ( $_ < 121 )    { $date_from_num_00 =  "4/" . ($_ -  90) . "/$year_input_07"; last SWITCH; } #      elsif ( $_ < (31 + 28 + 31 + 31) )                                                 $date_from_num_00 = "4/" . ($_ - (31 + 28 + 31)) . "/$year_input_07";
            if ( $_ < 152 )    { $date_from_num_00 =  "5/" . ($_ - 120) . "/$year_input_07"; last SWITCH; } #      elsif ( $_ < (31 + 28 + 31 + 30 + 32) )                                            $date_from_num_00 = "5/" . ($_ - (31 + 28 + 31 + 30)) . "/$year_input_07";
            if ( $_ < 182 )    { $date_from_num_00 =  "6/" . ($_ - 151) . "/$year_input_07"; last SWITCH; } #      elsif ( $_ < (31 + 28 + 31 + 30 + 31 + 31) )                                       $date_from_num_00 = "6/" . ($_ - (31 + 28 + 31 + 30 + 31)) . "/$year_input_07";
            if ( $_ < 213 )    { $date_from_num_00 =  "7/" . ($_ - 181) . "/$year_input_07"; last SWITCH; } #      elsif ( $_ < (31 + 28 + 31 + 30 + 31 + 30 + 32) )                                  $date_from_num_00 = "7/" . ($_ - (31 + 28 + 31 + 30 + 31 + 30)) . "/$year_input_07";
            if ( $_ < 244 )    { $date_from_num_00 =  "8/" . ($_ - 212) . "/$year_input_07"; last SWITCH; } #      elsif ( $_ < (31 + 28 + 31 + 30 + 31 + 30 + 31 + 32) )                             $date_from_num_00 = "8/" . ($_ - (31 + 28 + 31 + 30 + 31 + 30 + 31)) . "/$year_input_07";
            if ( $_ < 274 )    { $date_from_num_00 =  "9/" . ($_ - 243) . "/$year_input_07"; last SWITCH; } #      elsif ( $_ < (31 + 28 + 31 + 30 + 31 + 30 + 31 + 31 + 31) )                        $date_from_num_00 = "9/" . ($_ - (31 + 28 + 31 + 30 + 31 + 30 + 31 + 31)) . "/$year_input_07";
            if ( $_ < 305 )    { $date_from_num_00 = "10/" . ($_ - 273) . "/$year_input_07"; last SWITCH; } #      elsif ( $_ < (31 + 28 + 31 + 30 + 31 + 30 + 31 + 31 + 30 + 32) )                   $date_from_num_00 = "10/" . ($_ - (31 + 28 + 31 + 30 + 31 + 30 + 31 + 31 + 30)) . "/$year_input_07";
            if ( $_ < 335 )    { $date_from_num_00 = "11/" . ($_ - 304) . "/$year_input_07"; last SWITCH; } #      elsif ( $_ < (31 + 28 + 31 + 30 + 31 + 30 + 31 + 31 + 30 + 31 + 31) )              $date_from_num_00 = "11/" . ($_ - (31 + 28 + 31 + 30 + 31 + 30 + 31 + 31 + 30 + 31)) . "/$year_input_07";
                                 $date_from_num_00 = "12/" . ($_ - 334) . "/$year_input_07";                #                                                                                         $date_from_num_00 = "12/" . ($_ - (31 + 28 + 31 + 30 + 31 + 30 + 31 + 31 + 30 + 31 + 30)) . "/$year_input_07";
            }
         }
      }
   else
      {
      foreach ($day_number_in_year_00)
         {
         SWITCH:
            {
            if ( $_ <  61 )    { $date_from_num_00 =  "2/" . ($_ -  31) . "/$year_input_07"; last SWITCH; } #   if    ( $_ < (31 + 30) )
            if ( $_ <  92 )    { $date_from_num_00 =  "3/" . ($_ -  60) . "/$year_input_07"; last SWITCH; } #   elsif ( $_ < (31 + 29 + 32) )                                              $date_from_num_00 = "3/" . ($_ - (31 + 29)) . "/$year_input_07";
            if ( $_ < 122 )    { $date_from_num_00 =  "4/" . ($_ -  91) . "/$year_input_07"; last SWITCH; } #   elsif ( $_ < (31 + 29 + 31 + 31) )                                         $date_from_num_00 = "4/" . ($_ - (31 + 29 + 31)) . "/$year_input_07";
            if ( $_ < 153 )    { $date_from_num_00 =  "5/" . ($_ - 121) . "/$year_input_07"; last SWITCH; } #   elsif ( $_ < (31 + 29 + 31 + 30 + 32) )                                    $date_from_num_00 = "5/" . ($_ - (31 + 29 + 31 + 30)) . "/$year_input_07";
            if ( $_ < 183 )    { $date_from_num_00 =  "6/" . ($_ - 152) . "/$year_input_07"; last SWITCH; } #   elsif ( $_ < (31 + 29 + 31 + 30 + 31 + 31) )                               $date_from_num_00 = "6/" . ($_ - (31 + 29 + 31 + 30 + 31)) . "/$year_input_07";
            if ( $_ < 214 )    { $date_from_num_00 =  "7/" . ($_ - 182) . "/$year_input_07"; last SWITCH; } #   elsif ( $_ < (31 + 29 + 31 + 30 + 31 + 30 + 32) )                          $date_from_num_00 = "7/" . ($_ - (31 + 29 + 31 + 30 + 31 + 30)) . "/$year_input_07";
            if ( $_ < 245 )    { $date_from_num_00 =  "8/" . ($_ - 213) . "/$year_input_07"; last SWITCH; } #   elsif ( $_ < (31 + 29 + 31 + 30 + 31 + 30 + 31 + 32) )                     $date_from_num_00 = "8/" . ($_ - (31 + 29 + 31 + 30 + 31 + 30 + 31)) . "/$year_input_07";
            if ( $_ < 275 )    { $date_from_num_00 =  "9/" . ($_ - 244) . "/$year_input_07"; last SWITCH; } #   elsif ( $_ < (31 + 29 + 31 + 30 + 31 + 30 + 31 + 31 + 31) )                $date_from_num_00 = "9/" . ($_ - (31 + 29 + 31 + 30 + 31 + 30 + 31 + 31)) . "/$year_input_07";
            if ( $_ < 306 )    { $date_from_num_00 = "10/" . ($_ - 274) . "/$year_input_07"; last SWITCH; } #   elsif ( $_ < (31 + 29 + 31 + 30 + 31 + 30 + 31 + 31 + 30 + 32) )           $date_from_num_00 = "10/" . ($_ - (31 + 29 + 31 + 30 + 31 + 30 + 31 + 31 + 30)) . "/$year_input_07";
            if ( $_ < 336 )    { $date_from_num_00 = "11/" . ($_ - 305) . "/$year_input_07"; last SWITCH; } #   elsif ( $_ < (31 + 29 + 31 + 30 + 31 + 30 + 31 + 31 + 30 + 31 + 31) )      $date_from_num_00 = "11/" . ($_ - (31 + 29 + 31 + 30 + 31 + 30 + 31 + 31 + 30 + 31)) . "/$year_input_07";
                                 $date_from_num_00 = "12/" . ($_ - 335) . "/$year_input_07";                #                                                                              $date_from_num_00 = "12/" . ($_ - (31 + 29 + 31 + 30 + 31 + 30 + 31 + 31 + 30 + 31 + 30)) . "/$year_input_07";
            }
         }
      }

   return ( format_date( $date_from_num_00 ) );
   }




###############################################################################
# Usage      : day_number_within_400_year_cycle_to_date( SCALAR, SCALAR )
# Purpose    : converts the number of the day within the standard 400 year cycle to a date
# Returns    : date if successful
# Parameters : (
#            :  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'
# See Also   : N/A
###############################################################################
sub day_number_within_400_year_cycle_to_date
   {
   my (
       $four_hundred_year_cycle_00,
       $day_number_in_400_year_cycle_00,
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_27 = 2;
   ( @_ ==  $num_input_params_27) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly $num_input_params_27 parameter(s), (400 year cycle<-400,0,400,...,2000>, day number within 400 year cycle<1 - 146097> ).   '@_'.\n\n\n";

   ( ref(\$four_hundred_year_cycle_00) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the 400 year cycle<-400,0,400,...,2000>, day number within 400 year cycle<1 - 146097>    '$four_hundred_year_cycle_00'.\n\n\n";
   ( $four_hundred_year_cycle_00  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty value for the 400 year cycle<-400,0,400,...,2000>, day number within 400 year cycle<1 - 146097>    '$four_hundred_year_cycle_00'.\n\n\n";
   ( is_valid_400_year_cycle($four_hundred_year_cycle_00) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects an integer value, positive, negative or zero, for the 400 year cycle<-400,0,400,...,2000>, day number within 400 year cycle<1 - 146097>    '$four_hundred_year_cycle_00'.\n\n\n";

   ( ref(\$day_number_in_400_year_cycle_00) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the day number within the 400 year cycle    '$day_number_in_400_year_cycle_00'.\n\n\n";
   ( $day_number_in_400_year_cycle_00  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty value for the day number within the 400 year cycle    '$day_number_in_400_year_cycle_00'.\n\n\n";
   ( ( $day_number_in_400_year_cycle_00 =~ m/^(\d{1,6})$/ )  &&  ( $1 > 0 )  &&  ( $1 <= $NUMBER_OF_DAYS_IN_400_YEAR_CYCLE ) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects an integer (1 - 146097) for the day number within the 400 year cycle    '$day_number_in_400_year_cycle_00'.\n\n\n";


   my $current_day_count_00 = $day_number_in_400_year_cycle_00;
   my $iii_002;
   for ( $iii_002=0; $iii_002<$NUMBER_OF_YEAR_PHASES; $iii_002++ )
      {
      my $days_in_this_year_00 = get_num_days_in_year($iii_002);
      if ( $current_day_count_00  >  $days_in_this_year_00 )
         {
         $current_day_count_00 -= $days_in_this_year_00;
         }
      else
         {
         last;
         }
      }

   my ( $month_num_11, $day_of_month_11, $year_num_11, $day_of_week_11 ) = date_only_parse(day_number_within_year_to_date($iii_002, $current_day_count_00));
   $year_num_11 += $four_hundred_year_cycle_00;

   my $date_from_num_01 = "${month_num_11}/${day_of_month_11}/${year_num_11}";

   return ( format_date( $date_from_num_01 ) );
   }




###############################################################################
# Usage      : Function is overloaded to accept EITHER a date string OR a date
#            : component.
#            :    1) Date string,
#            :       format_date( SCALAR,  )
#            :    2) Month, dayofmonth, year,
#            :       format_date( SCALAR, SCALAR, SCALAR,  )
# Purpose    : Formats dates
# Returns    : date string if successful
# Parameters : 1) ( date string in any format,  )
#            :           OR
#            : 2) ( month, day of month, year,  )
# 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
#            :     ->  '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'
# See Also   : N/A
###############################################################################
sub format_date
   {


   # Incoming Inspection
   ( ( @_ >  0 )  &&  ( @_ <  5 ) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}'  Should have a date string and an optional format field, or a list of month,dayofmonth,year and an optional format field.   '@_'.\n\n\n";


   my $format_selection_00 = '';
   my ($mmonth_00, $dday_00, $yyear_00, $day_of_week_04);
   # Parsing date string with optional format selection
   if (( @_ ==  1 )  ||  ( @_ ==  2 ) )
      {
      ( ref(\$_[0]) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the date string.    '$_[0]'.\n\n\n";
      ( $_[0]  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the date string    '$_[0]'.\n\n\n";
      ( date_only_parse($_[0]) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' date string, '$_[0]', cannot be parsed.\n\n\n";
      my $date_in_02;
      if ( @_ ==  1 )
         {
         $date_in_02 = $_[0];
         }
      else
         {
         ( ref(\$_[1]) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the desired date format.    '$_[1]'.\n\n\n";
         ( $_[1]  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the desired date format    '$_[1]'.\n\n\n";
         ( $date_in_02, $format_selection_00 ) = @_;
         }
      ($mmonth_00, $dday_00, $yyear_00, $day_of_week_04) = date_only_parse($date_in_02);
      }
   # Individual date components with optional format selection
   else
      {
      ( ref(\$_[0]) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the month    '$_[0]'.\n\n\n";
      ( $_[0]  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty value for the month    '$_[0]'.\n\n\n";
      ( is_valid_month($_[0]) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a valid month    '$_[0]'.\n\n\n";

      ( ref(\$_[2]) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the year number    '$_[2]'.\n\n\n";
      ( $_[2]  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty value for the year number    '$_[2]'.\n\n\n";
      ( is_valid_year($_[2]) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects an integer value, positive, negative or zero, for the year number    '$_[2]'.\n\n\n";

      ( ref(\$_[1]) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the day of month    '$_[1]'.\n\n\n";
      ( $_[1]  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty value for the day of month    '$_[1]'.\n\n\n";
      ( is_valid_day_of_month($_[0], $_[1], $_[2]) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects an integer value for the day of month (1-31)    '$_[1]'.\n\n\n";

      ($mmonth_00, $dday_00, $yyear_00 ) = ( $_[0], $_[1], $_[2] );
      $day_of_week_04 = get_numeric_day_of_week( $mmonth_00, $dday_00, $yyear_00 );
      if ( @_ ==  4 )
         {
         ( ref(\$_[3]) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the desired date format.    '$_[3]'.\n\n\n";
         ( $_[3]  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the desired date format    '$_[3]'.\n\n\n";
         $format_selection_00 = $_[3];
         }
      }

   $mmonth_00 = set_month_to_month_number($mmonth_00);

   my $formatted_date_00;
# '12/30/1999'
   if ( uc($format_selection_00) eq '' ) # default format
      {
      $formatted_date_00 = sprintf "%02d/%02d/%d",  $mmonth_00, $dday_00, $yyear_00;
      }
# 'Sun Feb 29 12:00:00 1604'
   elsif ( uc($format_selection_00) eq 'A' )
      {
      my $day_of_week_abbreviated_00 = set_day_to_day_name_abbrev( $day_of_week_04 );
      my $month_abbreviated_00 = set_month_to_month_name_abbrev( $mmonth_00 );
      $formatted_date_00 = sprintf "%3s %3s %2d 12:00:00 %d", $day_of_week_abbreviated_00, $month_abbreviated_00, $dday_00, $yyear_00;
      }
# 'September 17, 2007'
   elsif ( uc($format_selection_00) eq 'B' )
      {
      my $month_12       = set_month_to_month_name_full( $mmonth_00 );
      $formatted_date_00 = sprintf "%3s %01d, %d", $month_12, $dday_00, $yyear_00;
      }
# '17 September, 2007'
   elsif ( uc($format_selection_00) eq 'C' )
      {
      my $month_14       = set_month_to_month_name_full( $mmonth_00 );
      $formatted_date_00 = sprintf "%01d %3s, %d", $dday_00, $month_14, $yyear_00;
      }
# 'YYYY-MM-DD' (ex: 2007-09-01 )
   elsif ( uc($format_selection_00) eq 'D' )
      {
      my $month_15       = set_month_to_month_number( $mmonth_00 );
      $formatted_date_00 = sprintf "%d-%02d-%02d", $yyear_00, $month_15, $dday_00;
      }
   else
      {
      croak "\n\n   ($0)   '${\(caller(0))[3]}' This date format selection, '$format_selection_00', is not recognized.  Refer to documentation for allowable options.\n\n\n";
      }

   return ($formatted_date_00);
   }




###############################################################################
# Usage      : get_first_of_month_day_of_week( SCALAR, SCALAR )
# Purpose    : get the day of the week for the first of the month for a specified month/year combination
# Returns    : - day of the week (1-7) if successful
# Parameters : (
#            :  alpha or month integer<1-12>,
#            :  year integer,
#            : )
# Throws     : Throws exception for any invalid input
# Comments   : - Handles all years, even negative years (aka BC)
#            : - <1 for Mon ... 7 for Sun>
# See Also   : N/A
###############################################################################
sub get_first_of_month_day_of_week
   {
   my (
       $month_input_09,
       $year_in_05,
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_28 = 2;
   ( @_ ==  $num_input_params_28) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly $num_input_params_28 parameter(s), (month, year).   '@_'.\n\n\n";

   ( ref(\$month_input_09) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the month    '$month_input_09'.\n\n\n";
   ( $month_input_09  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty value for the month    '$month_input_09'.\n\n\n";
   ( is_valid_month($month_input_09) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a valid month    '$month_input_09'.\n\n\n";

   ( ref(\$year_in_05) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the year number    '$year_in_05'.\n\n\n";
   ( $year_in_05  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty value for the year number    '$year_in_05'.\n\n\n";
   ( is_valid_year($year_in_05) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects an integer value, positive, negative or zero, for the year number    '$year_in_05'.\n\n\n";


   my $month_num_12 = set_month_to_month_number($month_input_09);
   my $year_phase_02 = get_year_phase( $year_in_05 );
   my $first_of_month_day_of_week_00 = set_day_to_day_number($DAY_OF_WEEK_ON_FIRST_OF_YEAR{$year_phase_02});
   if ( !(is_leap_year($year_in_05) ) )
      {
      foreach ($month_num_12)
         {
         SWITCH:
            {
            if ( $_ ==  2 )    { $first_of_month_day_of_week_00 +=  31; last SWITCH; }
            if ( $_ ==  3 )    { $first_of_month_day_of_week_00 +=  59; last SWITCH; } #   $first_of_month_day_of_week_00 += 31 + 28;
            if ( $_ ==  4 )    { $first_of_month_day_of_week_00 +=  90; last SWITCH; } #   $first_of_month_day_of_week_00 += 31 + 28 + 31;
            if ( $_ ==  5 )    { $first_of_month_day_of_week_00 += 120; last SWITCH; } #   $first_of_month_day_of_week_00 += 31 + 28 + 31 + 30;
            if ( $_ ==  6 )    { $first_of_month_day_of_week_00 += 151; last SWITCH; } #   $first_of_month_day_of_week_00 += 31 + 28 + 31 + 30 + 31;
            if ( $_ ==  7 )    { $first_of_month_day_of_week_00 += 181; last SWITCH; } #   $first_of_month_day_of_week_00 += 31 + 28 + 31 + 30 + 31 + 30;
            if ( $_ ==  8 )    { $first_of_month_day_of_week_00 += 212; last SWITCH; } #   $first_of_month_day_of_week_00 += 31 + 28 + 31 + 30 + 31 + 30 + 31;
            if ( $_ ==  9 )    { $first_of_month_day_of_week_00 += 243; last SWITCH; } #   $first_of_month_day_of_week_00 += 31 + 28 + 31 + 30 + 31 + 30 + 31 + 31;
            if ( $_ == 10 )    { $first_of_month_day_of_week_00 += 273; last SWITCH; } #   $first_of_month_day_of_week_00 += 31 + 28 + 31 + 30 + 31 + 30 + 31 + 31 + 30;
            if ( $_ == 11 )    { $first_of_month_day_of_week_00 += 304; last SWITCH; } #   $first_of_month_day_of_week_00 += 31 + 28 + 31 + 30 + 31 + 30 + 31 + 31 + 30 + 31;
            if ( $_ == 12 )    { $first_of_month_day_of_week_00 += 334; last SWITCH; } #   $first_of_month_day_of_week_00 += 31 + 28 + 31 + 30 + 31 + 30 + 31 + 31 + 30 + 31 + 30;
            }
         }
      }
   else
      {
      foreach ($month_num_12)
         {
         SWITCH:
            {
            if ( $_ ==  2 )    { $first_of_month_day_of_week_00 +=  31; last SWITCH; }
            if ( $_ ==  3 )    { $first_of_month_day_of_week_00 +=  60; last SWITCH; } #  $first_of_month_day_of_week_00 += 31 + 29;
            if ( $_ ==  4 )    { $first_of_month_day_of_week_00 +=  91; last SWITCH; } #  $first_of_month_day_of_week_00 += 31 + 29 + 31;
            if ( $_ ==  5 )    { $first_of_month_day_of_week_00 += 121; last SWITCH; } #  $first_of_month_day_of_week_00 += 31 + 29 + 31 + 30;
            if ( $_ ==  6 )    { $first_of_month_day_of_week_00 += 152; last SWITCH; } #  $first_of_month_day_of_week_00 += 31 + 29 + 31 + 30 + 31;
            if ( $_ ==  7 )    { $first_of_month_day_of_week_00 += 182; last SWITCH; } #  $first_of_month_day_of_week_00 += 31 + 29 + 31 + 30 + 31 + 30;
            if ( $_ ==  8 )    { $first_of_month_day_of_week_00 += 213; last SWITCH; } #  $first_of_month_day_of_week_00 += 31 + 29 + 31 + 30 + 31 + 30 + 31;
            if ( $_ ==  9 )    { $first_of_month_day_of_week_00 += 244; last SWITCH; } #  $first_of_month_day_of_week_00 += 31 + 29 + 31 + 30 + 31 + 30 + 31 + 31;
            if ( $_ == 10 )    { $first_of_month_day_of_week_00 += 274; last SWITCH; } #  $first_of_month_day_of_week_00 += 31 + 29 + 31 + 30 + 31 + 30 + 31 + 31 + 30;
            if ( $_ == 11 )    { $first_of_month_day_of_week_00 += 305; last SWITCH; } #  $first_of_month_day_of_week_00 += 31 + 29 + 31 + 30 + 31 + 30 + 31 + 31 + 30 + 31;
            if ( $_ == 12 )    { $first_of_month_day_of_week_00 += 335; last SWITCH; } #  $first_of_month_day_of_week_00 += 31 + 29 + 31 + 30 + 31 + 30 + 31 + 31 + 30 + 31 + 30;
            }
         }
      }


   # Map day of week to 0-6
   $first_of_month_day_of_week_00 %= 7;

   # Map day of week '0' to '7'
   if ( $first_of_month_day_of_week_00 == 0 )
      {
      $first_of_month_day_of_week_00 = 7;
      }

   return ( $first_of_month_day_of_week_00 );
   }




###############################################################################
# Usage      : Function is overloaded to accept one of two date input types
#            :    1) Date string
#            :       get_numeric_day_of_week( SCALAR )
#            :    2) Month, dayofmonth, year
#            :       get_numeric_day_of_week( SCALAR, SCALAR, SCALAR )
# Purpose    : get numeric day of week (1-7) for given date
# Returns    : - day of week number if successful
# Parameters : 1) ( date string in any format )
#            :           OR
#            : 2) ( month, day of month, year )
# Throws     : Throws exception for any invalid input
# Comments   : - Handles all years, even negative years (aka BC)
#            : - <1 for Mon ... 7 for Sun>
# See Also   : N/A
###############################################################################
sub get_numeric_day_of_week
   {


   # Incoming Inspection
   ( ( @_ ==  1 )  ||  ( @_ ==  3 ) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}'  Should have either a date string, or a list of month,dayofmonth,year.   '@_'.\n\n\n";


   my ( $month_input_10, $day_of_month_in_02, $year_in_06, $day_of_week_12 );
   # Parsing date string and is recursive one time into this function
   if ( @_ ==  1 )
      {
      ( ref(\$_[0]) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the date string.    '$_[0]'.\n\n\n";
      ( $_[0]  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the date string    '$_[0]'.\n\n\n";

      ($month_input_10, $day_of_month_in_02, $year_in_06, $day_of_week_12 ) = date_only_parse($_[0]);
      if ( $day_of_week_12 )
         {
         return ( $day_of_week_12 );
         }
      else
         {
         croak "\n\n   ($0)   '${\(caller(0))[3]}' date string, '$_[0]', cannot be parsed.\n\n\n";
         }
      }
   # Individual date components
   else
      {
      ( ref(\$_[0]) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the month    '$_[0]'.\n\n\n";
      ( $_[0]  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty value for the month    '$_[0]'.\n\n\n";
      ( is_valid_month($_[0]) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a valid month    '$_[0]'.\n\n\n";

      ( ref(\$_[2]) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the year number    '$_[2]'.\n\n\n";
      ( $_[2]  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty value for the year number    '$_[2]'.\n\n\n";
      ( is_valid_year($_[2]) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects an integer value, positive, negative or zero, for the year number    '$_[2]'.\n\n\n";

      ( ref(\$_[1]) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the day of month    '$_[1]'.\n\n\n";
      ( $_[1]  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty value for the day of month    '$_[1]'.\n\n\n";
      ( is_valid_day_of_month($_[0], $_[1], $_[2]) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects an integer value for the day of month (1-31)    '$_[1]'.\n\n\n";

      ($month_input_10, $day_of_month_in_02, $year_in_06 ) = ( $_[0], $_[1], $_[2] );
      }


   my $month_num_14 = set_month_to_month_number($month_input_10);
   my $year_phase_03 = get_year_phase( $year_in_06 );

   my $first_of_month_day_of_week_02 = $NUMERIC_DAY_OF_WEEK_ON_FIRST_OF_MONTH{$year_phase_03}{$month_num_14} + $day_of_month_in_02 - 1;
   $first_of_month_day_of_week_02 %= 7;

   # Map day of week to 0-6
   $first_of_month_day_of_week_02 %= 7;

   # Map day of week '0' to '7'
   if ( $first_of_month_day_of_week_02 == 0 )
      {
      $first_of_month_day_of_week_02 = 7;
      }

   return ( $first_of_month_day_of_week_02 );
   }




###############################################################################
# Usage      : get_month_from_string( SCALAR )
# Purpose    : extract month from given date string
# Returns    : month number if successful
# Parameters : 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
# See Also   : N/A
###############################################################################
sub get_month_from_string
   {


   # Incoming Inspection
   ( @_ ==  1 ) or croak "\n\n   ($0)   '${\(caller(0))[3]}'  Should have a date string to be parsed.   '@_'.\n\n\n";

   ( ref(\$_[0]) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the date string.    '$_[0]'.\n\n\n";
   ( $_[0]  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the date string    '$_[0]'.\n\n\n";


   my  ($month_input_15, $day_of_month_15, $year_15, $day_of_week_15) = date_only_parse( $_[0] );
   if ( $month_input_15  eq  '' )
      {
      croak "\n\n   ($0)   '${\(caller(0))[3]}' Cannot extract the date from the input date string    '$_[0]'.\n\n\n";
      }
   else
      {
      return ( $month_input_15 );
      }

   }




###############################################################################
# Usage      : get_dayofmonth_from_string( SCALAR )
# Purpose    : extract day of month from given date string
# Returns    : day of month if successful
# Parameters : date string in any format
# Throws     : Throws exception for any invalid input
# Comments   : - Handles all years, even negative years (aka BC)
# See Also   : N/A
###############################################################################
sub get_dayofmonth_from_string
   {


   # Incoming Inspection
   ( @_ ==  1 ) or croak "\n\n   ($0)   '${\(caller(0))[3]}'  Should have a date string to be parsed.   '@_'.\n\n\n";

   ( ref(\$_[0]) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the date string.    '$_[0]'.\n\n\n";
   ( $_[0]  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the date string    '$_[0]'.\n\n\n";


   my  ($month_input_18, $day_of_month_18, $year_18, $day_of_week_18) = date_only_parse( $_[0] );
   if ( !(defined ($day_of_month_18) ) )
      {
      croak "\n\n   ($0)   '${\(caller(0))[3]}' Cannot extract the date from the input date string    '$_[0]'.\n\n\n";
      }
   else
      {
      return ( $day_of_month_18 );
      }

   }




###############################################################################
# Usage      : get_year_from_string( SCALAR )
# Purpose    : extract year from given date string
# Returns    : year if successful
# Parameters : date string in any format
# Throws     : Throws exception for any invalid input
# Comments   : - Handles all years, even negative years (aka BC)
# See Also   : N/A
###############################################################################
sub get_year_from_string
   {


   # Incoming Inspection
   ( @_ ==  1 ) or croak "\n\n   ($0)   '${\(caller(0))[3]}'  Should have a date string to be parsed.   '@_'.\n\n\n";

   ( ref(\$_[0]) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the date string.    '$_[0]'.\n\n\n";
   ( $_[0]  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the date string    '$_[0]'.\n\n\n";


   my  ($month_input_14, $day_of_month_14, $year_14, $day_of_week_14) = date_only_parse( $_[0] );
   if ( !(defined ($year_14) ) )
      {
      croak "\n\n   ($0)   '${\(caller(0))[3]}' Cannot extract the date from the input date string    '$_[0]'.\n\n\n";
      }
   else
      {
      return ( $year_14 );
      }

   }




###############################################################################
# Usage      : compare_year1_and_year2( SCALAR, SCALAR )
# 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
# Parameters : (
#            :   date ONE in any format,
#            :   date TWO in any format
#            : )
# Throws     : Throws exception for any invalid input
# Comments   : N/A
# See Also   : N/A
###############################################################################
sub compare_year1_and_year2
   {
   my (
       $date_one_03,
       $date_two_03
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_30 = 2;
   ( @_ ==  $num_input_params_30) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly $num_input_params_30 parameters ('date1' and date2).   '@_'.\n\n\n";

   ( ref(\$date_one_03) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR first parameter for the first date    '$date_one_03'.\n\n\n";
   ( ref(\$date_two_03) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR second parameter for the second date    '$date_two_03'.\n\n\n";

   ( $date_one_03  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the first date    '$date_one_03'.\n\n\n";
   ( $date_two_03  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the second date    '$date_two_03'.\n\n\n";

   ( date_only_parse($date_one_03) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Cannot extract the date from the input date1 string    '$date_one_03'.\n\n\n";
   ( date_only_parse($date_two_03) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Cannot extract the date from the input date2 string    '$date_two_03'.\n\n\n";


   my ( $date1_month_num_06, $date1_day_of_month_06, $date1_year_num_06, $date1_day_of_week_06 ) = date_only_parse($date_one_03);
   my ( $date2_month_num_06, $date2_day_of_month_06, $date2_year_num_06, $date2_day_of_week_06 ) = date_only_parse($date_two_03);

   if ( $date1_year_num_06  ==  $date2_year_num_06 )
      {
      return ( '0' );
      }
   elsif ( $date1_year_num_06  >  $date2_year_num_06 )
      {
      return ( '1' );
      }
   else
      {
      return ( '-1' );
      }

   }




###############################################################################
# Usage      : year1_to_year2_delta( SCALAR, SCALAR )
# Purpose    : calculates the difference in WHOLE years between two dates (basically it truncates the date difference to whole years)
# Returns    : integer year difference if successful
# Parameters : (
#            :   date ONE in any format,
#            :   date 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  Date1 = 4/5/1977 and Date2 = 11/16/1975 equals ONE complete year difference
# See Also   : N/A
###############################################################################
sub year1_to_year2_delta
   {
   my (
       $date_one_04,
       $date_two_04
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_31 = 2;
   ( @_ ==  $num_input_params_31) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly $num_input_params_31 parameters ('date1' and date2).   '@_'.\n\n\n";

   ( ref(\$date_one_04) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR first parameter for the first date    '$date_one_04'.\n\n\n";
   ( ref(\$date_two_04) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR second parameter for the second date    '$date_two_04'.\n\n\n";

   ( $date_one_04  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the first date    '$date_one_04'.\n\n\n";
   ( $date_two_04  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the second date    '$date_two_04'.\n\n\n";

   ( date_only_parse($date_one_04) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Cannot extract the date from the input date1 string    '$date_one_04'.\n\n\n";
   ( date_only_parse($date_two_04) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Cannot extract the date from the input date2 string    '$date_two_04'.\n\n\n";


   my ( $date1_month_num_07, $date1_day_of_month_07, $date1_year_num_07, $date1_day_of_week_07 ) = date_only_parse($date_one_04);
   my ( $date2_month_num_07, $date2_day_of_month_07, $date2_year_num_07, $date2_day_of_week_07 ) = date_only_parse($date_two_04);

   my $year_difference_00;
   if ( $date1_year_num_07  ==  $date2_year_num_07 )
      {
      $year_difference_00 = '0';
      }
   else
      {
      $year_difference_00 = $date1_year_num_07  -  $date2_year_num_07;
      }


   $date1_month_num_07 = set_month_to_month_number($date1_month_num_07);
   $date2_month_num_07 = set_month_to_month_number($date2_month_num_07);


   my $date1_is_leap_year = 'no';
   if ( is_leap_year($date1_year_num_07) )
      {
      $date1_is_leap_year = 'yes';
      }

   my $date2_is_leap_year = 'no';
   if ( is_leap_year($date2_year_num_07) )
      {
      $date2_is_leap_year = 'yes';
      }


   if ( $year_difference_00 > 0 )
      {
      if ( $date1_month_num_07  <  $date2_month_num_07 )
         {
         $year_difference_00--;
         }
      elsif ( ( $date1_month_num_07  ==  $date2_month_num_07 )  &&  ( $date1_day_of_month_07  <  $date2_day_of_month_07  ) )
         {
         $year_difference_00--;
         }

      # Leap Year Adjustments
      #                      whole year    whole year
      #  Date1     Date2     current       fix
      #  28        28        YES           YES
      #  28        28(9)     YES           YES
      #  28        29        no            YES (to be adjusted UP)
      #  28(9)     28        YES           no  (to be adjusted DOWN)
      #  28(9)     28(9)     YES           YES
      #  28(9)     29        no            no
      #  29        28        YES           YES
      #  29        28(9)     YES           YES
      #  29        29        YES           YES
      if ( ( $date1_is_leap_year eq 'no' ) &&  ( $date2_is_leap_year eq 'yes' ) )
         {
         if ( ( $date1_day_of_month_07  ==  28 )  &&  ( $date2_day_of_month_07  ==  29 ) )
            {
            $year_difference_00++;
            }
         }
      elsif ( ( $date1_is_leap_year eq 'yes' ) &&  ( $date2_is_leap_year eq 'no' ) )
         {
         if ( ( $date1_day_of_month_07  ==  28 )  &&  ( $date2_day_of_month_07  ==  28 ) )
            {
            $year_difference_00--;
            }
         }
      }
   elsif ( $year_difference_00 < 0 )
      {
      if ( $date1_month_num_07  >  $date2_month_num_07 )
         {
         $year_difference_00++;
         }
      elsif ( ( $date1_month_num_07  ==  $date2_month_num_07 )  &&  ( $date1_day_of_month_07  >  $date2_day_of_month_07  ) )
         {
         $year_difference_00++;
         }

      # Leap Year Adjustments
      #                      whole year    whole year
      #  Date1     Date2     current       fix
      #  28        28        YES           YES
      #  28        28(9)     YES           no    (to be adjusted UP)
      #  28        29        YES           YES
      #  28(9)     28        YES           YES
      #  28(9)     28(9)     YES           YES
      #  28(9)     29        YES           YES
      #  29        28        no            YES   (to be adjusted DOWN)
      #  29        28(9)     no            no
      #  29        29        YES           YES
      if ( ( $date1_is_leap_year eq 'no' ) &&  ( $date2_is_leap_year eq 'yes' ) )
         {
         if ( ( $date1_day_of_month_07  ==  28 )  &&  ( $date2_day_of_month_07  ==  28 ) )
            {
            $year_difference_00++;
            }
         }
      elsif ( ( $date1_is_leap_year eq 'yes' ) &&  ( $date2_is_leap_year eq 'no' ) )
         {
         if ( ( $date1_day_of_month_07  ==  29 )  &&  ( $date2_day_of_month_07  ==  28 ) )
            {
            $year_difference_00--;
            }
         }
      }

   # Set year difference to string '0' if it is zero
   if ( $year_difference_00 == 0 )
      {
      $year_difference_00 = '0';
      }

   return( $year_difference_00 );
   }




###############################################################################
# Usage      : date_offset_in_years( SCALAR, SCALAR )
# Purpose    : find a date in the future or past offset by the number of YEARS from the given date
# Returns    : - date of the day offset from the given date if successful
# Parameters : (
#            :   date in any format,
#            :   number of WHOLE offset years, positive is future date, negative is past date, zero is current date (no offset)
#            : )
# 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
# See Also   : N/A
###############################################################################
sub date_offset_in_years
   {
   my (
       $date_in_03,
       $date_delta_years_00
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_32 = 2;
   ( @_ ==  $num_input_params_32) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly $num_input_params_32 parameter(s), a date string followed by the number of offset days.   '@_'.\n\n\n";

   ( ref(\$date_in_03) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the date string    '$date_in_03'.\n\n\n";
   ( $date_in_03  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the date string    '$date_in_03'.\n\n\n";
   ( date_only_parse($date_in_03) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Cannot parse the date from the input date string    '$date_in_03'.\n\n\n";

   ( ref(\$date_delta_years_00) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the number of WHOLE offset years    '$date_delta_years_00'.\n\n\n";
   ( $date_delta_years_00  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty value for the number of WHOLE offset years    '$date_delta_years_00'.\n\n\n";
   ( $date_delta_years_00  =~ m/^\-{0,1}\d+$/ ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects an integer value, positive, negative or zero, for the number of WHOLE offset years    '$date_delta_years_00'.\n\n\n";


   if ( $date_delta_years_00  ==  0 )
      {
      return ( format_date( $date_in_03 ) );
      }


   my ( $date1_month_num_08, $date1_day_of_month_08, $date1_year_num_08, $date1_day_of_week_08 ) = date_only_parse($date_in_03);


   my $offset_year_01 = $date1_year_num_08 + $date_delta_years_00;

   # Handle case where leap year (Feb 29) is to be mapped to a NON leap year (Feb 28)
   my $mapped_to_end_of_month = $date1_day_of_month_08;
   if ( !is_leap_year( $offset_year_01 ) )
      {
      if ( ( $date1_month_num_08  ==  2 )  &&  ( $date1_day_of_month_08  ==  29 ) )
         {
         $mapped_to_end_of_month = 28;
         }
      }

   # Handle case where NON leap year (Feb 28) is to be mapped to a leap year (Feb 29)
   elsif ( !is_leap_year( $date1_year_num_08 ) )
      {
      if ( ( $date1_month_num_08  ==  2 )  &&  ( $date1_day_of_month_08  ==  28 ) )
         {
         $mapped_to_end_of_month = 29;
         }
      }

   return( format_date( $date1_month_num_08, $mapped_to_end_of_month, $offset_year_01 ) );
   }




###############################################################################
# Usage      : number_of_weekdays_in_range( SCALAR, SCALAR )
# Purpose    : calculates the number of weekdays in the range of the two dates
# Returns    : integer number of weekdays if successful
# Parameters : (
#            :   date ONE in any format,
#            :   date 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
# See Also   : N/A
###############################################################################
sub number_of_weekdays_in_range
   {
   my (
       $date_one_05,
       $date_two_05
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_33 = 2;
   ( @_ ==  $num_input_params_33) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly $num_input_params_33 parameters ('date1' and date2).   '@_'.\n\n\n";

   ( ref(\$date_one_05) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR first parameter for the first date    '$date_one_05'.\n\n\n";
   ( ref(\$date_two_05) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR second parameter for the second date    '$date_two_05'.\n\n\n";

   ( $date_one_05  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the first date    '$date_one_05'.\n\n\n";
   ( $date_two_05  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the second date    '$date_two_05'.\n\n\n";

   ( date_only_parse($date_one_05) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Cannot extract the date from the input date1 string    '$date_one_05'.\n\n\n";
   ( date_only_parse($date_two_05) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Cannot extract the date from the input date2 string    '$date_two_05'.\n\n\n";


   # Get count of ALL days in range as a starting point
   my $number_of_days_in_range_00 = date1_to_date2_delta( $date_one_05, $date_two_05 );

   # Get the number of weekdays in the range for the WHOLE weeks in the range
   my $number_weekdays_00 = int( abs($number_of_days_in_range_00) / 7 ) * 5;

   # Get the remainder of weekdays in the range that is discarded by the previous variable
   my $week_remainder_00 = abs( $number_of_days_in_range_00 ) % 7;

   my $current_dayofweek_00 = get_numeric_day_of_week($date_two_05);
   # Cycle through the left over days in the range that do not form a WHOLE week and add them in into the total IF they are weekdays
   for ( my $iii_004=0; $iii_004<$week_remainder_00; $iii_004++ )
      {
      if ( $number_of_days_in_range_00 > 0 ) # range is positive
         {
         $current_dayofweek_00++;
         if ( $current_dayofweek_00 > 7 )
            {
            $current_dayofweek_00 -= 7;
            }

         if ( $current_dayofweek_00 < 6 ) # weekdays
            {
            $number_weekdays_00++;
            }
         }
      if ( $number_of_days_in_range_00 < 0 ) # range is negative
         {
         $current_dayofweek_00--;
         if ( $current_dayofweek_00 < 1 )
            {
            $current_dayofweek_00 += 7;
            }

         if ( $current_dayofweek_00 < 6 ) # weekdays
            {
            $number_weekdays_00++;
            }
         }
      }


   # Put correct sign to number of days in range
   if ( $number_of_days_in_range_00 > 0 )
      {
      return( $number_weekdays_00 );
      }
   elsif ( $number_of_days_in_range_00 < 0 )
      {
      return( -$number_weekdays_00 );
      }
   else
      {
      return( '0' );
      }

   }




###############################################################################
# Usage      : date_offset_in_weekdays( SCALAR, SCALAR )
# 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 day offset from the given WEEKDAY date if successful
# Parameters : (
#            :   WEEKDAY date in any format,
#            :   number of weekdays offset, positive is future date, negative is past date, zero is current date (no offset)
#            : )
# 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
# See Also   : N/A
###############################################################################
sub date_offset_in_weekdays
   {
   my (
       $date_in_05,
       $date_delta_01
      )
       = @_;


   # Incoming Inspection
   my $num_input_params_36 = 2;
   ( @_ ==  $num_input_params_36) or croak "\n\n   ($0)   '${\(caller(0))[3]}' should have exactly $num_input_params_36 parameter(s), a date string followed by the number of offset days.   '@_'.\n\n\n";

   ( ref(\$date_in_05) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the date string    '$date_in_05'.\n\n\n";
   ( $date_in_05  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty string for the date string    '$date_in_05'.\n\n\n";
   ( date_only_parse($date_in_05) ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Cannot parse the date from the input date string    '$date_in_05'.\n\n\n";

   ( ref(\$date_delta_01) eq 'SCALAR' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a SCALAR parameter for the number of offset days    '$date_delta_01'.\n\n\n";
   ( $date_delta_01  ne  '' ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects a NON-empty value for the number of offset days    '$date_delta_01'.\n\n\n";
   ( $date_delta_01  =~ m/^\-{0,1}\d+$/ ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects an integer value, positive, negative or zero, for the number of offset days    '$date_delta_01'.\n\n\n";


   # Check that starting date is a WEEKDAY
   my $day_of_week_16 = get_numeric_day_of_week($date_in_05);

   ( $day_of_week_16 < 6 ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects the starting date, '$date_in_05', to be a WEEKDAY.  It is incorrectly a ${\(set_day_to_day_name_full($day_of_week_16))}.\n\n\n";

   my $past_future = 1;
   if ( $date_delta_01 < 0 )
      {
      $past_future = -1;
      }

#  1    0    0       7/5                       2    0    0       7/5                       3    0    0       7/5                       4    0    0       7/5                       5    0    0       7/5
#  1    1    1   int(7/5)                      2    1    1   int(7/5)                      3    1    1   int(7/5)                      4    1    1   int(7/5)                      5    1    3   int(7/5) + 2
#  1    2    2   int(7/5)                      2    2    2   int(7/5)                      3    2    2   int(7/5)                      4    2    4   int(7/5) + 2                  5    2    4   int(7/5) + 2
#  1    3    3   int(7/5) - 1                  2    3    3   int(7/5) - 1                  3    3    5   int(7/5) + 1                  4    3    5   int(7/5) + 1                  5    3    5   int(7/5) + 1
#  1    4    4   int(7/5) - 1                  2    4    6   int(7/5) + 1                  3    4    6   int(7/5) + 1                  4    4    6   int(7/5) + 1                  5    4    6   int(7/5) + 1

#  1    0    0           7/5                   2    0    0           7/5                   3    0    0           7/5                   4    0    0           7/5                   5    0    0           7/5
#  1   -1   -3  -int(abs(7/5)) - 2             2   -1   -1  -int(abs(7/5))                 3   -1   -1  -int(abs(7/5))                 4   -1   -1  -int(abs(7/5))                 5   -1   -1  -int(abs(7/5))
#  1   -2   -4  -int(abs(7/5)) - 2             2   -2   -4  -int(abs(7/5)) - 2             3   -2   -2  -int(abs(7/5))                 4   -2   -2  -int(abs(7/5))                 5   -2   -2  -int(abs(7/5))
#  1   -3   -5  -int(abs(7/5)) - 1             2   -3   -5  -int(abs(7/5)) - 1             3   -3   -5  -int(abs(7/5)) - 1             4   -3   -3  -int(abs(7/5)) + 1             5   -3   -3  -int(abs(7/5)) + 1
#  1   -4   -6  -int(abs(7/5)) - 1             2   -4   -6  -int(abs(7/5)) - 1             3   -4   -6  -int(abs(7/5)) - 1             4   -4   -6  -int(abs(7/5)) - 1             5   -4   -4  -int(abs(7/5)) + 1

   my $weekday_remainder = abs($date_delta_01) % 5;
   my $num_days_effective = 'xxx';
   if (
       ( ( $day_of_week_16  ==  1 )  &&  ( $date_delta_01  >  0 ) )  ||
       ( ( $day_of_week_16  ==  5 )  &&  ( $date_delta_01  <  0 ) )
      )
      {
      foreach ( $weekday_remainder )
         {
         SWITCH:
            {
            if ( $_ <=  2 )   { $num_days_effective = $past_future * int( abs($date_delta_01 * (7/5) ) );                       last SWITCH; }
                                $num_days_effective = $past_future * int( abs($date_delta_01 * (7/5) ) ) - $past_future;
            }
         }
      }
   elsif (
          ( ( $day_of_week_16  ==  2 )  &&  ( $date_delta_01  >  0 ) )  ||
          ( ( $day_of_week_16  ==  4 )  &&  ( $date_delta_01  <  0 ) )
         )
      {
      foreach ( $weekday_remainder )
         {
         SWITCH:
            {
            if ( $_ <=  2 )   { $num_days_effective = $past_future * int( abs($date_delta_01 * (7/5) ) );                       last SWITCH; }
            if ( $_ ==  3 )   { $num_days_effective = $past_future * int( abs($date_delta_01 * (7/5) ) ) - $past_future;        last SWITCH; }
                                $num_days_effective = $past_future * int( abs($date_delta_01 * (7/5) ) ) + $past_future;
            }
         }
      }
   elsif (
          ( ( $day_of_week_16  ==  3 )  &&  ( $date_delta_01  >  0 ) )  ||
          ( ( $day_of_week_16  ==  3 )  &&  ( $date_delta_01  <  0 ) )
         )
      {
      foreach ( $weekday_remainder )
         {
         SWITCH:
            {
            if ( $_ <=  2 )   { $num_days_effective = $past_future * int( abs($date_delta_01 * (7/5) ) );                       last SWITCH; }
                                $num_days_effective = $past_future * int( abs($date_delta_01 * (7/5) ) ) + $past_future;
            }
         }
      }
   elsif (
          ( ( $day_of_week_16  ==  4 )  &&  ( $date_delta_01  >  0 ) )  ||
          ( ( $day_of_week_16  ==  2 )  &&  ( $date_delta_01  <  0 ) )
         )
      {
      foreach ( $weekday_remainder )
         {
         SWITCH:
            {
            if ( $_ <   2 )   { $num_days_effective = $past_future * int( abs($date_delta_01 * (7/5) ) );                       last SWITCH; }
            if ( $_ ==  2 )   { $num_days_effective = $past_future * int( abs($date_delta_01 * (7/5) ) ) + $past_future * 2;    last SWITCH; }
                                $num_days_effective = $past_future * int( abs($date_delta_01 * (7/5) ) ) + $past_future;
            }
         }
      }
   elsif (
          ( ( $day_of_week_16  ==  5 )  &&  ( $date_delta_01  >  0 ) )  ||
          ( ( $day_of_week_16  ==  1 )  &&  ( $date_delta_01  <  0 ) )
         )
      {
      foreach ( $weekday_remainder )
         {
         SWITCH:
            {
            if ( $_ ==  0 )   { $num_days_effective = $past_future * int( abs($date_delta_01 * (7/5) ) );                       last SWITCH; }
            if ( $_ ==  1 )   { $num_days_effective = $past_future * int( abs($date_delta_01 * (7/5) ) ) + $past_future * 2;    last SWITCH; }
            if ( $_ ==  2 )   { $num_days_effective = $past_future * int( abs($date_delta_01 * (7/5) ) ) + $past_future * 2;    last SWITCH; }
                                $num_days_effective = $past_future * int( abs($date_delta_01 * (7/5) ) ) + $past_future;
            }
         }
      }
   else
      {
      $num_days_effective = 0;
      }


   # Check that offset date is a WEEKDAY
   my $weekday_offset_00 = date_offset_in_days($date_in_05, $num_days_effective);
   my $day_of_week_17 = get_numeric_day_of_week($weekday_offset_00);

   ( $day_of_week_17 < 6 ) or croak "\n\n   ($0)   '${\(caller(0))[3]}' Expects the offset date, '$weekday_offset_00', to be a WEEKDAY.  It is incorrectly a ${\(set_day_to_day_name_full($day_of_week_17))}.  This condition should NOT occur.  Something is amiss.\n\n\n";

   return ( $weekday_offset_00 );
   }




}
1;

__END__