Macros | Functions
parsedate.h File Reference

Date parsing functions. More...

Macros

#define PARSEDATE_DAY_RELATIVE_TIME   PARSEDATE_RELATIVE_TIME
 day relative time More...
 
#define PARSEDATE_INVALID_DATE   0x0100
 invalid date string More...
 
#define PARSEDATE_MINUTE_RELATIVE_TIME   0x0002
 minute relative time More...
 
#define PARSEDATE_RELATIVE_TIME   0x0001
 relative time More...
 

Functions

const char ** get_dateformats (void)
 returns the internal format table currently used by parsedate() More...
 
time_t parsedate (const char *dateString, time_t now)
 Parses dateString relative to relativeTo. More...
 
time_t parsedate_etc (const char *dateString, time_t now, int *_storedFlags)
 Parses dateString relative to relativeTo More...
 
void set_dateformats (const char *table[])
 sets the internal format table for parsedate() More...
 

Detailed Description

Date parsing functions.

This is a set a functions for parsing date strings in various formats. It's mostly tailored for parsing user given data, although originally, it was developed to parse the date strings found in usenet messages.

The given date will be parsed relative to the specified time, and using a predefined set of time/date formats.

Valid Input Strings

The internal formats allow parsedate() to understand a wide range of input strings. The format list is ought to be compiled from the Date: line of 80.000 usenet messages.

But since this function is also used in end-user applications like the Tracker's find panel, it's helpful to know what this function accepts and what not.

Here are some examples of input strings that parsedate() will be able to convert along with some notes:

Format Specifier

While the get_dateformats() function allow you to retrieve the built-in formats, you can also define your own and use set_dateformats() to let parsedate() use them in all subsequent calls.

The following is a list valid format specifiers and their meanings:

Any of ",.:" is allowed and will be expected in the input string as is. You can enclose a single field with "[]" to mark it as being optional. A blank stands for white space. No other character is allowed. An invalid format string won't do any harm, but of course, no input string will ever match that format.

For example, "H:M [p]" will match against "21:33", "4:12 am", but not "30:30 pm" (hours out of range), "15:16 GMT" (this time zone is certainly not a valid meridian specifier), or "4:66" (minutes out of range).

Note
At the time of this writing, the parsedate() functions are not localized and will only recognize English time specifications following the examples above.

Macro Definition Documentation

◆ PARSEDATE_DAY_RELATIVE_TIME

#define PARSEDATE_DAY_RELATIVE_TIME   PARSEDATE_RELATIVE_TIME

day relative time

The time value was computed relative to the specified time, and it would vary with every day passed in the specified time.

◆ PARSEDATE_INVALID_DATE

#define PARSEDATE_INVALID_DATE   0x0100

invalid date string

This flag will be set if the specified date string could not be parsed correctly. For example, this may happen if there are some unknown words in that string.

◆ PARSEDATE_MINUTE_RELATIVE_TIME

#define PARSEDATE_MINUTE_RELATIVE_TIME   0x0002

minute relative time

The time value was computed relative to the specified time, and it would vary with every minute passed in the specified time.

◆ PARSEDATE_RELATIVE_TIME

#define PARSEDATE_RELATIVE_TIME   0x0001

relative time

The time value was computed relative to the specified time.

Function Documentation

◆ get_dateformats()

const char ** get_dateformats ( void  )

returns the internal format table currently used by parsedate()

Returns the internal format table currently used by parsedate() - this is either a pointer to the built-in one, or one that you have previously set using set_dateformats().

See also
set_dateformats()

◆ parsedate()

time_t parsedate ( const char *  dateString,
time_t  relativeTo 
)

Parses dateString relative to relativeTo.

Parses the given dateString relative to the time specified by relativeTo using the internal formats table.

Parameters
dateStringthe date that should be parsed, i.e. "next thursday".
relativeToall relative dates will be relative to this time, if -1 is passed, the current time will be used.
Returns
The parsed time value or -1 if the dateString could not be parsed.

◆ parsedate_etc()

time_t parsedate_etc ( const char *  dateString,
time_t  relativeTo,
int *  _storedFlags 
)

Parses dateString relative to relativeTo

This does basically the same as parsedate(), but will set the following flags in _storedFlags:

ConstantMeaning
PARSEDATE_RELATIVE_TIME relative time \copydetails PARSEDATE_RELATIVE_TIME \htmlonly
PARSEDATE_DAY_RELATIVE_TIME day relative time \copydetails PARSEDATE_DAY_RELATIVE_TIME \htmlonly
PARSEDATE_MINUTE_RELATIVE_TIME minute relative time \copydetails PARSEDATE_MINUTE_RELATIVE_TIME \htmlonly
PARSEDATE_INVALID_DATE invalid date string \copydetails PARSEDATE_INVALID_DATE \htmlonly This flag will only be set if the function returns -1.

◆ set_dateformats()

void set_dateformats ( const char *  formatTable[])

sets the internal format table for parsedate()

This function let you set the format table which is used by parsedate(). When formatTable is NULL, the standard built-in format table will be set again.

Parameters
formatTablethe NULL terminated formats list. This list must stay valid when using parsedate() - it is not copied, but directly used.
See also
parsedateFormats Format!