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