diff options
Diffstat (limited to 'man-pages-posix-2017/man3p/wcstod.3p')
| -rw-r--r-- | man-pages-posix-2017/man3p/wcstod.3p | 270 |
1 files changed, 270 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man3p/wcstod.3p b/man-pages-posix-2017/man3p/wcstod.3p new file mode 100644 index 0000000..5a68707 --- /dev/null +++ b/man-pages-posix-2017/man3p/wcstod.3p @@ -0,0 +1,270 @@ +'\" et +.TH WCSTOD "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcstod, +wcstof, +wcstold +\(em convert a wide-character string to a double-precision number +.SH SYNOPSIS +.LP +.nf +#include <wchar.h> +.P +double wcstod(const wchar_t *restrict \fInptr\fP, wchar_t **restrict \fIendptr\fP); +float wcstof(const wchar_t *restrict \fInptr\fP, wchar_t **restrict \fIendptr\fP); +long double wcstold(const wchar_t *restrict \fInptr\fP, + wchar_t **restrict \fIendptr\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall convert the initial portion of the wide-character +string pointed to by +.IR nptr +to +.BR double , +.BR float , +and +.BR "long double" +representation, respectively. First, they shall decompose the input +wide-character string into three parts: +.IP " 1." 4 +An initial, possibly empty, sequence of white-space wide-character +codes (as specified by +\fIiswspace\fR()) +.IP " 2." 4 +A subject sequence interpreted as a floating-point constant or +representing infinity or NaN +.IP " 3." 4 +A final wide-character string of one or more unrecognized wide-character +codes, including the terminating null wide-character code of the input +wide-character string +.P +Then they shall attempt to convert the subject sequence to a +floating-point number, and return the result. +.P +The expected form of the subject sequence is an optional +.BR '+' +or +.BR '\-' +sign, then one of the following: +.IP " *" 4 +A non-empty sequence of decimal digits optionally containing a radix +character; then an optional exponent part consisting of the wide +character +.BR 'e' +or the wide character +.BR 'E' , +optionally followed by a +.BR '+' +or +.BR '\-' +wide character, and then followed by one or more decimal digits +.IP " *" 4 +A 0x or 0X, then a non-empty sequence of hexadecimal digits optionally +containing a radix character; then an optional binary exponent part +consisting of the wide character +.BR 'p' +or the wide character +.BR 'P' , +optionally followed by a +.BR '+' +or +.BR '\-' +wide character, and then followed by one or more decimal digits +.IP " *" 4 +One of INF or INFINITY, or any other wide string equivalent except for +case +.IP " *" 4 +One of NAN or NAN(\fIn-wchar-sequence\s-3\dopt\u\s+3\fR), or any other +wide string ignoring case in the NAN part, where: +.RS 4 +.sp +.RS 4 +.nf + +n-wchar-sequence: + digit + nondigit + n-wchar-sequence digit + n-wchar-sequence nondigit +.fi +.P +.RE +.RE +.P +The subject sequence is defined as the longest initial subsequence of +the input wide string, starting with the first non-white-space wide +character, that is of the expected form. The subject sequence contains +no wide characters if the input wide string is not of the expected +form. +.P +If the subject sequence has the expected form for a floating-point +number, the sequence of wide characters starting with the first digit +or the radix character (whichever occurs first) shall be interpreted as +a floating constant according to the rules of the C language, except +that the radix character shall be used in place of a period, and that +if neither an exponent part nor a radix character appears in a decimal +floating-point number, or if a binary exponent part does not appear in +a hexadecimal floating-point number, an exponent part of the +appropriate type with value zero shall be assumed to follow the last +digit in the string. If the subject sequence begins with a +<hyphen-minus>, +the sequence shall be interpreted as negated. A wide-character sequence +INF or INFINITY shall be interpreted as an infinity, if representable +in the return type, else as if it were a floating constant that is too +large for the range of the return type. A wide-character sequence NAN +or NAN(\fIn-wchar-sequence\s-3\dopt\u\s+3\fR) shall be interpreted as a +quiet NaN, if supported in the return type, else as if it were a +subject sequence part that does not have the expected form; the meaning +of the \fIn\fP-wchar sequences is implementation-defined. A pointer to +the final wide string shall be stored in the object pointed to by +.IR endptr , +provided that +.IR endptr +is not a null pointer. +.P +If the subject sequence has the hexadecimal form and FLT_RADIX is a +power of 2, the conversion shall be rounded in an +implementation-defined manner. +.P +The radix character shall be as defined in the current locale +(category +.IR LC_NUMERIC ). +In the POSIX locale, or in a locale where the radix character is not +defined, the radix character shall default to a +<period> +(\c +.BR '.' ). +.P +In other than the C +or POSIX +locale, additional locale-specific subject sequence forms may be +accepted. +.P +If the subject sequence is empty or does not have the expected form, no +conversion shall be performed; the value of +.IR nptr +shall be stored in the object pointed to by +.IR endptr , +provided that +.IR endptr +is not a null pointer. +.P +These functions shall not change the setting of +.IR errno +if successful. +.P +Since 0 is returned on error and is also a valid return on success, +an application wishing to check for error situations should set +.IR errno +to 0, then call +\fIwcstod\fR(), +\fIwcstof\fR(), +or +\fIwcstold\fR(), +then check +.IR errno . +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the converted +value. If no conversion could be performed, 0 shall be returned +and +.IR errno +may be set to +.BR [EINVAL] . +.P +If the correct value is outside the range of representable values, +\(+-HUGE_VAL, \(+-HUGE_VALF, or \(+-HUGE_VALL shall be returned +(according to the sign of the value), and +.IR errno +shall be set to +.BR [ERANGE] . +.P +If the correct value would cause underflow, a value whose magnitude is +no greater than the smallest normalized positive number in the return +type shall be returned and +.IR errno +set to +.BR [ERANGE] . +.SH ERRORS +The +\fIwcstod\fR() +function shall fail if: +.TP +.BR ERANGE +The value to be returned would cause overflow or underflow. +.P +The +\fIwcstod\fR() +function may fail if: +.TP +.BR EINVAL +No conversion could be performed. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If the subject sequence has the hexadecimal form and FLT_RADIX is not a +power of 2, and the result is not exactly representable, the result +should be one of the two numbers in the appropriate internal format +that are adjacent to the hexadecimal floating source value, with the +extra stipulation that the error should have a correct sign for the +current rounding direction. +.P +If the subject sequence has the decimal form and at most DECIMAL_DIG +(defined in +.IR <float.h> ) +significant digits, the result should be correctly rounded. If the +subject sequence \fID\fP has the decimal form and more than DECIMAL_DIG +significant digits, consider the two bounding, adjacent decimal strings +\fIL\fP and \fIU\fP, both having DECIMAL_DIG significant digits, such +that the values of \fIL\fP, \fID\fP, and \fIU\fP satisfy +.BR \(dqL <= D <= U\(dq . +The result should be one of the (equal or adjacent) values that would +be obtained by correctly rounding \fIL\fP and \fIU\fP according to the +current rounding direction, with the extra stipulation that the error +with respect to \fID\fP should have a correct sign for the current +rounding direction. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIlocaleconv\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIwcstol\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB<float.h>\fP", +.IR "\fB<wchar.h>\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |