lib/xstrtol.h

   1 /* A more useful interface to strtol.
   2
   3    Copyright (C) 1995-1996, 1998-1999, 2001-2004, 2006-2025 Free Software
   4    Foundation, Inc.
   5
   6    This program is free software: you can redistribute it and/or modify
   7    it under the terms of the GNU General Public License as published by
   8    the Free Software Foundation, either version 3 of the License, or
   9    (at your option) any later version.
  10
  11    This program is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14    GNU General Public License for more details.
  15
  16    You should have received a copy of the GNU General Public License
  17    along with this program.  If not, see <https://www.gnu.org/licenses/>.  */
  18
  19 #ifndef XSTRTOL_H_
  20 #define XSTRTOL_H_ 1
  21
  22 /* Get intmax_t, uintmax_t.  */
  23 #include <stdint.h>
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29
  30 enum strtol_error
  31   {
  32     LONGINT_OK = 0,
  33
  34     /* These two values can be ORed together, to indicate that both
  35        errors occurred.  */
  36     LONGINT_OVERFLOW = 1,
  37     LONGINT_INVALID_SUFFIX_CHAR = 2,
  38
  39     LONGINT_INVALID_SUFFIX_CHAR_WITH_OVERFLOW = (LONGINT_INVALID_SUFFIX_CHAR
  40                                                  | LONGINT_OVERFLOW),
  41     LONGINT_INVALID = 4
  42   };
  43 typedef enum strtol_error strtol_error;
  44
  45 /* Act like the system's strtol (NPTR, ENDPTR, BASE) except:
  46    - The TYPE of the result might be something other than long int.
  47    - Return strtol_error, and store any result through an additional
  48      TYPE *VAL pointer instead of returning the result.
  49    - If TYPE is unsigned, reject leading '-'.
  50    - Behavior is undefined if BASE is negative, 1, or greater than 36.
  51      (In this respect xstrtol acts like the C standard, not like POSIX.)
  52    - Accept an additional char const *VALID_SUFFIXES pointer to a
  53      possibly-empty string containing allowed numeric suffixes,
  54      which multiply the value.  These include SI suffixes like 'k' and 'M';
  55      these normally stand for powers of 1024, but if VALID_SUFFIXES also
  56      includes '0' they can be followed by "B" to stand for the usual
  57      SI powers of 1000 (or by "iB" to stand for powers of 1024 as before).
  58      Other supported suffixes include 'K' for 1024 or 1000, 'b' for 512,
  59      'c' for 1, and 'w' for 2.
  60    - Suppose that after the initial whitespace, the number is missing
  61      but there is a valid suffix.  Then the number is treated as 1.  */
  62
  63 #define _DECLARE_XSTRTOL(name, type) \
  64   strtol_error name (char const *restrict /*nptr*/,             \
  65                      char **restrict /*endptr*/,                \
  66                      int /*base*/,                              \
  67                      type *restrict /*val*/,                    \
  68                      char const *restrict /*valid_suffixes*/);
  69 _DECLARE_XSTRTOL (xstrtol, long int)
  70 _DECLARE_XSTRTOL (xstrtoul, unsigned long int)
  71 _DECLARE_XSTRTOL (xstrtoll, long long int)
  72 _DECLARE_XSTRTOL (xstrtoull, unsigned long long int)
  73 _DECLARE_XSTRTOL (xstrtoimax, intmax_t)
  74 _DECLARE_XSTRTOL (xstrtoumax, uintmax_t)
  75
  76
  77 #ifdef __cplusplus
  78 }
  79 #endif
  80
  81 #endif /* not XSTRTOL_H_ */