git.notmuchmail.org Git - notmuch/blob - 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 */