Revert delta 190174

[pf3gnuchains/gcc-fork.git] / libquadmath / libquadmath.texi

diff --git a/libquadmath/libquadmath.texi b/libquadmath/libquadmath.texi
index ab8ed01..1ce245e 100644 (file)
--- a/libquadmath/libquadmath.texi
+++ b/libquadmath/libquadmath.texi
@@ -72,6 +72,7 @@ Math Library Application Programming Interface (API).
 @comment  better formatting.
 @comment
 @menu
 @comment  better formatting.
 @comment
 @menu

+* Typedef and constants::      Defined data types and constants

 * Math Library Routines::      The Libquadmath math runtime application
                                programming interface.
 * I/O Library Routines::       The Libquadmath I/O runtime application
 * Math Library Routines::      The Libquadmath math runtime application
                                programming interface.
 * I/O Library Routines::       The Libquadmath I/O runtime application


@@ -84,6 +85,55 @@ Math Library Application Programming Interface (API).
 
 
 @c ---------------------------------------------------------------------
 
 
 @c ---------------------------------------------------------------------

+@c Defined macros
+@c ---------------------------------------------------------------------
+
+@node Typedef and constants
+@chapter Typedef and constants
+
+The following data type has been defined via @code{typedef}.
+
+@table @asis
+@item @code{__complex128}: @code{__float128}-based complex number
+@end table
+
+The following macros are defined, which give the numeric limits of the
+@code{__float128} data type.
+
+@table @asis
+@item @code{FLT128_MAX}: largest finite number
+@item @code{FLT128_MIN}: smallest positive number with full precision
+@item @code{FLT128_EPSILON}: difference between 1 and the next larger
+                             representable number
+@item @code{FLT128_DENORM_MIN}: smallest positive denormalized number
+@item @code{FLT128_MANT_DIG}: number of digits in the mantissa (bit precision)
+@item @code{FLT128_MIN_EXP}: maximal negative exponent
+@item @code{FLT128_MAX_EXP}: maximal positive exponent
+@item @code{FLT128_DIG}: number of decimal digits in the mantissa
+@item @code{FLT128_MIN_10_EXP}: maximal negative decimal exponent
+@item @code{FLT128_MAX_10_EXP}: maximal positive decimal exponent
+@end table
+
+The following mathematical constants of type @code{__float128} are defined.
+
+@table @asis
+@item @code{M_Eq}: the constant e (Euler's number)
+@item @code{M_LOG2Eq}: binary logarithm of 2
+@item @code{M_LOG10Eq}: common, decimal logarithm of 2
+@item @code{M_LN2q}: natural logarithm of 2
+@item @code{M_LN10q}: natural logarithm of 10
+@item @code{M_PIq}: pi
+@item @code{M_PI_2q}: two pi
+@item @code{M_PI_4q}: four pi
+@item @code{M_1_PIq}: one over pi
+@item @code{M_2_PIq}: one over two pi
+@item @code{M_2_SQRTPIq}: two over square root of pi
+@item @code{M_SQRT2q}: square root of 2
+@item @code{M_SQRT1_2q}: one over square root of 2
+@end table
+
+
+@c ---------------------------------------------------------------------

 @c Math routines
 @c ---------------------------------------------------------------------
 
 @c Math routines
 @c ---------------------------------------------------------------------
 


@@ -111,11 +161,16 @@ The following mathematical functions are available:
 @item @code{expm1q}: exponential minus 1 function
 @need 800
 @item @code{fabsq}: absolute value function
 @item @code{expm1q}: exponential minus 1 function
 @need 800
 @item @code{fabsq}: absolute value function

+@item @code{fdimq}: positive difference function

 @item @code{finiteq}: check finiteness of value
 @item @code{floorq}: floor value function
 @item @code{finiteq}: check finiteness of value
 @item @code{floorq}: floor value function

+@item @code{fmaq}: fused multiply and add
+@item @code{fmaxq}: determine maximum of two values
+@item @code{fminq}: determine minimum of two values

 @item @code{fmodq}: remainder value function
 @item @code{frexpq}: extract mantissa and exponent
 @item @code{hypotq}: Eucledian distance function
 @item @code{fmodq}: remainder value function
 @item @code{frexpq}: extract mantissa and exponent
 @item @code{hypotq}: Eucledian distance function

+@item @code{ilogbq}: get exponent of the value

 @item @code{isinfq}: check for infinity
 @item @code{isnanq}: check for not a number
 @item @code{j0q}: Bessel function of the first kind, first order
 @item @code{isinfq}: check for infinity
 @item @code{isnanq}: check for not a number
 @item @code{j0q}: Bessel function of the first kind, first order


@@ -123,17 +178,22 @@ The following mathematical functions are available:
 @item @code{jnq}: Bessel function of the first kind, @var{n}-th order
 @item @code{ldexpq}: load exponent of the value
 @item @code{lgammaq}: logarithmic gamma function
 @item @code{jnq}: Bessel function of the first kind, @var{n}-th order
 @item @code{ldexpq}: load exponent of the value
 @item @code{lgammaq}: logarithmic gamma function

+@item @code{llrintq}: round to nearest integer value

 @item @code{llroundq}: round to nearest integer value away from zero
 @item @code{logq}: natural logarithm function
 @item @code{log10q}: base 10 logarithm function
 @item @code{log1pq}: compute natural logarithm of the value plus one
 @item @code{llroundq}: round to nearest integer value away from zero
 @item @code{logq}: natural logarithm function
 @item @code{log10q}: base 10 logarithm function
 @item @code{log1pq}: compute natural logarithm of the value plus one

+@item @code{log2q}: base 2 logarithm function

 @need 800
 @need 800

+@item @code{lrintq}: round to nearest integer value

 @item @code{lroundq}: round to nearest integer value away from zero
 @item @code{modfq}: decompose the floating-point number
 @item @code{nanq}: return quiet NaN
 @item @code{lroundq}: round to nearest integer value away from zero
 @item @code{modfq}: decompose the floating-point number
 @item @code{nanq}: return quiet NaN

+@item @code{nearbyintq}: round to nearest integer

 @item @code{nextafterq}: next representable floating-point number
 @item @code{powq}: power function
 @item @code{remainderq}: remainder function
 @item @code{nextafterq}: next representable floating-point number
 @item @code{powq}: power function
 @item @code{remainderq}: remainder function

+@item @code{remquoq}: remainder and part of quotient

 @item @code{rintq}: round-to-nearest integral value
 @item @code{roundq}: round-to-nearest integral value, return @code{__float128}
 @item @code{scalblnq}: compute exponent using @code{FLT_RADIX}
 @item @code{rintq}: round-to-nearest integral value
 @item @code{roundq}: round-to-nearest integral value, return @code{__float128}
 @item @code{scalblnq}: compute exponent using @code{FLT_RADIX}


@@ -151,19 +211,29 @@ The following mathematical functions are available:
 @item @code{y0q}: Bessel function of the second kind, first order
 @item @code{y1q}: Bessel function of the second kind, second order
 @item @code{ynq}: Bessel function of the second kind, @var{n}-th order
 @item @code{y0q}: Bessel function of the second kind, first order
 @item @code{y1q}: Bessel function of the second kind, second order
 @item @code{ynq}: Bessel function of the second kind, @var{n}-th order

-@item @code{cabsq} complex absolute value function:
+@item @code{cabsq} complex absolute value function

 @item @code{cargq}: calculate the argument
 @item @code{cargq}: calculate the argument

+@item @code{cimagq} imaginary part of complex number
+@item @code{crealq}: real part of complex number
+@item @code{cacoshq}: complex arc hyperbolic cosine function
+@item @code{cacosq}: complex arc cosine function
+@item @code{casinhq}: complex arc hyperbolic sine function
+@item @code{casinq}: complex arc sine function
+@item @code{catanhq}: complex arc hyperbolic tangent function
+@item @code{catanq}: complex arc tangent function

 @item @code{ccosq} complex cosine function:
 @item @code{ccoshq}: complex hyperbolic cosine function
 @item @code{cexpq}: complex exponential function
 @item @code{ccosq} complex cosine function:
 @item @code{ccoshq}: complex hyperbolic cosine function
 @item @code{cexpq}: complex exponential function

+@need 800

 @item @code{cexpiq}: computes the exponential function of ``i'' times a
                      real value
 @item @code{clogq}: complex natural logarithm
 @item @code{clog10q}: complex base 10 logarithm
 @item @code{cexpiq}: computes the exponential function of ``i'' times a
                      real value
 @item @code{clogq}: complex natural logarithm
 @item @code{clog10q}: complex base 10 logarithm

+@item @code{conjq}: complex conjugate function

 @item @code{cpowq}: complex power function
 @item @code{cpowq}: complex power function

+@item @code{cprojq}: project into Riemann Sphere

 @item @code{csinq}: complex sine function
 @item @code{csinhq}: complex hyperbolic sine function
 @item @code{csinq}: complex sine function
 @item @code{csinhq}: complex hyperbolic sine function

-@need 800

 @item @code{csqrtq}: complex square root
 @item @code{ctanq}: complex tangent function
 @item @code{ctanhq}: complex hyperbolic tangent function
 @item @code{csqrtq}: complex square root
 @item @code{ctanq}: complex tangent function
 @item @code{ctanhq}: complex hyperbolic tangent function


@@ -178,30 +248,25 @@ The following mathematical functions are available:
 @chapter I/O Library Routines
 
 @menu
 @chapter I/O Library Routines
 
 @menu

-* @code{quadmath_strtopQ}:  quadmath_strtopQ,  Convert from string
-* @code{quadmath_dtoaq}:    quadmath_dtoaq,    Convert to string
+* @code{strtoflt128}:          strtoflt128,          Convert from string
+* @code{quadmath_snprintf}:    quadmath_snprintf,    Convert to string

 @end menu
 
 
 @end menu
 
 

-@node quadmath_strtopQ
-@section @code{quadmath_strtopQ} --- Convert from string
+@node strtoflt128
+@section @code{strtoflt128} --- Convert from string

 
 

-The function @code{dmath_strtopQ} converts a string into a
+The function @code{strtoflt128} converts a string into a

 @code{__float128} number.
 
 @table @asis
 @item Syntax
 @code{__float128} number.
 
 @table @asis
 @item Syntax

-@code{int quadmath_strtopQ (const char *s, char **sp, void *V)}
-
-@c The return values are defined in gdtoa/gdtoa.h STRTOG_*
-@c However, the values are currently not exported - thus we
-@c do not define them here, either.
+@code{__float128 strtoflt128 (const char *s, char **sp)}

 
 @item @emph{Arguments}:
 @multitable @columnfractions .15 .70
 @item @var{s}  @tab input string
 @item @var{sp} @tab the address of the next character in the string
 
 @item @emph{Arguments}:
 @multitable @columnfractions .15 .70
 @item @var{s}  @tab input string
 @item @var{sp} @tab the address of the next character in the string

-@item @var{V}  @tab @code{__float128} containing the converted number

 @end multitable
 
 The argument @var{sp} contains, if not @code{NULL}, the address of the
 @end multitable
 
 The argument @var{sp} contains, if not @code{NULL}, the address of the


@@ -214,9 +279,8 @@ next character following the parts of the string, which have been read.
 int main ()
 @{
   __float128 r;
 int main ()
 @{
   __float128 r;

-  char str[200];

 
 

-  quadmath_strtopQ ("1.2345678", NULL, &r);
+  r = strtoflt128 ("1.2345678", NULL);

 
   return 0;
 @}
 
   return 0;
 @}


@@ -224,41 +288,72 @@ int main ()
 @end table
 
 
 @end table
 
 

-@node quadmath_dtoaq
-@section @code{quadmath_dtoaq} --- Convert to string
+@node quadmath_snprintf
+@section @code{quadmath_snprintf} --- Convert to string

 
 

-The function @code{quadmath_dtoaq} converts a @code{__float128} floating-point
-number into a string.
+The function @code{quadmath_snprintf} converts a @code{__float128} floating-point
+number into a string.  It is a specialized alternative to @code{snprintf}, where
+the format string is restricted to a single conversion specifier with @code{Q}
+modifier and conversion specifier @code{e}, @code{E}, @code{f}, @code{F}, @code{g},
+@code{G}, @code{a} or @code{A}, with no extra characters before or after the
+conversion specifier.  The @code{%m$} or @code{*m$} style must not be used in
+the format.

 
 @table @asis
 @item Syntax
 
 @table @asis
 @item Syntax

-@code{void quadmath_dtoaq (char *s, size_t size, size_t n, __float128 x)}
+@code{int quadmath_snprintf (char *s, size_t size, const char *format, ...)}

 
 @item @emph{Arguments}:
 @multitable @columnfractions .15 .70
 @item @var{s}    @tab output string
 @item @var{size} @tab byte size of the string, including tailing NUL
 
 @item @emph{Arguments}:
 @multitable @columnfractions .15 .70
 @item @var{s}    @tab output string
 @item @var{size} @tab byte size of the string, including tailing NUL

-@item @var{n}    @tab number of digits after the decimal point
-@item @var{x}    @tab the number to be converted
+@item @var{format} @tab conversion specifier string

 @end multitable
 
 @end multitable
 

+@item Note
+On some targets when supported by the C library hooks are installed
+for @code{printf} family of functions, so that @code{printf ("%Qe", 1.2Q);}
+etc.@: works too.
+

 @item Example
 @smallexample
 #include <quadmath.h>
 @item Example
 @smallexample
 #include <quadmath.h>

+#include <stdlib.h>
+#include <stdio.h>

 
 int main ()
 @{
   __float128 r;
 
 int main ()
 @{
   __float128 r;

-  char str[200];
+  int prec = 20;
+  int width = 46;
+  char buf[128];

 
   r = 2.0q;
 
   r = 2.0q;

-  r = sqrtq(r);
-  quadmath_dtoaq (str, sizeof (str), 20, r);
-  printf("%s\n", str);
-  /* Prints: +1.41421356237309504880e+00 */
+  r = sqrtq (r);
+  int n = quadmath_snprintf (buf, sizeof buf, "%+-#*.20Qe", width, r);
+  if ((size_t) n < sizeof buf)
+    printf ("%s\n", buf);
+    /* Prints: +1.41421356237309504880e+00 */
+  quadmath_snprintf (buf, sizeof buf, "%Qa", r);
+  if ((size_t) n < sizeof buf)
+    printf ("%s\n", buf);
+    /* Prints: 0x1.6a09e667f3bcc908b2fb1366ea96p+0 */
+  n = quadmath_snprintf (NULL, 0, "%+-#46.*Qe", prec, r);
+  if (n > -1)
+    @{
+      char *str = malloc (n + 1);
+      if (str)
+        @{
+          quadmath_snprintf (str, n + 1, "%+-#46.*Qe", prec, r);
+          printf ("%s\n", str);
+          /* Prints: +1.41421356237309504880e+00 */
+        @}
+      free (str);
+    @}

   return 0;
 @}
 @end smallexample
   return 0;
 @}
 @end smallexample

+

 @end table
 
 
 @end table
 
 


@@ -272,6 +367,9 @@ int main ()
 @c Reporting Bugs
 @c ---------------------------------------------------------------------
 
 @c Reporting Bugs
 @c ---------------------------------------------------------------------
 

+@c For BUGURL
+@include libquadmath-vers.texi
+

 @node Reporting Bugs
 @chapter Reporting Bugs
 
 @node Reporting Bugs
 @chapter Reporting Bugs