begriffs open source - ai-pg/blob - full-docs/txt/functions-math.txt

   1
   2 9.3. Mathematical Functions and Operators #
   3
   4    Mathematical operators are provided for many PostgreSQL types. For
   5    types without standard mathematical conventions (e.g., date/time types)
   6    we describe the actual behavior in subsequent sections.
   7
   8    Table 9.4 shows the mathematical operators that are available for the
   9    standard numeric types. Unless otherwise noted, operators shown as
  10    accepting numeric_type are available for all the types smallint,
  11    integer, bigint, numeric, real, and double precision. Operators shown
  12    as accepting integral_type are available for the types smallint,
  13    integer, and bigint. Except where noted, each form of an operator
  14    returns the same data type as its argument(s). Calls involving multiple
  15    argument data types, such as integer + numeric, are resolved by using
  16    the type appearing later in these lists.
  17
  18    Table 9.4. Mathematical Operators
  19
  20    Operator
  21
  22    Description
  23
  24    Example(s)
  25
  26    numeric_type + numeric_type → numeric_type
  27
  28    Addition
  29
  30    2 + 3 → 5
  31
  32    + numeric_type → numeric_type
  33
  34    Unary plus (no operation)
  35
  36    + 3.5 → 3.5
  37
  38    numeric_type - numeric_type → numeric_type
  39
  40    Subtraction
  41
  42    2 - 3 → -1
  43
  44    - numeric_type → numeric_type
  45
  46    Negation
  47
  48    - (-4) → 4
  49
  50    numeric_type * numeric_type → numeric_type
  51
  52    Multiplication
  53
  54    2 * 3 → 6
  55
  56    numeric_type / numeric_type → numeric_type
  57
  58    Division (for integral types, division truncates the result towards
  59    zero)
  60
  61    5.0 / 2 → 2.5000000000000000
  62
  63    5 / 2 → 2
  64
  65    (-5) / 2 → -2
  66
  67    numeric_type % numeric_type → numeric_type
  68
  69    Modulo (remainder); available for smallint, integer, bigint, and
  70    numeric
  71
  72    5 % 4 → 1
  73
  74    numeric ^ numeric → numeric
  75
  76    double precision ^ double precision → double precision
  77
  78    Exponentiation
  79
  80    2 ^ 3 → 8
  81
  82    Unlike typical mathematical practice, multiple uses of ^ will associate
  83    left to right by default:
  84
  85    2 ^ 3 ^ 3 → 512
  86
  87    2 ^ (3 ^ 3) → 134217728
  88
  89    |/ double precision → double precision
  90
  91    Square root
  92
  93    |/ 25.0 → 5
  94
  95    ||/ double precision → double precision
  96
  97    Cube root
  98
  99    ||/ 64.0 → 4
 100
 101    @ numeric_type → numeric_type
 102
 103    Absolute value
 104
 105    @ -5.0 → 5.0
 106
 107    integral_type & integral_type → integral_type
 108
 109    Bitwise AND
 110
 111    91 & 15 → 11
 112
 113    integral_type | integral_type → integral_type
 114
 115    Bitwise OR
 116
 117    32 | 3 → 35
 118
 119    integral_type # integral_type → integral_type
 120
 121    Bitwise exclusive OR
 122
 123    17 # 5 → 20
 124
 125    ~ integral_type → integral_type
 126
 127    Bitwise NOT
 128
 129    ~1 → -2
 130
 131    integral_type << integer → integral_type
 132
 133    Bitwise shift left
 134
 135    1 << 4 → 16
 136
 137    integral_type >> integer → integral_type
 138
 139    Bitwise shift right
 140
 141    8 >> 2 → 2
 142
 143    Table 9.5 shows the available mathematical functions. Many of these
 144    functions are provided in multiple forms with different argument types.
 145    Except where noted, any given form of a function returns the same data
 146    type as its argument(s); cross-type cases are resolved in the same way
 147    as explained above for operators. The functions working with double
 148    precision data are mostly implemented on top of the host system's C
 149    library; accuracy and behavior in boundary cases can therefore vary
 150    depending on the host system.
 151
 152    Table 9.5. Mathematical Functions
 153
 154    Function
 155
 156    Description
 157
 158    Example(s)
 159
 160    abs ( numeric_type ) → numeric_type
 161
 162    Absolute value
 163
 164    abs(-17.4) → 17.4
 165
 166    cbrt ( double precision ) → double precision
 167
 168    Cube root
 169
 170    cbrt(64.0) → 4
 171
 172    ceil ( numeric ) → numeric
 173
 174    ceil ( double precision ) → double precision
 175
 176    Nearest integer greater than or equal to argument
 177
 178    ceil(42.2) → 43
 179
 180    ceil(-42.8) → -42
 181
 182    ceiling ( numeric ) → numeric
 183
 184    ceiling ( double precision ) → double precision
 185
 186    Nearest integer greater than or equal to argument (same as ceil)
 187
 188    ceiling(95.3) → 96
 189
 190    degrees ( double precision ) → double precision
 191
 192    Converts radians to degrees
 193
 194    degrees(0.5) → 28.64788975654116
 195
 196    div ( y numeric, x numeric ) → numeric
 197
 198    Integer quotient of y/x (truncates towards zero)
 199
 200    div(9, 4) → 2
 201
 202    erf ( double precision ) → double precision
 203
 204    Error function
 205
 206    erf(1.0) → 0.8427007929497149
 207
 208    erfc ( double precision ) → double precision
 209
 210    Complementary error function (1 - erf(x), without loss of precision for
 211    large inputs)
 212
 213    erfc(1.0) → 0.15729920705028513
 214
 215    exp ( numeric ) → numeric
 216
 217    exp ( double precision ) → double precision
 218
 219    Exponential (e raised to the given power)
 220
 221    exp(1.0) → 2.7182818284590452
 222
 223    factorial ( bigint ) → numeric
 224
 225    Factorial
 226
 227    factorial(5) → 120
 228
 229    floor ( numeric ) → numeric
 230
 231    floor ( double precision ) → double precision
 232
 233    Nearest integer less than or equal to argument
 234
 235    floor(42.8) → 42
 236
 237    floor(-42.8) → -43
 238
 239    gamma ( double precision ) → double precision
 240
 241    Gamma function
 242
 243    gamma(0.5) → 1.772453850905516
 244
 245    gamma(6) → 120
 246
 247    gcd ( numeric_type, numeric_type ) → numeric_type
 248
 249    Greatest common divisor (the largest positive number that divides both
 250    inputs with no remainder); returns 0 if both inputs are zero; available
 251    for integer, bigint, and numeric
 252
 253    gcd(1071, 462) → 21
 254
 255    lcm ( numeric_type, numeric_type ) → numeric_type
 256
 257    Least common multiple (the smallest strictly positive number that is an
 258    integral multiple of both inputs); returns 0 if either input is zero;
 259    available for integer, bigint, and numeric
 260
 261    lcm(1071, 462) → 23562
 262
 263    lgamma ( double precision ) → double precision
 264
 265    Natural logarithm of the absolute value of the gamma function
 266
 267    lgamma(1000) → 5905.220423209181
 268
 269    ln ( numeric ) → numeric
 270
 271    ln ( double precision ) → double precision
 272
 273    Natural logarithm
 274
 275    ln(2.0) → 0.6931471805599453
 276
 277    log ( numeric ) → numeric
 278
 279    log ( double precision ) → double precision
 280
 281    Base 10 logarithm
 282
 283    log(100) → 2
 284
 285    log10 ( numeric ) → numeric
 286
 287    log10 ( double precision ) → double precision
 288
 289    Base 10 logarithm (same as log)
 290
 291    log10(1000) → 3
 292
 293    log ( b numeric, x numeric ) → numeric
 294
 295    Logarithm of x to base b
 296
 297    log(2.0, 64.0) → 6.0000000000000000
 298
 299    min_scale ( numeric ) → integer
 300
 301    Minimum scale (number of fractional decimal digits) needed to represent
 302    the supplied value precisely
 303
 304    min_scale(8.4100) → 2
 305
 306    mod ( y numeric_type, x numeric_type ) → numeric_type
 307
 308    Remainder of y/x; available for smallint, integer, bigint, and numeric
 309
 310    mod(9, 4) → 1
 311
 312    pi ( ) → double precision
 313
 314    Approximate value of π
 315
 316    pi() → 3.141592653589793
 317
 318    power ( a numeric, b numeric ) → numeric
 319
 320    power ( a double precision, b double precision ) → double precision
 321
 322    a raised to the power of b
 323
 324    power(9, 3) → 729
 325
 326    radians ( double precision ) → double precision
 327
 328    Converts degrees to radians
 329
 330    radians(45.0) → 0.7853981633974483
 331
 332    round ( numeric ) → numeric
 333
 334    round ( double precision ) → double precision
 335
 336    Rounds to nearest integer. For numeric, ties are broken by rounding
 337    away from zero. For double precision, the tie-breaking behavior is
 338    platform dependent, but “round to nearest even” is the most common
 339    rule.
 340
 341    round(42.4) → 42
 342
 343    round ( v numeric, s integer ) → numeric
 344
 345    Rounds v to s decimal places. Ties are broken by rounding away from
 346    zero.
 347
 348    round(42.4382, 2) → 42.44
 349
 350    round(1234.56, -1) → 1230
 351
 352    scale ( numeric ) → integer
 353
 354    Scale of the argument (the number of decimal digits in the fractional
 355    part)
 356
 357    scale(8.4100) → 4
 358
 359    sign ( numeric ) → numeric
 360
 361    sign ( double precision ) → double precision
 362
 363    Sign of the argument (-1, 0, or +1)
 364
 365    sign(-8.4) → -1
 366
 367    sqrt ( numeric ) → numeric
 368
 369    sqrt ( double precision ) → double precision
 370
 371    Square root
 372
 373    sqrt(2) → 1.4142135623730951
 374
 375    trim_scale ( numeric ) → numeric
 376
 377    Reduces the value's scale (number of fractional decimal digits) by
 378    removing trailing zeroes
 379
 380    trim_scale(8.4100) → 8.41
 381
 382    trunc ( numeric ) → numeric
 383
 384    trunc ( double precision ) → double precision
 385
 386    Truncates to integer (towards zero)
 387
 388    trunc(42.8) → 42
 389
 390    trunc(-42.8) → -42
 391
 392    trunc ( v numeric, s integer ) → numeric
 393
 394    Truncates v to s decimal places
 395
 396    trunc(42.4382, 2) → 42.43
 397
 398    width_bucket ( operand numeric, low numeric, high numeric, count
 399    integer ) → integer
 400
 401    width_bucket ( operand double precision, low double precision, high
 402    double precision, count integer ) → integer
 403
 404    Returns the number of the bucket in which operand falls in a histogram
 405    having count equal-width buckets spanning the range low to high. The
 406    buckets have inclusive lower bounds and exclusive upper bounds. Returns
 407    0 for an input less than low, or count+1 for an input greater than or
 408    equal to high. If low > high, the behavior is mirror-reversed, with
 409    bucket 1 now being the one just below low, and the inclusive bounds now
 410    being on the upper side.
 411
 412    width_bucket(5.35, 0.024, 10.06, 5) → 3
 413
 414    width_bucket(9, 10, 0, 10) → 2
 415
 416    width_bucket ( operand anycompatible, thresholds anycompatiblearray ) →
 417    integer
 418
 419    Returns the number of the bucket in which operand falls given an array
 420    listing the inclusive lower bounds of the buckets. Returns 0 for an
 421    input less than the first lower bound. operand and the array elements
 422    can be of any type having standard comparison operators. The thresholds
 423    array must be sorted, smallest first, or unexpected results will be
 424    obtained.
 425
 426    width_bucket(now(), array['yesterday', 'today',
 427    'tomorrow']::timestamptz[]) → 2
 428
 429    Table 9.6 shows functions for generating random numbers.
 430
 431    Table 9.6. Random Functions
 432
 433    Function
 434
 435    Description
 436
 437    Example(s)
 438
 439    random ( ) → double precision
 440
 441    Returns a random value in the range 0.0 <= x < 1.0
 442
 443    random() → 0.897124072839091
 444
 445    random ( min integer, max integer ) → integer
 446
 447    random ( min bigint, max bigint ) → bigint
 448
 449    random ( min numeric, max numeric ) → numeric
 450
 451    Returns a random value in the range min <= x <= max. For type numeric,
 452    the result will have the same number of fractional decimal digits as
 453    min or max, whichever has more.
 454
 455    random(1, 10) → 7
 456
 457    random(-0.499, 0.499) → 0.347
 458
 459    random_normal ( [ mean double precision [, stddev double precision ]] )
 460    → double precision
 461
 462    Returns a random value from the normal distribution with the given
 463    parameters; mean defaults to 0.0 and stddev defaults to 1.0
 464
 465    random_normal(0.0, 1.0) → 0.051285419
 466
 467    setseed ( double precision ) → void
 468
 469    Sets the seed for subsequent random() and random_normal() calls;
 470    argument must be between -1.0 and 1.0, inclusive
 471
 472    setseed(0.12345)
 473
 474    The random() and random_normal() functions listed in Table 9.6 use a
 475    deterministic pseudo-random number generator. It is fast but not
 476    suitable for cryptographic applications; see the pgcrypto module for a
 477    more secure alternative. If setseed() is called, the series of results
 478    of subsequent calls to these functions in the current session can be
 479    repeated by re-issuing setseed() with the same argument. Without any
 480    prior setseed() call in the same session, the first call to any of
 481    these functions obtains a seed from a platform-dependent source of
 482    random bits.
 483
 484    Table 9.7 shows the available trigonometric functions. Each of these
 485    functions comes in two variants, one that measures angles in radians
 486    and one that measures angles in degrees.
 487
 488    Table 9.7. Trigonometric Functions
 489
 490    Function
 491
 492    Description
 493
 494    Example(s)
 495
 496    acos ( double precision ) → double precision
 497
 498    Inverse cosine, result in radians
 499
 500    acos(1) → 0
 501
 502    acosd ( double precision ) → double precision
 503
 504    Inverse cosine, result in degrees
 505
 506    acosd(0.5) → 60
 507
 508    asin ( double precision ) → double precision
 509
 510    Inverse sine, result in radians
 511
 512    asin(1) → 1.5707963267948966
 513
 514    asind ( double precision ) → double precision
 515
 516    Inverse sine, result in degrees
 517
 518    asind(0.5) → 30
 519
 520    atan ( double precision ) → double precision
 521
 522    Inverse tangent, result in radians
 523
 524    atan(1) → 0.7853981633974483
 525
 526    atand ( double precision ) → double precision
 527
 528    Inverse tangent, result in degrees
 529
 530    atand(1) → 45
 531
 532    atan2 ( y double precision, x double precision ) → double precision
 533
 534    Inverse tangent of y/x, result in radians
 535
 536    atan2(1, 0) → 1.5707963267948966
 537
 538    atan2d ( y double precision, x double precision ) → double precision
 539
 540    Inverse tangent of y/x, result in degrees
 541
 542    atan2d(1, 0) → 90
 543
 544    cos ( double precision ) → double precision
 545
 546    Cosine, argument in radians
 547
 548    cos(0) → 1
 549
 550    cosd ( double precision ) → double precision
 551
 552    Cosine, argument in degrees
 553
 554    cosd(60) → 0.5
 555
 556    cot ( double precision ) → double precision
 557
 558    Cotangent, argument in radians
 559
 560    cot(0.5) → 1.830487721712452
 561
 562    cotd ( double precision ) → double precision
 563
 564    Cotangent, argument in degrees
 565
 566    cotd(45) → 1
 567
 568    sin ( double precision ) → double precision
 569
 570    Sine, argument in radians
 571
 572    sin(1) → 0.8414709848078965
 573
 574    sind ( double precision ) → double precision
 575
 576    Sine, argument in degrees
 577
 578    sind(30) → 0.5
 579
 580    tan ( double precision ) → double precision
 581
 582    Tangent, argument in radians
 583
 584    tan(1) → 1.5574077246549023
 585
 586    tand ( double precision ) → double precision
 587
 588    Tangent, argument in degrees
 589
 590    tand(45) → 1
 591
 592 Note
 593
 594    Another way to work with angles measured in degrees is to use the unit
 595    transformation functions radians() and degrees() shown earlier.
 596    However, using the degree-based trigonometric functions is preferred,
 597    as that way avoids round-off error for special cases such as sind(30).
 598
 599    Table 9.8 shows the available hyperbolic functions.
 600
 601    Table 9.8. Hyperbolic Functions
 602
 603    Function
 604
 605    Description
 606
 607    Example(s)
 608
 609    sinh ( double precision ) → double precision
 610
 611    Hyperbolic sine
 612
 613    sinh(1) → 1.1752011936438014
 614
 615    cosh ( double precision ) → double precision
 616
 617    Hyperbolic cosine
 618
 619    cosh(0) → 1
 620
 621    tanh ( double precision ) → double precision
 622
 623    Hyperbolic tangent
 624
 625    tanh(1) → 0.7615941559557649
 626
 627    asinh ( double precision ) → double precision
 628
 629    Inverse hyperbolic sine
 630
 631    asinh(1) → 0.881373587019543
 632
 633    acosh ( double precision ) → double precision
 634
 635    Inverse hyperbolic cosine
 636
 637    acosh(1) → 0
 638
 639    atanh ( double precision ) → double precision
 640
 641    Inverse hyperbolic tangent
 642
 643    atanh(0.5) → 0.5493061443340548