cdtime(3)

NAME
CDMS C and FORTRAN time conversion and arithmetic functions.

SYNOPSIS (C ROUTINES)

#include "cdms.h"

int cdAbs2Comp(char* absunits, void* abstime, cdType abstimetype, cdCompTime* comptime, double* frac)

void cdChar2Comp(cdCalenType timetype, char* chartime, cdCompTime* comptime)

void cdChar2Rel(cdCalenType timetype, char* chartime, char* relunits, double* reltime)

int cdComp2Abs(cdCompTime comptime, char* absunits, cdType abstimetype, double frac, void* abstime)

void cdComp2Char(cdCalenType timetype, cdCompTime comptime, char* chartime)

void cdComp2Rel(cdCalenType timetype, cdCompTime comptime, char* relunits, double* reltime)

void cdRel2Char(cdCalenType timetype, char* relunits, double reltime, char* chartime)

void cdRel2Comp(cdCalenType timetype, char* relunits, double reltime, cdCompTime* comptime)

void cdRel2Rel(cdCalenType timetype, char* inunits, double intime, char* newunits, double* outtime)

SYNOPSIS (FORTRAN ROUTINES)

include 'cdms.inc'

subroutine fcdchar2comp(integer timetype, character*(*) chartime, integer year, integer month, integer day, double precision hour)

subroutine fcdchar2rel(integer timetype, character*(*) chartime, character*(*) relunits, double precision reltime)

subroutine fcdcomp2char(integer timetype, integer year, integer month, integer day, double precision hour, character*(*) chartime)

subroutine fcdcomp2rel(integer timetype, integer year, integer month, integer day, double precision hour, character*(*) relunits, double precision reltime)

subroutine fcdrel2char(integer timetype, character*(*) relunits, double precision reltime, character*(*) chartime)

subroutine fcdrel2comp(integer timetype, character*(*) relunits, double precision reltime, integer year, integer month, integer day, double precision hour)

subroutine fcdrel2rel(integer timetype, character*(*) inunits, double precision intime, character*(*) newunits, double precision outtime)

DESCRIPTION

These functions convert between representations of time values.

CDMS supports the following calendar types:

    cdStandard
        Standard Gregorian calendar
    cdJulian
        Julian calendar, only years divisible by four are leap years
    cdMixed
        Mixed Julian/Gregorian calendar
    cdNoLeap
        365 days/year, no leap years
    cd360
        Each year is 12 30-day months
    cdClim
        Climatological time (no associated year), 365 days
    cdClimLeap
        Climatological time, 366 days

For any calendar, CDMS supports four representations of time values: character time (chartime), relative time (reltime), component time (comptime), and absolute time (abstime).

Character time values have the form "yyyy[-mm[-dd[ hh[:mi[:ss]]]]]", where yyyy is the four-digit year, mm is the month number (1 .. 12), dd is the day number (1 .. 31), hh is the hour, mi is the minute, and ss is the floating-point seconds. For climatological time, the year is omitted. Any trailing portion is optional. If omitted, mm and dd default to 1, hh, mi and ss default to 0.

Relative time values have two parts: value and units. The value is of datatype double. The relative units are a character string of the form "n unit(s)[ since chartime]", where n is the number of units, unit is one of: second, minute, hour, day, week, month, season, year, or one of the abbreviations: s, mn, hr, dy, wk, mo, or yr, and chartime is the basetime. The since clause is optional. If omitted, the basetime defaults to "1979-01-01". If the units are in months, seasons, or years, the fractional part of the time value is ignored.

Component time values consist of the four components year, month, day, and hour. Hour is floating-point, the other components are integers. Predefined values are: (for year) CD_NULL_YEAR, (for month) CD_NULL_MONTH, cdJan, cdFeb, cdMar, cdApr, cdMay, cdJun, cdJul, cdAug, cdSep, cdOct, cdNov, cdDec, (for day) CD_NULL_DAY, CD_LAST_DAY (of month), and (for hour) CD_NULL_HOUR are recognized.

Absolute time consists of two parts, value and units. The value is of type float, double, int, or long. The units are a character string of the form "unit as format", where unit is one of second, minute, hour, day, calendar_month, or calendar_year. format is a string of the form "%x[%x[...]][.%f]", where x is one of the format letters 'Y' (year, including century), 'm' (two digit month, 01=January), 'd' (two-digit day within month), 'H' (hours since midnight), 'M' (minutes since midnight), or 'S' (seconds since midnight). The optional '.%f' denotes a floating-point fraction of the unit. If the fraction is present, the corresponding value has type float or double, otherwise it is long or int. For more information on the absolute time representation, see http://www-pcmdi.llnl.gov/drach/GDT_convention.html.

FUNCTION ARGUMENTS
timetype arguments are of value cdStandard, cdJulian, cdNoLeap, cd360, cdClim, or cdClimLeap.

chartime arguments are null-terminated character strings of maximum length CD_MAX_CHARTIME.

Relative units arguments (relunits) are null-terminated character strings of maximum length CD_MAX_RELUNITS.

Absolute units arguments (absunits) are null-terminated character strings of maximum length CD_MAX_ABSUNITS.

A cdCompTime argument is a structure with members:

    long	year;	/* year */
    short	month;	/* numerical month, 1..12 */
    short	day;	/* day of month, 1..31 */
    double	hour;	/* hour and fractional hour */

For FORTRAN subroutines, the comptime argument is replaced with four arguments: year, month, day, and hour. hour is double precision, while year, month, and day are integers.

FUNCTION DESCRIPTIONS

(C) int cdAbs2Comp(char* absunits, void* abstime, cdType abstimetype, cdCompTime* comptime, double* frac)

Convert from absolute time to component time comptime. abstimetype is the datatype of abstime, one of cdDouble, cdFloat, cdLong, or cdInt. frac is the fractional part, or 0.0 if abstimetype equals cdInt or cdLong. If the unit is one of day, hour, minute, or second, the fractional part is also incorporated into comptime->hour. The function returns 0 on success, 1 on failure.

(C) void cdChar2Comp(cdCalenType timetype, char* chartime, cdCompTime* comptime)

(FORTRAN) subroutine fcdchar2comp(integer timetype, character*(*) chartime, integer year, integer month, integer day, double precision hour)

Convert from character time chartime to component time comptime.

(C) void cdChar2Rel(cdCalenType timetype, char* chartime, char* relunits, double* reltime)

(FORTRAN) subroutine fcdchar2rel(integer timetype, character*(*) chartime, character*(*) relunits, double precision reltime)

Convert from character time to relative time. Given character time chartime and relative units relunits, return relative time value reltime.

(C) int cdComp2Abs(cdCompTime comptime, char* absunits, cdType abstimetype, double frac, void* abstime)

Convert from component time to absolute time. Given comptime and absolute time units absunits, the desired datatype abstimetype (one of cdDouble, cdFloat, cdInt, or cdLong) and the fractional part frac (0.0 if none), the absolute time is returned in abstime. frac is only used if the unit is calendar_month or calendar_year, and the type is cdDouble or cdFloat. Otherwise, the fractional part is derived from comptime.hour. The function returns 0 on success, 1 on failure.

(C) void cdComp2Char(cdCalenType timetype, cdCompTime comptime, char* time)

(FORTRAN) subroutine fcdcomp2char(integer timetype, integer year, integer month, integer day, double precision hour, character*(*) chartime)

Convert from component time comptime to character time chartime.

(C) void cdComp2Rel(cdCalenType timetype, cdCompTime comptime, char* relunits, double* reltime)

(FORTRAN) subroutine fcdcomp2rel(integer timetype, integer year, integer month, integer day, double precision hour, character*(*) relunits, double precision reltime)

Convert from component time to relative time. Given comptime and relative time units relunits, return relative time value reltime.

(C) void cdRel2Char(cdCalenType timetype, char* relunits, double reltime, char* chartime)

(FORTRAN) subroutine fcdrel2char(integer timetype, character*(*) relunits, double precision reltime, character*(*) chartime)

Convert from relative time (reltime, relunits) to character time chartime. If relunits is in months, seasons, or years, the fractional portion of reltime is ignored.

(C) void cdRel2Comp(cdCalenType timetype, char* relunits, double reltime, cdCompTime* comptime)

(FORTRAN) subroutine fcdrel2comp(integer timetype, character*(*) relunits, double precision reltime, integer year, integer month, integer day, double precision hour)

Convert from relative time (reltime, relunits) to component time comptime. If relunits is in months, seasons, or years, the fractional portion of reltime is ignored.

(C) void cdRel2Rel(cdCalenType timetype, char* inunits, double intime, char* newunits, double* outtime)

(FORTRAN) subroutine fcdrel2rel(integer timetype, character*(*) inunits, double precision intime, character*(*) newunits, double precision outtime)

Convert from relative time to relative time. Given input time (intime, inunits), and output units newunits, return output relative time value outtime. If inunits is in months, seasons, or years, the fractional portion of intime is ignored. Similarly, if the newunits is in months, seasons, or years, the day and hour component of the input time, after conversion to component time, is ignored.

EXAMPLES

Example (FORTRAN): Convert 89088 "hours since 1970" to "months since 1979":

     include 'cdms.inc'
     double precision months
     fcdrel2rel(CD_STANDARD, "hours since 1970", 89088.0,
    $           "months since 1979", months)

Example (C): Find the number of hours from January 1, 1900 0:0, to July 4, 1994, 10:37, using a standard calendar type:

    #include "cdms.h"
    double hours;
    cdChar2Rel( cdStandard, "1994-7-4 10:37",
                "hours since 1900", &hours);

Example (C): Break the character time "1994-7-4 10:37" into components:

    #include "cdms.h"
    cdCompTime time;
    cdChar2Comp(cdStandard, "1994-7-4 10:37", &time);

Example (C): Convert year=1994, month=July, to "months since 1900:

    #include "cdms.h"
    cdCompTime time;
    double months;
    time.year = 1994;
    time.month = cdJul;
    time.day = cdNullDay;
    time.hour = cdNullHour;
    cdComp2Rel(cdStandard, time, "months since 1900", &months);

Example (C): In climatological time, find the day which is 300 days past March 31:

    #include "cdms.h"
    double doy, result;
    cdChar2Rel( cdClim, "3-31", "days", &doy);
    cdRel2Rel( cdClim, "days", doy+300, "days", &result);

SEE ALSO
cdunif(3)

BUGS