1/** \file parsedate.h 2\brief date parsing functions 3 4This is a set a functions for parsing date strings in various formats. 5It's mostly tailored for parsing user given data, although originally, 6it was developed to parse the date strings found in usenet messages. 7 8The given date will be parsed relative to the specified time, and using 9a predefined set of time/date formats. 10 11\par Valid Input Strings 12 13The internal formats allow parsedate() to understand a wide range of 14input strings. The format list is ought to be compiled from the Date: 15line of 80.000 usenet messages. 16 17But since this function is also used in end-user applications like the 18Tracker's find panel, it's helpful to know what this function accepts 19and what not. 20 21Here are some examples of input strings that parsedate() will be able 22to convert along with some notes: 23 - "last friday", "this wednesday", "next July" 24 "last", "next", and "this" refer to the week or year (depending 25 on the context). So "last friday" means last week's friday. 26 "This wednesday" is referring to this week's wednesday, no matter 27 if it has already passed or not. 28 "Next July" refers to next year's July. All of these dates are 29 parsed relative to the specified time (usually "now"), and will 30 be set to the first moment of that time span: "next monday" is 31 monday, 0:00:00, midnight. 32 - "now" just returns the time all calculations are relative to. 33 - "next 5 minutes", "5 minutes", "+5 mins" all mean the same thing, 34 that is, current time plus exactly 5 minutes. 35 - "5 weeks" means in 5 weeks from now on. 36 - "8/5/2003", "5.8.2003", "2003-08-05" are all referring to August 37 5th, 2003, again at 0:00 midnight. 38 - "Thursday 3:00" means this week's thursday, at 3 o'clock. 39 40\anchor parsedateFormats 41\par Format Specifier 42 43While the get_dateformats() function allow you to retrieve the built-in 44formats, you can also define your own and use set_dateformats() to let 45parsedate() use them in all subsequent calls. 46 47The following is a list valid format specifiers and their meanings. 48 49 - \b a/A weekday (Sunday, Monday, ...) 50 - \b d day of month (1-31) 51 - \b b/B month name (January, February, ...) 52 - \b month (1-12) 53 - \b y/Y year 54 - \b H/I hours (1-24) 55 - \b M minutes (0-60) 56 - \b S seconds (0-60) 57 - \b p meridian (am/pm) 58 - \b z/Z time zone (i.e. GMT) 59 - \b T time unit, like "last friday", "next 5 minutes", "-15 hours", etc. 60 - \b - dash or slash 61 62Any of ",.:" is allowed and will be expected in the input string as is. 63You can enclose a \b single field with "[]" to mark it as being optional. 64A blank stands for white space. No other character is allowed. 65An invalid format string won't do any harm, but of course, no input string 66will ever match that format. 67 68For example, "H:M [p]" will match against "21:33", "4:12 am", but not "30:30 pm" 69(hours out of range), "15:16 GMT" (this time zone is certainly not a valid 70meridian specifier), or "4:66" (minutes out of range). 71 72\par Note: 73At the time of this writing, the parsedate() functions are not localized and 74will only recognize English time specifications following the examples above. 75 76*/ 77 78/** \def PARSEDATE_RELATIVE_TIME 79\brief relative time 80 81The time value was computed relative to the specified time. 82*/ 83 84/** \def PARSEDATE_DAY_RELATIVE_TIME 85\brief day relative time 86 87The time value was computed relative to the specified time, and it would vary with 88every day passed in the specified time. 89*/ 90 91/** \def PARSEDATE_MINUTE_RELATIVE_TIME 92\brief minute relative time 93 94The time value was computed relative to the specified time, and it would vary with 95every minute passed in the specified time. 96*/ 97 98/** \def PARSEDATE_INVALID_DATE 99\brief invalid date string 100 101This flag will be set if the specified date string could not be parsed correctly. 102For example, this may happen if there are some unknown words in that string. 103*/ 104 105/** \fn time_t parsedate(const char *dateString, time_t relativeTo) 106\brief Parses <span class="var">dateString</span> relative to <span class="var">relativeTo</span> 107 108Parses the given <span class="var">dateString</span> relative to the time 109specified by <span class="var">relativeTo</span> using the internal formats 110table. 111 112\param dateString the date that should be parsed, i.e. "next thursday" 113\param relativeTo all relative dates will be relative to this time, if -1 is passed, the current time will be used 114\return the parsed time value or -1 if the <span class="var">dateString</span> 115could not be parsed. 116*/ 117 118/** \fn time_t parsedate_etc(const char *dateString, time_t relativeTo, int *_storedFlags) 119\brief Parses <span class="var">dateString</span> relative to <span class="var">relativeTo</span> 120 121This does basically the same as parsedate(), but will set the following 122flags in <span class="var">_storedFlags</span>: 123\htmlonly 124 <table border=1> 125<!-- ToDo: this certainly is a hack --> 126 <tr><th bgcolor="#eeeeee">Constant</th><th bgcolor="#eeeeee">Meaning</th></tr> 127 <tr><td class="mdname1">PARSEDATE_RELATIVE_TIME</td> 128 <td>\endhtmlonly \copydoc PARSEDATE_RELATIVE_TIME \htmlonly 129 </td></tr> 130 <tr><td class="mdname1">PARSEDATE_DAY_RELATIVE_TIME</td> 131 <td>\endhtmlonly \copydoc PARSEDATE_DAY_RELATIVE_TIME \htmlonly 132 </td></tr> 133 <tr><td class="mdname1">PARSEDATE_MINUTE_RELATIVE_TIME</td> 134 <td>\endhtmlonly \copydoc PARSEDATE_MINUTE_RELATIVE_TIME \htmlonly 135 </td></tr> 136 <tr><td class="mdname1">PARSEDATE_INVALID_DATE</td> 137 <td> 138 \endhtmlonly \copydoc PARSEDATE_INVALID_DATE \htmlonly 139 This flag will only be set if the function returns -1. 140 </td></tr> 141 </table> 142\endhtmlonly 143*/ 144 145/** \fn void set_dateformats(const char *formatTable[]) 146\brief sets the internal format table for parsedate() 147 148This function let you set the format table which is used by parsedate(). 149When <span class="var">formatTable</span> is NULL, the standard built-in format table will be set again. 150\param formatTable the NULL terminated formats list. This list must stay 151 valid when using parsedate() - it is not copied, but directly used. 152\see 153 \ref parsedateFormats Format! 154 155*/ 156 157/** \fn const char **get_dateformats(void) 158\brief returns the internal format table currently used by parsedate() 159 160Returns the internal format table currently used by parsedate() - this is 161either a pointer to the built-in one, or one that you have previously 162set using set_dateformats(). 163 164\see 165 \ref set_dateformats() 166*/ 167 168