[src/trunk]: src/lib/libc/stdlib strtoi and strtou additions

[christos <christos%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/e825f5db1ea2
branches:  trunk
changeset: 335591:e825f5db1ea2
user:      christos <christos%NetBSD.org@localhost>
date:      Fri Jan 16 18:37:21 2015 +0000

description:
strtoi and strtou additions

diffstat:

 lib/libc/stdlib/Makefile.inc |   5 ++-
 lib/libc/stdlib/strtol.3     |  75 ++++++++++++++++++++++++++++++++++++++++++-
 lib/libc/stdlib/strtoul.3    |  74 ++++++++++++++++++++++++++++++++++++++++++-
 3 files changed, 149 insertions(+), 5 deletions(-)

diffs (299 lines):

diff -r 438254187afd -r e825f5db1ea2 lib/libc/stdlib/Makefile.inc
--- a/lib/libc/stdlib/Makefile.inc      Fri Jan 16 18:36:31 2015 +0000
+++ b/lib/libc/stdlib/Makefile.inc      Fri Jan 16 18:37:21 2015 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: Makefile.inc,v 1.83 2014/12/10 16:55:54 pooka Exp $
+#      $NetBSD: Makefile.inc,v 1.84 2015/01/16 18:37:21 christos Exp $
 #      from: @(#)Makefile.inc  8.3 (Berkeley) 2/4/95
 
 # stdlib sources
@@ -13,6 +13,7 @@
        nrand48.c putenv.c qabs.c qdiv.c qsort.c posix_openpt.c pty.c \
        quick_exit.c radixsort.c rand.c rand_r.c random.c remque.c \
        seed48.c setenv.c srand48.c strsuftoll.c \
+       strtoi.c strtou.c \
        strtoimax.c strtol.c strtoll.c strtoq.c strtoul.c strtoull.c \
        strtoumax.c strtouq.c system.c tdelete.c tfind.c tsearch.c twalk.c \
        unsetenv.c strfmon.c
@@ -86,7 +87,9 @@
 MLINKS+=strtol.3 strtoimax.3
 MLINKS+=strtol.3 strtoll.3
 MLINKS+=strtol.3 strtoq.3
+MLINKS+=strtol.3 strtoi.3
 MLINKS+=strtoul.3 strtoull.3
 MLINKS+=strtoul.3 strtoumax.3
 MLINKS+=strtoul.3 strtouq.3
+MLINKS+=strtoul.3 strtou.3
 MLINKS+=tsearch.3 tfind.3 tsearch.3 twalk.3 tsearch.3 tdelete.3
diff -r 438254187afd -r e825f5db1ea2 lib/libc/stdlib/strtol.3
--- a/lib/libc/stdlib/strtol.3  Fri Jan 16 18:36:31 2015 +0000
+++ b/lib/libc/stdlib/strtol.3  Fri Jan 16 18:37:21 2015 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: strtol.3,v 1.26 2009/07/23 13:38:57 wiz Exp $
+.\"    $NetBSD: strtol.3,v 1.27 2015/01/16 18:37:21 christos Exp $
 .\"
 .\" Copyright (c) 1990, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -33,10 +33,11 @@
 .\"
 .\"     from: @(#)strtol.3     8.1 (Berkeley) 6/4/93
 .\"
-.Dd July 23, 2009
+.Dd December 27, 2014
 .Dt STRTOL 3
 .Os
 .Sh NAME
+.Nm strtoi ,
 .Nm strtol ,
 .Nm strtoll ,
 .Nm strtoimax ,
@@ -53,6 +54,8 @@
 .Fn strtoll "const char * restrict nptr" "char ** restrict endptr" "int base"
 .Pp
 .In inttypes.h
+.Ft intmax_t 
+.Fn strtoi "const char * restrict nptr" "char ** restrict endptr" "int base" "intmax_t lo" "intmax_t hi" "int *rerror"
 .Ft intmax_t
 .Fn strtoimax "const char * restrict nptr" "char ** restrict endptr" "int base"
 .Pp
@@ -87,6 +90,27 @@
 .Ft intmax_t
 value.
 The
+.Fn strtoi
+function
+is using internally
+.Fn strtoimax
+and ensures that the result is always in the range [
+.Fa lo ..
+.Fa hi
+].
+In adddition it always places
+.Dv 0
+on success or an error value in the
+.Fa rerror
+argument, avoiding the
+.Dv errno
+gymnastics the other functions require.
+The
+.Fa rerror
+argument can be
+.Dv NULL
+if errors are to be ignored.
+The
 .Fn strtoq
 function
 converts the string in
@@ -156,6 +180,15 @@
 on return, the entire string was valid.)
 .Sh RETURN VALUES
 The
+.Fn strtoi
+function
+always returns the closest value in the range specified by
+the
+.Fa lo
+and
+.Fa hi
+arguments.
+The
 .Fn strtol
 function
 returns the result of the conversion,
@@ -200,6 +233,21 @@
 This behavior (which is unlike most library functions) is guaranteed
 by the pertinent standards.
 .Sh EXAMPLES
+The
+.Fn strtoi
+function is the simplest to use:
+.Bd -literal -offset indent
+int e;
+intmax_t lval = strtoi(buf, NULL, 0, 1, 99, &e);
+if (e)
+       warn("conversion of `%s' to a number failed, using %jd",
+           buf, lval);
+.Ed
+.Pp
+This will always return a number in
+.Dv [1..99]
+range no matter what the input is, and warn if the conversion failed.
+.Pp
 Because the return value of
 .Fn strtol
 cannot be used unambiguously to detect an error,
@@ -269,12 +317,31 @@
 .It Bq Er ERANGE
 The given string was out of range; the value converted has been clamped.
 .El
+.Pp
+In addition to the above errors
+.Fn strtoi 
+returns:
+.Bl -tag -width Er
+.It Bq Er ECANCELED
+The string did not contain any characters that could be converted.
+.It Bq Er ENOTSUP
+The string contained non-numeric characters that did not get converted.
+In this case,
+.Fa endptr
+points to the first unconverted character.
+.It Bq Er ERANGE
+The range given was invalid, i.e.
+.Fa lo
+\*[Gt]
+.Fa hi .
+.El
 .Sh SEE ALSO
 .Xr atof 3 ,
 .Xr atoi 3 ,
 .Xr atol 3 ,
 .Xr atoll 3 ,
 .Xr strtod 3 ,
+.Xr strtou 3 ,
 .Xr strtoul 3 ,
 .Xr strtoull 3 ,
 .Xr strtoumax 3
@@ -290,5 +357,9 @@
 .Fn strtoimax
 functions conform to
 .St -isoC-99 .
+The
+.Fn strtoi
+function appeared in
+.Nx 8 .
 .Sh BUGS
 Ignores the current locale.
diff -r 438254187afd -r e825f5db1ea2 lib/libc/stdlib/strtoul.3
--- a/lib/libc/stdlib/strtoul.3 Fri Jan 16 18:36:31 2015 +0000
+++ b/lib/libc/stdlib/strtoul.3 Fri Jan 16 18:37:21 2015 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: strtoul.3,v 1.25 2009/12/02 12:50:27 pooka Exp $
+.\"    $NetBSD: strtoul.3,v 1.26 2015/01/16 18:37:21 christos Exp $
 .\"
 .\" Copyright (c) 1990, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -33,10 +33,11 @@
 .\"
 .\"     from: @(#)strtoul.3    8.1 (Berkeley) 6/4/93
 .\"
-.Dd December 2, 2009
+.Dd December 27, 2014
 .Dt STRTOUL 3
 .Os
 .Sh NAME
+.Nm strtou ,
 .Nm strtoul ,
 .Nm strtoull ,
 .Nm strtoumax ,
@@ -53,6 +54,8 @@
 .Fn strtoull "const char * restrict nptr" "char ** restrict endptr" "int base"
 .Pp
 .In inttypes.h
+.Ft uintmax_t 
+.Fn strtou "const char * restrict nptr" "char ** restrict endptr" "int base" "uintmax_t lo" "uintmax_t hi" "int *rerror"
 .Ft uintmax_t
 .Fn strtoumax "const char * restrict nptr" "char ** restrict endptr" "int base"
 .Pp
@@ -86,6 +89,26 @@
 to an
 .Ft uintmax_t
 value.
+.Fn strtou
+function
+is using internally
+.Fn strtoumax
+and ensures that the result is always in the range [
+.Fa lo ..
+.Fa hi
+].
+In adddition it always places
+.Dv 0
+on success or an error value in the
+.Fa rerror
+argument, avoiding the
+.Dv errno
+gymnastics the other functions require.
+The
+.Fa rerror
+argument can be
+.Dv NULL
+if errors are to be ignored.
 The
 .Fn strtouq
 function
@@ -157,6 +180,15 @@
 on return, the entire string was valid.)
 .Sh RETURN VALUES
 The
+.Fn strtou
+function
+always returns the closest value in the range specified by
+the
+.Fa lo
+and
+.Fa hi
+arguments.
+The
 .Fn strtoul
 function
 returns either the result of the conversion
@@ -201,6 +233,21 @@
 This behavior (which is unlike most library functions) is guaranteed
 by the pertinent standards.
 .Sh EXAMPLES
+The
+.Fn strtou
+function is the simplest to use:
+.Bd -literal -offset indent
+int e;
+uintmax_t lval = strtou(buf, NULL, 0, 1, 99, &e);
+if (e)
+       warn("conversion of `%s' to a number failed, using %ju",
+           buf, lval);
+.Ed
+.Pp
+This will always return a number in
+.Dv [1..99]
+range no matter what the input is, and warn if the conversion failed.
+.Pp
 Because the return value of
 .Fn strtoul
 cannot be used unambiguously to detect an error,
@@ -243,7 +290,26 @@
 .It Bq Er ERANGE
 The given string was out of range; the value converted has been clamped.
 .El
+.Pp
+In addition to the above errors
+.Fn strtou
+returns:
+.Bl -tag -width Er
+.It Bq Er ECANCELED
+The string did not contain any characters that could be converted.
+.It Bq Er ENOTSUP
+The string contained non-numeric characters that did not get converted.
+In this case,
+.Fa endptr
+points to the first unconverted character.
+.It Bq Er ERANGE
+The range given was invalid, i.e.
+.Fa lo
+\*[Gt]
+.Fa hi .
+.El
 .Sh SEE ALSO
+.Xr strtoi 3 ,
 .Xr strtoimax 3 ,
 .Xr strtol 3 ,
 .Xr strtoll 3
@@ -259,5 +325,9 @@
 .Fn strtoumax
 functions conform to
 .St -isoC-99 .
+The
+.Fn strtou
+function appeared in
+.Nx 8 .
 .Sh BUGS
 Ignores the current locale.