docs/user/support/parsedate.dox

   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 */