Mu scan datetime - Revision history

Gray: Document changes in endp semantics.

2020-11-27T11:33:16Z

Document changes in endp semantics.

Gray at 18:52, 7 July 2014

2014-07-07T18:52:14Z

Gray at 11:59, 17 December 2011

2011-12-17T11:59:39Z

Gray: Created page with "{{DISPLAYTITLE:mu_scan_datetime}} #include int mu_scan_datetime (const char input, const char format, struct tm *tm, ..."

2011-12-17T11:58:24Z

Created page with "{{DISPLAYTITLE:mu_scan_datetime}} <syntaxhighlight lang="C"> #include <mailutils/datetime.h> int mu_scan_datetime (const char *input, const char *format, struct tm *tm, ..."

New page

{{DISPLAYTITLE:mu_scan_datetime}}
<syntaxhighlight lang="C">
#include <mailutils/datetime.h>

int mu_scan_datetime (const char *input, const char *format, struct tm *tm,
struct mu_timezone *tz, char **endp);
</syntaxhighlight>

The function <tt>mu_scan_datetime</tt> parses the string <tt>input</tt>, which is supposed to contain a date/time information, according to the <tt>format</tt> and places the resulting broken-down time in the <tt>tm</tt> variable. Unless <tt>tz</tt> is <tt>NULL</tt> the time zone information is stored there. Unless <tt>endp</tt> is <tt>NULL</tt>, <tt>mu_scan_datetime</tt> stores the address of the character where parsing stopped in <tt>endp</tt>.

The function returns 0 on success, <tt>MU_ERR_PARSE</tt> if <tt>input</tt> does not satisfy <tt>format</tt>, and <tt>MU_ERR_FORMAT</tt> if <tt>format</tt> itself is erroneous. In the latter case, a detailed information about the error is output to the [[Debug level|debugging channel]] <tt>mailbox.error</tt>.

The <tt>format</tt> follows the [[mu_c_streamftime#Format_string|mu_c_streamftime format specification]] with several extensions. It is interpreted as follows:

* A sequence of white-space characters (space, tab, newline, etc.; see [[mu_isspace]]) matches any amount of white space, including none, in the input.
* An ordinary character (i.e., one other than white space or <tt>%</tt>) must exactly match the next character of input.
* A [[mu_c_streamftime#Format_string|conversion specifier]] parses next characters according to its definition and stores the result in the corresponding location in <tt>tm</tt> or <tt>tz</tt> (unless the latter is <tt>NULL</tt>.
* A '''flow control''' conversion alters the way the format is interpreted.

Flow control specifiers are:

;%?
:This specifier matches any single character on input.

;%\'''C'''
:(where '''C''' is any single character) This specifier matches character '''C''' exactly. It is useful for specifying mandatory whitespace, as in:

"%d-%b-%Y%\ %H:%M:%S %z"

The above format requires date and time parts to be separated by a single space character.

;%$
:This specifier means optional end of input. That is, if the input does not match conversion past this specifier, it is not considered an error. Instead, the <tt>endp</tt> is set to the position where scanning stopped and 0 is returned. The <tt>tm</tt> and <tt>tz</tt> variables are left with the partial information collected so far.

Consider, for example, date format used in IMAP SEARCH command. It is basically described as follows:

"%d-%b-%Y %H:%M:%S %z"

However, the time and timezone information is optional. To allow for that, the following format can be used instead:

"%d-%b-%Y%$ %H:%M:%S %z"

(see the <tt>MU_DATETIME_INTERNALDATE</tt> in <tt>mailutils/datetime.h</tt><ref>http://git.gnu.org.ua/cgit/mailutils.git/tree/include/mailutils/datetime.h</ref>).

;%[ %| %]
:The part of format enclosed between <tt>%[</tt> and <tt>%]</tt> specifiers is optional. The specifiers can be nested to any depth. The <tt>%|</tt> specifier appearing within the optional group introduces an '''optional alternative'''. Any number of alternatives may be present.

Let's return to the above format for an example. It can be rewritten using optional group as follows:

"%d-%b-%Y%[ %H:%M:%S %z%]"

As a more complex example, consider RFC-822 date format. It has two optional parts: the day of week at the beginning and seconds at the end. The corresponding scan format is:

"%[%a, %]%e %b %Y %H:%M%[:%S%] %z"

See the <tt>MU_DATETIME_SCAN_RFC822</tt> define in <tt>mailutils/datetime.h</tt>.

The following example illustrates nested optional groups:

%[%a%[,%] %]%d %b %Y %H:%M:%S %z

It matches any of the following date specifications:

Tue, 03 May 2011 13:25:26 +0200
Tue 03 May 2011 13:25:26 +0200
03 May 2011 13:25:26 +0200

;%( %| %)
:Alternatives. This specifier requires that the input matches one of the alternatives separated by <tt>%|</tt>. Two or more alternatives may be specified, but at least two must be present.

For example the following format

"%a%(,%|:%|/%) %d %b %Y %H:%M:%S %z"

requires the day of time (<tt>%a</tt>) to be followed by a single comma, semicolon or slash. Any other character following it will cause the format to fail.

Optional blocks and alternative specifiers can be nested.

==Notes==
<references/>

== See also ==
[[mu_c_streamftime]]

[[Category:Date/Time Functions]]
[[Category:C API]]

@@ Line 7: / Line 7: @@
 </syntaxhighlight>
-The function <tt>mu_scan_datetime</tt> scans the string <tt>input</tt>, which is supposed to contain a date/time information, according to the <tt>format</tt> and places the resulting broken-down time in the <tt>tm</tt> variable. Unless <tt>tz</tt> is <tt>NULL</tt> the time zone information is stored there.  Unless <tt>endp</tt> is <tt>NULL</tt>, <tt>mu_scan_datetime</tt> stores the address of the character where scanning stopped in <tt>endp</tt>.
+The function <tt>mu_scan_datetime</tt> scans the string <tt>input</tt>, which is supposed to contain a date/time information, according to the <tt>format</tt> and places the resulting broken-down time in the <tt>tm</tt> variable. Unless <tt>tz</tt> is <tt>NULL</tt> the time zone information is stored there.
-The function returns 0 on success, <tt>MU_ERR_PARSE</tt> if <tt>input</tt> does not satisfy <tt>format</tt>, and <tt>MU_ERR_FORMAT</tt> if <tt>format</tt> itself is erroneous.  In the latter case, a detailed information about the error is output to the [[Debug level|debugging channel]] <tt>mailbox.error</tt>.
+On success, the function returns 0.  If the input does not satisfy the format, <tt>MU_ERR_PARSE</tt> is returned.  In both cases, unless <tt>endp</tt> is <tt>NULL</tt>, it will be initialized with the address of the character in <tt>input</tt> where the scanning stopped.
 The <tt>format</tt> follows the [[mu_c_streamftime#Format_string|mu_c_streamftime format specification]] with several extensions.  It is interpreted as follows:

@@ Line 15: / Line 15: @@
 * A sequence of white-space characters (space, tab, newline, etc.; see [[mu_isspace]]) matches any amount of white space, including none, in the input.
 * An ordinary character (i.e., one other than white space or <tt>%</tt>) must exactly match the next character of input.
-* A [[mu_c_streamftime#Format_string|conversion specifier]] parses next characters according to its definition and stores the result in the corresponding location in <tt>tm</tt> or <tt>tz</tt> (unless the latter is <tt>NULL</tt>.
+* A [[mu_c_streamftime#Format_string|conversion specifier]] parses next characters according to its definition and stores the result in the corresponding location in <tt>tm</tt> or <tt>tz</tt> (unless the latter is <tt>NULL</tt>).
 * A '''flow control''' conversion alters the way the format is interpreted.

Mu scan datetime - Revision history

Gray: Document changes in endp semantics.

Gray at 18:52, 7 July 2014

Gray at 11:59, 17 December 2011

Gray: Created page with "{{DISPLAYTITLE:mu_scan_datetime}} #include int mu_scan_datetime (const char *input, const char *format, struct tm *tm, ..."

Gray: Created page with "{{DISPLAYTITLE:mu_scan_datetime}} #include int mu_scan_datetime (const char input, const char format, struct tm *tm, ..."