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