Name
       liba2i - String-to-numeric library

Synopsis
       Library to parse numbers from strings.

Description
   Why?
       Originally, we had atoi(3) and atol(3).  Those APIs are not
       inherently bad, but the implementations left the behavior
       undefined when the input wasn't in range.  They are also limited
       to base 10.

       Then came the strtol(3) family of functions.  This API allows
       checking for errors (overflow, trailing text, invalid base, and
       no number at all).  The method for reporting those errors isn't
       exactly easy to check, though; it's very different to most
       standard libc functions.  Also, often one wants to parse a number
       into a typedef, which might be narrower than the type returned by
       strto*(3), or might be a signed or unsigned integer depending on
       the system; and checking for overflow of that type (not the type
       that strto*(3) returns) is very tricky.

       Another problem is that strtoul(3) doesn't reject negative
       values, which often results in bugs.

       Then came strtonum(3) and later strtoi(3) and strtou(3) to the
       BSDs.  They considerably simplify the error checking, reporting
       them via errno.

       These new BSD functions are still problematic with typedefs whose
       signedness may vary, and also don't reject negative values.  And
       they've had a bug which conceals range errors when there's
       trailing text after the number.

   What?
       The functions provided by this library store the value via a
       pointer, which adds some type safety: passing a pointer to a
       different integer type would result in an error.  The return
       value is either 0 or -1, for success or error.

       The functions for parsing unsigned integers reject negative
       values, considering them underflow.

       The type-generic macros allow use with typedefs, providing
       appropriate range checks.

       The short-hand versions of the functions and macros provide a
       simple API (almost as simple as atoi(3)) with common defaults.

Files
   GNUmakefile
   share/mk/
       Build system.  For help, run `make help`.

   LICENSES/
   share/licenses/
       Licenses in use by the project.

   etc/
       Configuration files for (linter) programs called by the build
       system.

   include/a2i/
       Header files.

   lib/pkgconfig/
       Package configuration file.  See pc(5) and pkgconf(1).

   lib/src/a2i/
       Source code.

   share/doc/
       Project documentation.

   man/
       Manual pages.

   .tmp/
       Default directory for files created by the build system.

Versions
   Distribution
       <https://kernel.org/pub/software/libs/liba2i/>
       <https://www.alejandro-colomar.es/share/dist/liba2i/>

   Git
       <https://git.kernel.org/pub/scm/libs/liba2i/liba2i.git/>
       <https://www.alejandro-colomar.es/src/alx/alx/liba2i.git/>

   Online man-pages
       <https://www.alejandro-colomar.es/share/dist/liba2i/git/HEAD/liba2i-HEAD.pdf>

Maintainers
       Alejandro Colomar <alx@kernel.org> <https://www.alejandro-colomar.es/>

Bugs
       See the <share/doc/contributing> file.

Copyright
       LGPL-3.0-only WITH LGPL-3.0-linking-exception

See also
       <https://git.kernel.org/pub/scm/libs/liba2i/liba2i.git/tree/share/docs/readme>
       <https://www.alejandro-colomar.es/src/alx/alx/liba2i.git/tree/share/docs/readme>
