 Tabular data handling toolkit |
Manual page for libchron(3)(TDH)
libchron(3) - date and time library
DESCRIPTION
libchron is a compact C function library for
manipulating dates and times. Many date notations are supported.
Convert dates to other formats, perform date and time arithmetic, etc.
DATE and TIME notations
Supported date notations and additional info
Supported time notations and additional info
AVAILABLILITY
libchron is bundled with the TDHkit package
(http://midriff.sourceforge.net/tdhkit).
To get libchron, download
TDHkit,
go into the libsrc 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;
otherwise 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 conformance 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 dealing
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 mixture 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 component 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 represented 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
|
 Tabular data handling toolkit
Copyright Steve Grubb
|