File : s-libsin-ada.ads


   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                    S Y S T E M . L I B M _ S I N G L E                   --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --          Copyright (C) 2014-2016, Free Software Foundation, Inc.         --
  10 --                                                                          --
  11 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
  12 -- terms of the  GNU General Public License as published  by the Free Soft- --
  13 -- ware  Foundation;  either version 3,  or (at your option) any later ver- --
  14 -- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
  15 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  16 -- or FITNESS FOR A PARTICULAR PURPOSE.                                     --
  17 --                                                                          --
  18 --                                                                          --
  19 --                                                                          --
  20 --                                                                          --
  21 --                                                                          --
  22 -- You should have received a copy of the GNU General Public License and    --
  23 -- a copy of the GCC Runtime Library Exception along with this program;     --
  24 -- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
  25 -- <http://www.gnu.org/licenses/>.                                          --
  26 --                                                                          --
  27 -- GNAT was originally developed  by the GNAT team at  New York University. --
  28 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  29 --                                                                          --
  30 ------------------------------------------------------------------------------
  31 
  32 --  This is the Ada Cert Math specific version of s-libsin.ads
  33 
  34 with System.Libm_Prefix;
  35 
  36 --  @llrset Libm
  37 --  LLR Libm
  38 --  ========
  39 
  40 package System.Libm_Single is
  41    pragma Pure;
  42 
  43    package SLP renames System.Libm_Prefix;
  44 
  45    --  This package provides an implementation of the various C99 functions
  46    --  used in the Ada run time. It is intended to be used for targets that
  47    --  do not have a C math library, or where the C math library isn't of
  48    --  sufficient quality and accuracy to meet Ada requirements.
  49 
  50    --  In case of error conditions, NaNs or infinities are returned as
  51    --  recommended in clause F.9 of the C99 standard. When called from C code,
  52    --  the implementation behaves as if the FENV_ACCESS state is off, assuming
  53    --  default rounding behavior and exception behavior.
  54 
  55    --  The following C99 elementary functions are provided for single
  56    --  precision (with the "f" suffix):
  57 
  58    --    Acos, Acosh, Asin, Asinh, Atan, Atan2, Atanh, Cosh, Exp, Exp2, Log,
  59    --    Log1p, Log2, Pow, Sin, Sinh, Tan, Tanh
  60 
  61    --  All functions with a NaN argument return a NaN result, except where
  62    --  stated otherwise. Unless otherwise specified, where the symbol +- occurs
  63    --  in both an argument and the result, the result has the same sign as
  64    --  the argument.
  65 
  66    --  Each function lists C special values, Ada expected values as well as
  67    --  Ada accuracy requirements the function meets. For accuracy requirements
  68    --  the maximum relative error (abbreviated as MRE) is given, as well as
  69    --  the domain for which the accuracy is guaranteed, where applicable.
  70    --  The maximum relative error is expressed as multiple of Eps,
  71    --  where Eps is Float'Model_Epsilon.
  72 
  73    --  What about principal branch ???
  74 
  75    ----------
  76    -- Acos --
  77    ----------
  78 
  79    function Acos (X : Float) return Float
  80      with Export, Convention => C, External_Name => SLP.Prefix & "acosf";
  81    --  @llr acos (Float) Special Values
  82    --  The Acos function shall return the following special values:
  83    --
  84    --  C99 special values:
  85    --    Acos (1) = +0
  86    --    Acos (x) = NaN if abs (x) > 1
  87    --
  88    --  Ada expected values:
  89    --    Acos (0)  = Pi/2.0 (tightly approximated)
  90    --    Acos (-1) = Pi (tightly approximated)
  91    --    Acos (x) return a result in [0, Pi] radians
  92    --
  93    --  @llr acos (Float) Accuracy
  94    --  The Acos function shall return the inverse cosine of <X> with the
  95    --  following accuracy:
  96    --
  97    --  Ada accuracy requirements:
  98    --    MRE <= 4.0 * Eps
  99 
 100    -----------
 101    -- Acosh --
 102    -----------
 103 
 104    function Acosh (X : Float) return Float
 105      with Export, Convention => C, External_Name => SLP.Prefix & "acoshf";
 106    --  @llr acosh (Float) Special Values
 107    --  The Acosh function shall return the following special values:
 108    --
 109    --  C99 special values:
 110    --    Acosh (1) = +0
 111    --    Acosh (x) = NaN if abs X > 1
 112    --    Acosh (+INF) = +INF
 113    --
 114    --  @llr acosh (Float) Accuracy
 115    --  The Acosh function shall return the inverse hyperbolic tangent of <X>
 116    --  with the following accuracy:
 117    --
 118    --  Ada accuracy requirements:
 119    --    MRE <= 8.0 * Eps
 120 
 121    ----------
 122    -- Asin --
 123    ----------
 124 
 125    function Asin (X : Float) return Float
 126      with Export, Convention => C, External_Name => SLP.Prefix & "asinf";
 127    --  @llr asin (Float) Special Values
 128    --  The Asin function shall return the following special values:
 129    --
 130    --  C99 special values:
 131    --    Asin (+-0) = +-0
 132    --    Asin (x)   = NaN if abs (x) > 1
 133    --
 134    --  Ada expected values:
 135    --    Asin (1)  = Pi/2.0 (tightly approximated)
 136    --    Asin (-1) = -Pi/2 (tightly approximated)
 137    --    Asin (x) return a result in [-Pi/2, Pi/2] radians
 138    --
 139    --  @llr asin (Float) Accuracy
 140    --  The Asin function shall return the inverse sine of <X> with the
 141    --  following accuracy:
 142    --
 143    --  Ada accuracy requirements:
 144    --    MRE <= 4.0 * Eps
 145 
 146    -----------
 147    -- Asinh --
 148    -----------
 149 
 150    function Asinh (X : Float) return Float
 151      with Export, Convention => C, External_Name => SLP.Prefix & "asinhf";
 152    --  @llr asinh (Float) Special Values
 153    --  The Asinh function shall return the following special values:
 154    --
 155    --  C99 special values:
 156    --    Asinh (0) = 0
 157    --    Asinh (+INF) = +INF
 158    --
 159    --  @llr asinh (Float) Accuracy
 160    --  The Asinh function shall return the inverse hyperbolic sine of <X>
 161    --  with the following accuracy:
 162    --
 163    --  Ada accuracy requirements:
 164    --    MRE <= 8.0 * Eps
 165 
 166    ----------
 167    -- Atan --
 168    ----------
 169 
 170    function Atan (X : Float) return Float
 171      with Export, Convention => C, External_Name => SLP.Prefix & "atanf";
 172    --  @llr atan (Float) Special Values
 173    --  The Atan function shall return the following special values:
 174    --
 175    --  C99 special values:
 176    --    Atan (+-0)     = +-Pi
 177    --    Atan2 (+-INF)    = +-0.5 * Pi
 178    --
 179    --  C expected values:
 180    --    Atan (x) return a result in [-Pi/2, Pi/2]
 181 
 182    -----------
 183    -- Atan2 --
 184    -----------
 185 
 186    function Atan2 (Y : Float; X : Float) return Float
 187      with Export, Convention => C, External_Name => SLP.Prefix & "atan2f";
 188    --  @llr atan2 (Float; Float) Special Values
 189    --  The Atan2 function shall return the following special values:
 190    --
 191    --  C99 special values:
 192    --    Atan2 (+-0, -0)     = +-Pi
 193    --    Atan2 (+-0, +0)     = +-0
 194    --    Atan2 (+-0, x)      = +-Pi,        if x < 0
 195    --    Atan2 (+-0, x)      = +-0,         if x > 0
 196    --    Atan2 (y, +-0)      = -0.5 * Pi,   if y < 0
 197    --    Atan2 (y, +-0)      =  0.5 * Pi,   if y > 0
 198    --    Atan2 (+-y, -INF)   = +-Pi,        if y > 0 and y is finite
 199    --      (tightly approximated)
 200    --    Atan2 (+-y, -INF)   = +-0,         if y < 0 and y is finite
 201    --    Atan2 (+-INF, x)    = +-0.5 * Pi,  if x is finite
 202    --      (tightly approximated)
 203    --    Atan2 (+-INF, -INF) = +-0.75 * Pi (tightly approximated)
 204    --    Atan2 (+-INF, +INF) = +-0.25 * Pi (tightly approximated)
 205    --
 206    --  Ada expected values:
 207    --    Atan2 (y, x) return a result in [-Pi, Pi]
 208    --
 209    --  @llr atan2 (Float; Float) Accuracy
 210    --  The Atan2 function shall return the inverse tangent of <Y> / <X>
 211    --  with the following accuracy:
 212    --
 213    --  Ada accuracy requirements:
 214    --    MRE <= 4.0 * Eps
 215 
 216    -----------
 217    -- Atanh --
 218    -----------
 219 
 220    function Atanh (X : Float) return Float
 221      with Export, Convention => C, External_Name => SLP.Prefix & "atanhf";
 222    --  @llr atanh (Float) Special Values
 223    --  The Atanh function shall return the following special values:
 224    --
 225    --  C99 special values:
 226    --    Atanh (0) = 0
 227    --    Atanh (+-1) = +- INF
 228    --    Atanh (X) = NaN for abs X > 1
 229    --
 230    --  @llr atanh (Float) Accuracy
 231    --  The Atanh function shall return the inverse hyperbolic tangent of <X>
 232    --  with the following accuracy:
 233    --
 234    --  Ada accuracy requirements:
 235    --    MRE <= 8.0 * Eps
 236 
 237    ---------
 238    -- Cos --
 239    ---------
 240 
 241    function Cos (X : Float) return Float
 242      with Export, Convention => C, External_Name => SLP.Prefix & "cosf";
 243    --  @llr cos (Float) Special Values
 244    --  The Cos function shall return the following special values:
 245    --
 246    --  C99 special values:
 247    --    Cos (+-0)   = 1
 248    --    Cos (+-INF) = NaN
 249    --
 250    --  Ada expected values:
 251    --    abs (Cos (x)) <= 1
 252    --
 253    --  @llr cos (Float) Accuracy
 254    --  The Cos function shall return the cosine of <X>
 255    --  with the following accuracy:
 256    --
 257    --  Ada accuracy requirements:
 258    --    MRE <= 2.0 * Eps
 259 
 260    ----------
 261    -- Cosh --
 262    ----------
 263 
 264    function Cosh (X : Float) return Float
 265      with Export, Convention => C, External_Name => SLP.Prefix & "coshf";
 266    --  @llr cosh (Float) Special Values
 267    --  The Cosh function shall return the following special values:
 268    --
 269    --  C99 special values:
 270    --    Cosh (+-0)   = 1
 271    --    Cosh (+-INF) = +INF
 272    --
 273    --  Ada expected values:
 274    --    abs (Cosh (x)) > 1
 275    --
 276    --  @llr cosh (Float) Accuracy
 277    --  The Cosh function shall return the inverse cosine of <X>
 278    --  with the following accuracy:
 279    --
 280    --  Ada accuracy requirements:
 281    --    MRE <= 8.0 * Eps
 282 
 283    ---------
 284    -- Exp --
 285    ---------
 286 
 287    function Exp (X : Float) return Float
 288      with Export, Convention => C, External_Name => SLP.Prefix & "expf";
 289    --  @llr exp (Float) Special Values
 290    --  The Exp function shall return the following special values:
 291    --
 292    --  C99 special values:
 293    --    Exp (+-0)  = 1
 294    --    Exp (-INF) = +0
 295    --    Exp (+INF) = +INF
 296    --
 297    --  @llr exp (Float) Accuracy
 298    --  The Exp function shall return the exponential of <X>
 299    --  with the following accuracy:
 300    --
 301    --  Ada accuracy requirements:
 302    --    MRE <= 4.0 * Eps
 303 
 304    ----------
 305    -- Exp2 --
 306    ----------
 307 
 308    function Exp2 (X : Float) return Float
 309      with Export, Convention => C, External_Name => SLP.Prefix & "exp2f";
 310    --  @llr exp2 (Float) Special Values
 311    --  The Exp2 function shall return the following special values:
 312    --
 313    --  C99 special values:
 314    --    Exp2 (+-0)  = 1
 315    --    Exp2 (-INF) = +0
 316    --    Exp2 (+INF) = +INF
 317    --
 318    --  @llr exp2 (Float) Accuracy
 319    --  The Exp2 function shall return the exponential of <X> in base 2
 320    --  with the following accuracy:
 321    --
 322    --  Accuracy requirements:
 323    --    MRE <= 4.0 * Eps
 324 
 325    ---------
 326    -- Log --
 327    ---------
 328 
 329    function Log (X : Float) return Float
 330      with Export, Convention => C, External_Name => SLP.Prefix & "logf";
 331    --  @llr log (Float) Special Values
 332    --  The Log function shall return the following special values:
 333    --
 334    --  C99 special values:
 335    --    Log (+-0)  = -INF
 336    --    Log (1)    = +0
 337    --    Log (x)    = NaN if x<0
 338    --    Log (+INF) = +INF
 339    --
 340    --  @llr log (Float) Accuracy
 341    --  The Log function shall return the logarithm of <X>
 342    --  with the following accuracy:
 343    --
 344    --  Ada accuracy requirements:
 345    --    MRE <= 4.0 * Eps
 346 
 347    -----------
 348    -- Log1p --
 349    -----------
 350 
 351    function Log1p (X : Float) return Float
 352      with Export, Convention => C, External_Name => SLP.Prefix & "log1pf";
 353    --  @llr log1p (Float) Special Values:
 354    --  The Log1p function shall return the following special values:
 355    --
 356    --  C99 special values:
 357    --    Log1p (+-0)  = -INF
 358    --    Log1p (1)    = +0
 359    --    Log1p (x)    = NaN if x<0
 360    --    Log1p (+INF) = +INF
 361    --
 362    --  @llr log1p (Float) Accuracy
 363    --  The Log1p function shall return the logarithm of <X> + 1
 364    --  with the following accuracy:
 365    --
 366    --  Accuracy requirements:
 367    --    MRE <= 4.0 * Eps
 368 
 369    ----------
 370    -- Log2 --
 371    ----------
 372 
 373    function Log2 (X : Float) return Float
 374      with Export, Convention => C, External_Name => SLP.Prefix & "log2f";
 375    --  @llr log2 (Float) Special Values
 376    --  The Log2 function shall return the following special values:
 377    --
 378    --  C99 Special values:
 379    --    Log2 (+-0)  = -INF
 380    --    Log2 (1)    = +0
 381    --    Log2 (x)    = NaN if x<0
 382    --    Log2 (+INF) = +INF
 383    --
 384    --  @llr log2 (Float) Accuracy
 385    --  The Log function shall return the logarithm of <X> in base 2
 386    --  with the following accuracy:
 387    --
 388    --  Accuracy requirements:
 389    --    MRE <= 4.0 * Eps
 390 
 391    ---------
 392    -- Pow --
 393    ---------
 394 
 395    function Pow (Left, Right : Float) return Float
 396      with Export, Convention => C, External_Name => SLP.Prefix & "powf";
 397    --  @llr pow (Float; Float) Special Values
 398    --  The Pow function shall return the following special values
 399    --
 400    --  C99 Special values:
 401    --    Pow (+-0, y)    = +-INF, if y < 0 and y an odd integer
 402    --    Pow (+-0, y)    = +INF, if y < 0 and y not an odd integer
 403    --    Pow (+-0, y)    = +-0   if y > 0 and y an odd integer
 404    --    Pow (+-0, y)    = +0    if y > 0 and y not an odd integer
 405    --    Pow (-1, +-INF) = 1
 406    --    Pow (1, y)      = 1 for any y, even a NaN
 407    --    Pow (x, +-0)    = 1 for any x, even a NaN
 408    --    Pow (x, y)  = NaN, if x < 0 and both x and y finite and not integer
 409    --    Pow (x, -INF)   = +INF      if abs (x) < 1
 410    --    Pow (x, -INF)   = +0        if abs (x) > 1
 411    --    Pow (x, +INF)   = +0        if abs (x) < 1
 412    --    Pow (x, +INF)   = +INF      if abs (x) > 1
 413    --    Pow (-INF, y)   = -0        if y < 0 and y an odd integer
 414    --    Pow (-INF, y)   = +0        if y < 0 and y not an odd integer
 415    --    Pow (-INF, y)   = -INF      if y > 0 and y an odd integer
 416    --    Pow (-INF, y)   = +INF      if y > 0 and y not an odd integer
 417    --    Pow (+INF, y)   = +0        if y < 0
 418    --    Pow (+INF, y)   = +INF      if y > 0
 419    --
 420    --  @llr pow (Float; Float) Accuracy
 421    --  The Pow function shall return <Left> to the power of <Right>
 422    --  with the following accuracy:
 423    --
 424    --  Ada Accuracy requirements:
 425    --    MRE <= (4.0 + abs (x * Log (y)) / 32) * Eps
 426 
 427    ---------
 428    -- Sin --
 429    ---------
 430 
 431    function Sin (X : Float) return Float
 432      with Export, Convention => C, External_Name => SLP.Prefix & "sinf";
 433    --  @llr sin (Float) Special Values
 434    --  The Sin function shall return the following special values:
 435    --
 436    --  C99 special values:
 437    --    Sin (+-0)   = +-0
 438    --    Sin (+-INF) = NaN
 439    --
 440    --  @llr sin (Float) Accuracy
 441    --  The Sin function shall return the sine of <X>
 442    --  with the following accuracy:
 443    --
 444    --  Ada accuracy requirements:
 445    --    MRE <= 2.0 * Eps
 446 
 447    ----------
 448    -- Sinh --
 449    ----------
 450 
 451    function Sinh (X : Float) return Float
 452      with Export, Convention => C, External_Name => SLP.Prefix & "sinhf";
 453    --  @llr sinh (Float) Special Values
 454    --  The Sinh function shall return the following special values:
 455    --
 456    --  C99 Special values:
 457    --    Sinh (+-0)   = +-0
 458    --    Sinh (+-INF) = +-INF
 459    --
 460    --  @llr sinh (Float) Accuracy
 461    --  The Sinh function shall return the hyperbolic sine of <X>
 462    --  with the following accuracy:
 463    --
 464    --  Ada accuracy requirements:
 465    --    MRE <= 8.0 * Eps
 466 
 467    ----------
 468    -- Sqrt --
 469    ----------
 470 
 471    function Sqrt (X : Float) return Float
 472      with Convention => C;
 473    --  @ignore
 474    --  The Sqrt function shall return the following special values:
 475    --
 476    --  C99 special values:
 477    --    Sqrt (+-0) = +-0
 478    --    Sqrt (INF) = INF
 479    --    Sqrt (X)   = NaN, for X < 0.0
 480 
 481    ---------
 482    -- Tan --
 483    ---------
 484 
 485    function Tan (X : Float) return Float
 486      with Export, Convention => C, External_Name => SLP.Prefix & "tanf";
 487    --  @llr tan (Float) Special Values
 488    --  The Tan function shall return the following special values:
 489    --
 490    --  C99 special values:
 491    --    Tan (+-0)   = +0
 492    --    Tan (+-INF) = NaN
 493    --
 494    --  @llr tan (Float) Accuracy
 495    --  The Tan function shall return the tangent of <X>
 496    --  with the following accuracy:
 497    --
 498    --  Ada accuracy requirements:
 499    --    MRE <= 4.0 * Eps
 500 
 501    ----------
 502    -- Tanh --
 503    ----------
 504 
 505    function Tanh (X : Float) return Float
 506      with Export, Convention => C, External_Name => SLP.Prefix & "tanhf";
 507    --  @llr tanh (Float) Special Values
 508    --  The Tanh function shall return the following special values:
 509    --
 510    --  C99 special values:
 511    --    Tanh (+-0) = +-0
 512    --    Tanh (+-INF) = +-1
 513    --
 514    --  @llr tanh (Float) Accuracy
 515    --  The Tanh function shall return the hyperbolic tangent of <X>
 516    --  with the following accuracy:
 517    --
 518    --  Ada accuracy requirements:
 519    --    MRE <= 8.0 * Eps
 520 
 521 private
 522    function Identity (X : Float) return Float is (X);
 523 
 524    function Infinity return Float
 525      with Import, Convention => Intrinsic, External_Name => "__builtin_inff";
 526 
 527    function NaN return Float is (Infinity - Infinity);
 528 
 529    function Exact (X : Long_Long_Float) return Float is (Float (X));
 530 
 531    function Epsilon return Float is (Float'Model_Epsilon);
 532 
 533    function Maximum_Relative_Error (X : Float) return Float is (0.0 * X);
 534 
 535 end System.Libm_Single;