Inspired by the discussion around xstrtol, I looked at xstrtod.
I plan to commit this documentation, when savannah allows. And to look
at the two FIXMEs regarding platform-dependent behaviour...
2024-07-18 Bruno Haible <br...@clisp.org>
xstrtod, xstrtold: Add documentation.
* lib/xstrtod.h (xstrtod, xstrtold): Add comments.
* lib/xstrtod.c (XSTRTOD): Add two FIXMEs.
diff --git a/lib/xstrtod.c b/lib/xstrtod.c
index 55b4bb4a8f..f99c943805 100644
--- a/lib/xstrtod.c
+++ b/lib/xstrtod.c
@@ -59,6 +59,8 @@ XSTRTOD (char const *str, char const **ptr, DOUBLE *result,
/* 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. */
+ /* FIXME: Upon underflow, CONVERT may return non-zero. */
+ /* FIXME: errno is unchanged if (math_errhandling & MATH_ERRNO) == 0. */
if (val != 0 && errno == ERANGE)
ok = false;
}
diff --git a/lib/xstrtod.h b/lib/xstrtod.h
index 9ae4be13da..a1d2ce06f7 100644
--- a/lib/xstrtod.h
+++ b/lib/xstrtod.h
@@ -26,8 +26,37 @@ 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 set to
+ - 0.0 upon conversion error,
+ - ±HUGE_VAL (i.e. ±Infinity) upon overflow,
+ - a value near zero upon underflow (only in implementations which consider
+ underflow to be an error),
+ and _maybe_ errno set as well.
+ 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 set to
+ - 0.0L upon conversion error,
+ - ±HUGE_VALL (i.e. ±Infinity) upon overflow,
+ - a value near zero upon underflow (only in implementations which consider
+ underflow to be an error),
+ and _maybe_ errno set as well.
+ 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 **));
