float

FRAMES NO FRAMES

Overview

Package

Deprecated

Help

API Reference for EPL (ApamaDoc) 10.11.3.3

SUMMARY: IMPORT | CONSTANT | MEMBER | ACTION

DETAIL: IMPORT | CONSTANT | MEMBER | ACTION

<Default Package>
Type float

64-bit signed floating point number.

A signed floating point number. Either a decimal point (.) or an exponent symbol (e) must be present within the number for it to be a valid float.

When perfect accuracy is a requirement, use the decimal type in place of the float type. When extremely small floating point variations are acceptable, you might choose to use the float type to obtain better performance.

Values of the float type are a finite-precision approximation of the mathematical real numbers, encoded as 64-bit binary floating-point values consisting of sign, significand, and exponent, as defined by the IEEE Standard for Binary Floating-Point Arithmetic, ANSI/IEEE Standard 754-1985 (IEEE, New York). Values of the float type have a precision of approximately 16 decimal digits. (The binary significand is 52 bits wide.)

The largest positive floating point value that can be stored in a variable of type float is 1.7976931348623157 * 10³⁰⁸ and the smallest non-zero positive value that can be stored is 2.2250738585072014 * 10^-308.

In addition to the usual positive and negative numbers, the IEEE standard also defines positive and negative zeros, positive and negative infinities, and Not-a-Number (NaN) values.

Because float values are of finite precision and binary encoded, they cannot accurately represent all values. In particular, when a floating point literal expressed in decimal notation is converted to its binary floating-point representation, there can be a slight loss of accuracy. This occurs because most decimal fractions cannot be represented precisely in binary. So the fraction 0.1 or 1/10 in base 10 becomes the infinitely repeating fraction 0.0001100110011001100110011... when it is converted to base 2. Similarly, conversions from floating point values to integral or string types will sometimes be inexact.

Operations where rounding is required use the IEEE standard approach of "round half to even" (also known as "banker's rounding").

Floats are routable in an event, they are acyclic, they can be parsed and they are comparable. The default value is 0.0.

Floats support the following operators:

`<`	Less-than comparison
`<=`	Less-than or equal comparison
`=`	Equal comparison
`!=`	Not equal comparison
`>=`	Greater-than or equal comparison
`>`	Greater-than comparison
`+`	Unary float identity
`-`	Unary float additive inverse
`+`	Float addition
`-`	Float subtraction
`*`	Float multiplication
`/`	Float division

with the following conditions:

-Infinity is equal to -Infinity and less than all other numbers
+Infinity is equal to +Infinity and greater than all other numbers
NaN is not equal to anything, including another NaN (so use isNaN() not "=" to detect NaN values)
Attempting to use NaN for keying or sorting will throw an exception

The following operations return NaN:

0.0/0.0
Infinity - Infinity
0.0 * Infinity
All operations which take NaN as a parameter

The following operations return positive infinity:

x/0.0 if x > 0
x/-0.0 if x > 0

The following operations return negative infinity:

x/0.0 if x < 0
x/-0.0 if x < 0

For the behavior regarding IEEE special values of the individual methods on float, see the documentation of each method.

Constant summary
`float`	`E` Euler's constant, e (2.71828...).
`float`	`EPSILON` The smallest `x` where `(1+x) > 1`.
`float`	`INFINITY` IEEE 754 positive infinity.
`float`	`MAX` The largest positive float number (~2*10³⁰⁸).
`float`	`MIN` The smallest positive float number (~2*10^-308).
`float`	`NAN` IEEE 754 Not-a-Number.
`float`	`PI` The ratio of a circle's circumference to its diameter (3.14159265...).

Action summary
`float`	`abs()` The absolute value of this float.
`float`	`acos()` Calculate the inverse cosine of this number in radians.
`float`	`acosh()` Calculate the inverse hyperbolic cosine of this number.
`float`	`asin()` Calculate the inverse sine of this number in radians.
`float`	`asinh()` Calculate the inverse hyperbolic sine of this number.
`float`	`atan()` Calculate the inverse tangent of this number.
`float`	`atan2(float d)` Calculate the two-parameter inverse tangent of this number and the argument.
`float`	`atanh()` Calculate the inverse hyperbolic tangent of this number.
`boolean`	`bitEquals(float other)` Bitwise comparison of two floats.
`boolean`	`static` `canParse(string s)` Check if the string argument can be successfully parsed as a float.
`float`	`cbrt()` Return the cube root of this float.
`integer`	`ceil()` Return the smallest possible integer that is greater than or equal to this float.
`float`	`cos()` Calculate the cosine of this float in radians.
`float`	`cosh()` Calculate the hyperbolic cosine of this float.
`float`	`erf()` Calculate the error function of this float.
`float`	`exp()` Raise `e` to the power of this float.
`integer`	`exponent()` Return the exponent of this float.
`integer`	`floor()` Return the largest possible integer that is less than or equal to this float.
`float`	`fmod(float y)` Calculate x mod y where `x` is this float.
`string`	`formatFixed(integer dp)` Render this float to a string with a fixed number of float places.
`string`	`formatScientific(integer sf)` Render this float in scientific notation with the given number of significant figures.
`float`	`fractionalPart()` Return the fractional component of this float.
`float`	`gammal()` Calculate the logarithm of the gamma function.
`integer`	`hash()` Get an integer hash representation of the underlying object.
`integer`	`ilogb()` Calculate the integer binary logarithm of this float.
`integer`	`integralPart()` Return the integer component of this float.
`boolean`	`isFinite()` Check if this float is finite.
`boolean`	`isInfinite()` Check if this float is infinite.
`boolean`	`isNaN()` Check if this float is a Not-a-Number value.
`float`	`ln()` Calculate the natural logarithm of this float.
`float`	`log10()` Calculate the logarithm of this float in base 10.
`float`	`mantissa()` Return the mantissa of this float.
`float`	`static` `max(float a, float b)` Return the larger of two floats.
`float`	`static` `min(float a, float b)` Return the smaller of two floats.
`float`	`nextAfter(float towards)` Return the next distinct float number after this float in the direction of the argument.
`float`	`static` `parse(string s)` Parse a string to a float.
`float`	`pow(float y)` Calculate this float raised to the power of another float.
`float`	`rand()` Generate a random value between 0.0 and this float.
`integer`	`round()` Return the nearest integer to this float.
`float`	`scalbn(integer n)` Scale this float by a power of 10.
`float`	`sin()` Calculate the sine of this float in radians.
`float`	`sinh()` Computes the hyperbolic sine of this float in radians.
`float`	`sqrt()` Calculate the square-root of this float.
`float`	`tan()` Computes the tangent of this float in radians.
`float`	`tanh()` Computes the hyperbolic tangent of this float in radians.
`decimal`	`toDecimal()` Convert this float to a decimal.
`string`	`toString()` Convert this float to a string.

Constant detail

E

            float E

Euler's constant, e (2.71828...).

EPSILON

            float EPSILON

The smallest x where (1+x) > 1.

INFINITY

            float INFINITY

IEEE 754 positive infinity.

To get negative infinity write: -float.INFINITY.

MAX

            float MAX

The largest positive float number (~2*10³⁰⁸).

MIN

            float MIN

The smallest positive float number (~2*10^-308).

NAN

            float NAN

IEEE 754 Not-a-Number.

Do not ever be tempted use this value in comparisons, sorting or as a key in a dictionary. For example, if myfloat = float.NAN will return false even if myfloat is a NaN; instead, use isNaN() to detect whether a float has a NaN value.

See Also:: float#isNaN() - Use this action (not a "=" comparison) to detect whether a float is a NaN value.

PI

            float PI

The ratio of a circle's circumference to its diameter (3.14159265...).

Action detail

abs

            float abs()

The absolute value of this float.

Returns:: |x| where x is this float.

acos

            float acos()

Calculate the inverse cosine of this number in radians.

x.acos() returns NaN if |x| > 1.

Returns:: Returns acos(x) where x is this float.

acosh

            float acosh()

Calculate the inverse hyperbolic cosine of this number.

x.acosh() returns NaN if x < 1.

Returns:: Returns acosh(x) where x is this float.

asin

            float asin()

Calculate the inverse sine of this number in radians.

x.asin() returns NaN if |x| > 1.

Returns:: Returns asin(x) where x is this float.

asinh

            float asinh()

Calculate the inverse hyperbolic sine of this number.

x.asin() is defined for all values of x.

Returns:: Returns asin(x) where x is this float.

atan

            float atan()

Calculate the inverse tangent of this number.

x.atan() is defined for all values of x.

Returns:: Returns atan(x) where x is this float.

atan2

            float atan2(float d)

Calculate the two-parameter inverse tangent of this number and the argument.

(±0).atan2(x) returns ±0 if x >= 0
(±0).atan2(x) returns ±π if x < 0
x.atan2(0) returns ±π/2
(±Infinity).atan2(+Infinity) returns ±π/4
(±Infinity).atan2(-Infinity) returns ±3π/4
(±Infinity).atan2(x) returns ±π/2
(x).atan2(+Infinity) returns ±0
(x).atan2(-Infinity) returns ±π

Parameters:: d - The second parameter to the tangent function.

Returns:: The two-parameter inverse tangent of this number and d.

atanh

            float atanh()

Calculate the inverse hyperbolic tangent of this number.

x.atanh() returns NaN if |x| > 1
x.atanh() returns ±Infinity if x = ±1

Returns:: Returns atanh(x) where x is this float.

bitEquals

            boolean bitEquals(float other)

Bitwise comparison of two floats.

This method will return true if both this number and other are NaN, but false when comparing +0 with -0.

Parameters:: other - The other float to compare to this one.

Returns:: True if this and other are bitwise-identical, false otherwise.

canParse

            boolean static canParse(string s)

Check if the string argument can be successfully parsed as a float.

Parameters:: s - The string to test for parseability.

Returns:: True if the string could be parsed as a float, false otherwise.

See Also:: float#parse() - See the parse method for how floats are parsed.

cbrt

            float cbrt()

Return the cube root of this float.

Returns:: ³√x where x is this float.

ceil

            integer ceil()

Return the smallest possible integer that is greater than or equal to this float.

(Infinity).ceil() returns integer.MAX
(-Infinity).ceil() returns integer.MIN

Returns:: The integer part of this float (rounding up).

Throws:: Throws ArithmeticException if this float is NaN.

cos

            float cos()

Calculate the cosine of this float in radians.

(±Infinity).cos() returns NaN.

Returns:: Returns cos(x) where x is this float.

cosh

            float cosh()

Calculate the hyperbolic cosine of this float.

(±Infinity).cosh() returns Infinity.

Returns:: Returns cosh(x) where x is this float.

erf

            float erf()

Calculate the error function of this float.

erf(x) returns (2 / √π) ∫₀^x e^-t*tdt

Returns:: The error function of this float.

exp

            float exp()

Raise e to the power of this float.

(Infinity).exp() returns Infinity
(-Infinity).exp() returns 0

Returns:: Returns e^x where x is this float.

exponent

            integer exponent()

Return the exponent of this float.

If x = M*2^E where 0.5 <= |M| < 1.0 then x.exponent() returns E.

(0.0).exponent() returns 0.

Returns:: The exponent in base 2 of this float.

Throws:: Throws ArithmeticException if this float is ±Infinity or NaN.

floor

            integer floor()

Return the largest possible integer that is less than or equal to this float.

(Infinity).floor() returns integer.MAX
(-Infinity).floor() returns integer.MIN

Returns:: The integer part of this float (rounding down).

Throws:: Throws ArithmeticException if this float is NaN.

fmod

            float fmod(float y)

Calculate x mod y where x is this float.

Parameters:: y - The base for this modulus.

Returns:: The modulus of this float in base y.

formatFixed

            string formatFixed(integer dp)

Render this float to a string with a fixed number of float places.

Parameters:: dp - The number of float places.

Returns:: The string representation of this float to dp float places.

formatScientific

            string formatScientific(integer sf)

Render this float in scientific notation with the given number of significant figures.

Parameters:: sf - The number of significant figures.

Returns:: The scientific notation string of this float with sf significant figures.

fractionalPart

            float fractionalPart()

Return the fractional component of this float.

Returns:: The fractional component of this float.

gammal

            float gammal()

Calculate the logarithm of the gamma function.

Returns:: Returns ln Γ(x) where x is this float.

hash

            integer hash()

Get an integer hash representation of the underlying object.

This function will return an integer evenly distributed over the whole range suitable for partitioning or indexing of that structure. Multiple different object can resolve to the same hash value.

Returns:: An integer respresentation of the underlying object.

ilogb

            integer ilogb()

Calculate the integer binary logarithm of this float.

Returns:: The integer that is the binary exponent of this float.

Throws:: Throws ArithmeticException if this float is NaN.

integralPart

            integer integralPart()

Return the integer component of this float.

Returns:: This float rounded towards 0.

Throws:: Throws ArithmeticException if this float is NaN.

isFinite

            boolean isFinite()

Check if this float is finite.

Returns:: False if this float is ±Infinity or NaN, true otherwise.

isInfinite

            boolean isInfinite()

Check if this float is infinite.

Note: This function is not the complement of isFinite.

Returns:: True if this float is ±Infinity, false otherwise.

isNaN

            boolean isNaN()

Check if this float is a Not-a-Number value.

Returns:: True if this float has a NaN value, false otherwise.

ln

            float ln()

Calculate the natural logarithm of this float.

(0).ln() returns -Infinity
(x).ln() returns NaN if x < 0

Returns:: Returns log_e(x) where x is this float.

log10

            float log10()

Calculate the logarithm of this float in base 10.

(0).log10() returns -Infinity
(x).log10() returns NaN if x < 0

Returns:: Returns log₁₀(x) where x is this float.

mantissa

            float mantissa()

Return the mantissa of this float.

If x = M*10^E where 0.1 >= |M| < 1.0 then x.mantissa() returns M.

(0.0).mantissa() returns 0.

Returns:: The mantissa of this float.

Throws:: Throws ArithmeticException if this float is ±Infinity or NaN.

max

            float static max(float a, float b)

Return the larger of two floats.

Parameters:: a - The first number to compare.; b - The second number to compare.

Returns:: The larger of a and b.

min

            float static min(float a, float b)

Return the smaller of two floats.

Parameters:: a - The first number to compare.; b - The second number to compare.

Returns:: The smaller of a and b.

nextAfter

            float nextAfter(float towards)

Return the next distinct float number after this float in the direction of the argument.

x.nextAfter(x) returns x
(0.0).nextAfter(±x) returns ±float.MIN
Infinity.nextAfter(x) returns float.MAX
-Infinity.nextAfter(x) returns -float.MAX
float.MAX.nextAfter(Infinity) returns Infinity
(-float.MAX).nextAfter(-Infinity) returns -Infinity

Parameters:: towards - The number towards which to increment this float.

Returns:: The next representable float from this float in the direction of towards.

Since:: 10.3.1

parse

            float static parse(string s)

Parse a string to a float.

The string must be in a numerical format and may or may not include decimal point. It may also be written using scientific notation, for example, 3.1e15.

Parameters:: s - The string to parse.

Returns:: The float corresponding to the string.

Throws:: Throws ParseException if the string cannot be parsed as a float.

See Also:: string#toFloat() - string.toFloat will convert a float in the presence of trailing characters.

pow

            float pow(float y)

Calculate this float raised to the power of another float.

In the normal case, x.pow(y) yields exactly what you might expect, so 3.0.pow(3.0) = 27.0 and 2.0.pow(0.5) = 1.41421. But there is a very large number of special cases.

x.pow(0.0) returns 1
x.pow(1.0) returns x
NaN.pow(0.0) returns 1
x.pow(+Infinity) returns +Infinity if |x| > 1
x.pow(-Infinity) returns +0 if |x| > 1
x.pow(+Infinity) returns +0 if |x| < 1
x.pow(-Infinity) returns +Infinity if |x| < 1
(±1.0).pow(±Infinity) returns NaN
(±0.0).pow(x) returns +0 if x > 0
(±0.0).pow(x) returns +Infinity if x < 0
(-0.0).pow(x) returns -( +0.pow(x) ) if x is odd
+Infinity.pow(x) returns +Infinity if x > 0
+Infinity.pow(x) returns +0 if x < 0
-Infinity.pow(x) returns -0^-x
(-x).pow(y) returns (-1)^y*(+x^y) if y is an integer
(-x).pow(y) returns NaN if y is not an integer

Parameters:: y - The exponent to raise this float to.

Returns:: Returns x^y where x is this float.

rand

            float rand()

Generate a random value between 0.0 and this float.

Returns a random value from 0.0 up to (but not including) the value the method was invoked on. If the value was negative, then the random value will be from the value (but not including it) up to 0.0. (0.0).rand() always returns 0.

Caution: This random number generator is verified not to be cryptographically strong. Therefore, it should not be used for purposes where a strong random number is required.

Returns:: A random float between 0.0 (inclusive) and this float (exclusive).

round

            integer round()

Return the nearest integer to this float.

Uses banker's rounding, which means round-to-even, to break ties. For example, it rounds both 3.5 and 4.5 to 4.

(Infinity).round() returns integer.MAX
(-Infinity).round() returns integer.MIN

Returns:: The integer part of this float (round to even).

Throws:: Throws ArithmeticException if this float is NaN.

scalbn

            float scalbn(integer n)

Scale this float by a power of 10.

Parameters:: n - The power of 10 to scale by.

Returns:: Returns x*10ⁿ where x is this float.

sin

            float sin()

Calculate the sine of this float in radians.

(±Infinity).sin() returns NaN.

Returns:: Returns sin(x) where x is this float.

sinh

            float sinh()

Computes the hyperbolic sine of this float in radians.

(±Infinity or ±0).sinh() returns the unmodified value.

Returns:: Returns sinh(x) where x is this float.

sqrt

            float sqrt()

Calculate the square-root of this float.

(x).sqrt() returns NaN if x < 0
(+Infinity).sqrt() returns +Infinity

Returns:: √x where x is this float.

tan

            float tan()

Computes the tangent of this float in radians.

(±Infinity).tan() returns NaN.

Returns:: Returns tan(x) where x is this float.

tanh

            float tanh()

Computes the hyperbolic tangent of this float in radians.

(±Infinity).tanh() returns ±1.

Returns:: Returns tanh(x) where x is this float.

toDecimal

            decimal toDecimal()

Convert this float to a decimal.

Returns:: The nearest representable decimal to this float.

toString

            string toString()

Convert this float to a string.

NaN will be rendered as "NaN", infinities will be rendered as "Infinity" or "-Infinity". Whole numbers will be rendered without a decimal point. Numbers above 10⁶ will use scientific notation.

Returns:: A string representation of this float.

See Also:: float#formatFixed() - Use formatFixed for a fixed-float-place conversion to string.; float#formatScientific() - Use formatScientific to always get a scientific-notation conversion to string.