2 * parse time string - user friendly date and time parser
3 * Copyright © 2012 Jani Nikula
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.
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.
15 * You should have received a copy of the GNU General Public License
16 * along with this program. If not, see <http://www.gnu.org/licenses/>.
18 * Author: Jani Nikula <jani@nikula.org>
21 #ifndef PARSE_TIME_STRING_H
22 #define PARSE_TIME_STRING_H
30 /* return values for parse_time_string() */
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 */
44 /* round values for parse_time_string() */
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,
53 * parse_time_string() - user friendly date and time parser
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
60 * Parse a date/time string 's' and store the parsed date/time result
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.
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:
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.
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.
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.
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.
93 * Return 0 (PARSE_TIME_OK) for succesfully parsed date/time, or one
94 * of PARSE_TIME_ERR_* on error. 't' is not modified on error.
96 int parse_time_string (const char *s, time_t *t, const time_t *ref, int round);
102 #endif /* PARSE_TIME_STRING_H */