parse-time-string: run uncrustify
[notmuch] / parse-time-string / parse-time-string.h
1 /*
2  * parse time string - user friendly date and time parser
3  * Copyright © 2012 Jani Nikula
4  *
5  * This program is free software: you can redistribute it and/or modify
6  * it under the terms of the GNU General Public License as published by
7  * the Free Software Foundation, either version 2 of the License, or
8  * (at your option) any later version.
9  *
10  * This program is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU General Public License for more details.
14  *
15  * You should have received a copy of the GNU General Public License
16  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
17  *
18  * Author: Jani Nikula <jani@nikula.org>
19  */
20
21 #ifndef PARSE_TIME_STRING_H
22 #define PARSE_TIME_STRING_H
23
24 #ifdef __cplusplus
25 extern "C" {
26 #endif
27
28 #include <time.h>
29
30 /* return values for parse_time_string() */
31 enum {
32     PARSE_TIME_OK = 0,
33     PARSE_TIME_ERR,             /* unspecified error */
34     PARSE_TIME_ERR_LIB,         /* library call failed */
35     PARSE_TIME_ERR_ALREADYSET,  /* attempt to set unit twice */
36     PARSE_TIME_ERR_FORMAT,      /* generic date/time format error */
37     PARSE_TIME_ERR_DATEFORMAT,  /* date format error */
38     PARSE_TIME_ERR_TIMEFORMAT,  /* time format error */
39     PARSE_TIME_ERR_INVALIDDATE, /* date value error */
40     PARSE_TIME_ERR_INVALIDTIME, /* time value error */
41     PARSE_TIME_ERR_KEYWORD,     /* unknown keyword */
42 };
43
44 /* round values for parse_time_string() */
45 enum {
46     PARSE_TIME_ROUND_DOWN               = -1,
47     PARSE_TIME_NO_ROUND                 = 0,
48     PARSE_TIME_ROUND_UP                 = 1,
49     PARSE_TIME_ROUND_UP_INCLUSIVE       = 2,
50 };
51
52 /**
53  * parse_time_string() - user friendly date and time parser
54  * @s:          string to parse
55  * @t:          pointer to time_t to store parsed time in
56  * @ref:        pointer to time_t containing reference date/time, or NULL
57  * @round:      PARSE_TIME_NO_ROUND, PARSE_TIME_ROUND_DOWN, or
58  *              PARSE_TIME_ROUND_UP
59  *
60  * Parse a date/time string 's' and store the parsed date/time result
61  * in 't'.
62  *
63  * A reference date/time is used for determining the "date/time units"
64  * (roughly equivalent to struct tm members) not specified by 's'. If
65  * 'ref' is non-NULL, it must contain a pointer to a time_t to be used
66  * as reference date/time. Otherwise, the current time is used.
67  *
68  * If 's' does not specify a full date/time, the 'round' parameter
69  * specifies if and how the result should be rounded as follows:
70  *
71  *   PARSE_TIME_NO_ROUND: All date/time units that are not specified
72  *   by 's' are set to the corresponding unit derived from the
73  *   reference date/time.
74  *
75  *   PARSE_TIME_ROUND_DOWN: All date/time units that are more accurate
76  *   than the most accurate unit specified by 's' are set to the
77  *   smallest valid value for that unit. Rest of the unspecified units
78  *   are set as in PARSE_TIME_NO_ROUND.
79  *
80  *   PARSE_TIME_ROUND_UP: All date/time units that are more accurate
81  *   than the most accurate unit specified by 's' are set to the
82  *   smallest valid value for that unit. The most accurate unit
83  *   specified by 's' is incremented by one (and this is rolled over
84  *   to the less accurate units as necessary), unless the most
85  *   accurate unit is seconds. Rest of the unspecified units are set
86  *   as in PARSE_TIME_NO_ROUND.
87  *
88  *   PARSE_TIME_ROUND_UP_INCLUSIVE: Same as PARSE_TIME_ROUND_UP, minus
89  *   one second, unless the most accurate unit specified by 's' is
90  *   seconds. This is useful for callers that require a value for
91  *   inclusive comparison of the result.
92  *
93  * Return 0 (PARSE_TIME_OK) for successfully parsed date/time, or one
94  * of PARSE_TIME_ERR_* on error. 't' is not modified on error.
95  */
96 int parse_time_string (const char *s, time_t *t, const time_t *ref, int round);
97
98 #ifdef __cplusplus
99 }
100 #endif
101
102 #endif /* PARSE_TIME_STRING_H */