 Tabular data handling toolkit |
.>> .TH libchron(3) TDH "25-SEP-2003 TDH scg@jax.org" .SH NAME libchron(3) - date and time library .ig >> .>> .SH DESCRIPTION \fBlibchron\fR 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. .ig >> .>> .SH DATE and TIME notations .ig >> .>> \0Supported date notations and additional info .ig >> .>> .LP .ig >> .>> \0Supported time notations and additional info .ig >> .>> .ig >> .>> .SH AVAILABLILITY \fBlibchron\fR is bundled with the TDHkit package (http://midriff.sourceforge.net/tdhkit). To get \fBlibchron\fR, download .ig >> .>> \0TDHkit, .ig >> .>> go into the \fClibsrc\fR directory, and do \fCmake libchron\fR. The source code for libchron is contained in \fCdates.c\fR and \fCtimes.c\fR. .ig >> .>> .SH HEADER FILES None. .ig >> .>> .SH LIBCHRON FUNCTION LIBRARY The following is a description of the LIBCHRON C functions, grouped and ordered by what they do. Functions return \fC0\fR on normal completion; otherwise a non-zero error code is returned indicating that any result should be discarded. .ig >> .>> .SH Date formats .LP \fCDT_setdatefmt( char *fmt ) .IP Set the current date format to \fCfmt\fR. Dates accepted by most other functions in the library will then be expected to be in this format. .ig >> .>> \0Available format codes. .ig >> .>> The default date format is normally \fCmmddyy\fR. .br Example: \fCDT_setdatefmt( "yyyy-mmm-dd" );\fR .ig >> .>> .LP \fCDT_getdatefmt( char *fmt ) .IP Get the current date format. .ig >> .>> .LP \fCDT_checkdatelengths( int mode )\fR .IP 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 \fCmode\fR as 0 for relaxed date checking. Pass \fCmode\fR as 1 for strict date checking. .ig >> .>> .LP \fCDT_setlazydates( int lazymonths, int lazydays )\fR .IP A lazy date is a date where the year and month are known, but not the day, so the day component is given as \fC0\fR. Or, perhaps only the year is known, but a full date is expected, so the day and month components are both expressed as \fC0\fR. This library has a mode where lazy dates can be handled.. to turn this on for days pass \fClazydays\fR 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. .ig >> .>> .SH Today's date .LP \fCDT_todaysdate( char *today )\fR .IP Get the current date, expressed in the current date format. .ig >> .>> .SH Converting to and from Julian \fCDT_jdate( char *indate, long *julian )\fR .IP Find the julian equivalent of \fCindate\fR. \fCindate\fR must be expressed in the current date format. It may also be passed as \fC"today"\fR. .ig >> .>> \fCDT_fromjul( long julian, char *result )\fR .IP Express \fCjulian\fR date in current date format. Dates earlier than 1 Jan 1800 not supported. .ig >> .>> \fCDT_getmdy( int *mon, int *day, int *yr )\fR .IP Get the month, day, and year of date most recently processed by \fCDT_jdate()\fR. This can be used to get from a formatted date string to mon, day, yr integers by calling DT_jdate() then DT_getmdy(). .ig >> .>> .SH Formatting dates .LP \fCDT_formatdate( char *indate, char *newformat, char *result )\fR .IP Convert \fCindate\fR, which must be in the current date format, to a new format (\fCnewformat\fR). \fCnewformat\fR can be a .ig >> .>> \0date arithmetic format or a display-only format. .ig >> .>> .br Example: \fCDT_formatdate( "033102", "yyyy-mm-dd", result );\fR .LP \fCDT_makedate( int yr, int mon, int day, char *format, char *result )\fR .IP Build a date string expressed in \fCformat\fR using integer \fCyr\fR, \fCmon\fR and \fCday\fR. \fCformat\fR may be passed as \fC""\fR to use current date format. Note: to convert a string date to mon, day, yr integers, see DT_getmdy() above. .ig >> .>> .SH Date arithmetic .LP \fCDT_daysdiff( char *date1, char *date2, long *result )\fR .IP Find the number of days difference between two dates (\fCdate1\fR minus \fCdate2\fR). Both dates must be expressed in the current date format. .br Example: \fCDT_daysdiff( "041502", "033102", &ndays ); .br \fCndays\fR will be 15. .ig >> .>> .LP \fCDT_daysdiff_m( char *date1, char *fmt1, char *date2, char *fmt2, long *ndays )\fR .IP Find the number of days difference between two dates which are in any supported format. \fCfmt1\fR specifies the format that \fCdate1\fR uses, and \fCfmt2\fR specifies the format that \fCdate2\fR uses. .ig >> .>> .LP \fCDT_dateinrange( char *testdate, char *earlydate, char *latedate )\fR .IP Determine if \fCtestdate\fR is within the range defined by \fCearlydate\fR and \fClatedate\fR (all should be in current date format). .ig >> .>> .LP \fCDT_dateadd( char *date, int ndays, char *result )\fR .IP Add \fCndays\fR to \fCdate\fR. \fCdate\fR must be in current date format. .br Example: \fCDT_dateadd( "031803", 21, result );\fR .ig >> .>> .LP \fCDT_weekday( char *date, char *result )\fR .IP Find the weekday that a certain date falls on. \fCdate\fR must be in current date format. .ig >> .>> .LP \fCDT_yearsold( char *birthday, char *testdate, int *age )\fR .IP Compute the age in years between \fCbirthdate\fR and \fCtestdate\fR (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). .ig >> .>> .LP \fCDT_group( char interval, char mode, char *indate, char *outdate )\fR .IP Adjust \fCindate\fR for grouping or tabulating. \fCinterval\fR is one of \fCh d w m q y\fR to round to nearest hour, day, week, month, quarter, or year, respectively. \fCmode\fR may be either \fCm\fR or \fCf\fR, to round to the middle or beginning of the interval, respectively. .IP This function can accept dates, times, or a date.time eg. \fC31Jul2003.14:07:22\fR .IP 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: .br \fCDT_group( 'w', 'm', indate, result );\fR .ig >> .>> .SH Date settings .LP \fCDT_setdateparms( char *parmname, char *value )\fR .IP Allow month names, weekday names, and other parameters to be set to something other than the (English) defaults. See \fCdates.c\fR for available parmnames and values, and defaults. .ig >> .>> .ig >> .>> .ig >> .>> .SH Times To get the current time in minutes past midnight, use \fCDT_tomin( "now", &min );\fR .br To get the current time expressed in the current time format use \fCDT_frommin( -1.0, result ); .ig >> .>> .LP \fCDT_settimefmt( char *format )\fR .IP Set the current .ig >> .>> \0time format .ig >> .>> .ig >> .>> .LP \fCDT_tomin( char *time, double *result )\fR .IP Take a time in the current time format, and compute the number of minutes since midnight, as a floating point quantity, eg. the time \fC02:01:30\fR would yield \fC121.5\fR. Note that the seconds component of time values can contain a decimal portion. \fCtime\fR can be passed as \fCnow\fR to get the current time. .ig >> .>> .LP \fCDT_frommin( double min, char *result )\fR .IP Take number of minutes since midnight and return the time represented in current time format. .ig >> .>> .LP \fCDT_gethms( int *hour, int *min, double *sec )\fR .IP Get the hour, minute, and second components of the time string most recently processed with \fCDT_tomin()\fR. Thus you can get from a time string to hour, min, sec numeric values by calling \fCDT_tomin()\fR then \fCDT_gethms()\fR. .ig >> .>> .LP \fCDT_maketime( int hr, int min, double sec, char *result )\fR .IP Given \fChr\fR, \fCmin\fR, and \fCsec\fR numeric values, build a time string expressed in the current time format. .ig >> .>> .LP \fCDT_formattime( char *intime, char *newformat, char *result )\fR .IP Take \fCintime\fR and reformat using \fCnewformat\fR. \fCnewformat\fR can be a time arithmetic format or a display-only format. \fCnewformat\fR can be a .ig >> .>> \0time arithmetic format or a display-only format. .ig >> .>> .ig >> .>> .LP \fCDT_timediff( char *time1, char *time2, double *diff )\fR .IP Find the difference between two times (\fCtime1\fR minus \fCtime2\fR). The difference (in minutes) will be placed into \fCdiff\fR. .br Example: \fCDT_timediff( "14:25:30", "14:20:00", &result );\fR .br Result will be \fC5.5\fR .ig >> .>> .SH Author .ig >> .>> \0Steve Grubb .ig >> .>> .ig >> |
Tabular data handling toolkit Copyright Steve Grubb |