lib/parse-duration.h

   1 /* Parse a time duration and return a seconds count
   2    Copyright (C) 2008-2024 Free Software Foundation, Inc.
   3    Written by Bruce Korb <bkorb@gnu.org>, 2008.
   4
   5    This file is free software: you can redistribute it and/or modify
   6    it under the terms of the GNU Lesser General Public License as
   7    published by the Free Software Foundation; either version 2.1 of the
   8    License, or (at your option) any later version.
   9
  10    This file 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 Lesser General Public License for more details.
  14
  15    You should have received a copy of the GNU Lesser General Public License
  16    along with this program.  If not, see <https://www.gnu.org/licenses/>.  */
  17
  18 /*
  19
  20   Readers and users of this function are referred to the ISO-8601
  21   specification, with particular attention to "Durations".
  22
  23   At the time of writing, this worked:
  24
  25   https://en.wikipedia.org/wiki/ISO_8601#Durations
  26
  27   The string must start with a 'P', 'T' or a digit.
  28
  29   ==== if it is a digit
  30
  31   the string may contain:  NNN Y NNN M NNN W NNN d NNN h NNN m NNN s
  32   This represents NNN years, NNN months, NNN weeks, NNN days, NNN hours,
  33     NNN minutes and NNN seconds.
  34   The embedded white space is optional.
  35   These terms must appear in this order.
  36   Case is significant:  'M' is months and 'm' is minutes.
  37   The final "s" is optional.
  38   All of the terms ("NNN" plus designator) are optional.
  39   Minutes and seconds may optionally be represented as NNN:NNN.
  40   Also, hours, minute and seconds may be represented as NNN:NNN:NNN.
  41   There is no limitation on the value of any of the terms, except
  42   that the final result must fit in a time_t value.
  43
  44   ==== if it is a 'P' or 'T', please see ISO-8601 for a rigorous definition.
  45
  46   The 'P' term may be followed by any of three formats:
  47     yyyymmdd
  48     yy-mm-dd
  49     yy Y mm M ww W dd D
  50
  51   or it may be empty and followed by a 'T'.  The "yyyymmdd" must be eight
  52   digits long.
  53
  54   NOTE!  Months are always 30 days and years are always 365 days long.
  55   5 years is always 1825 days, not 1826 or 1827 depending on leap year
  56   considerations.  3 months is always 90 days.  There is no consideration
  57   for how many days are in the current, next or previous months.
  58
  59   For the final format:
  60   *  Embedded white space is allowed, but it is optional.
  61   *  All of the terms are optional.  Any or all-but-one may be omitted.
  62   *  The meanings are yy years, mm months, ww weeks and dd days.
  63   *  The terms must appear in this order.
  64
  65   ==== The 'T' term may be followed by any of these formats:
  66
  67     hhmmss
  68     hh:mm:ss
  69     hh H mm M ss S
  70
  71   For the final format:
  72   *  Embedded white space is allowed, but it is optional.
  73   *  All of the terms are optional.  Any or all-but-one may be omitted.
  74   *  The terms must appear in this order.
  75
  76  */
  77 #ifndef GNULIB_PARSE_DURATION_H
  78 #define GNULIB_PARSE_DURATION_H
  79
  80 #include <time.h>
  81
  82 #ifdef __cplusplus
  83 extern "C" {
  84 #endif
  85
  86
  87 /* Return value when a valid duration cannot be parsed.  */
  88 #define BAD_TIME        ((time_t)~0)
  89
  90 /* Parses the given string.  If it has the syntax of a valid duration,
  91    this duration is returned.  Otherwise, the return value is BAD_TIME,
  92    and errno is set to either EINVAL (bad syntax) or ERANGE (out of range).  */
  93 extern time_t parse_duration (char const * in_pz);
  94
  95
  96 #ifdef __cplusplus
  97 }
  98 #endif
  99
 100 #endif /* GNULIB_PARSE_DURATION_H */