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