Document grok_atou as strtoul replacement.

3 files changed, 31 insertions, 8 deletions

diff --git a/numeric.c b/numeric.c
index d997d1150b..062c7669f4 100644
--- a/numeric.c
+++ b/numeric.c
@@ -789,16 +789,26 @@ Perl_grok_number_flags(pTHX_ const char *pv, STRLEN len, UV *valuep, U32 flags)
 /*
 =for perlapi
 
-grok_atou is a safer replacement for atoi.
+grok_atou is a safer replacement for atoi or strtoul.
 
-(atoi has severe problems with illegal inputs, and should not be used.
-atoi is also affected by locale settings, which can be seen as a bug.)
+atoi has severe problems with illegal inputs, and should not be used.
+
+atoi and strtoul are also affected by locale settings, which can
+be seen as a bug (global state controlled by user environment).
 
 Returns the unsigned value, if a valid one can be parsed.
 
 Only the decimal digits '0'..'9' are accepted.
 
-Does NOT allow optional leading whitespace, as opposed to atoi.
+As opposed to atoi or strtoul:
+- does NOT allow optional leading whitespace
+- does NOT allow negative inputs
+
+Also rejected:
+- leading plus signs
+- leading zeros (meaning that only "0" is the zero)
+
+Trailing non-digit bytes are allowed if the endptr is non-NULL.
 
 On return the *endptr will contain the pointer to the first non-digit byte.
 
diff --git a/pod/perlclib.pod b/pod/perlclib.pod
index b7d8c10861..b4ebe4e194 100644
--- a/pod/perlclib.pod
+++ b/pod/perlclib.pod
@@ -203,12 +203,17 @@ C<toUPPER_uni>, as described in L<perlapi/Character case changing>.)
  atoi(s)                     grok_atou(s, &e)
  atol(s)                     grok_atou(s, &e)
  strtod(s, &p)               Nothing.  Just don't use it.
- strtol(s, &p, n)            Strtol(s, &p, n)
- strtoul(s, &p, n)           Strtoul(s, &p, n)
+ strtol(s, &p, n)            grok_atou(s, &e)
+ strtoul(s, &p, n)           grok_atou(s, &e)
 
 Notice also the C<grok_bin>, C<grok_hex>, and C<grok_oct> functions in
 F<numeric.c> for converting strings representing numbers in the respective
-bases into C<NV>s.
+bases into C<NV>s.  Note that grok_atou() doesn't handle negative inputs,
+or leading whitespace (being purposefully strict).  It also doesn't always
+handle full IV/UV-range, being limited to Size_t.
+
+Note that strtol() and strtoul() may be disguised as Strtol(), Strtoul(),
+Atol(), Atoul().  Avoid those, too.
 
 In theory C<Strtol> and C<Strtoul> may not be defined if the machine perl is
 built on doesn't actually have strtol and strtoul. But as those 2
diff --git a/pod/perlhacktips.pod b/pod/perlhacktips.pod
index 1d8aa1975c..3d477da89e 100644
--- a/pod/perlhacktips.pod
+++ b/pod/perlhacktips.pod
@@ -629,7 +629,15 @@ Do not use atoi()
 
 Use grok_atou() instead.  atoi() has ill-defined behavior on overflows,
 and cannot be used for incremental parsing.  It is also affected by locale,
-which can be construed as a bug.
+which is bad.
+
+=item *
+
+Do not use strtol() or strtoul()
+
+Use grok_atou() instead.  strtol() or strtoul() (or their IV/UV-friendly
+macro disguises, Strtol() and Strtoul(), or Atol() and Atoul() are
+affected by locale, which is bad.
 
 =back