decimal

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 decimal

64-bit signed decimal floating point number.

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

When perfect accuracy of base-10 numbers 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 decimal type are a finite-precision approximation of the mathematical real numbers, encoded as 64-bit decimal floating-point values consisting of sign, significand, and exponent, as defined by the IEEE Standard for Floating-Point Arithmetic, ANSI/IEEE Standard 754-2008 (IEEE, New York). Values of the decimal type have a precision of exactly 16 decimal digits.

The largest positive decimal floating point value that can be stored in a variable of type decimal is 9.999999999999999 * 10³⁸⁴ and the smallest non-zero positive value that can be stored is 10^-398.

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 decimal values are of finite precision, they cannot accurately represent all values, for example, recurring decimals or irrational numbers. However, decimals have the advantage over floats in that provided a decimal literal does not exceed the 16-place precision, it will be represented exactly within the correlator.

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

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

Decimals 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 decimal identity
`-`	Unary decimal additive inverse
`+`	Decimal addition
`-`	Decimal subtraction
`*`	Decimal multiplication
`/`	Decimal 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
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 decimal, see the documentation of each method.

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

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

Constant detail

E

            decimal E

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

EPSILON

            decimal EPSILON

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

INFINITY

            decimal INFINITY

IEEE 754 positive infinity.

To get negative infinity, write -decimal.INFINITY.

MAX

            decimal MAX

The largest positive decimal number (~10³⁸⁵).

MIN

            decimal MIN

The smallest positive decimal number (10^-398).

NAN

            decimal NAN

IEEE 754 Not-a-Number.

PI

            decimal PI

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

Action detail

abs

            decimal abs()

The absolute value of this decimal.

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

acos

            decimal 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 decimal.

acosh

            decimal acosh()

Calculate the inverse hyperbolic cosine of this number.

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

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

asin

            decimal 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 decimal.

asinh

            decimal 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 decimal.

atan

            decimal 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 decimal.

atan2

            decimal atan2(decimal 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

            decimal 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 decimal.

bitEquals

            boolean bitEquals(decimal other)

Bitwise comparison of two decimals.

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

Parameters:: other - The other decimal 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 decimal.

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

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

See Also:: decimal#parse() - See the parse method for how decimals are parsed.

cbrt

            decimal cbrt()

Return the cube root of this decimal.

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

ceil

            integer ceil()

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

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

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

Throws:: Throws ArithmeticException if this decimal is NaN.

cos

            decimal cos()

Calculate the cosine of this decimal in radians.

(±Infinity).cos() returns NaN.

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

cosh

            decimal cosh()

Calculate the hyperbolic cosine of this decimal.

(±Infinity).cosh() returns Infinity.

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

erf

            decimal erf()

Calculate the error function of this decimal.

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

Returns:: The error function of this decimal.

exp

            decimal exp()

Raise e to the power of this decimal.

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

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

exponent

            integer exponent()

Return the exponent of this decimal.

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

(0.0).exponent() returns 0.

Returns:: The exponent of this decimal.

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

floor

            integer floor()

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

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

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

Throws:: Throws ArithmeticException if this decimal is NaN.

fmod

            decimal fmod(decimal y)

Calculate x mod y where x is this decimal.

Parameters:: y - The base for this modulus.

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

formatFixed

            string formatFixed(integer dp)

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

Parameters:: dp - The number of decimal places.

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

formatScientific

            string formatScientific(integer sf)

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

Parameters:: sf - The number of significant figures.

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

fractionalPart

            decimal fractionalPart()

Return the fractional component of this decimal.

Returns:: The fractional component of this decimal.

gammal

            decimal gammal()

Calculate the logarithm of the gamma function.

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

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 decimal.

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

Throws:: Throws ArithmeticException if this decimal is NaN.

integralPart

            integer integralPart()

Return the integer component of this decimal.

Returns:: This decimal rounded towards 0.

Throws:: Throws ArithmeticException if this decimal is NaN.

isFinite

            boolean isFinite()

Check if this decimal is finite.

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

isInfinite

            boolean isInfinite()

Check if this decimal is infinite.

Note: This function is not the complement of isFinite.

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

isNaN

            boolean isNaN()

Check if this decimal is Not-a-Number.

Returns:: True if this decimal is NaN, false otherwise.

ln

            decimal ln()

Calculate the natural logarithm of this decimal.

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

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

log10

            decimal log10()

Calculate the logarithm of this decimal in base 10.

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

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

mantissa

            decimal mantissa()

Return the mantissa of this decimal.

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 decimal.

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

max

            decimal static max(decimal a, decimal b)

Return the larger of two decimals.

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

Returns:: The larger of a and b.

min

            decimal static min(decimal a, decimal b)

Return the smaller of two decimals.

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

Returns:: The smaller of a and b.

nextAfter

            decimal nextAfter(decimal towards)

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

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

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

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

Since:: 10.3.1

parse

            decimal static parse(string s)

Parse a string to a decimal.

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

Parameters:: s

Returns:: The decimal corresponding to the string.

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

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

pow

            decimal pow(decimal y)

Calculate this decimal raised to the power of another decimal.

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 decimal to.

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

rand

            decimal rand()

Generate a random value between 0.0 and this decimal.

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 decimal between 0.0 (inclusive) and this decimal (exclusive).

round

            integer round()

Return the nearest integer to this decimal.

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 decimal (round to even).

Throws:: Throws ArithmeticException if this decimal is NaN.

scalbn

            decimal scalbn(integer n)

Scale this decimal by a power of 10.

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

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

sin

            decimal sin()

Calculate the sine of this decimal in radians.

(±Infinity).sin() returns NaN.

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

sinh

            decimal sinh()

Computes the hyperbolic sine of this decimal in radians.

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

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

sqrt

            decimal sqrt()

Calculate the square-root of this decimal.

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

Returns:: √x where x is this decimal.

tan

            decimal tan()

Computes the tangent of this decimal in radians.

(±Infinity).tan() returns NaN.

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

tanh

            decimal tanh()

Computes the hyperbolic tangent of this decimal in radians.

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

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

toFloat

            float toFloat()

Convert this decimal to a float.

Returns:: The nearest representable float to this decimal.

toString

            string toString()

Convert this decimal 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.

The d suffix is not included.

Returns:: A string representation of this decimal.

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