Added doxygen documentation for the parsedate() function.
Tried to get right with doxygen, but it ain't easy... git-svn-id: file:///srv/svn/repos/haiku/trunk/current@4386 a95241bf-73f2-0310-859d-f6bbb57e9c96
This commit is contained in:
Axel Dörfler
parent
d3fdd732fa
commit
4d00ee5ddd
163
docs/user/support/parsedate.dox
Normal file
163
docs/user/support/parsedate.dox
Normal file
@ -0,0 +1,163 @@
|
||||
/** \file parsedate.h
|
||||
This is a set a functions for parsing date strings in various formats.
|
||||
It's mostly tailored for parsing user given data, although originally,
|
||||
it was developed to parse the date strings found in usenet messages.
|
||||
|
||||
The given date will be parsed relative to the specified time, and using
|
||||
a predefined set of time/date formats.
|
||||
|
||||
\par Valid Input Strings
|
||||
|
||||
The internal formats allow parsedate() to understand a wide range of
|
||||
input strings. The format list is ought to be compiled from the Date:
|
||||
line of 80.000 usenet messages.
|
||||
|
||||
But since this function is also used in end-user applications like the
|
||||
Tracker's find panel, it's helpful to know what this function accepts
|
||||
and what not.
|
||||
|
||||
Here are some examples of input strings that parsedate() will be able
|
||||
to convert along with some notes:
|
||||
- "last friday", "this wednesday", "next July"
|
||||
"last", "next", and "this" refer to the week or year (depending
|
||||
on the context). So "last friday" means last week's friday.
|
||||
"This wednesday" is referring to this week's wednesday, no matter
|
||||
if it has already passed or not.
|
||||
"Next July" refers to next year's July. All of these dates are
|
||||
parsed relative to the specified time (usually "now"), and will
|
||||
be set to the first moment of that time span: "next monday" is
|
||||
monday, 0:00:00, midnight.
|
||||
- "now" just returns the time all calculations are relative to.
|
||||
- "next 5 minutes", "5 minutes", "+5 mins" all mean the same thing,
|
||||
that is, current time plus exactly 5 minutes.
|
||||
- "5 weeks" means in 5 weeks from now on.
|
||||
- "8/5/2003", "5.8.2003", "2003-08-05" are all referring to August
|
||||
5th, 2003, again at 0:00 midnight.
|
||||
- "Thursday 3:00" means this week's thursday, at 3 o'clock.
|
||||
|
||||
\anchor parsedateFormats
|
||||
\par Format Specifier
|
||||
|
||||
While the get_dateformats() function allow you to retrieve the built-in
|
||||
formats, you can also define your own and use set_dateformats() to let
|
||||
parsedate() use them in all subsequent calls.
|
||||
|
||||
The following is a list valid format specifiers and their meanings.
|
||||
|
||||
- \b a/A weekday (Sunday, Monday, ...)
|
||||
- \b d day of month (1-31)
|
||||
- \b b/B month name (January, February, ...)
|
||||
- \b month (1-12)
|
||||
- \b y/Y year
|
||||
- \b H/I hours (1-24)
|
||||
- \b M minutes (0-60)
|
||||
- \b S seconds (0-60)
|
||||
- \b p meridian (am/pm)
|
||||
- \b z/Z time zone (i.e. GMT)
|
||||
- \b T time unit, like "last friday", "next 5 minutes", "-15 hours", etc.
|
||||
- \b - dash or slash
|
||||
|
||||
Any of ",.:" is allowed and will be expected in the input string as is.
|
||||
You can enclose a \b single field with "[]" to mark it as being optional.
|
||||
A blank stands for white space. No other character is allowed.
|
||||
An invalid format string won't do any harm, but of course, no input string
|
||||
will ever match that format.
|
||||
|
||||
For example, "H:M [p]" will match against "21:33", "4:12 am", but not "30:30 pm"
|
||||
(hours out of range), "15:16 GMT" (this time zone is certainly not a valid
|
||||
meridian specifier), or "4:66" (minutes out of range).
|
||||
|
||||
\par Note:
|
||||
At the time of this writing, the parsedate() functions are not localized and
|
||||
will only recognize English time specifications following the examples above.
|
||||
|
||||
*/
|
||||
|
||||
/** \def PARSEDATE_RELATIVE_TIME
|
||||
\brief relative time
|
||||
|
||||
The time value was computed relative to the specified time.
|
||||
*/
|
||||
|
||||
/** \def PARSEDATE_DAY_RELATIVE_TIME
|
||||
\brief day relative time
|
||||
|
||||
The time value was computed relative to the specified time, and it would vary with
|
||||
every day passed in the specified time.
|
||||
*/
|
||||
|
||||
/** \def PARSEDATE_MINUTE_RELATIVE_TIME
|
||||
\brief minute relative time
|
||||
|
||||
The time value was computed relative to the specified time, and it would vary with
|
||||
every minute passed in the specified time.
|
||||
*/
|
||||
|
||||
/** \def PARSEDATE_INVALID_DATE
|
||||
\brief invalid date string
|
||||
|
||||
This flag will be set if the specified date string could not be parsed correctly.
|
||||
For example, this may happen if there are some unknown words in that string.
|
||||
*/
|
||||
|
||||
/** \fn time_t parsedate(const char *dateString, time_t relativeTo)
|
||||
\brief Parses \p dateString relative to \p relativeTo
|
||||
|
||||
Parses the given \p dateString relative to the time specified by \p relativeTo
|
||||
using the internal formats table.
|
||||
|
||||
\param dateString the date that should be parsed, i.e. "next thursday"
|
||||
\param relativeTo all relative dates will be relative to this time, if -1 is passed, the current time will be used
|
||||
\return the parsed time value or -1 if the \p dateString could not be parsed.
|
||||
*/
|
||||
|
||||
/** \fn time_t parsedate_etc(const char *dateString, time_t relativeTo, int *_storedFlags)
|
||||
\brief Parses \p dateString relative to \p relativeTo
|
||||
|
||||
This does basically the same as parsedate(), but will set the following
|
||||
flags in \p _storedFlags:
|
||||
\htmlonly
|
||||
<table border=1>
|
||||
<!-- ToDo: this certainly is a hack -->
|
||||
<tr><th bgcolor="#eeeeee">Constant</th><th bgcolor="#eeeeee">Meaning</th></tr>
|
||||
<tr><td class="mdname1">PARSEDATE_RELATIVE_TIME</td>
|
||||
<td>\endhtmlonly \copydoc PARSEDATE_RELATIVE_TIME \htmlonly
|
||||
</td></tr>
|
||||
<tr><td class="mdname1">PARSEDATE_DAY_RELATIVE_TIME</td>
|
||||
<td>\endhtmlonly \copydoc PARSEDATE_DAY_RELATIVE_TIME \htmlonly
|
||||
</td></tr>
|
||||
<tr><td class="mdname1">PARSEDATE_MINUTE_RELATIVE_TIME</td>
|
||||
<td>\endhtmlonly \copydoc PARSEDATE_MINUTE_RELATIVE_TIME \htmlonly
|
||||
</td></tr>
|
||||
<tr><td class="mdname1">PARSEDATE_INVALID_DATE</td>
|
||||
<td>
|
||||
\endhtmlonly \copydoc PARSEDATE_INVALID_DATE \htmlonly
|
||||
This flag will only be set if the function returns -1.
|
||||
</td></tr>
|
||||
</table>
|
||||
\endhtmlonly
|
||||
*/
|
||||
|
||||
/** \fn void set_dateformats(const char *formatTable[])
|
||||
\brief sets the internal format table for parsedate()
|
||||
|
||||
This function let you set the format table which is used by parsedate().
|
||||
When \c formatTable is NULL, the standard built-in format table will be set again.
|
||||
\param formatTable the NULL terminated formats list. This list must stay
|
||||
valid when using parsedate() - it is not copied, but directly used.
|
||||
\see
|
||||
\ref parsedateFormats Format!
|
||||
|
||||
*/
|
||||
|
||||
/** \fn const char **get_dateformats(void)
|
||||
\brief returns the internal format table currently used by parsedate()
|
||||
|
||||
Returns the internal format table currently used by parsedate() - this is
|
||||
either a pointer to the built-in one, or one that you have previously
|
||||
set using set_dateformats().
|
||||
|
||||
\see
|
||||
\ref set_dateformats()
|
||||
*/
|
||||
|
||||
10
docs/user/support/support_intro.dox
Normal file
10
docs/user/support/support_intro.dox
Normal file
@ -0,0 +1,10 @@
|
||||
/** \page support The Support Kit
|
||||
|
||||
The Support Kit provides a handy set of functions and classes that you can
|
||||
use in your applications. It is part of libbe.so.
|
||||
Documentation is avaible for the following parts:
|
||||
|
||||
- \ref parsedate.h Date parsing functions
|
||||
|
||||
*/
|
||||
|
||||
Loading…
Reference in New Issue
Block a user