# libdate(n) 1.0 "flibs"

## NAME

libdate - Manipulating date/time information

## TABLE OF CONTENTS

TABLE OF CONTENTS
SYNOPSIS
DESCRIPTION
DERIVED TYPES AND ROUTINES
ACKNOWLEDGEMENTS
COPYRIGHT

## SYNOPSIS

type(DATETYPE) date
type(JULIANDATETYPE) julian
relational operators
newdate = basedate + timestep
newdate = basedate - timestep
newstep = factor * timestep
newstep = timestep * factor
timelag_in_days = timelag( date1, date2 )
seconds = delayseconds( timestep )
isleap = leapyear( date )
daynumber = doy( date )
earlier = mindate( date1, date2 )
later = maxdate( date1, date2 )
call format_date( date, pattern, datestring )
julian = date2julian( date )
date = julian2date( julian )

## DESCRIPTION

The libdate module defines a derived type and several functions and subroutines to deal with date/time information:

- Store date and time in the form of year, month, day, hour, minute
- Compare dates
- Basic arithmetic
- Formatting date and time as a string based on a pattern

Note: Timezones and seconds are not taken into account. Also, there are no provisions to take care of the various historical introductions of the Gregorian calendar.

## DERIVED TYPES AND ROUTINES

The module libdate defines two separate derived types, DATETYPE and JULIANDATETYPE, though this second type is mainly meant for internal use:

type(DATETYPE) date
  This type has the following fields: year, month, day, hour, minute, in that order, so that thisdate = datetype( 2007, 1, 29, 17, 0) defines a date 29 january 2007 and a time 17:00.
  A duration is expressed in days, hours and minutes: period = datetype( 0, 0, 2, 1, 0) means a period of 2 days and and 1 hour. (When adding a duration to a date/time the month and year fields are ignored, as they are not additive).
type(JULIANDATETYPE) julian
  Julian dates are used internally to make the computations easier. You should not need to use them explicitly, unless you want to implement new functionality.

The following functions, subroutines and operators are available:

relational operators
  You can compare two dates using the standard operators .EQ., .NE., .GE., .GT., .LE., .LT., with conventional meaning
newdate = basedate + timestep
  Add a duration to a date. The second date/time is considered to be the duration.
  type(DATETYPE) basedate
    The base date/time to which the duration is to be added.
  type(DATETYPE) timestep
    The duration that will be added. Only the day, hour and minute fields are considered.
newdate = basedate - timestep
  Subtract a duration from a date. The second date/time is considered to be the duration.
  type(DATETYPE) basedate
    The base date/time from which the duration is to be subtracted.
  type(DATETYPE) timestep
    The duration that will be subtracted. Only the day, hour and minute fields are considered.
newstep = factor * timestep
  Multiply a timestep by a real or integer factor. For the timestep, only the day, hour and minute are considered.
  integer/real factor
    Factor to be applied
  type(DATETYPE) timestep
    The duration that will be scaled.
newstep = timestep * factor
  Multiply a timestep by a real or integer factor. For the timestep, only the day, hour and minute are considered. (The order of teh arguments is reversed).
timelag_in_days = timelag( date1, date2 )
  Compute the time difference between two dates. Return the value in days.
  type(DATETYPE) date1
    First date
  type(DATETYPE) date2
    Second date. If this date is earlier than the first date, the difference is positive.
seconds = delayseconds( timestep )
  Compute the number of seconds in a timestep
  type(DATETYPE) timestep
    Timestep to be converted to seconds
isleap = leapyear( date )
  Determine if the year in the date structure is a leap year or not
  type(DATETYPE) date
    Date/time to be considered (only the year is of interest of course).
daynumber = doy( date )
  Compute the day of the year
  type(DATETYPE) date
    Date/time to be considered.
earlier = mindate( date1, date2 )
  Return the earlier of the two dates
  type(DATETYPE) date1
    First date/time to be considered.
  type(DATETYPE) date2
    Second date/time to be considered.
later = maxdate( date1, date2 )
  Return the later of the two dates
  type(DATETYPE) date1
    First date/time to be considered.
  type(DATETYPE) date2
    Second date/time to be considered.
call format_date( date, pattern, datestring )
  Format a date according to a pattern.
  The pattern may contain any of the following format codes:
  - dd - Day of month ("01" for instance)
  - ds - Day of month ("1" for instance, s for space)
  - DDD - Day of the year
  - HH - Hour (00-23)
  - HS - Hour (0-23)
  - mm - Month ("01" for january)
  - ms - Month ("1" for january, s for space)
  - MM - Minutes within the hour (00-59)
  - MS - Minutes within the hour (0-59)
  - YY - Year with the century
  - yyyy - Year with the century
  type(DATETYPE) date
    Date to be converted
  character(len=*) pattern
    String containing the format pattern
  character(len=*) datestring
    String containing the result. The contents will not be longer than the pattern.
julian = date2julian( date )
  Convert a date/time structure to Julian date. Mainly for internal use.
  type(DATETYPE) date
    Date/time structure to be converted.
date = julian2date( julian )
  Convert a Julian date to a date/time structure. Mainly for internal use.
  type(JULIANDATETYPE) julian
    Julian date to be converted.

## ACKNOWLEDGEMENTS

This module was written and contributed by Arjan van Dijk. Small modifications and the addition of the format_date routine by Arjen Markus.

## COPYRIGHT

Copyright © 2008 Arjan van Dijk <arjan dot van dijk at rivm dot nl>
Copyright © 2008 Arjen Markus <arjenmarkus at sourceforge dot net>