* Complex Numbers:: The types. Writing complex constants.
* Operations on Complex:: Projection, conjugation, decomposition.
* Parsing of Numbers:: Converting strings to numbers.
+* Printing of Floats:: Converting floating-point numbers to strings.
* System V Number Conversion:: An archaic way to convert numbers to strings.
@end menu
To use these facilities, you should include the header file
@file{stdlib.h} in your program.
-@comment stdlib.h
-@comment ISO
@deftp {Data Type} div_t
+@standards{ISO, stdlib.h}
This is a structure type used to hold the result returned by the @code{div}
function. It has the following members:
@end table
@end deftp
-@comment stdlib.h
-@comment ISO
@deftypefun div_t div (int @var{numerator}, int @var{denominator})
+@standards{ISO, stdlib.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c Functions in this section are pure, and thus safe.
-This function @code{div} computes the quotient and remainder from
+The function @code{div} computes the quotient and remainder from
the division of @var{numerator} by @var{denominator}, returning the
result in a structure of type @code{div_t}.
Now @code{result.quot} is @code{-3} and @code{result.rem} is @code{2}.
@end deftypefun
-@comment stdlib.h
-@comment ISO
@deftp {Data Type} ldiv_t
+@standards{ISO, stdlib.h}
This is a structure type used to hold the result returned by the @code{ldiv}
function. It has the following members:
type @code{long int} rather than @code{int}.)
@end deftp
-@comment stdlib.h
-@comment ISO
@deftypefun ldiv_t ldiv (long int @var{numerator}, long int @var{denominator})
+@standards{ISO, stdlib.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{ldiv} function is similar to @code{div}, except that the
arguments are of type @code{long int} and the result is returned as a
structure of type @code{ldiv_t}.
@end deftypefun
-@comment stdlib.h
-@comment ISO
@deftp {Data Type} lldiv_t
+@standards{ISO, stdlib.h}
This is a structure type used to hold the result returned by the @code{lldiv}
function. It has the following members:
type @code{long long int} rather than @code{int}.)
@end deftp
-@comment stdlib.h
-@comment ISO
@deftypefun lldiv_t lldiv (long long int @var{numerator}, long long int @var{denominator})
+@standards{ISO, stdlib.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{lldiv} function is like the @code{div} function, but the
arguments are of type @code{long long int} and the result is returned as
The @code{lldiv} function was added in @w{ISO C99}.
@end deftypefun
-@comment inttypes.h
-@comment ISO
@deftp {Data Type} imaxdiv_t
+@standards{ISO, inttypes.h}
This is a structure type used to hold the result returned by the @code{imaxdiv}
function. It has the following members:
@end deftp
-@comment inttypes.h
-@comment ISO
@deftypefun imaxdiv_t imaxdiv (intmax_t @var{numerator}, intmax_t @var{denominator})
+@standards{ISO, inttypes.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{imaxdiv} function is like the @code{div} function, but the
arguments are of type @code{intmax_t} and the result is returned as
@w{ISO C99} defines macros that let you determine what sort of
floating-point number a variable holds.
-@comment math.h
-@comment ISO
@deftypefn {Macro} int fpclassify (@emph{float-type} @var{x})
+@standards{ISO, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This is a generic macro which works on all floating-point types and
which returns a value of type @code{int}. The possible values are:
@vtable @code
@item FP_NAN
+@standards{C99, math.h}
The floating-point number @var{x} is ``Not a Number'' (@pxref{Infinity
and NaN})
@item FP_INFINITE
+@standards{C99, math.h}
The value of @var{x} is either plus or minus infinity (@pxref{Infinity
and NaN})
@item FP_ZERO
+@standards{C99, math.h}
The value of @var{x} is zero. In floating-point formats like @w{IEEE
754}, where zero can be signed, this value is also returned if
@var{x} is negative zero.
@item FP_SUBNORMAL
+@standards{C99, math.h}
Numbers whose absolute value is too small to be represented in the
normal format are represented in an alternate, @dfn{denormalized} format
(@pxref{Floating Point Concepts}). This format is less precise but can
represent values closer to zero. @code{fpclassify} returns this value
for values of @var{x} in this alternate format.
@item FP_NORMAL
+@standards{C99, math.h}
This value is returned for all other values of @var{x}. It indicates
that there is nothing special about the number.
@end vtable
@code{fpclassify}, since there is special hardware support for them.
You should therefore use the specific macros whenever possible.
-@comment math.h
-@comment ISO
+@deftypefn {Macro} int iscanonical (@emph{float-type} @var{x})
+@standards{ISO, math.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+In some floating-point formats, some values have canonical (preferred)
+and noncanonical encodings (for IEEE interchange binary formats, all
+encodings are canonical). This macro returns a nonzero value if
+@var{x} has a canonical encoding. It is from TS 18661-1:2014.
+
+Note that some formats have multiple encodings of a value which are
+all equally canonical; @code{iscanonical} returns a nonzero value for
+all such encodings. Also, formats may have encodings that do not
+correspond to any valid value of the type. In ISO C terms these are
+@dfn{trap representations}; in @theglibc{}, @code{iscanonical} returns
+zero for such encodings.
+@end deftypefn
+
@deftypefn {Macro} int isfinite (@emph{float-type} @var{x})
+@standards{ISO, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This macro returns a nonzero value if @var{x} is finite: not plus or
minus infinity, and not NaN. It is equivalent to
floating-point type.
@end deftypefn
-@comment math.h
-@comment ISO
@deftypefn {Macro} int isnormal (@emph{float-type} @var{x})
+@standards{ISO, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This macro returns a nonzero value if @var{x} is finite and normalized.
It is equivalent to
@end smallexample
@end deftypefn
-@comment math.h
-@comment ISO
@deftypefn {Macro} int isnan (@emph{float-type} @var{x})
+@standards{ISO, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This macro returns a nonzero value if @var{x} is NaN. It is equivalent
to
@end smallexample
@end deftypefn
-@comment math.h
-@comment ISO
@deftypefn {Macro} int issignaling (@emph{float-type} @var{x})
+@standards{ISO, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This macro returns a nonzero value if @var{x} is a signaling NaN
(sNaN). It is from TS 18661-1:2014.
@end deftypefn
-@comment math.h
-@comment ISO
@deftypefn {Macro} int issubnormal (@emph{float-type} @var{x})
+@standards{ISO, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This macro returns a nonzero value if @var{x} is subnormal. It is
from TS 18661-1:2014.
@end deftypefn
-@comment math.h
-@comment ISO
@deftypefn {Macro} int iszero (@emph{float-type} @var{x})
+@standards{ISO, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This macro returns a nonzero value if @var{x} is zero. It is from TS
18661-1:2014.
and will be available more widely. Also, since they are macros, you do
not have to worry about the type of their argument.
-@comment math.h
-@comment BSD
@deftypefun int isinf (double @var{x})
-@comment math.h
-@comment BSD
@deftypefunx int isinff (float @var{x})
-@comment math.h
-@comment BSD
@deftypefunx int isinfl (long double @var{x})
+@standards{BSD, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function returns @code{-1} if @var{x} represents negative infinity,
@code{1} if @var{x} represents positive infinity, and @code{0} otherwise.
@end deftypefun
-@comment math.h
-@comment BSD
@deftypefun int isnan (double @var{x})
-@comment math.h
-@comment BSD
@deftypefunx int isnanf (float @var{x})
-@comment math.h
-@comment BSD
@deftypefunx int isnanl (long double @var{x})
+@standards{BSD, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function returns a nonzero value if @var{x} is a ``not a number''
value, and zero otherwise.
@end smallexample
@end deftypefun
-@comment math.h
-@comment BSD
@deftypefun int finite (double @var{x})
-@comment math.h
-@comment BSD
@deftypefunx int finitef (float @var{x})
-@comment math.h
-@comment BSD
@deftypefunx int finitel (long double @var{x})
+@standards{BSD, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
-This function returns a nonzero value if @var{x} is finite or a ``not a
-number'' value, and zero otherwise.
+This function returns a nonzero value if @var{x} is neither infinite nor
+a ``not a number'' value, and zero otherwise.
@end deftypefun
@strong{Portability Note:} The functions listed in this section are BSD
program. @xref{Signal Handling}, for how you can change the effect of
the signal.
-@findex matherr
-In the System V math library, the user-defined function @code{matherr}
-is called when certain exceptions occur inside math library functions.
-However, the Unix98 standard deprecates this interface. We support it
-for historical compatibility, but recommend that you do not use it in
-new programs. When this interface is used, exceptions may not be
-raised.
-
@noindent
The exceptions defined in @w{IEEE 754} are:
Remainder: @math{x} REM @math{y}, where @math{y} is zero or @math{x} is
infinite.
@item
-Square root if the operand is less then zero. More generally, any
+Square root if the operand is less than zero. More generally, any
mathematical function evaluated outside its domain produces this
exception.
@item
@file{math.h} defines macros that allow you to explicitly set a variable
to infinity or NaN.
-@comment math.h
-@comment ISO
@deftypevr Macro float INFINITY
+@standards{ISO, math.h}
An expression representing positive infinity. It is equal to the value
produced by mathematical operations like @code{1.0 / 0.0}.
@code{-INFINITY} represents negative infinity.
This macro was introduced in the @w{ISO C99} standard.
@end deftypevr
-@comment math.h
-@comment GNU
@deftypevr Macro float NAN
+@standards{GNU, math.h}
An expression representing a value which is ``not a number''. This
macro is a GNU extension, available only on machines that support the
``not a number'' value---that is to say, on all machines that support
@file{math.h}.)
@end deftypevr
+@deftypevr Macro float SNANF
+@deftypevrx Macro double SNAN
+@deftypevrx Macro {long double} SNANL
+@deftypevrx Macro _FloatN SNANFN
+@deftypevrx Macro _FloatNx SNANFNx
+@standards{TS 18661-1:2014, math.h}
+@standardsx{SNANFN, TS 18661-3:2015, math.h}
+@standardsx{SNANFNx, TS 18661-3:2015, math.h}
+These macros, defined by TS 18661-1:2014 and TS 18661-3:2015, are
+constant expressions for signaling NaNs.
+@end deftypevr
+
+@deftypevr Macro int FE_SNANS_ALWAYS_SIGNAL
+@standards{ISO, fenv.h}
+This macro, defined by TS 18661-1:2014, is defined to @code{1} in
+@file{fenv.h} to indicate that functions and operations with signaling
+NaN inputs and floating-point results always raise the invalid
+exception and return a quiet NaN, even in cases (such as @code{fmax},
+@code{hypot} and @code{pow}) where a quiet NaN input can produce a
+non-NaN result. Because some compiler optimizations may not handle
+signaling NaNs correctly, this macro is only defined if compiler
+support for signaling NaNs is enabled. That support can be enabled
+with the GCC option @option{-fsignaling-nans}.
+@end deftypevr
+
@w{IEEE 754} also allows for another unusual value: negative zero. This
value is produced when you divide a positive number by negative
infinity, or when a negative result is smaller than the limits of
@file{fenv.h}.
@vtable @code
-@comment fenv.h
-@comment ISO
@item FE_INEXACT
+@standards{ISO, fenv.h}
The inexact exception.
-@comment fenv.h
-@comment ISO
@item FE_DIVBYZERO
+@standards{ISO, fenv.h}
The divide by zero exception.
-@comment fenv.h
-@comment ISO
@item FE_UNDERFLOW
+@standards{ISO, fenv.h}
The underflow exception.
-@comment fenv.h
-@comment ISO
@item FE_OVERFLOW
+@standards{ISO, fenv.h}
The overflow exception.
-@comment fenv.h
-@comment ISO
@item FE_INVALID
+@standards{ISO, fenv.h}
The invalid exception.
@end vtable
These functions allow you to clear exception flags, test for exceptions,
and save and restore the set of exceptions flagged.
-@comment fenv.h
-@comment ISO
@deftypefun int feclearexcept (int @var{excepts})
+@standards{ISO, fenv.h}
@safety{@prelim{}@mtsafe{}@assafe{@assposix{}}@acsafe{@acsposix{}}}
@c The other functions in this section that modify FP status register
@c mostly do so with non-atomic load-modify-store sequences, but since
non-zero value otherwise.
@end deftypefun
-@comment fenv.h
-@comment ISO
@deftypefun int feraiseexcept (int @var{excepts})
+@standards{ISO, fenv.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function raises the supported exceptions indicated by
@var{excepts}. If more than one exception bit in @var{excepts} is set
non-zero value otherwise.
@end deftypefun
-@comment fenv.h
-@comment ISO
@deftypefun int fesetexcept (int @var{excepts})
+@standards{ISO, fenv.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function sets the supported exception flags indicated by
@var{excepts}, like @code{feraiseexcept}, but without causing enabled
non-zero value otherwise.
@end deftypefun
-@comment fenv.h
-@comment ISO
@deftypefun int fetestexcept (int @var{excepts})
+@standards{ISO, fenv.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Test whether the exception flags indicated by the parameter @var{except}
are currently set. If any of them are, a nonzero value is returned
save the entire status word and restore it later. This is done with the
following functions:
-@comment fenv.h
-@comment ISO
@deftypefun int fegetexceptflag (fexcept_t *@var{flagp}, int @var{excepts})
+@standards{ISO, fenv.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function stores in the variable pointed to by @var{flagp} an
implementation-defined value representing the current setting of the
non-zero value otherwise.
@end deftypefun
-@comment fenv.h
-@comment ISO
@deftypefun int fesetexceptflag (const fexcept_t *@var{flagp}, int @var{excepts})
+@standards{ISO, fenv.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function restores the flags for the exceptions indicated by
@var{excepts} to the values stored in the variable pointed to by
the bit mask returned by @code{fetestexcept}. The type may not even be
an integer. Do not attempt to modify an @code{fexcept_t} variable.
-@comment fenv.h
-@comment ISO
@deftypefun int fetestexceptflag (const fexcept_t *@var{flagp}, int @var{excepts})
+@standards{ISO, fenv.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Test whether the exception flags indicated by the parameter
@var{excepts} are set in the variable pointed to by @var{flagp}. If
underflow is to an appropriately signed zero, but not necessarily for
other underflows.
+When a math function has an argument that is a signaling NaN,
+@theglibc{} does not consider this a domain error, so @code{errno} is
+unchanged, but the invalid exception is still raised (except for a few
+functions that are specified to handle signaling NaNs differently).
+
Some of the math functions are defined mathematically to result in a
complex value over parts of their domains. The most familiar example of
this is taking the square root of a negative number. The complex math
largest representable number). @file{math.h} defines macros you can use
to test for overflow on both old and new hardware.
-@comment math.h
-@comment ISO
@deftypevr Macro double HUGE_VAL
-@comment math.h
-@comment ISO
@deftypevrx Macro float HUGE_VALF
-@comment math.h
-@comment ISO
@deftypevrx Macro {long double} HUGE_VALL
+@deftypevrx Macro _FloatN HUGE_VAL_FN
+@deftypevrx Macro _FloatNx HUGE_VAL_FNx
+@standards{ISO, math.h}
+@standardsx{HUGE_VAL_FN, TS 18661-3:2015, math.h}
+@standardsx{HUGE_VAL_FNx, TS 18661-3:2015, math.h}
An expression representing a particular very large number. On machines
that use @w{IEEE 754} floating point format, @code{HUGE_VAL} is infinity.
On other machines, it's typically the largest positive number that can
various rounding modes. Each one will be defined if and only if the FPU
supports the corresponding rounding mode.
-@table @code
-@comment fenv.h
-@comment ISO
-@vindex FE_TONEAREST
+@vtable @code
@item FE_TONEAREST
+@standards{ISO, fenv.h}
Round to nearest.
-@comment fenv.h
-@comment ISO
-@vindex FE_UPWARD
@item FE_UPWARD
+@standards{ISO, fenv.h}
Round toward @math{+@infinity{}}.
-@comment fenv.h
-@comment ISO
-@vindex FE_DOWNWARD
@item FE_DOWNWARD
+@standards{ISO, fenv.h}
Round toward @math{-@infinity{}}.
-@comment fenv.h
-@comment ISO
-@vindex FE_TOWARDZERO
@item FE_TOWARDZERO
+@standards{ISO, fenv.h}
Round toward zero.
-@end table
+@end vtable
Underflow is an unusual case. Normally, @w{IEEE 754} floating point
numbers are always normalized (@pxref{Floating Point Concepts}).
Negative zero can also result from some operations on infinity, such as
@math{4/-@infinity{}}.
-At any time one of the above four rounding modes is selected. You can
+At any time, one of the above four rounding modes is selected. You can
find out which one with this function:
-@comment fenv.h
-@comment ISO
@deftypefun int fegetround (void)
+@standards{ISO, fenv.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Returns the currently selected rounding mode, represented by one of the
values of the defined rounding mode macros.
@noindent
To change the rounding mode, use this function:
-@comment fenv.h
-@comment ISO
@deftypefun int fesetround (int @var{round})
+@standards{ISO, fenv.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Changes the currently selected rounding mode to @var{round}. If
@var{round} does not correspond to one of the supported rounding modes
nothing is changed. @code{fesetround} returns zero if it changed the
-rounding mode, a nonzero value if the mode is not supported.
+rounding mode, or a nonzero value if the mode is not supported.
@end deftypefun
You should avoid changing the rounding mode if possible. It can be an
To save the state of the FPU, use one of these functions:
-@comment fenv.h
-@comment ISO
@deftypefun int fegetenv (fenv_t *@var{envp})
+@standards{ISO, fenv.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Store the floating-point environment in the variable pointed to by
@var{envp}.
non-zero value otherwise.
@end deftypefun
-@comment fenv.h
-@comment ISO
@deftypefun int feholdexcept (fenv_t *@var{envp})
+@standards{ISO, fenv.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Store the current floating-point environment in the object pointed to by
@var{envp}. Then clear all exception flags, and set the FPU to trap no
To set the floating-point environment, you can use either of these
functions:
-@comment fenv.h
-@comment ISO
@deftypefun int fesetenv (const fenv_t *@var{envp})
+@standards{ISO, fenv.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Set the floating-point environment to that described by @var{envp}.
non-zero value otherwise.
@end deftypefun
-@comment fenv.h
-@comment ISO
@deftypefun int feupdateenv (const fenv_t *@var{envp})
+@standards{ISO, fenv.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Like @code{fesetenv}, this function sets the floating-point environment
to that described by @var{envp}. However, if any exceptions were
@code{fesetmode}. It represents the floating-point control modes at
program start.
-@comment fenv.h
-@comment ISO
@deftypefun int fegetmode (femode_t *@var{modep})
+@standards{ISO, fenv.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Store the floating-point control modes in the variable pointed to by
@var{modep}.
non-zero value otherwise.
@end deftypefun
-@comment fenv.h
-@comment ISO
@deftypefun int fesetmode (const femode_t *@var{modep})
+@standards{ISO, fenv.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Set the floating-point control modes to those described by
@var{modep}.
@strong{Portability Note:} These functions are all GNU extensions.
-@comment fenv.h
-@comment GNU
@deftypefun int feenableexcept (int @var{excepts})
+@standards{GNU, fenv.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
-This functions enables traps for each of the exceptions as indicated by
-the parameter @var{except}. The individual exceptions are described in
+This function enables traps for each of the exceptions as indicated by
+the parameter @var{excepts}. The individual exceptions are described in
@ref{Status bit operations}. Only the specified exceptions are
enabled, the status of the other exceptions is not changed.
operation was successful, @code{-1} otherwise.
@end deftypefun
-@comment fenv.h
-@comment GNU
@deftypefun int fedisableexcept (int @var{excepts})
+@standards{GNU, fenv.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
-This functions disables traps for each of the exceptions as indicated by
-the parameter @var{except}. The individual exceptions are described in
+This function disables traps for each of the exceptions as indicated by
+the parameter @var{excepts}. The individual exceptions are described in
@ref{Status bit operations}. Only the specified exceptions are
disabled, the status of the other exceptions is not changed.
operation was successful, @code{-1} otherwise.
@end deftypefun
-@comment fenv.h
-@comment GNU
@deftypefun int fegetexcept (void)
+@standards{GNU, fenv.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The function returns a bitmask of all currently enabled exceptions. It
returns @code{-1} in case of failure.
@pindex stdlib.h
Prototypes for @code{abs}, @code{labs} and @code{llabs} are in @file{stdlib.h};
@code{imaxabs} is declared in @file{inttypes.h};
-@code{fabs}, @code{fabsf} and @code{fabsl} are declared in @file{math.h}.
-@code{cabs}, @code{cabsf} and @code{cabsl} are declared in @file{complex.h}.
+the @code{fabs} functions are declared in @file{math.h};
+the @code{cabs} functions are declared in @file{complex.h}.
-@comment stdlib.h
-@comment ISO
@deftypefun int abs (int @var{number})
-@comment stdlib.h
-@comment ISO
@deftypefunx {long int} labs (long int @var{number})
-@comment stdlib.h
-@comment ISO
@deftypefunx {long long int} llabs (long long int @var{number})
-@comment inttypes.h
-@comment ISO
@deftypefunx intmax_t imaxabs (intmax_t @var{number})
+@standards{ISO, stdlib.h}
+@standardsx{imaxabs, ISO, inttypes.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
These functions return the absolute value of @var{number}.
@end deftypefun
-@comment math.h
-@comment ISO
@deftypefun double fabs (double @var{number})
-@comment math.h
-@comment ISO
@deftypefunx float fabsf (float @var{number})
-@comment math.h
-@comment ISO
@deftypefunx {long double} fabsl (long double @var{number})
+@deftypefunx _FloatN fabsfN (_Float@var{N} @var{number})
+@deftypefunx _FloatNx fabsfNx (_Float@var{N}x @var{number})
+@standards{ISO, math.h}
+@standardsx{fabsfN, TS 18661-3:2015, math.h}
+@standardsx{fabsfNx, TS 18661-3:2015, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function returns the absolute value of the floating-point number
@var{number}.
@end deftypefun
-@comment complex.h
-@comment ISO
@deftypefun double cabs (complex double @var{z})
-@comment complex.h
-@comment ISO
@deftypefunx float cabsf (complex float @var{z})
-@comment complex.h
-@comment ISO
@deftypefunx {long double} cabsl (complex long double @var{z})
+@deftypefunx _FloatN cabsfN (complex _Float@var{N} @var{z})
+@deftypefunx _FloatNx cabsfNx (complex _Float@var{N}x @var{z})
+@standards{ISO, complex.h}
+@standardsx{cabsfN, TS 18661-3:2015, complex.h}
+@standardsx{cabsfNx, TS 18661-3:2015, complex.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
These functions return the absolute value of the complex number @var{z}
(@pxref{Complex Numbers}). The absolute value of a complex number is:
@pindex math.h
All these functions are declared in @file{math.h}.
-@comment math.h
-@comment ISO
@deftypefun double frexp (double @var{value}, int *@var{exponent})
-@comment math.h
-@comment ISO
@deftypefunx float frexpf (float @var{value}, int *@var{exponent})
-@comment math.h
-@comment ISO
@deftypefunx {long double} frexpl (long double @var{value}, int *@var{exponent})
+@deftypefunx _FloatN frexpfN (_Float@var{N} @var{value}, int *@var{exponent})
+@deftypefunx _FloatNx frexpfNx (_Float@var{N}x @var{value}, int *@var{exponent})
+@standards{ISO, math.h}
+@standardsx{frexpfN, TS 18661-3:2015, math.h}
+@standardsx{frexpfNx, TS 18661-3:2015, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
These functions are used to split the number @var{value}
into a normalized fraction and an exponent.
zero is stored in @code{*@var{exponent}}.
@end deftypefun
-@comment math.h
-@comment ISO
@deftypefun double ldexp (double @var{value}, int @var{exponent})
-@comment math.h
-@comment ISO
@deftypefunx float ldexpf (float @var{value}, int @var{exponent})
-@comment math.h
-@comment ISO
@deftypefunx {long double} ldexpl (long double @var{value}, int @var{exponent})
+@deftypefunx _FloatN ldexpfN (_Float@var{N} @var{value}, int @var{exponent})
+@deftypefunx _FloatNx ldexpfNx (_Float@var{N}x @var{value}, int @var{exponent})
+@standards{ISO, math.h}
+@standardsx{ldexpfN, TS 18661-3:2015, math.h}
+@standardsx{ldexpfNx, TS 18661-3:2015, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
These functions return the result of multiplying the floating-point
number @var{value} by 2 raised to the power @var{exponent}. (It can
The following functions, which come from BSD, provide facilities
equivalent to those of @code{ldexp} and @code{frexp}. See also the
@w{ISO C} function @code{logb} which originally also appeared in BSD.
+The @code{_Float@var{N}} and @code{_Float@var{N}} variants of the
+following functions come from TS 18661-3:2015.
-@comment math.h
-@comment BSD
@deftypefun double scalb (double @var{value}, double @var{exponent})
-@comment math.h
-@comment BSD
@deftypefunx float scalbf (float @var{value}, float @var{exponent})
-@comment math.h
-@comment BSD
@deftypefunx {long double} scalbl (long double @var{value}, long double @var{exponent})
+@standards{BSD, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{scalb} function is the BSD name for @code{ldexp}.
@end deftypefun
-@comment math.h
-@comment BSD
@deftypefun double scalbn (double @var{x}, int @var{n})
-@comment math.h
-@comment BSD
@deftypefunx float scalbnf (float @var{x}, int @var{n})
-@comment math.h
-@comment BSD
@deftypefunx {long double} scalbnl (long double @var{x}, int @var{n})
+@deftypefunx _FloatN scalbnfN (_Float@var{N} @var{x}, int @var{n})
+@deftypefunx _FloatNx scalbnfNx (_Float@var{N}x @var{x}, int @var{n})
+@standards{BSD, math.h}
+@standardsx{scalbnfN, TS 18661-3:2015, math.h}
+@standardsx{scalbnfNx, TS 18661-3:2015, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@code{scalbn} is identical to @code{scalb}, except that the exponent
@var{n} is an @code{int} instead of a floating-point number.
@end deftypefun
-@comment math.h
-@comment BSD
@deftypefun double scalbln (double @var{x}, long int @var{n})
-@comment math.h
-@comment BSD
@deftypefunx float scalblnf (float @var{x}, long int @var{n})
-@comment math.h
-@comment BSD
@deftypefunx {long double} scalblnl (long double @var{x}, long int @var{n})
+@deftypefunx _FloatN scalblnfN (_Float@var{N} @var{x}, long int @var{n})
+@deftypefunx _FloatNx scalblnfNx (_Float@var{N}x @var{x}, long int @var{n})
+@standards{BSD, math.h}
+@standardsx{scalblnfN, TS 18661-3:2015, math.h}
+@standardsx{scalblnfNx, TS 18661-3:2015, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@code{scalbln} is identical to @code{scalb}, except that the exponent
@var{n} is a @code{long int} instead of a floating-point number.
@end deftypefun
-@comment math.h
-@comment BSD
@deftypefun double significand (double @var{x})
-@comment math.h
-@comment BSD
@deftypefunx float significandf (float @var{x})
-@comment math.h
-@comment BSD
@deftypefunx {long double} significandl (long double @var{x})
+@standards{BSD, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@code{significand} returns the mantissa of @var{x} scaled to the range
@math{[1, 2)}.
numbers, this is impossible. The functions listed here return the
result as a @code{double} instead to get around this problem.
-@comment math.h
-@comment ISO
+The @code{fromfp} functions use the following macros, from TS
+18661-1:2014, to specify the direction of rounding. These correspond
+to the rounding directions defined in IEEE 754-2008.
+
+@vtable @code
+@item FP_INT_UPWARD
+@standards{ISO, math.h}
+Round toward @math{+@infinity{}}.
+
+@item FP_INT_DOWNWARD
+@standards{ISO, math.h}
+Round toward @math{-@infinity{}}.
+
+@item FP_INT_TOWARDZERO
+@standards{ISO, math.h}
+Round toward zero.
+
+@item FP_INT_TONEARESTFROMZERO
+@standards{ISO, math.h}
+Round to nearest, ties round away from zero.
+
+@item FP_INT_TONEAREST
+@standards{ISO, math.h}
+Round to nearest, ties round to even.
+@end vtable
+
@deftypefun double ceil (double @var{x})
-@comment math.h
-@comment ISO
@deftypefunx float ceilf (float @var{x})
-@comment math.h
-@comment ISO
@deftypefunx {long double} ceill (long double @var{x})
+@deftypefunx _FloatN ceilfN (_Float@var{N} @var{x})
+@deftypefunx _FloatNx ceilfNx (_Float@var{N}x @var{x})
+@standards{ISO, math.h}
+@standardsx{ceilfN, TS 18661-3:2015, math.h}
+@standardsx{ceilfNx, TS 18661-3:2015, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
These functions round @var{x} upwards to the nearest integer,
returning that value as a @code{double}. Thus, @code{ceil (1.5)}
is @code{2.0}.
@end deftypefun
-@comment math.h
-@comment ISO
@deftypefun double floor (double @var{x})
-@comment math.h
-@comment ISO
@deftypefunx float floorf (float @var{x})
-@comment math.h
-@comment ISO
@deftypefunx {long double} floorl (long double @var{x})
+@deftypefunx _FloatN floorfN (_Float@var{N} @var{x})
+@deftypefunx _FloatNx floorfNx (_Float@var{N}x @var{x})
+@standards{ISO, math.h}
+@standardsx{floorfN, TS 18661-3:2015, math.h}
+@standardsx{floorfNx, TS 18661-3:2015, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
These functions round @var{x} downwards to the nearest
integer, returning that value as a @code{double}. Thus, @code{floor
(1.5)} is @code{1.0} and @code{floor (-1.5)} is @code{-2.0}.
@end deftypefun
-@comment math.h
-@comment ISO
@deftypefun double trunc (double @var{x})
-@comment math.h
-@comment ISO
@deftypefunx float truncf (float @var{x})
-@comment math.h
-@comment ISO
@deftypefunx {long double} truncl (long double @var{x})
+@deftypefunx _FloatN truncfN (_Float@var{N} @var{x})
+@deftypefunx _FloatNx truncfNx (_Float@var{N}x @var{x})
+@standards{ISO, math.h}
+@standardsx{truncfN, TS 18661-3:2015, math.h}
+@standardsx{truncfNx, TS 18661-3:2015, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{trunc} functions round @var{x} towards zero to the nearest
integer (returned in floating-point format). Thus, @code{trunc (1.5)}
is @code{1.0} and @code{trunc (-1.5)} is @code{-1.0}.
@end deftypefun
-@comment math.h
-@comment ISO
@deftypefun double rint (double @var{x})
-@comment math.h
-@comment ISO
@deftypefunx float rintf (float @var{x})
-@comment math.h
-@comment ISO
@deftypefunx {long double} rintl (long double @var{x})
+@deftypefunx _FloatN rintfN (_Float@var{N} @var{x})
+@deftypefunx _FloatNx rintfNx (_Float@var{N}x @var{x})
+@standards{ISO, math.h}
+@standardsx{rintfN, TS 18661-3:2015, math.h}
+@standardsx{rintfNx, TS 18661-3:2015, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
These functions round @var{x} to an integer value according to the
current rounding mode. @xref{Floating Point Parameters}, for
inexact exception.
@end deftypefun
-@comment math.h
-@comment ISO
@deftypefun double nearbyint (double @var{x})
-@comment math.h
-@comment ISO
@deftypefunx float nearbyintf (float @var{x})
-@comment math.h
-@comment ISO
@deftypefunx {long double} nearbyintl (long double @var{x})
+@deftypefunx _FloatN nearbyintfN (_Float@var{N} @var{x})
+@deftypefunx _FloatNx nearbyintfNx (_Float@var{N}x @var{x})
+@standards{ISO, math.h}
+@standardsx{nearbyintfN, TS 18661-3:2015, math.h}
+@standardsx{nearbyintfNx, TS 18661-3:2015, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
These functions return the same value as the @code{rint} functions, but
do not raise the inexact exception if @var{x} is not an integer.
@end deftypefun
-@comment math.h
-@comment ISO
@deftypefun double round (double @var{x})
-@comment math.h
-@comment ISO
@deftypefunx float roundf (float @var{x})
-@comment math.h
-@comment ISO
@deftypefunx {long double} roundl (long double @var{x})
+@deftypefunx _FloatN roundfN (_Float@var{N} @var{x})
+@deftypefunx _FloatNx roundfNx (_Float@var{N}x @var{x})
+@standards{ISO, math.h}
+@standardsx{roundfN, TS 18661-3:2015, math.h}
+@standardsx{roundfNx, TS 18661-3:2015, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
These functions are similar to @code{rint}, but they round halfway
cases away from zero instead of to the nearest integer (or other
current rounding mode).
@end deftypefun
-@comment math.h
-@comment ISO
+@deftypefun double roundeven (double @var{x})
+@deftypefunx float roundevenf (float @var{x})
+@deftypefunx {long double} roundevenl (long double @var{x})
+@deftypefunx _FloatN roundevenfN (_Float@var{N} @var{x})
+@deftypefunx _FloatNx roundevenfNx (_Float@var{N}x @var{x})
+@standards{ISO, math.h}
+@standardsx{roundevenfN, TS 18661-3:2015, math.h}
+@standardsx{roundevenfNx, TS 18661-3:2015, math.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions, from TS 18661-1:2014 and TS 18661-3:2015, are similar
+to @code{round}, but they round halfway cases to even instead of away
+from zero.
+@end deftypefun
+
@deftypefun {long int} lrint (double @var{x})
-@comment math.h
-@comment ISO
@deftypefunx {long int} lrintf (float @var{x})
-@comment math.h
-@comment ISO
@deftypefunx {long int} lrintl (long double @var{x})
+@deftypefunx {long int} lrintfN (_Float@var{N} @var{x})
+@deftypefunx {long int} lrintfNx (_Float@var{N}x @var{x})
+@standards{ISO, math.h}
+@standardsx{lrintfN, TS 18661-3:2015, math.h}
+@standardsx{lrintfNx, TS 18661-3:2015, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
These functions are just like @code{rint}, but they return a
@code{long int} instead of a floating-point number.
@end deftypefun
-@comment math.h
-@comment ISO
@deftypefun {long long int} llrint (double @var{x})
-@comment math.h
-@comment ISO
@deftypefunx {long long int} llrintf (float @var{x})
-@comment math.h
-@comment ISO
@deftypefunx {long long int} llrintl (long double @var{x})
+@deftypefunx {long long int} llrintfN (_Float@var{N} @var{x})
+@deftypefunx {long long int} llrintfNx (_Float@var{N}x @var{x})
+@standards{ISO, math.h}
+@standardsx{llrintfN, TS 18661-3:2015, math.h}
+@standardsx{llrintfNx, TS 18661-3:2015, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
These functions are just like @code{rint}, but they return a
@code{long long int} instead of a floating-point number.
@end deftypefun
-@comment math.h
-@comment ISO
@deftypefun {long int} lround (double @var{x})
-@comment math.h
-@comment ISO
@deftypefunx {long int} lroundf (float @var{x})
-@comment math.h
-@comment ISO
@deftypefunx {long int} lroundl (long double @var{x})
+@deftypefunx {long int} lroundfN (_Float@var{N} @var{x})
+@deftypefunx {long int} lroundfNx (_Float@var{N}x @var{x})
+@standards{ISO, math.h}
+@standardsx{lroundfN, TS 18661-3:2015, math.h}
+@standardsx{lroundfNx, TS 18661-3:2015, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
These functions are just like @code{round}, but they return a
@code{long int} instead of a floating-point number.
@end deftypefun
-@comment math.h
-@comment ISO
@deftypefun {long long int} llround (double @var{x})
-@comment math.h
-@comment ISO
@deftypefunx {long long int} llroundf (float @var{x})
-@comment math.h
-@comment ISO
@deftypefunx {long long int} llroundl (long double @var{x})
+@deftypefunx {long long int} llroundfN (_Float@var{N} @var{x})
+@deftypefunx {long long int} llroundfNx (_Float@var{N}x @var{x})
+@standards{ISO, math.h}
+@standardsx{llroundfN, TS 18661-3:2015, math.h}
+@standardsx{llroundfNx, TS 18661-3:2015, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
These functions are just like @code{round}, but they return a
@code{long long int} instead of a floating-point number.
@end deftypefun
+@deftypefun intmax_t fromfp (double @var{x}, int @var{round}, unsigned int @var{width})
+@deftypefunx intmax_t fromfpf (float @var{x}, int @var{round}, unsigned int @var{width})
+@deftypefunx intmax_t fromfpl (long double @var{x}, int @var{round}, unsigned int @var{width})
+@deftypefunx intmax_t fromfpfN (_Float@var{N} @var{x}, int @var{round}, unsigned int @var{width})
+@deftypefunx intmax_t fromfpfNx (_Float@var{N}x @var{x}, int @var{round}, unsigned int @var{width})
+@deftypefunx uintmax_t ufromfp (double @var{x}, int @var{round}, unsigned int @var{width})
+@deftypefunx uintmax_t ufromfpf (float @var{x}, int @var{round}, unsigned int @var{width})
+@deftypefunx uintmax_t ufromfpl (long double @var{x}, int @var{round}, unsigned int @var{width})
+@deftypefunx uintmax_t ufromfpfN (_Float@var{N} @var{x}, int @var{round}, unsigned int @var{width})
+@deftypefunx uintmax_t ufromfpfNx (_Float@var{N}x @var{x}, int @var{round}, unsigned int @var{width})
+@deftypefunx intmax_t fromfpx (double @var{x}, int @var{round}, unsigned int @var{width})
+@deftypefunx intmax_t fromfpxf (float @var{x}, int @var{round}, unsigned int @var{width})
+@deftypefunx intmax_t fromfpxl (long double @var{x}, int @var{round}, unsigned int @var{width})
+@deftypefunx intmax_t fromfpxfN (_Float@var{N} @var{x}, int @var{round}, unsigned int @var{width})
+@deftypefunx intmax_t fromfpxfNx (_Float@var{N}x @var{x}, int @var{round}, unsigned int @var{width})
+@deftypefunx uintmax_t ufromfpx (double @var{x}, int @var{round}, unsigned int @var{width})
+@deftypefunx uintmax_t ufromfpxf (float @var{x}, int @var{round}, unsigned int @var{width})
+@deftypefunx uintmax_t ufromfpxl (long double @var{x}, int @var{round}, unsigned int @var{width})
+@deftypefunx uintmax_t ufromfpxfN (_Float@var{N} @var{x}, int @var{round}, unsigned int @var{width})
+@deftypefunx uintmax_t ufromfpxfNx (_Float@var{N}x @var{x}, int @var{round}, unsigned int @var{width})
+@standards{ISO, math.h}
+@standardsx{fromfpfN, TS 18661-3:2015, math.h}
+@standardsx{fromfpfNx, TS 18661-3:2015, math.h}
+@standardsx{ufromfpfN, TS 18661-3:2015, math.h}
+@standardsx{ufromfpfNx, TS 18661-3:2015, math.h}
+@standardsx{fromfpxfN, TS 18661-3:2015, math.h}
+@standardsx{fromfpxfNx, TS 18661-3:2015, math.h}
+@standardsx{ufromfpxfN, TS 18661-3:2015, math.h}
+@standardsx{ufromfpxfNx, TS 18661-3:2015, math.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions, from TS 18661-1:2014 and TS 18661-3:2015, convert a
+floating-point number to an integer according to the rounding direction
+@var{round} (one of the @code{FP_INT_*} macros). If the integer is
+outside the range of a signed or unsigned (depending on the return type
+of the function) type of width @var{width} bits (or outside the range of
+the return type, if @var{width} is larger), or if @var{x} is infinite or
+NaN, or if @var{width} is zero, a domain error occurs and an unspecified
+value is returned. The functions with an @samp{x} in their names raise
+the inexact exception when a domain error does not occur and the
+argument is not an integer; the other functions do not raise the inexact
+exception.
+@end deftypefun
+
-@comment math.h
-@comment ISO
@deftypefun double modf (double @var{value}, double *@var{integer-part})
-@comment math.h
-@comment ISO
@deftypefunx float modff (float @var{value}, float *@var{integer-part})
-@comment math.h
-@comment ISO
@deftypefunx {long double} modfl (long double @var{value}, long double *@var{integer-part})
+@deftypefunx _FloatN modffN (_Float@var{N} @var{value}, _Float@var{N} *@var{integer-part})
+@deftypefunx _FloatNx modffNx (_Float@var{N}x @var{value}, _Float@var{N}x *@var{integer-part})
+@standards{ISO, math.h}
+@standardsx{modffN, TS 18661-3:2015, math.h}
+@standardsx{modffNx, TS 18661-3:2015, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
These functions break the argument @var{value} into an integer part and a
fractional part (between @code{-1} and @code{1}, exclusive). Their sum
floating-point numbers. Each is a little different; pick the one that
suits your problem.
-@comment math.h
-@comment ISO
@deftypefun double fmod (double @var{numerator}, double @var{denominator})
-@comment math.h
-@comment ISO
@deftypefunx float fmodf (float @var{numerator}, float @var{denominator})
-@comment math.h
-@comment ISO
@deftypefunx {long double} fmodl (long double @var{numerator}, long double @var{denominator})
+@deftypefunx _FloatN fmodfN (_Float@var{N} @var{numerator}, _Float@var{N} @var{denominator})
+@deftypefunx _FloatNx fmodfNx (_Float@var{N}x @var{numerator}, _Float@var{N}x @var{denominator})
+@standards{ISO, math.h}
+@standardsx{fmodfN, TS 18661-3:2015, math.h}
+@standardsx{fmodfNx, TS 18661-3:2015, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
These functions compute the remainder from the division of
@var{numerator} by @var{denominator}. Specifically, the return value is
If @var{denominator} is zero, @code{fmod} signals a domain error.
@end deftypefun
-@comment math.h
-@comment BSD
-@deftypefun double drem (double @var{numerator}, double @var{denominator})
-@comment math.h
-@comment BSD
-@deftypefunx float dremf (float @var{numerator}, float @var{denominator})
-@comment math.h
-@comment BSD
-@deftypefunx {long double} dreml (long double @var{numerator}, long double @var{denominator})
+@deftypefun double remainder (double @var{numerator}, double @var{denominator})
+@deftypefunx float remainderf (float @var{numerator}, float @var{denominator})
+@deftypefunx {long double} remainderl (long double @var{numerator}, long double @var{denominator})
+@deftypefunx _FloatN remainderfN (_Float@var{N} @var{numerator}, _Float@var{N} @var{denominator})
+@deftypefunx _FloatNx remainderfNx (_Float@var{N}x @var{numerator}, _Float@var{N}x @var{denominator})
+@standards{ISO, math.h}
+@standardsx{remainderfN, TS 18661-3:2015, math.h}
+@standardsx{remainderfNx, TS 18661-3:2015, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
These functions are like @code{fmod} except that they round the
internal quotient @var{n} to the nearest integer instead of towards zero
-to an integer. For example, @code{drem (6.5, 2.3)} returns @code{-0.4},
-which is @code{6.5} minus @code{6.9}.
+to an integer. For example, @code{remainder (6.5, 2.3)} returns
+@code{-0.4}, which is @code{6.5} minus @code{6.9}.
The absolute value of the result is less than or equal to half the
absolute value of the @var{denominator}. The difference between
-@code{fmod (@var{numerator}, @var{denominator})} and @code{drem
+@code{fmod (@var{numerator}, @var{denominator})} and @code{remainder
(@var{numerator}, @var{denominator})} is always either
@var{denominator}, minus @var{denominator}, or zero.
-If @var{denominator} is zero, @code{drem} signals a domain error.
+If @var{denominator} is zero, @code{remainder} signals a domain error.
@end deftypefun
-@comment math.h
-@comment BSD
-@deftypefun double remainder (double @var{numerator}, double @var{denominator})
-@comment math.h
-@comment BSD
-@deftypefunx float remainderf (float @var{numerator}, float @var{denominator})
-@comment math.h
-@comment BSD
-@deftypefunx {long double} remainderl (long double @var{numerator}, long double @var{denominator})
+@deftypefun double drem (double @var{numerator}, double @var{denominator})
+@deftypefunx float dremf (float @var{numerator}, float @var{denominator})
+@deftypefunx {long double} dreml (long double @var{numerator}, long double @var{denominator})
+@standards{BSD, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
-This function is another name for @code{drem}.
+This function is another name for @code{remainder}.
@end deftypefun
@node FP Bit Twiddling
functions to do these operations, which mostly involve changing single
bits.
-@comment math.h
-@comment ISO
@deftypefun double copysign (double @var{x}, double @var{y})
-@comment math.h
-@comment ISO
@deftypefunx float copysignf (float @var{x}, float @var{y})
-@comment math.h
-@comment ISO
@deftypefunx {long double} copysignl (long double @var{x}, long double @var{y})
+@deftypefunx _FloatN copysignfN (_Float@var{N} @var{x}, _Float@var{N} @var{y})
+@deftypefunx _FloatNx copysignfNx (_Float@var{N}x @var{x}, _Float@var{N}x @var{y})
+@standards{ISO, math.h}
+@standardsx{copysignfN, TS 18661-3:2015, math.h}
+@standardsx{copysignfNx, TS 18661-3:2015, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
These functions return @var{x} but with the sign of @var{y}. They work
even if @var{x} or @var{y} are NaN or zero. Both of these can carry a
recommended functions in @w{IEEE 754}/@w{IEEE 854}).
@end deftypefun
-@comment math.h
-@comment ISO
@deftypefun int signbit (@emph{float-type} @var{x})
+@standards{ISO, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@code{signbit} is a generic macro which can work on all floating-point
types. It returns a nonzero value if the value of @var{x} has its sign
false, but @code{signbit (-0.0)} will return a nonzero value.
@end deftypefun
-@comment math.h
-@comment ISO
@deftypefun double nextafter (double @var{x}, double @var{y})
-@comment math.h
-@comment ISO
@deftypefunx float nextafterf (float @var{x}, float @var{y})
-@comment math.h
-@comment ISO
@deftypefunx {long double} nextafterl (long double @var{x}, long double @var{y})
+@deftypefunx _FloatN nextafterfN (_Float@var{N} @var{x}, _Float@var{N} @var{y})
+@deftypefunx _FloatNx nextafterfNx (_Float@var{N}x @var{x}, _Float@var{N}x @var{y})
+@standards{ISO, math.h}
+@standardsx{nextafterfN, TS 18661-3:2015, math.h}
+@standardsx{nextafterfNx, TS 18661-3:2015, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{nextafter} function returns the next representable neighbor of
@var{x} in the direction towards @var{y}. The size of the step between
recommended functions in @w{IEEE 754}/@w{IEEE 854}).
@end deftypefun
-@comment math.h
-@comment ISO
@deftypefun double nexttoward (double @var{x}, long double @var{y})
-@comment math.h
-@comment ISO
@deftypefunx float nexttowardf (float @var{x}, long double @var{y})
-@comment math.h
-@comment ISO
@deftypefunx {long double} nexttowardl (long double @var{x}, long double @var{y})
+@standards{ISO, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
These functions are identical to the corresponding versions of
@code{nextafter} except that their second argument is a @code{long
double}.
@end deftypefun
-@comment math.h
-@comment ISO
@deftypefun double nextup (double @var{x})
-@comment math.h
-@comment ISO
@deftypefunx float nextupf (float @var{x})
-@comment math.h
-@comment ISO
@deftypefunx {long double} nextupl (long double @var{x})
+@deftypefunx _FloatN nextupfN (_Float@var{N} @var{x})
+@deftypefunx _FloatNx nextupfNx (_Float@var{N}x @var{x})
+@standards{ISO, math.h}
+@standardsx{nextupfN, TS 18661-3:2015, math.h}
+@standardsx{nextupfNx, TS 18661-3:2015, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{nextup} function returns the next representable neighbor of @var{x}
in the direction of positive infinity. If @var{x} is the smallest negative
@math{@var{x} = @code{0}} the function returns the smallest positive subnormal
number in the type of @var{x}. If @var{x} is NaN, NaN is returned.
If @var{x} is @math{+@infinity{}}, @math{+@infinity{}} is returned.
-@code{nextup} is from TS 18661-1:2014.
+@code{nextup} is from TS 18661-1:2014 and TS 18661-3:2015.
@code{nextup} never raises an exception except for signaling NaNs.
@end deftypefun
-@comment math.h
-@comment ISO
@deftypefun double nextdown (double @var{x})
-@comment math.h
-@comment ISO
@deftypefunx float nextdownf (float @var{x})
-@comment math.h
-@comment ISO
@deftypefunx {long double} nextdownl (long double @var{x})
+@deftypefunx _FloatN nextdownfN (_Float@var{N} @var{x})
+@deftypefunx _FloatNx nextdownfNx (_Float@var{N}x @var{x})
+@standards{ISO, math.h}
+@standardsx{nextdownfN, TS 18661-3:2015, math.h}
+@standardsx{nextdownfNx, TS 18661-3:2015, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{nextdown} function returns the next representable neighbor of @var{x}
in the direction of negative infinity. If @var{x} is the smallest positive
@math{@var{x} = @code{0}} the function returns the smallest negative subnormal
number in the type of @var{x}. If @var{x} is NaN, NaN is returned.
If @var{x} is @math{-@infinity{}}, @math{-@infinity{}} is returned.
-@code{nextdown} is from TS 18661-1:2014.
+@code{nextdown} is from TS 18661-1:2014 and TS 18661-3:2015.
@code{nextdown} never raises an exception except for signaling NaNs.
@end deftypefun
@cindex NaN
-@comment math.h
-@comment ISO
@deftypefun double nan (const char *@var{tagp})
-@comment math.h
-@comment ISO
@deftypefunx float nanf (const char *@var{tagp})
-@comment math.h
-@comment ISO
@deftypefunx {long double} nanl (const char *@var{tagp})
+@deftypefunx _FloatN nanfN (const char *@var{tagp})
+@deftypefunx _FloatNx nanfNx (const char *@var{tagp})
+@standards{ISO, math.h}
+@standardsx{nanfN, TS 18661-3:2015, math.h}
+@standardsx{nanfNx, TS 18661-3:2015, math.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
@c The unsafe-but-ruled-safe locale use comes from strtod.
The @code{nan} function returns a representation of NaN, provided that
selects one. On other systems it may do nothing.
@end deftypefun
+@deftypefun int canonicalize (double *@var{cx}, const double *@var{x})
+@deftypefunx int canonicalizef (float *@var{cx}, const float *@var{x})
+@deftypefunx int canonicalizel (long double *@var{cx}, const long double *@var{x})
+@deftypefunx int canonicalizefN (_Float@var{N} *@var{cx}, const _Float@var{N} *@var{x})
+@deftypefunx int canonicalizefNx (_Float@var{N}x *@var{cx}, const _Float@var{N}x *@var{x})
+@standards{ISO, math.h}
+@standardsx{canonicalizefN, TS 18661-3:2015, math.h}
+@standardsx{canonicalizefNx, TS 18661-3:2015, math.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+In some floating-point formats, some values have canonical (preferred)
+and noncanonical encodings (for IEEE interchange binary formats, all
+encodings are canonical). These functions, defined by TS
+18661-1:2014 and TS 18661-3:2015, attempt to produce a canonical version
+of the floating-point value pointed to by @var{x}; if that value is a
+signaling NaN, they raise the invalid exception and produce a quiet
+NaN. If a canonical value is produced, it is stored in the object
+pointed to by @var{cx}, and these functions return zero. Otherwise
+(if a canonical value could not be produced because the object pointed
+to by @var{x} is not a valid representation of any floating-point
+value), the object pointed to by @var{cx} is unchanged and a nonzero
+value is returned.
+
+Note that some formats have multiple encodings of a value which are
+all equally canonical; when such an encoding is used as an input to
+this function, any such encoding of the same value (or of the
+corresponding quiet NaN, if that value is a signaling NaN) may be
+produced as output.
+@end deftypefun
+
+@deftypefun double getpayload (const double *@var{x})
+@deftypefunx float getpayloadf (const float *@var{x})
+@deftypefunx {long double} getpayloadl (const long double *@var{x})
+@deftypefunx _FloatN getpayloadfN (const _Float@var{N} *@var{x})
+@deftypefunx _FloatNx getpayloadfNx (const _Float@var{N}x *@var{x})
+@standards{ISO, math.h}
+@standardsx{getpayloadfN, TS 18661-3:2015, math.h}
+@standardsx{getpayloadfNx, TS 18661-3:2015, math.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+IEEE 754 defines the @dfn{payload} of a NaN to be an integer value
+encoded in the representation of the NaN. Payloads are typically
+propagated from NaN inputs to the result of a floating-point
+operation. These functions, defined by TS 18661-1:2014 and TS
+18661-3:2015, return the payload of the NaN pointed to by @var{x}
+(returned as a positive integer, or positive zero, represented as a
+floating-point number); if @var{x} is not a NaN, they return an
+unspecified value. They raise no floating-point exceptions even for
+signaling NaNs.
+@end deftypefun
+
+@deftypefun int setpayload (double *@var{x}, double @var{payload})
+@deftypefunx int setpayloadf (float *@var{x}, float @var{payload})
+@deftypefunx int setpayloadl (long double *@var{x}, long double @var{payload})
+@deftypefunx int setpayloadfN (_Float@var{N} *@var{x}, _Float@var{N} @var{payload})
+@deftypefunx int setpayloadfNx (_Float@var{N}x *@var{x}, _Float@var{N}x @var{payload})
+@standards{ISO, math.h}
+@standardsx{setpayloadfN, TS 18661-3:2015, math.h}
+@standardsx{setpayloadfNx, TS 18661-3:2015, math.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions, defined by TS 18661-1:2014 and TS 18661-3:2015, set the
+object pointed to by @var{x} to a quiet NaN with payload @var{payload}
+and a zero sign bit and return zero. If @var{payload} is not a
+positive-signed integer that is a valid payload for a quiet NaN of the
+given type, the object pointed to by @var{x} is set to positive zero and
+a nonzero value is returned. They raise no floating-point exceptions.
+@end deftypefun
+
+@deftypefun int setpayloadsig (double *@var{x}, double @var{payload})
+@deftypefunx int setpayloadsigf (float *@var{x}, float @var{payload})
+@deftypefunx int setpayloadsigl (long double *@var{x}, long double @var{payload})
+@deftypefunx int setpayloadsigfN (_Float@var{N} *@var{x}, _Float@var{N} @var{payload})
+@deftypefunx int setpayloadsigfNx (_Float@var{N}x *@var{x}, _Float@var{N}x @var{payload})
+@standards{ISO, math.h}
+@standardsx{setpayloadsigfN, TS 18661-3:2015, math.h}
+@standardsx{setpayloadsigfNx, TS 18661-3:2015, math.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions, defined by TS 18661-1:2014 and TS 18661-3:2015, set the
+object pointed to by @var{x} to a signaling NaN with payload
+@var{payload} and a zero sign bit and return zero. If @var{payload} is
+not a positive-signed integer that is a valid payload for a signaling
+NaN of the given type, the object pointed to by @var{x} is set to
+positive zero and a nonzero value is returned. They raise no
+floating-point exceptions.
+@end deftypefun
+
@node FP Comparison Functions
@subsection Floating-Point Comparison Functions
@cindex unordered comparison
do not raise exceptions when NaN is examined. All of the functions are
implemented as macros which allow their arguments to be of any
floating-point type. The macros are guaranteed to evaluate their
-arguments only once.
+arguments only once. TS 18661-1:2014 adds such a macro for an
+equality comparison that @emph{does} raise an exception for a NaN
+argument; it also adds functions that provide a total ordering on all
+floating-point values, including NaNs, without raising any exceptions
+even for signaling NaNs.
-@comment math.h
-@comment ISO
@deftypefn Macro int isgreater (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
+@standards{ISO, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This macro determines whether the argument @var{x} is greater than
@var{y}. It is equivalent to @code{(@var{x}) > (@var{y})}, but no
exception is raised if @var{x} or @var{y} are NaN.
@end deftypefn
-@comment math.h
-@comment ISO
@deftypefn Macro int isgreaterequal (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
+@standards{ISO, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This macro determines whether the argument @var{x} is greater than or
equal to @var{y}. It is equivalent to @code{(@var{x}) >= (@var{y})}, but no
exception is raised if @var{x} or @var{y} are NaN.
@end deftypefn
-@comment math.h
-@comment ISO
@deftypefn Macro int isless (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
+@standards{ISO, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This macro determines whether the argument @var{x} is less than @var{y}.
It is equivalent to @code{(@var{x}) < (@var{y})}, but no exception is
raised if @var{x} or @var{y} are NaN.
@end deftypefn
-@comment math.h
-@comment ISO
@deftypefn Macro int islessequal (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
+@standards{ISO, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This macro determines whether the argument @var{x} is less than or equal
to @var{y}. It is equivalent to @code{(@var{x}) <= (@var{y})}, but no
exception is raised if @var{x} or @var{y} are NaN.
@end deftypefn
-@comment math.h
-@comment ISO
@deftypefn Macro int islessgreater (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
+@standards{ISO, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This macro determines whether the argument @var{x} is less or greater
than @var{y}. It is equivalent to @code{(@var{x}) < (@var{y}) ||
expression is true if @var{x} or @var{y} are NaN.
@end deftypefn
-@comment math.h
-@comment ISO
@deftypefn Macro int isunordered (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
+@standards{ISO, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This macro determines whether its arguments are unordered. In other
words, it is true if @var{x} or @var{y} are NaN, and false otherwise.
@end deftypefn
+@deftypefn Macro int iseqsig (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
+@standards{ISO, math.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro determines whether its arguments are equal. It is
+equivalent to @code{(@var{x}) == (@var{y})}, but it raises the invalid
+exception and sets @code{errno} to @code{EDOM} if either argument is a
+NaN.
+@end deftypefn
+
+@deftypefun int totalorder (double @var{x}, double @var{y})
+@deftypefunx int totalorderf (float @var{x}, float @var{y})
+@deftypefunx int totalorderl (long double @var{x}, long double @var{y})
+@deftypefunx int totalorderfN (_Float@var{N} @var{x}, _Float@var{N} @var{y})
+@deftypefunx int totalorderfNx (_Float@var{N}x @var{x}, _Float@var{N}x @var{y})
+@standards{TS 18661-1:2014, math.h}
+@standardsx{totalorderfN, TS 18661-3:2015, math.h}
+@standardsx{totalorderfNx, TS 18661-3:2015, math.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions determine whether the total order relationship,
+defined in IEEE 754-2008, is true for @var{x} and @var{y}, returning
+nonzero if it is true and zero if it is false. No exceptions are
+raised even for signaling NaNs. The relationship is true if they are
+the same floating-point value (including sign for zero and NaNs, and
+payload for NaNs), or if @var{x} comes before @var{y} in the following
+order: negative quiet NaNs, in order of decreasing payload; negative
+signaling NaNs, in order of decreasing payload; negative infinity;
+finite numbers, in ascending order, with negative zero before positive
+zero; positive infinity; positive signaling NaNs, in order of
+increasing payload; positive quiet NaNs, in order of increasing
+payload.
+@end deftypefun
+
+@deftypefun int totalordermag (double @var{x}, double @var{y})
+@deftypefunx int totalordermagf (float @var{x}, float @var{y})
+@deftypefunx int totalordermagl (long double @var{x}, long double @var{y})
+@deftypefunx int totalordermagfN (_Float@var{N} @var{x}, _Float@var{N} @var{y})
+@deftypefunx int totalordermagfNx (_Float@var{N}x @var{x}, _Float@var{N}x @var{y})
+@standards{TS 18661-1:2014, math.h}
+@standardsx{totalordermagfN, TS 18661-3:2015, math.h}
+@standardsx{totalordermagfNx, TS 18661-3:2015, math.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions determine whether the total order relationship,
+defined in IEEE 754-2008, is true for the absolute values of @var{x}
+and @var{y}, returning nonzero if it is true and zero if it is false.
+No exceptions are raised even for signaling NaNs.
+@end deftypefun
+
Not all machines provide hardware support for these operations. On
machines that don't, the macros can be very slow. Therefore, you should
not use these functions when NaN is not a concern.
processors these functions can use special machine instructions to
perform these operations faster than the equivalent C code.
-@comment math.h
-@comment ISO
@deftypefun double fmin (double @var{x}, double @var{y})
-@comment math.h
-@comment ISO
@deftypefunx float fminf (float @var{x}, float @var{y})
-@comment math.h
-@comment ISO
@deftypefunx {long double} fminl (long double @var{x}, long double @var{y})
+@deftypefunx _FloatN fminfN (_Float@var{N} @var{x}, _Float@var{N} @var{y})
+@deftypefunx _FloatNx fminfNx (_Float@var{N}x @var{x}, _Float@var{N}x @var{y})
+@standards{ISO, math.h}
+@standardsx{fminfN, TS 18661-3:2015, math.h}
+@standardsx{fminfNx, TS 18661-3:2015, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{fmin} function returns the lesser of the two values @var{x}
and @var{y}. It is similar to the expression
are NaN, NaN is returned.
@end deftypefun
-@comment math.h
-@comment ISO
@deftypefun double fmax (double @var{x}, double @var{y})
-@comment math.h
-@comment ISO
@deftypefunx float fmaxf (float @var{x}, float @var{y})
-@comment math.h
-@comment ISO
@deftypefunx {long double} fmaxl (long double @var{x}, long double @var{y})
+@deftypefunx _FloatN fmaxfN (_Float@var{N} @var{x}, _Float@var{N} @var{y})
+@deftypefunx _FloatNx fmaxfNx (_Float@var{N}x @var{x}, _Float@var{N}x @var{y})
+@standards{ISO, math.h}
+@standardsx{fmaxfN, TS 18661-3:2015, math.h}
+@standardsx{fmaxfNx, TS 18661-3:2015, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{fmax} function returns the greater of the two values @var{x}
and @var{y}.
are NaN, NaN is returned.
@end deftypefun
-@comment math.h
-@comment ISO
+@deftypefun double fminmag (double @var{x}, double @var{y})
+@deftypefunx float fminmagf (float @var{x}, float @var{y})
+@deftypefunx {long double} fminmagl (long double @var{x}, long double @var{y})
+@deftypefunx _FloatN fminmagfN (_Float@var{N} @var{x}, _Float@var{N} @var{y})
+@deftypefunx _FloatNx fminmagfNx (_Float@var{N}x @var{x}, _Float@var{N}x @var{y})
+@standards{ISO, math.h}
+@standardsx{fminmagfN, TS 18661-3:2015, math.h}
+@standardsx{fminmagfNx, TS 18661-3:2015, math.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions, from TS 18661-1:2014 and TS 18661-3:2015, return
+whichever of the two values @var{x} and @var{y} has the smaller absolute
+value. If both have the same absolute value, or either is NaN, they
+behave the same as the @code{fmin} functions.
+@end deftypefun
+
+@deftypefun double fmaxmag (double @var{x}, double @var{y})
+@deftypefunx float fmaxmagf (float @var{x}, float @var{y})
+@deftypefunx {long double} fmaxmagl (long double @var{x}, long double @var{y})
+@deftypefunx _FloatN fmaxmagfN (_Float@var{N} @var{x}, _Float@var{N} @var{y})
+@deftypefunx _FloatNx fmaxmagfNx (_Float@var{N}x @var{x}, _Float@var{N}x @var{y})
+@standards{ISO, math.h}
+@standardsx{fmaxmagfN, TS 18661-3:2015, math.h}
+@standardsx{fmaxmagfNx, TS 18661-3:2015, math.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions, from TS 18661-1:2014, return whichever of the two
+values @var{x} and @var{y} has the greater absolute value. If both
+have the same absolute value, or either is NaN, they behave the same
+as the @code{fmax} functions.
+@end deftypefun
+
@deftypefun double fdim (double @var{x}, double @var{y})
-@comment math.h
-@comment ISO
@deftypefunx float fdimf (float @var{x}, float @var{y})
-@comment math.h
-@comment ISO
@deftypefunx {long double} fdiml (long double @var{x}, long double @var{y})
+@deftypefunx _FloatN fdimfN (_Float@var{N} @var{x}, _Float@var{N} @var{y})
+@deftypefunx _FloatNx fdimfNx (_Float@var{N}x @var{x}, _Float@var{N}x @var{y})
+@standards{ISO, math.h}
+@standardsx{fdimfN, TS 18661-3:2015, math.h}
+@standardsx{fdimfNx, TS 18661-3:2015, math.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{fdim} function returns the positive difference between
@var{x} and @var{y}. The positive difference is @math{@var{x} -
If @var{x}, @var{y}, or both are NaN, NaN is returned.
@end deftypefun
-@comment math.h
-@comment ISO
@deftypefun double fma (double @var{x}, double @var{y}, double @var{z})
-@comment math.h
-@comment ISO
@deftypefunx float fmaf (float @var{x}, float @var{y}, float @var{z})
-@comment math.h
-@comment ISO
@deftypefunx {long double} fmal (long double @var{x}, long double @var{y}, long double @var{z})
+@deftypefunx _FloatN fmafN (_Float@var{N} @var{x}, _Float@var{N} @var{y}, _Float@var{N} @var{z})
+@deftypefunx _FloatNx fmafNx (_Float@var{N}x @var{x}, _Float@var{N}x @var{y}, _Float@var{N}x @var{z})
+@standards{ISO, math.h}
+@standardsx{fmafN, TS 18661-3:2015, math.h}
+@standardsx{fmafNx, TS 18661-3:2015, math.h}
@cindex butterfly
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{fma} function performs floating-point multiply-add. This is
hardware.
@end deftypefun
+@deftypefun float fadd (double @var{x}, double @var{y})
+@deftypefunx float faddl (long double @var{x}, long double @var{y})
+@deftypefunx double daddl (long double @var{x}, long double @var{y})
+@deftypefunx _FloatM fMaddfN (_Float@var{N} @var{x}, _Float@var{N} @var{y})
+@deftypefunx _FloatM fMaddfNx (_Float@var{N}x @var{x}, _Float@var{N}x @var{y})
+@deftypefunx _FloatMx fMxaddfN (_Float@var{N} @var{x}, _Float@var{N} @var{y})
+@deftypefunx _FloatMx fMxaddfNx (_Float@var{N}x @var{x}, _Float@var{N}x @var{y})
+@standards{TS 18661-1:2014, math.h}
+@standardsx{fMaddfN, TS 18661-3:2015, math.h}
+@standardsx{fMaddfNx, TS 18661-3:2015, math.h}
+@standardsx{fMxaddfN, TS 18661-3:2015, math.h}
+@standardsx{fMxaddfNx, TS 18661-3:2015, math.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions, from TS 18661-1:2014 and TS 18661-3:2015, return
+@math{@var{x} + @var{y}}, rounded once to the return type of the
+function without any intermediate rounding to the type of the
+arguments.
+@end deftypefun
+
+@deftypefun float fsub (double @var{x}, double @var{y})
+@deftypefunx float fsubl (long double @var{x}, long double @var{y})
+@deftypefunx double dsubl (long double @var{x}, long double @var{y})
+@deftypefunx _FloatM fMsubfN (_Float@var{N} @var{x}, _Float@var{N} @var{y})
+@deftypefunx _FloatM fMsubfNx (_Float@var{N}x @var{x}, _Float@var{N}x @var{y})
+@deftypefunx _FloatMx fMxsubfN (_Float@var{N} @var{x}, _Float@var{N} @var{y})
+@deftypefunx _FloatMx fMxsubfNx (_Float@var{N}x @var{x}, _Float@var{N}x @var{y})
+@standards{TS 18661-1:2014, math.h}
+@standardsx{fMsubfN, TS 18661-3:2015, math.h}
+@standardsx{fMsubfNx, TS 18661-3:2015, math.h}
+@standardsx{fMxsubfN, TS 18661-3:2015, math.h}
+@standardsx{fMxsubfNx, TS 18661-3:2015, math.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions, from TS 18661-1:2014 and TS 18661-3:2015, return
+@math{@var{x} - @var{y}}, rounded once to the return type of the
+function without any intermediate rounding to the type of the
+arguments.
+@end deftypefun
+
+@deftypefun float fmul (double @var{x}, double @var{y})
+@deftypefunx float fmull (long double @var{x}, long double @var{y})
+@deftypefunx double dmull (long double @var{x}, long double @var{y})
+@deftypefunx _FloatM fMmulfN (_Float@var{N} @var{x}, _Float@var{N} @var{y})
+@deftypefunx _FloatM fMmulfNx (_Float@var{N}x @var{x}, _Float@var{N}x @var{y})
+@deftypefunx _FloatMx fMxmulfN (_Float@var{N} @var{x}, _Float@var{N} @var{y})
+@deftypefunx _FloatMx fMxmulfNx (_Float@var{N}x @var{x}, _Float@var{N}x @var{y})
+@standards{TS 18661-1:2014, math.h}
+@standardsx{fMmulfN, TS 18661-3:2015, math.h}
+@standardsx{fMmulfNx, TS 18661-3:2015, math.h}
+@standardsx{fMxmulfN, TS 18661-3:2015, math.h}
+@standardsx{fMxmulfNx, TS 18661-3:2015, math.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions, from TS 18661-1:2014 and TS 18661-3:2015, return
+@math{@var{x} * @var{y}}, rounded once to the return type of the
+function without any intermediate rounding to the type of the
+arguments.
+@end deftypefun
+
+@deftypefun float fdiv (double @var{x}, double @var{y})
+@deftypefunx float fdivl (long double @var{x}, long double @var{y})
+@deftypefunx double ddivl (long double @var{x}, long double @var{y})
+@deftypefunx _FloatM fMdivfN (_Float@var{N} @var{x}, _Float@var{N} @var{y})
+@deftypefunx _FloatM fMdivfNx (_Float@var{N}x @var{x}, _Float@var{N}x @var{y})
+@deftypefunx _FloatMx fMxdivfN (_Float@var{N} @var{x}, _Float@var{N} @var{y})
+@deftypefunx _FloatMx fMxdivfNx (_Float@var{N}x @var{x}, _Float@var{N}x @var{y})
+@standards{TS 18661-1:2014, math.h}
+@standardsx{fMdivfN, TS 18661-3:2015, math.h}
+@standardsx{fMdivfNx, TS 18661-3:2015, math.h}
+@standardsx{fMxdivfN, TS 18661-3:2015, math.h}
+@standardsx{fMxdivfNx, TS 18661-3:2015, math.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions, from TS 18661-1:2014 and TS 18661-3:2015, return
+@math{@var{x} / @var{y}}, rounded once to the return type of the
+function without any intermediate rounding to the type of the
+arguments.
+@end deftypefun
+
@node Complex Numbers
@section Complex Numbers
@pindex complex.h
corresponding to the three real types: @code{float complex},
@code{double complex}, and @code{long double complex}.
+Likewise, on machines that have support for @code{_Float@var{N}} or
+@code{_Float@var{N}x} enabled, the complex types @code{_Float@var{N}
+complex} and @code{_Float@var{N}x complex} are also available if
+@file{complex.h} has been included; @pxref{Mathematics}.
+
To construct complex numbers you need a way to indicate the imaginary
part of a number. There is no standard notation for an imaginary
floating point constant. Instead, @file{complex.h} defines two macros
that can be used to create complex numbers.
@deftypevr Macro {const float complex} _Complex_I
+@standards{C99, complex.h}
This macro is a representation of the complex number ``@math{0+1i}''.
Multiplying a real floating-point value by @code{_Complex_I} gives a
complex number whose value is purely imaginary. You can use this to
a shorter name for the same constant.
@deftypevr Macro {const float complex} I
+@standards{C99, complex.h}
This macro has exactly the same value as @code{_Complex_I}. Most of the
time it is preferable. However, it causes problems if you want to use
the identifier @code{I} for something else. You can safely write
for all these functions are in @file{complex.h}. All functions are
available in three variants, one for each of the three complex types.
-@comment complex.h
-@comment ISO
@deftypefun double creal (complex double @var{z})
-@comment complex.h
-@comment ISO
@deftypefunx float crealf (complex float @var{z})
-@comment complex.h
-@comment ISO
@deftypefunx {long double} creall (complex long double @var{z})
+@deftypefunx _FloatN crealfN (complex _Float@var{N} @var{z})
+@deftypefunx _FloatNx crealfNx (complex _Float@var{N}x @var{z})
+@standards{ISO, complex.h}
+@standardsx{crealfN, TS 18661-3:2015, complex.h}
+@standardsx{crealfNx, TS 18661-3:2015, complex.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
These functions return the real part of the complex number @var{z}.
@end deftypefun
-@comment complex.h
-@comment ISO
@deftypefun double cimag (complex double @var{z})
-@comment complex.h
-@comment ISO
@deftypefunx float cimagf (complex float @var{z})
-@comment complex.h
-@comment ISO
@deftypefunx {long double} cimagl (complex long double @var{z})
+@deftypefunx _FloatN cimagfN (complex _Float@var{N} @var{z})
+@deftypefunx _FloatNx cimagfNx (complex _Float@var{N}x @var{z})
+@standards{ISO, complex.h}
+@standardsx{cimagfN, TS 18661-3:2015, complex.h}
+@standardsx{cimagfNx, TS 18661-3:2015, complex.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
These functions return the imaginary part of the complex number @var{z}.
@end deftypefun
-@comment complex.h
-@comment ISO
@deftypefun {complex double} conj (complex double @var{z})
-@comment complex.h
-@comment ISO
@deftypefunx {complex float} conjf (complex float @var{z})
-@comment complex.h
-@comment ISO
@deftypefunx {complex long double} conjl (complex long double @var{z})
+@deftypefunx {complex _FloatN} conjfN (complex _Float@var{N} @var{z})
+@deftypefunx {complex _FloatNx} conjfNx (complex _Float@var{N}x @var{z})
+@standards{ISO, complex.h}
+@standardsx{conjfN, TS 18661-3:2015, complex.h}
+@standardsx{conjfNx, TS 18661-3:2015, complex.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
These functions return the conjugate value of the complex number
@var{z}. The conjugate of a complex number has the same real part and a
negated imaginary part. In other words, @samp{conj(a + bi) = a + -bi}.
@end deftypefun
-@comment complex.h
-@comment ISO
@deftypefun double carg (complex double @var{z})
-@comment complex.h
-@comment ISO
@deftypefunx float cargf (complex float @var{z})
-@comment complex.h
-@comment ISO
@deftypefunx {long double} cargl (complex long double @var{z})
+@deftypefunx _FloatN cargfN (complex _Float@var{N} @var{z})
+@deftypefunx _FloatNx cargfNx (complex _Float@var{N}x @var{z})
+@standards{ISO, complex.h}
+@standardsx{cargfN, TS 18661-3:2015, complex.h}
+@standardsx{cargfNx, TS 18661-3:2015, complex.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
These functions return the argument of the complex number @var{z}.
The argument of a complex number is the angle in the complex plane
@code{carg} has a branch cut along the negative real axis.
@end deftypefun
-@comment complex.h
-@comment ISO
@deftypefun {complex double} cproj (complex double @var{z})
-@comment complex.h
-@comment ISO
@deftypefunx {complex float} cprojf (complex float @var{z})
-@comment complex.h
-@comment ISO
@deftypefunx {complex long double} cprojl (complex long double @var{z})
+@deftypefunx {complex _FloatN} cprojfN (complex _Float@var{N} @var{z})
+@deftypefunx {complex _FloatNx} cprojfNx (complex _Float@var{N}x @var{z})
+@standards{ISO, complex.h}
+@standardsx{cprojfN, TS 18661-3:2015, complex.h}
+@standardsx{cprojfNx, TS 18661-3:2015, complex.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
These functions return the projection of the complex value @var{z} onto
the Riemann sphere. Values with an infinite imaginary part are projected
standard uses it (for the functions defined there) so we have to do it
as well.
-@comment stdlib.h
-@comment ISO
@deftypefun {long int} strtol (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
+@standards{ISO, stdlib.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
@c strtol uses the thread-local pointer to the locale in effect, and
@c strtol_l loads the LC_NUMERIC locale data from it early on and once,
There is an example at the end of this section.
@end deftypefun
-@comment wchar.h
-@comment ISO
@deftypefun {long int} wcstol (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
+@standards{ISO, wchar.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
The @code{wcstol} function is equivalent to the @code{strtol} function
in nearly all aspects but handles wide character strings.
The @code{wcstol} function was introduced in @w{Amendment 1} of @w{ISO C90}.
@end deftypefun
-@comment stdlib.h
-@comment ISO
-@deftypefun {unsigned long int} strtoul (const char *retrict @var{string}, char **restrict @var{tailptr}, int @var{base})
+@deftypefun {unsigned long int} strtoul (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
+@standards{ISO, stdlib.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
The @code{strtoul} (``string-to-unsigned-long'') function is like
@code{strtol} except it converts to an @code{unsigned long int} value.
range, or @code{ERANGE} on overflow.
@end deftypefun
-@comment wchar.h
-@comment ISO
@deftypefun {unsigned long int} wcstoul (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
+@standards{ISO, wchar.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
The @code{wcstoul} function is equivalent to the @code{strtoul} function
in nearly all aspects but handles wide character strings.
The @code{wcstoul} function was introduced in @w{Amendment 1} of @w{ISO C90}.
@end deftypefun
-@comment stdlib.h
-@comment ISO
@deftypefun {long long int} strtoll (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
+@standards{ISO, stdlib.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
The @code{strtoll} function is like @code{strtol} except that it returns
a @code{long long int} value, and accepts numbers with a correspondingly
The @code{strtoll} function was introduced in @w{ISO C99}.
@end deftypefun
-@comment wchar.h
-@comment ISO
@deftypefun {long long int} wcstoll (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
+@standards{ISO, wchar.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
The @code{wcstoll} function is equivalent to the @code{strtoll} function
in nearly all aspects but handles wide character strings.
The @code{wcstoll} function was introduced in @w{Amendment 1} of @w{ISO C90}.
@end deftypefun
-@comment stdlib.h
-@comment BSD
@deftypefun {long long int} strtoq (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
+@standards{BSD, stdlib.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
@code{strtoq} (``string-to-quad-word'') is the BSD name for @code{strtoll}.
@end deftypefun
-@comment wchar.h
-@comment GNU
@deftypefun {long long int} wcstoq (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
+@standards{GNU, wchar.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
The @code{wcstoq} function is equivalent to the @code{strtoq} function
in nearly all aspects but handles wide character strings.
The @code{wcstoq} function is a GNU extension.
@end deftypefun
-@comment stdlib.h
-@comment ISO
@deftypefun {unsigned long long int} strtoull (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
+@standards{ISO, stdlib.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
The @code{strtoull} function is related to @code{strtoll} the same way
@code{strtoul} is related to @code{strtol}.
The @code{strtoull} function was introduced in @w{ISO C99}.
@end deftypefun
-@comment wchar.h
-@comment ISO
@deftypefun {unsigned long long int} wcstoull (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
+@standards{ISO, wchar.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
The @code{wcstoull} function is equivalent to the @code{strtoull} function
in nearly all aspects but handles wide character strings.
The @code{wcstoull} function was introduced in @w{Amendment 1} of @w{ISO C90}.
@end deftypefun
-@comment stdlib.h
-@comment BSD
@deftypefun {unsigned long long int} strtouq (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
+@standards{BSD, stdlib.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
@code{strtouq} is the BSD name for @code{strtoull}.
@end deftypefun
-@comment wchar.h
-@comment GNU
@deftypefun {unsigned long long int} wcstouq (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
+@standards{GNU, wchar.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
The @code{wcstouq} function is equivalent to the @code{strtouq} function
in nearly all aspects but handles wide character strings.
The @code{wcstouq} function is a GNU extension.
@end deftypefun
-@comment inttypes.h
-@comment ISO
@deftypefun intmax_t strtoimax (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
+@standards{ISO, inttypes.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
The @code{strtoimax} function is like @code{strtol} except that it returns
a @code{intmax_t} value, and accepts numbers of a corresponding range.
@code{strtoimax} function was introduced in @w{ISO C99}.
@end deftypefun
-@comment wchar.h
-@comment ISO
@deftypefun intmax_t wcstoimax (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
+@standards{ISO, wchar.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
The @code{wcstoimax} function is equivalent to the @code{strtoimax} function
in nearly all aspects but handles wide character strings.
The @code{wcstoimax} function was introduced in @w{ISO C99}.
@end deftypefun
-@comment inttypes.h
-@comment ISO
@deftypefun uintmax_t strtoumax (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
+@standards{ISO, inttypes.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
The @code{strtoumax} function is related to @code{strtoimax}
the same way that @code{strtoul} is related to @code{strtol}.
@code{strtoumax} function was introduced in @w{ISO C99}.
@end deftypefun
-@comment wchar.h
-@comment ISO
@deftypefun uintmax_t wcstoumax (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
+@standards{ISO, wchar.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
The @code{wcstoumax} function is equivalent to the @code{strtoumax} function
in nearly all aspects but handles wide character strings.
The @code{wcstoumax} function was introduced in @w{ISO C99}.
@end deftypefun
-@comment stdlib.h
-@comment ISO
@deftypefun {long int} atol (const char *@var{string})
+@standards{ISO, stdlib.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
This function is similar to the @code{strtol} function with a @var{base}
argument of @code{10}, except that it need not detect overflow errors.
existing code; using @code{strtol} is more robust.
@end deftypefun
-@comment stdlib.h
-@comment ISO
@deftypefun int atoi (const char *@var{string})
+@standards{ISO, stdlib.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
This function is like @code{atol}, except that it returns an @code{int}.
The @code{atoi} function is also considered obsolete; use @code{strtol}
instead.
@end deftypefun
-@comment stdlib.h
-@comment ISO
@deftypefun {long long int} atoll (const char *@var{string})
+@standards{ISO, stdlib.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
This function is similar to @code{atol}, except it returns a @code{long
long int}.
standard uses it (for the functions defined there) so we have to do it
as well.
-@comment stdlib.h
-@comment ISO
@deftypefun double strtod (const char *restrict @var{string}, char **restrict @var{tailptr})
+@standards{ISO, stdlib.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
@c Besides the unsafe-but-ruled-safe locale uses, this uses a lot of
@c mpn, but it's all safe.
@c mpn_lshift_1 -> mpn_lshift ok
@c STRTOF_INTERNAL
@c MPN_VAR ok
-@c SET_MANTISSA ok
+@c SET_NAN_PAYLOAD ok
@c STRNCASECMP ok, wide and narrow
@c round_and_return ok
@c mpn_mul ok
examining @var{errno} and @var{tailptr}.
@end deftypefun
-@comment stdlib.h
-@comment ISO
@deftypefun float strtof (const char *@var{string}, char **@var{tailptr})
-@comment stdlib.h
-@comment ISO
@deftypefunx {long double} strtold (const char *@var{string}, char **@var{tailptr})
+@standards{ISO, stdlib.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+@comment See safety comments for strtod.
These functions are analogous to @code{strtod}, but return @code{float}
and @code{long double} values respectively. They report errors in the
same way as @code{strtod}. @code{strtof} can be substantially faster
These functions have been GNU extensions and are new to @w{ISO C99}.
@end deftypefun
-@comment wchar.h
-@comment ISO
+@deftypefun _FloatN strtofN (const char *@var{string}, char **@var{tailptr})
+@deftypefunx _FloatNx strtofNx (const char *@var{string}, char **@var{tailptr})
+@standards{ISO/IEC TS 18661-3, stdlib.h}
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+@comment See safety comments for strtod.
+These functions are like @code{strtod}, except for the return type.
+
+They were introduced in @w{ISO/IEC TS 18661-3} and are available on machines
+that support the related types; @pxref{Mathematics}.
+@end deftypefun
+
@deftypefun double wcstod (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr})
-@comment stdlib.h
-@comment ISO
@deftypefunx float wcstof (const wchar_t *@var{string}, wchar_t **@var{tailptr})
-@comment stdlib.h
-@comment ISO
@deftypefunx {long double} wcstold (const wchar_t *@var{string}, wchar_t **@var{tailptr})
+@deftypefunx _FloatN wcstofN (const wchar_t *@var{string}, wchar_t **@var{tailptr})
+@deftypefunx _FloatNx wcstofNx (const wchar_t *@var{string}, wchar_t **@var{tailptr})
+@standards{ISO, wchar.h}
+@standardsx{wcstofN, GNU, wchar.h}
+@standardsx{wcstofNx, GNU, wchar.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
-The @code{wcstod}, @code{wcstof}, and @code{wcstol} functions are
-equivalent in nearly all aspect to the @code{strtod}, @code{strtof}, and
-@code{strtold} functions but it handles wide character string.
+@comment See safety comments for strtod.
+The @code{wcstod}, @code{wcstof}, @code{wcstol}, @code{wcstof@var{N}},
+and @code{wcstof@var{N}x} functions are equivalent in nearly all aspects
+to the @code{strtod}, @code{strtof}, @code{strtold},
+@code{strtof@var{N}}, and @code{strtof@var{N}x} functions, but they
+handle wide character strings.
The @code{wcstod} function was introduced in @w{Amendment 1} of @w{ISO
C90}. The @code{wcstof} and @code{wcstold} functions were introduced in
@w{ISO C99}.
+
+The @code{wcstof@var{N}} and @code{wcstof@var{N}x} functions are not in
+any standard, but are added to provide completeness for the
+non-deprecated interface of wide character string to floating-point
+conversion functions. They are only available on machines that support
+the related types; @pxref{Mathematics}.
@end deftypefun
-@comment stdlib.h
-@comment ISO
@deftypefun double atof (const char *@var{string})
+@standards{ISO, stdlib.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
This function is similar to the @code{strtod} function, except that it
need not detect overflow and underflow errors. The @code{atof} function
See also @ref{Parsing of Integers}.
+@node Printing of Floats
+@section Printing of Floats
+
+@pindex stdlib.h
+The @samp{strfrom} functions are declared in @file{stdlib.h}.
+
+@deftypefun int strfromd (char *restrict @var{string}, size_t @var{size}, const char *restrict @var{format}, double @var{value})
+@deftypefunx int strfromf (char *restrict @var{string}, size_t @var{size}, const char *restrict @var{format}, float @var{value})
+@deftypefunx int strfroml (char *restrict @var{string}, size_t @var{size}, const char *restrict @var{format}, long double @var{value})
+@standards{ISO/IEC TS 18661-1, stdlib.h}
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+@comment All these functions depend on both __printf_fp and __printf_fphex,
+@comment which are both AS-unsafe (ascuheap) and AC-unsafe (acsmem).
+The functions @code{strfromd} (``string-from-double''), @code{strfromf}
+(``string-from-float''), and @code{strfroml} (``string-from-long-double'')
+convert the floating-point number @var{value} to a string of characters and
+stores them into the area pointed to by @var{string}. The conversion
+writes at most @var{size} characters and respects the format specified by
+@var{format}.
+
+The format string must start with the character @samp{%}. An optional
+precision follows, which starts with a period, @samp{.}, and may be
+followed by a decimal integer, representing the precision. If a decimal
+integer is not specified after the period, the precision is taken to be
+zero. The character @samp{*} is not allowed. Finally, the format string
+ends with one of the following conversion specifiers: @samp{a}, @samp{A},
+@samp{e}, @samp{E}, @samp{f}, @samp{F}, @samp{g} or @samp{G} (@pxref{Table
+of Output Conversions}). Invalid format strings result in undefined
+behavior.
+
+These functions return the number of characters that would have been
+written to @var{string} had @var{size} been sufficiently large, not
+counting the terminating null character. Thus, the null-terminated output
+has been completely written if and only if the returned value is less than
+@var{size}.
+
+These functions were introduced by ISO/IEC TS 18661-1.
+@end deftypefun
+
+@deftypefun int strfromfN (char *restrict @var{string}, size_t @var{size}, const char *restrict @var{format}, _Float@var{N} @var{value})
+@deftypefunx int strfromfNx (char *restrict @var{string}, size_t @var{size}, const char *restrict @var{format}, _Float@var{N}x @var{value})
+@standards{ISO/IEC TS 18661-3, stdlib.h}
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+@comment See safety comments for strfromd.
+These functions are like @code{strfromd}, except for the type of
+@code{value}.
+
+They were introduced in @w{ISO/IEC TS 18661-3} and are available on machines
+that support the related types; @pxref{Mathematics}.
+@end deftypefun
+
@node System V Number Conversion
@section Old-fashioned System V number-to-string functions
All these functions are defined in @file{stdlib.h}.
-@comment stdlib.h
-@comment SVID, Unix98
@deftypefun {char *} ecvt (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg})
+@standards{SVID, stdlib.h}
+@standards{Unix98, stdlib.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:ecvt}}@asunsafe{}@acsafe{}}
The function @code{ecvt} converts the floating-point number @var{value}
to a string with at most @var{ndigit} decimal digits. The
and sets @var{d} to @code{2} and @var{n} to @code{0}.
@end deftypefun
-@comment stdlib.h
-@comment SVID, Unix98
@deftypefun {char *} fcvt (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg})
+@standards{SVID, stdlib.h}
+@standards{Unix98, stdlib.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:fcvt}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
The function @code{fcvt} is like @code{ecvt}, but @var{ndigit} specifies
the number of digits after the decimal point. If @var{ndigit} is less
to @code{fcvt}.
@end deftypefun
-@comment stdlib.h
-@comment SVID, Unix98
@deftypefun {char *} gcvt (double @var{value}, int @var{ndigit}, char *@var{buf})
+@standards{SVID, stdlib.h}
+@standards{Unix98, stdlib.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c gcvt calls sprintf, that ultimately calls vfprintf, which malloc()s
@c args_value if it's too large, but gcvt never exercises this path.
As extensions, @theglibc{} provides versions of these three
functions that take @code{long double} arguments.
-@comment stdlib.h
-@comment GNU
@deftypefun {char *} qecvt (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg})
+@standards{GNU, stdlib.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:qecvt}}@asunsafe{}@acsafe{}}
This function is equivalent to @code{ecvt} except that it takes a
@code{long double} for the first parameter and that @var{ndigit} is
restricted by the precision of a @code{long double}.
@end deftypefun
-@comment stdlib.h
-@comment GNU
@deftypefun {char *} qfcvt (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg})
+@standards{GNU, stdlib.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:qfcvt}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
This function is equivalent to @code{fcvt} except that it
takes a @code{long double} for the first parameter and that @var{ndigit} is
restricted by the precision of a @code{long double}.
@end deftypefun
-@comment stdlib.h
-@comment GNU
@deftypefun {char *} qgcvt (long double @var{value}, int @var{ndigit}, char *@var{buf})
+@standards{GNU, stdlib.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function is equivalent to @code{gcvt} except that it takes a
@code{long double} for the first parameter and that @var{ndigit} is
@code{gcvt_r} is not necessary, because @code{gcvt} already uses a
user-supplied buffer.
-@comment stdlib.h
-@comment GNU
@deftypefun int ecvt_r (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len})
+@standards{GNU, stdlib.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{ecvt_r} function is the same as @code{ecvt}, except
that it places its result into the user-specified buffer pointed to by
This function is a GNU extension.
@end deftypefun
-@comment stdlib.h
-@comment SVID, Unix98
@deftypefun int fcvt_r (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len})
+@standards{SVID, stdlib.h}
+@standards{Unix98, stdlib.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{fcvt_r} function is the same as @code{fcvt}, except that it
places its result into the user-specified buffer pointed to by
This function is a GNU extension.
@end deftypefun
-@comment stdlib.h
-@comment GNU
@deftypefun int qecvt_r (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len})
+@standards{GNU, stdlib.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{qecvt_r} function is the same as @code{qecvt}, except
that it places its result into the user-specified buffer pointed to by
This function is a GNU extension.
@end deftypefun
-@comment stdlib.h
-@comment GNU
@deftypefun int qfcvt_r (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len})
+@standards{GNU, stdlib.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{qfcvt_r} function is the same as @code{qfcvt}, except
that it places its result into the user-specified buffer pointed to by