libchron(3)(TDH) libchron(3)(TDH)
NAMElibchron(3) - date and time library
DESCRIPTIONlibchron is a compact C function library for manipulating dates and
times. Many date notations are supported. Convert dates to other for‐
mats, perform date and time arithmetic, etc.
DATE and TIME notations
Supported date notations and additional info
Supported time notations and additional info
AVAILABLILITYlibchron is bundled with the TDHkit package (http://midriff.source‐
forge.net/tdhkit). To get libchron, download TDHkit, go into the lib‐
src directory, and do make libchron. The source code for libchron is
contained in dates.c and times.c.
HEADER FILES
None.
LIBCHRON FUNCTION LIBRARY
The following is a description of the LIBCHRON C functions, grouped and
ordered by what they do. Functions return 0 on normal completion; oth‐
erwise a non-zero error code is returned indicating that any result
should be discarded.
Date formats
DT_setdatefmt( char *fmt )
Set the current date format to fmt. Dates accepted by most
other functions in the library will then be expected to be in
this format. Available format codes. The default date format
is normally mmddyy.
Example: DT_setdatefmt( "yyyy-mmm-dd" );
DT_getdatefmt( char *fmt )
Get the current date format.
DT_checkdatelengths( int mode )
The default behavior of this library is to require strict con‐
formance to format, with days and months having leading zeros as
required. However this may be relaxed so that days or months
can be legally expressed as single digit quantities. Pass mode
as 0 for relaxed date checking. Pass mode as 1 for strict date
checking.
DT_setlazydates( int lazymonths, int lazydays )
A lazy date is a date where the year and month are known, but
not the day, so the day component is given as 0. Or, perhaps
only the year is known, but a full date is expected, so the day
and month components are both expressed as 0. This library has
a mode where lazy dates can be handled.. to turn this on for
days pass lazydays as 1. Likewise for months. To turn off this
behavior, pass 0. In lazy mode, date arithmetic will be done by
rounding to a midpoint.
Today's date
DT_todaysdate( char *today )
Get the current date, expressed in the current date format.
Converting to and from Julian
DT_jdate( char *indate, long *julian )
Find the julian equivalent of indate. indate must be expressed
in the current date format. It may also be passed as "today".
DT_fromjul( long julian, char *result )
Express julian date in current date format. Dates earlier than
1 Jan 1800 not supported.
DT_getmdy( int *mon, int *day, int *yr )
Get the month, day, and year of date most recently processed by
DT_jdate(). This can be used to get from a formatted date
string to mon, day, yr integers by calling DT_jdate() then
DT_getmdy().
Formatting dates
DT_formatdate( char *indate, char *newformat, char *result )
Convert indate, which must be in the current date format, to a
new format (newformat). newformat can be a date arithmetic
format or a display-only format.
Example: DT_formatdate( "033102", "yyyy-mm-dd", result );
DT_makedate( int yr, int mon, int day, char *format, char *result )
Build a date string expressed in format using integer yr, mon
and day. format may be passed as "" to use current date format.
Note: to convert a string date to mon, day, yr integers, see
DT_getmdy() above.
Date arithmetic
DT_daysdiff( char *date1, char *date2, long *result )
Find the number of days difference between two dates (date1
minus date2). Both dates must be expressed in the current date
format.
Example: DT_daysdiff( "041502", "033102", &ndays );
ndays will be 15.
DT_daysdiff_m( char *date1, char *fmt1, char *date2, char *fmt2, long
*ndays )
Find the number of days difference between two dates which are
in any supported format. fmt1 specifies the format that date1
uses, and fmt2 specifies the format that date2 uses.
DT_dateinrange( char *testdate, char *earlydate, char *latedate )
Determine if testdate is within the range defined by earlydate
and latedate (all should be in current date format).
DT_dateadd( char *date, int ndays, char *result )
Add ndays to date. date must be in current date format.
Example: DT_dateadd( "031803", 21, result );
DT_weekday( char *date, char *result )
Find the weekday that a certain date falls on. date must be in
current date format.
DT_yearsold( char *birthday, char *testdate, int *age )
Compute the age in years between birthdate and testdate (both in
current date format). If using a date format with a 2-digit
year, some heuristics are applied which assume that we are deal‐
ing people's ages relative to a recent timeframe (see dates.c
for more info).
DT_group( char interval, char mode, char *indate, char *outdate )
Adjust indate for grouping or tabulating. interval is one of h
d w m q y to round to nearest hour, day, week, month, quarter,
or year, respectively. mode may be either m or f, to round to
the middle or beginning of the interval, respectively.
This function can accept dates, times, or a date.time eg.
31Jul2003.14:07:22
Example: suppose you have with data containing continuous mix‐
ture of dates and you wish to round them to the middle of the
nearest week for doing counts by week:
DT_group( 'w', 'm', indate, result );
Date settings
DT_setdateparms( char *parmname, char *value )
Allow month names, weekday names, and other parameters to be set
to something other than the (English) defaults. See dates.c for
available parmnames and values, and defaults.
Times
To get the current time in minutes past midnight, use DT_tomin( "now",
&min );
To get the current time expressed in the current time format use
DT_frommin( -1.0, result );
DT_settimefmt( char *format )
Set the current time format
DT_tomin( char *time, double *result )
Take a time in the current time format, and compute the number
of minutes since midnight, as a floating point quantity, eg.
the time 02:01:30 would yield 121.5. Note that the seconds com‐
ponent of time values can contain a decimal portion. time can
be passed as now to get the current time.
DT_frommin( double min, char *result )
Take number of minutes since midnight and return the time repre‐
sented in current time format.
DT_gethms( int *hour, int *min, double *sec )
Get the hour, minute, and second components of the time string
most recently processed with DT_tomin(). Thus you can get from
a time string to hour, min, sec numeric values by calling
DT_tomin() then DT_gethms().
DT_maketime( int hr, int min, double sec, char *result )
Given hr, min, and sec numeric values, build a time string
expressed in the current time format.
DT_formattime( char *intime, char *newformat, char *result )
Take intime and reformat using newformat. newformat can be a
time arithmetic format or a display-only format. newformat can
be a time arithmetic format or a display-only format.
DT_timediff( char *time1, char *time2, double *diff )
Find the difference between two times (time1 minus time2). The
difference (in minutes) will be placed into diff.
Example: DT_timediff( "14:25:30", "14:20:00", &result );
Result will be 5.5
Author
Steve Grubb
25-SEP-2003 TDH scg@jax.org libchron(3)(TDH)
