]> Savannah Git Hosting - gnulib.git/commitdiff
xstrtod, xstrtold: Add documentation.
authorBruno Haible <bruno@clisp.org>
Tue, 23 Jul 2024 18:58:45 +0000 (20:58 +0200)
committerBruno Haible <bruno@clisp.org>
Tue, 23 Jul 2024 18:58:45 +0000 (20:58 +0200)
* lib/xstrtod.h (xstrtod, xstrtold): Add comments.
* lib/xstrtod.c (XSTRTOD): Improve comments.

ChangeLog
lib/xstrtod.c
lib/xstrtod.h

index 890cd57c2f1938d50497fc906b23c8558a3fd6d2..13e01f268400dd65eca92a8e5a960ca23a8088c0 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2024-07-23  Bruno Haible  <bruno@clisp.org>
+
+       xstrtod, xstrtold: Add documentation.
+       * lib/xstrtod.h (xstrtod, xstrtold): Add comments.
+       * lib/xstrtod.c (XSTRTOD): Improve comments.
+
 2024-07-23  Bruno Haible  <bruno@clisp.org>
 
        xstrtold: Add tests.
index 55b4bb4a8f2005708e546be055f5786f43dbd744..a9ca7e8d107a05c7bb8258c24bc88af2a5a934e0 100644 (file)
@@ -56,9 +56,10 @@ XSTRTOD (char const *str, char const **ptr, DOUBLE *result,
     ok = false;
   else
     {
-      /* Allow underflow (in which case CONVERT returns zero),
-         but flag overflow as an error.  The user can decide
-         to use the limits in RESULT upon ERANGE.  */
+      /* Flag overflow as an error.
+         Flag gradual underflow as an error.
+         Flag flush-to-zero underflow as no error.
+         In either case, the caller can inspect *RESULT to get more details.  */
       if (val != 0 && errno == ERANGE)
         ok = false;
     }
@@ -66,6 +67,8 @@ XSTRTOD (char const *str, char const **ptr, DOUBLE *result,
   if (ptr != NULL)
     *ptr = terminator;
 
+  /* Callers rely on *RESULT even when !ok.  */
   *result = val;
+
   return ok;
 }
index 9ae4be13da90eef62313d47709b027087658d46e..8ceca6c433d261b4fcc9e55340a246960899a810 100644 (file)
@@ -26,8 +26,55 @@ extern "C" {
 #endif
 
 
+/* Converts the initial portion of the string starting at STR (if PTR != NULL)
+   or the entire string starting at STR (if PTR == NULL) to a number of type
+   'double'.
+   CONVERT should be a conversion function with the same calling conventions
+   as strtod, such as strtod or c_strtod.
+   If successful, it returns true, with *RESULT set to the result.
+   If it fails, it returns false, with *RESULT and errno set.
+   In total, there are the following cases:
+
+   Condition                                          RET     *RESULT     errno
+   -----------------------------------------------------------------------------
+   conversion error: no number parsed                 false   0.0         EINVAL or 0
+   PTR == NULL, number parsed but junk after number   false   value       0
+   NaN                                                true    NaN         0
+   ±Infinity                                          true    ±HUGE_VAL   0
+   overflow                                           false   ±HUGE_VAL   ERANGE
+   gradual underflow [!MSVC]                          false   near zero   ERANGE
+   gradual underflow [MSVC]                           true    near zero   0
+   flush-to-zero underflow                            true    ±0.0        ERANGE
+   other finite value                                 true    value       0
+
+   In both cases, if PTR != NULL, *PTR is set to point to the character after
+   the parsed number.  */
 bool xstrtod (const char *str, const char **ptr, double *result,
               double (*convert) (char const *, char **));
+
+/* Converts the initial portion of the string starting at STR (if PTR != NULL)
+   or the entire string starting at STR (if PTR == NULL) to a number of type
+   'long double'.
+   CONVERT should be a conversion function with the same calling conventions
+   as strtold, such as strtold or c_strtold.
+   If successful, it returns true, with *RESULT set to the result.
+   If it fails, it returns false, with *RESULT and errno set.
+   In total, there are the following cases:
+
+   Condition                                          RET     *RESULT     errno
+   -----------------------------------------------------------------------------
+   conversion error: no number parsed                 false   0.0L        EINVAL or 0
+   PTR == NULL, number parsed but junk after number   false   value       0
+   NaN                                                true    NaN         0
+   ±Infinity                                          true    ±HUGE_VALL  0
+   overflow                                           false   ±HUGE_VALL  ERANGE
+   gradual underflow [!MSVC]                          false   near zero   ERANGE
+   gradual underflow [MSVC]                           true    near zero   0
+   flush-to-zero underflow                            true    ±0.0L       ERANGE
+   other finite value                                 true    value       0
+
+   In both cases, if PTR != NULL, *PTR is set to point to the character after
+   the parsed number.  */
 bool xstrtold (const char *str, const char **ptr, long double *result,
                long double (*convert) (char const *, char **));