Skip to content

Commit

Permalink
correct docs to reflect this change
Browse files Browse the repository at this point in the history
  • Loading branch information
not-napoleon committed Nov 15, 2023
1 parent 2e53c0d commit 196456b
Show file tree
Hide file tree
Showing 2 changed files with 3 additions and 38 deletions.
37 changes: 1 addition & 36 deletions docs/reference/esql/functions/pow.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
image::esql/functions/signature/pow.svg[Embedded,opts=inline]

Returns the value of a base (first argument) raised to the power of an exponent (second argument).
Both arguments must be numeric.
Both arguments must be numeric. The output is always a double.

[source.merge.styled,esql]
----
Expand All @@ -16,31 +16,6 @@ include::{esql-specs}/math.csv-spec[tag=powDI]
include::{esql-specs}/math.csv-spec[tag=powDI-result]
|===

[discrete]
==== Type rules

The type of the returned value is determined by the types of the base and exponent.
The following rules are applied to determine the result type:

* If either of the base or exponent are of a floating point type, the result will be a double
* Otherwise, if either the base or the exponent are 64-bit (long or unsigned long), the result will be a long
* Otherwise, the result will be a 32-bit integer (this covers all other numeric types, including int, short and byte)

For example, using simple integers as arguments will lead to an integer result:

[source.merge.styled,esql]
----
include::{esql-specs}/math.csv-spec[tag=powII]
----
[%header.monospaced.styled,format=dsv,separator=|]
|===
include::{esql-specs}/math.csv-spec[tag=powII-result]
|===

NOTE: The actual power function is performed using double precision values for all cases.
This means that for very large non-floating point values there is a small chance that the
operation can lead to slightly different answers than expected.
However, a more likely outcome of very large non-floating point values is numerical overflow.

[discrete]
==== Arithmetic errors
Expand All @@ -62,16 +37,6 @@ include::{esql-specs}/math.csv-spec[tag=powULOverrun-warning]
include::{esql-specs}/math.csv-spec[tag=powULOverrun-result]
|===

If it is desired to protect against numerical overruns, use `TO_DOUBLE` on either of the arguments:

[source.merge.styled,esql]
----
include::{esql-specs}/math.csv-spec[tag=pow2d]
----
[%header.monospaced.styled,format=dsv,separator=|]
|===
include::{esql-specs}/math.csv-spec[tag=pow2d-result]
|===

[discrete]
==== Fractional exponents
Expand Down
4 changes: 2 additions & 2 deletions docs/reference/esql/functions/types/pow.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ base | exponent | result
double | double | double
double | integer | double
integer | double | double
integer | integer | integer
integer | integer | double
long | double | double
long | integer | long
long | integer | double
|===

0 comments on commit 196456b

Please sign in to comment.