Date_Utility.f90

Go to the documentation of this file.

!
! Date_Utility
!
! Module containing date conversion routines
!
!
! CREATION HISTORY:
!       Written by:     Paul van Delst, 03-Apr-2000
!                       paul.vandelst@noaa.gov

MODULE date_utility

  ! -----------------
  ! Environment setup
  ! -----------------
  IMPLICIT NONE



  ! ------------
  ! Visibilities
  ! ------------
  PRIVATE
  ! Parameters
  PUBLIC :: n_months
  PUBLIC :: days_per_month_in_nonleap
  PUBLIC :: month_name
  PUBLIC :: n_days
  PUBLIC :: day_name
  ! Procedures
  PUBLIC :: isleapyear
  PUBLIC :: dayofyear
  PUBLIC :: daysinmonth
  PUBLIC :: nameofmonth
  PUBLIC :: dayofweek


  ! ----------
  ! Parameters
  ! ----------
  CHARACTER(*), PARAMETER :: module_version_id = &
  '$Id: Date_Utility.f90 60152 2015-08-13 19:19:13Z paul.vandelst@noaa.gov $'
  ! String length for character functions
  INTEGER, PARAMETER :: nl = 20
  ! Number of Months in a Year
  INTEGER, PARAMETER :: n_months = 12
  ! Days per Month in a non leap Year
  INTEGER, PARAMETER :: days_per_month_in_nonleap(n_months) = &
  (/ 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 /)
  ! Month names
  CHARACTER(*), PARAMETER :: month_name(n_months) = &
  (/'January  ','February ','March    ','April    ','May      ','June     ', &
    'July     ','August   ','September','October  ','November ','December ' /)
  ! Number of Days in a Week
  INTEGER, PARAMETER :: n_days = 7
  ! Day names
  CHARACTER(*), PARAMETER :: day_name(n_days) = &
  (/'Sunday   ','Monday   ','Tuesday  ','Wednesday','Thursday ','Friday   ','Saturday '/)


CONTAINS


!##############################################################################
!##############################################################################
!##                                                                          ##
!##                       ## PUBLIC MODULE ROUTINES ##                       ##
!##                                                                          ##
!##############################################################################
!##############################################################################

!------------------------------------------------------------------------------
!:sdoc+:
!
! NAME:
!       IsLeapYear
!
! PURPOSE:
!       Elemental function to determine if a specified year is a leap year.
!
! CALLING SEQUENCE:
!       Result = IsLeapYear( Year )
!
! INPUT ARGUMENTS:
!       Year:     The year in 4-digit format, e.g. 1997.
!                 UNITS:      N/A
!                 TYPE:       INTEGER
!                 DIMENSION:  Scalar
!                 ATTRIBUTES: INTENT(IN)
!
! FUNCTION RESULT:
!       Result:   The return value is a logical value indicating whether
!                 the specified year is a leap year.
!                 If .TRUE.  the specified year IS a leap year.
!                    .FALSE. the specified year is NOT a leap year.
!                 UNITS:      N/A
!                 TYPE:       LOGICAL
!                 DIMENSION:  Scalar
!:sdoc-:
!------------------------------------------------------------------------------

  ELEMENTAL FUNCTION isleapyear( Year )
    INTEGER, INTENT(IN) :: year
    LOGICAL :: isleapyear

    isleapyear = ( (mod(year,4)   == 0) .AND. (mod(year,100) /= 0) ) .OR. &
                 (mod(year,400) == 0)

  END FUNCTION isleapyear


!------------------------------------------------------------------------------
!:sdoc+:
!
! NAME:
!       DayOfYear
!
! PURPOSE:
!       Elemental function to convert input numeric (e.g. DD,MM,YYYY) date
!       information to a sequential day of year.
!
! CALLING SEQUENCE:
!       DoY = DayOfYear ( Day, Month, Year )
!
! INPUTS:
!       Day:       The day-of-month.
!                  UNITS:      N/A
!                  TYPE:       INTEGER
!                  DIMENSION:  Scalar or any rank
!                  ATTRIBUTES: INTENT(IN)
!
!       Month:     The month-of-year.
!                  UNITS:      N/A
!                  TYPE:       INTEGER
!                  DIMENSION:  Same as Day input
!                  ATTRIBUTES: INTENT(IN)
!
!       Year:      The year in 4-digit format, e.g. 1997.
!                  UNITS:      N/A
!                  TYPE:       INTEGER
!                  DIMENSION:  Same as Day input
!                  ATTRIBUTES: INTENT(IN)
!
! FUNCTION RESULT:
!       DoY:       Integer defining the day-of-year.
!                  Return value is 0 for invalid input.
!                  UNITS:      N/A
!                  TYPE:       INTEGER
!                  DIMENSION:  Same as Day input
!:sdoc-:
!------------------------------------------------------------------------------

  ELEMENTAL FUNCTION dayofyear( &
    Day  , &  ! Input
    Month, &  ! Input
    Year ) &  ! Input
  result( doy )
    ! Arguments
    INTEGER, INTENT(IN) :: day
    INTEGER, INTENT(IN) :: month
    INTEGER, INTENT(IN) :: year
    ! Function result
    INTEGER :: doy
    ! Local variables
    INTEGER :: days_per_month( n_months )

    ! Set up
    doy = 0
    ! ...Check year and month input
    IF ( year  < 1 .OR. &
         month < 1 .OR. &
         month > n_months ) RETURN
    ! ...Check the day of month
    days_per_month = days_per_month_in_nonleap
    IF ( isleapyear(year) ) days_per_month(2) = 29
    IF ( day > days_per_month(month) ) RETURN

    ! Compute the day of year
    doy = sum(days_per_month(1:month-1)) + day

  END FUNCTION dayofyear


!------------------------------------------------------------------------------
!:sdoc+:
! NAME:
!       DaysInMonth
!
! PURPOSE:
!       Elemental function to return the number of days in a given
!       month and year.
!
! CALLING SEQUENCE:
!       n_Days = DaysInMonth( Month, Year )
!
! INPUTS:
!       Month:     The month of the year (1-12).
!                  UNITS:      N/A
!                  TYPE:       INTEGER
!                  DIMENSION:  Scalar or any rank
!                  ATTRIBUTES: INTENT(IN)
!
!       Year:      The year in 4-digit format, e.g. 1997.
!                  UNITS:      N/A
!                  TYPE:       INTEGER
!                  DIMENSION:  Same as Month input
!                  ATTRIBUTES: INTENT(IN)
!
! FUNCTION RESULT:
!       n_Days:    The number of days in the month.
!                  Return value is 0 for invalid input.
!                  UNITS:      N/A
!                  TYPE:       INTEGER
!                  DIMENSION:  Same as input
!:sdoc-:
!------------------------------------------------------------------------------

  ELEMENTAL FUNCTION daysinmonth(Month, Year) RESULT(n_Days)
    ! Arguments
    INTEGER, INTENT(IN) :: month
    INTEGER, INTENT(IN) :: year
    ! Function result
    INTEGER :: n_days
    ! Local variables
    INTEGER :: days_per_month(n_months)

    ! Set up
    n_days = 0
    ! ...Check year and month input
    IF ( year  < 1 .OR. &
         month < 1 .OR. &
         month > n_months ) RETURN

    ! Assemble the days of month
    days_per_month = days_per_month_in_nonleap
    IF ( isleapyear(year=year) ) days_per_month(2) = 29

    ! Set the number of days
    n_days = days_per_month(month)

  END FUNCTION daysinmonth


!------------------------------------------------------------------------------
!:sdoc+:
!
! NAME:
!       NameOfMonth
!
! PURPOSE:
!       Elemental function to return the name of the month.
!
! CALLING SEQUENCE:
!       name = NameOfMonth( Month )
!
! INPUT ARGUMENTS:
!       Month:    The month of the year (1-12).
!                 UNITS:      N/A
!                 TYPE:       INTEGER
!                 DIMENSION:  Scalar or any rank.
!                 ATTRIBUTES: INTENT(IN)
!
! FUNCTION RESULT:
!       name:     The return value is a character string containing the
!                 name of the month.
!                 UNITS:      N/A
!                 TYPE:       CHARACTER
!                 DIMENSION:  Conformable with input Month arugment
!:sdoc-:
!------------------------------------------------------------------------------

  ELEMENTAL FUNCTION nameofmonth( Month )
    INTEGER, INTENT(IN) :: month
    CHARACTER(NL) :: nameofmonth
    nameofmonth = 'Invalid'
    IF ( month < 1 .OR. month > n_months ) RETURN
    nameofmonth = month_name( month )
  END FUNCTION nameofmonth


!------------------------------------------------------------------------------
!:sdoc+:
!
! NAME:
!       DayOfWeek
!
! PURPOSE:
!       Elemental function to return the name of the day of week.
!
!       NOTE:
!       - Only valid for Gregorian calendar.
!       - Since different places switched to the Gregorian calendar at
!         different times, this routine will only output day of week names
!         for dates AFTER 1918 (the year Russia adopted the Gregorian
!         calendar).
!
! CALLING SEQUENCE:
!       name = DayOfWeek ( Day, Month, Year )
!
! INPUTS:
!       Day:       The day of the month.
!                  UNITS:      N/A
!                  TYPE:       INTEGER
!                  DIMENSION:  Scalar or any rank
!                  ATTRIBUTES: INTENT(IN)
!
!       Month:     The month of the year (1-12).
!                  UNITS:      N/A
!                  TYPE:       INTEGER
!                  DIMENSION:  Conformable with input Day argument.
!                  ATTRIBUTES: INTENT(IN)
!
!       Year:      The year in 4-digit format, e.g. 1997.
!                  UNITS:      N/A
!                  TYPE:       INTEGER
!                  DIMENSION:  Conformable with input Day argument.
!                  ATTRIBUTES: INTENT(IN)
!
! FUNCTION RESULT:
!       name:      The return value is a character string containing the
!                  name of the day-of-week.
!                  UNITS:      N/A
!                  TYPE:       CHARACTER
!                  DIMENSION:  Conformable with input Day argument.
!
!:sdoc-:
!------------------------------------------------------------------------------

  ELEMENTAL FUNCTION dayofweek( Day, Month, Year )
    INTEGER, INTENT(IN) :: day
    INTEGER, INTENT(IN) :: month
    INTEGER, INTENT(IN) :: year
    CHARACTER(NL) :: dayofweek
    INTEGER :: i
    dayofweek = 'Invalid'
    i = idayofweek( day, month, year )
    IF ( i == 0 ) RETURN
    dayofweek = day_name(i)
  END FUNCTION dayofweek



!##############################################################################
!##############################################################################
!##                                                                          ##
!##                      ## PRIVATE MODULE ROUTINES ##                       ##
!##                                                                          ##
!##############################################################################
!##############################################################################

!------------------------------------------------------------------------------
!
! NAME:
!       iDayOfWeek
!
! PURPOSE:
!       Elemental function to convert input numeric (e.g. DD,MM,YYYY) date
!       information to a day of week index, 1-7.
!
!       NOTE:
!       - Only valid for Gregorian calendar.
!       - Since different places switched to the Gregorian calendar at
!         different times, this routine will only output valid day of week
!         indices for dates AFTER 1918 (the year Russia adopted the Gregorian
!         calendar).
!
! CALLING SEQUENCE:
!       iDoW = iDayOfWeek ( Day, Month, Year )
!
! INPUTS:
!       Day:       The day of the month.
!                  UNITS:      N/A
!                  TYPE:       INTEGER
!                  DIMENSION:  Scalar or any rank
!                  ATTRIBUTES: INTENT(IN)
!
!       Month:     The month of the year (1-12).
!                  UNITS:      N/A
!                  TYPE:       INTEGER
!                  DIMENSION:  Same as Day input
!                  ATTRIBUTES: INTENT(IN)
!
!       Year:      The year in 4-digit format, e.g. 1997.
!                  UNITS:      N/A
!                  TYPE:       INTEGER
!                  DIMENSION:  Same as Day input
!                  ATTRIBUTES: INTENT(IN)
!
! FUNCTION RESULT:
!       iDoW:      Integer defining the day-of-week (1-7).
!                  Return value is 0 for invalid input.
!                  UNITS:      N/A
!                  TYPE:       INTEGER
!                  DIMENSION:  Same as Day input
!
!------------------------------------------------------------------------------

  ELEMENTAL FUNCTION idayofweek( Day, Month, Year ) RESULT( iDoW )
    ! Arguments
    INTEGER, INTENT(IN) :: day
    INTEGER, INTENT(IN) :: month
    INTEGER, INTENT(IN) :: year
    ! Function result
    INTEGER :: idow
    ! Local variables
    INTEGER :: jdn

    idow = 0
    jdn = julianday( day, month, year )
    IF ( jdn < 0 ) RETURN

    idow = mod(jdn+1, 7) + 1
    IF ( idow < 1 .OR. idow > 7 ) idow = 0

  END FUNCTION idayofweek


!------------------------------------------------------------------------------
!
! NAME:
!       JulianDay
!
! PURPOSE:
!       Elemental function to convert input numeric (e.g. DD,MM,YYYY) date
!       information to a Julian Day Number, which is defined as the number of
!       days since noon January 1, 4713 BCE.
!
!       NOTE:
!       - Only valid for Gregorian calendar.
!       - Since different places switched to the Gregorian calendar at different
!         times, this routine will only output valid Julian day numbers for dates
!         AFTER 1918 (the year Russia adopted the Gregorian calendar).
!
! CALLING SEQUENCE:
!       jdn = JulianDay( Day, Month, Year )
!
! INPUTS:
!       Day:       The day of the month.
!                  UNITS:      N/A
!                  TYPE:       INTEGER
!                  DIMENSION:  Scalar or any rank
!                  ATTRIBUTES: INTENT(IN)
!
!       Month:     The month of the year (1-12).
!                  UNITS:      N/A
!                  TYPE:       INTEGER
!                  DIMENSION:  Same as Day input
!                  ATTRIBUTES: INTENT(IN)
!
!       Year:      The year in 4-digit format, e.g. 1997.
!                  UNITS:      N/A
!                  TYPE:       INTEGER
!                  DIMENSION:  Same as Day input
!                  ATTRIBUTES: INTENT(IN)
!
! FUNCTION RESULT:
!       jdn:       Julian Day Number.
!                  Return value is negative for invalid input.
!                  UNITS:      N/A
!                  TYPE:       INTEGER
!                  DIMENSION:  Same as Day input
!
! REFERENCES:
!   - http://en.wikipedia.org/wiki/Julian_day
!   - http://www.cs.utsa.edu/~cs1063/projects/Spring2011/Project1/jdn-explanation.html
!
!------------------------------------------------------------------------------

  ELEMENTAL FUNCTION julianday( Day, Month, Year ) RESULT( jdn )
    ! Arguments
    INTEGER, INTENT(IN) :: day
    INTEGER, INTENT(IN) :: month
    INTEGER, INTENT(IN) :: year
    ! Function result
    INTEGER :: jdn
    ! Local variables
    INTEGER :: m, y, a

    jdn = -1
    IF ( year <= 1918 ) RETURN

    ! Compute the number of years and months since March 1, 4801 BCE
    a = (14 - month)/12       !  1 for Jan, 2 for Feb, 0 for other months.
    y = year + 4800 - a       !  Add 4800 to start counting from -4800.
    m = month + (12*a) - 3    !  Pretend the year begins in March and ends in Feb.

    jdn = day + &
          (153*m + 2)/5 + &               !  Number of days in the previous months
          (365*y) + &                     !  Duh.
          (y/4) - (y/100) + (y/400) - &   !  Number of leap years since -4800
          32045                           !  Ensure result is 0 for Jan 1, 4713 BCE.

  END FUNCTION julianday

END MODULE date_utility