8.2 Mathematical Functions

8.2.1 ABS()

Available inDSQL, PSQL

Possible name conflictYES → Read details

Syntax 

ABS (number)

Table 8.2.1.1 ABS Function Parameter
ParameterDescription

number

An expression of a numeric type

Result typeNumerical

DescriptionReturns the absolute value of the argument.

8.2.2 ACOS()

Available inDSQL, PSQL

Possible name conflictYES → Read details

Syntax 

ACOS (number)

Table 8.2.2.1 ACOS Function Parameter
ParameterDescription

number

An expression of a numeric type within the range [-1; 1]

Result typeDOUBLE PRECISION

DescriptionReturns the arc cosine of the argument.

  • The result is an angle in the range [0, pi].

  • If the argument is outside the range [-1, 1], NaN is returned.

8.2.3 ASIN()

Available inDSQL, PSQL

Possible name conflictYES → Read details

Syntax 

ASIN (number)

Table 8.2.3.1 ASIN Function Parameter
ParameterDescription

number

An expression of a numeric type within the range [-1; 1]

Result typeDOUBLE PRECISION

DescriptionReturns the arc sine of the argument.

  • The result is an angle in the range [-pi/2, pi/2].

  • If the argument is outside the range [-1, 1], NaN is returned.

8.2.4 ATAN()

Available inDSQL, PSQL

Possible name conflictYES → Read details

Syntax 

ATAN (number)

Table 8.2.4.1 ATAN Function Parameter
ParameterDescription

number

An expression of a numeric type

Result typeDOUBLE PRECISION

DescriptionThe function ATAN returns the arc tangent of the argument. The result is an angle in the range ←pi/2, pi/2>.

8.2.5 ATAN2()

Available inDSQL, PSQL

Possible name conflictYES → Read details

Syntax 

ATAN2 (y, x)

Table 8.2.5.1 ATAN2 Function Parameters
ParameterDescription

y

An expression of a numeric type

x

An expression of a numeric type

Result typeDOUBLE PRECISION

DescriptionReturns the angle whose sine-to-cosine ratio is given by the two arguments, and whose sine and cosine signs correspond to the signs of the arguments. This allows results across the entire circle, including the angles -pi/2 and pi/2.

  • The result is an angle in the range [-pi, pi].

  • If x is negative, the result is pi if y is 0, and -pi if y is -0.

  • If both y and x are 0, the result is meaningless. Starting with Firebird 3, an error will be raised if both arguments are 0. At v.2.5.4, it is still not fixed in lower versions. For more details, visit Tracker ticket CORE-3201.

Notes

  • A fully equivalent description of this function is the following: ATAN2(y, x) is the angle between the positive X-axis and the line from the origin to the point (x, y). This also makes it obvious that ATAN2(0, 0) is undefined.

  • If x is greater than 0, ATAN2(y, x) is the same as ATAN(y/x).

  • If both sine and cosine of the angle are already known, ATAN2(sin, cos) gives the angle.

8.2.6 CEIL(), CEILING()

Available inDSQL, PSQL

Possible name conflictYES → Read details (Affects CEILING only)

Syntax 

CEIL[ING] (number)

Table 8.2.6.1 CEIL[ING] Function Parameters
ParameterDescription

number

An expression of a numeric type

Result typeBIGINT for exact numeric number, or DOUBLE PRECISION for floating point number

DescriptionReturns the smallest whole number greater than or equal to the argument.

See alsoSection 8.2.11, FLOOR()

8.2.7 COS()

Available inDSQL, PSQL

Possible name conflictYES → Read details

Syntax 

COS (angle)

Table 8.2.7.1 COS Function Parameter
ParameterDescription

angle

An angle in radians

Result typeDOUBLE PRECISION

DescriptionReturns an angle’s cosine. The argument must be given in radians.

  • Any non-NULL result is — obviously — in the range [-1, 1].

8.2.8 COSH()

Available inDSQL, PSQL

Possible name conflictYES → Read details

Syntax 

COSH (number)

Table 8.2.8.1 COSH Function Parameter
ParameterDescription

number

A number of a numeric type

Result typeDOUBLE PRECISION

DescriptionReturns the hyperbolic cosine of the argument.

  • Any non-NULL result is in the range [1, INF].

8.2.9 COT()

Available inDSQL, PSQL

Possible name conflictYES → Read details

Syntax 

COT (angle)

Table 8.2.9.1 COT Function Parameter
ParameterDescription

angle

An angle in radians

Result typeDOUBLE PRECISION

DescriptionReturns an angle’s cotangent. The argument must be given in radians.

8.2.10 EXP()

Available inDSQL, PSQL

Syntax 

EXP (number)

Table 8.2.10.1 EXP Function Parameter
ParameterDescription

number

A number of a numeric type

Result typeDOUBLE PRECISION

DescriptionReturns the natural exponential, enumber

See alsoSection 8.2.12, LN()

8.2.11 FLOOR()

Available inDSQL, PSQL

Possible name conflictYES → Read details

Syntax 

FLOOR (number)

Table 8.2.11.1 FLOOR Function Parameter
ParameterDescription

number

An expression of a numeric type

Result typeBIGINT for exact numeric number, or DOUBLE PRECISION for floating point number

DescriptionReturns the largest whole number smaller than or equal to the argument.

See alsoSection 8.2.6, CEIL(), CEILING()

8.2.12 LN()

Available inDSQL, PSQL

Possible name conflictYES → Read details

Syntax 

LN (number)

Table 8.2.12.1 LN Function Parameter
ParameterDescription

number

An expression of a numeric type

Result typeDOUBLE PRECISION

DescriptionReturns the natural logarithm of the argument.

  • An error is raised if the argument is negative or 0.

See alsoSection 8.2.10, EXP()

8.2.13 LOG()

Available inDSQL, PSQL

Possible name conflictYES → Read details

Syntax 

LOG (x, y)

Table 8.2.13.1 LOG Function Parameters
ParameterDescription

x

Base. An expression of a numeric type

y

An expression of a numeric type

Result typeDOUBLE PRECISION

DescriptionReturns the x-based logarithm of y.

  • If either argument is 0 or below, an error is raised. (Before 2.5, this would result in NaN, ±INF or 0, depending on the exact values of the arguments.)

  • If both arguments are 1, NaN is returned.

  • If x = 1 and y < 1, -INF is returned.

  • If x = 1 and y > 1, INF is returned.

8.2.14 LOG10()

Available inDSQL, PSQL

Changed in2.5

Possible name conflictYES → Read details

Syntax 

LOG10 (number)

Table 8.2.14.1 LOG10 Function Parameter
ParameterDescription

number

An expression of a numeric type

Result typeDOUBLE PRECISION

DescriptionReturns the 10-based logarithm of the argument.

  • An error is raised if the argument is negative or 0. (In versions prior to 2.5, such values would result in NaN and -INF, respectively.)

8.2.15 MOD()

Available inDSQL, PSQL

Possible name conflictYES → Read details

Syntax 

MOD (a, b)

Table 8.2.15.1 MOD Function Parameters
ParameterDescription

a

An expression of a numeric type

b

An expression of a numeric type

Result typeSMALLINT, INTEGER or BIGINT depending on the type of a. If a is a floating point type, the result is a BIGINT.

DescriptionReturns the remainder of an integer division.

  • Non-integer arguments are rounded before the division takes place. So, mod(7.5, 2.5) gives 2 (mod(8, 3)), not 0.

8.2.16 PI()

Available inDSQL, PSQL

Possible name conflictYES → Read details

Syntax 

PI ()

Result typeDOUBLE PRECISION

DescriptionReturns an approximation of the value of pi.

8.2.17 POWER()

Available inDSQL, PSQL

Possible name conflictYES → Read details

Syntax 

POWER (x, y)

Table 8.2.17.1 POWER Function Parameters
ParameterDescription

x

An expression of a numeric type

y

An expression of a numeric type

Result typeDOUBLE PRECISION

DescriptionReturns x to the power of y (xy).

8.2.18 RAND()

Available inDSQL, PSQL

Possible name conflictYES → Read details

Syntax 

RAND ()

Result typeDOUBLE PRECISION

DescriptionReturns a random number between 0 and 1.

8.2.19 ROUND()

Available inDSQL, PSQL

Possible name conflictYES → Read details

Syntax 

ROUND (number [, scale])

Table 8.2.19.1 ROUND Function Parameters
ParameterDescription

number

An expression of a numeric type

scale

An integer specifying the number of decimal places toward which rounding is to be performed, e.g.:

  •  2 for rounding to the nearest multiple of 0.01

  •  1 for rounding to the nearest multiple of 0.1

  •  0 for rounding to the nearest whole number

  • -1 for rounding to the nearest multiple of 10

  • -2 for rounding to the nearest multiple of 100

Result typeINTEGER, (scaled) BIGINT or DOUBLE PRECISION

DescriptionRounds a number to the nearest integer. If the fractional part is exactly 0.5, rounding is upward for positive numbers and downward for negative numbers. With the optional scale argument, the number can be rounded to powers-of-ten multiples (tens, hundreds, tenths, hundredths, etc.) instead of just integers.

☝︎
Important

If you are used to the behaviour of the external function ROUND, please notice that the internal function always rounds halves away from zero, i.e. downward for negative numbers.

ExamplesIf the scale argument is present, the result usually has the same scale as the first argument:

ROUND(123.654, 1) -- returns 123.700 (not 123.7)
ROUND(8341.7, -3) -- returns 8000.0 (not 8000)
ROUND(45.1212, 0) -- returns 45.0000 (not 45)

Otherwise, the result scale is 0:

ROUND(45.1212) -- returns 45

8.2.20 SIGN()

Available inDSQL, PSQL

Possible name conflictYES → Read details

Syntax 

SIGN (number)

Table 8.2.20.1 SIGN Function Parameter
ParameterDescription

number

An expression of a numeric type

Result typeSMALLINT

DescriptionReturns the sign of the argument: -1, 0 or 1.

8.2.21 SIN()

Available inDSQL, PSQL

Possible name conflictYES → Read details

Syntax 

SIN (angle)

Table 8.2.21.1 SIN Function Parameter
ParameterDescription

angle

An angle, in radians

Result typeDOUBLE PRECISION

DescriptionReturns an angle’s sine. The argument must be given in radians.

  • Any non-NULL result is — obviously — in the range [-1, 1].

8.2.22 SINH()

Available inDSQL, PSQL

Possible name conflictYES → Read details

Syntax 

SINH (number)

Table 8.2.22.1 SINH Function Parameter
ParameterDescription

number

An expression of a numeric type

Result typeDOUBLE PRECISION

DescriptionReturns the hyperbolic sine of the argument.

8.2.23 SQRT()

Available inDSQL, PSQL

Possible name conflictYES → Read details

Syntax 

SQRT (number)

Table 8.2.23.1 SQRT Function Parameter
ParameterDescription

number

An expression of a numeric type

Result typeDOUBLE PRECISION

DescriptionReturns the square root of the argument.

  • If number is negative, an error is raised.

8.2.24 TAN()

Available inDSQL, PSQL

Possible name conflictYES → Read details

Syntax 

TAN (angle)

Table 8.2.24.1 TAN Function Parameter
ParameterDescription

angle

An angle, in radians

Result typeDOUBLE PRECISION

DescriptionReturns an angle’s tangent. The argument must be given in radians.

8.2.25 TANH()

Available inDSQL, PSQL

Possible name conflictYES → Read details

Syntax 

TANH (number)

Table 8.2.25.1 TANH Function Parameters
ParameterDescription

number

An expression of a numeric type

Result typeDOUBLE PRECISION

DescriptionReturns the hyperbolic tangent of the argument.

  • Due to rounding, any non-NULL result is in the range [-1, 1] (mathematically, it’s ←1, 1>).

8.2.26 TRUNC()

Available inDSQL, PSQL

Syntax 

TRUNC (number [, scale])

Table 8.2.26.1 TRUNC Function Parameters
ParameterDescription

number

An expression of a numeric type

scale

An integer specifying the number of decimal places toward which truncating is to be performed, e.g.:

  •  2 for truncating to the nearest multiple of 0.01

  •  1 for truncating to the nearest multiple of 0.1

  •  0 for truncating to the nearest whole number

  • -1 for truncating to the nearest multiple of 10

  • -2 for truncating to the nearest multiple of 100

Result typeINTEGER, (scaled) BIGINT or DOUBLE PRECISION

DescriptionReturns the integer part of a number. With the optional scale argument, the number can be truncated to powers-of-ten multiples (tens, hundreds, tenths, hundredths, etc.) instead of just integers.

Notes

  • If the scale argument is present, the result usually has the same scale as the first argument, e.g.

    • TRUNC(789.2225, 2) returns 789.2200 (not 789.22)

    • TRUNC(345.4, -2) returns 300.0 (not 300)

    • TRUNC(-163.41, 0) returns -163.00 (not -163)

  • Otherwise, the result scale is 0:

    • TRUNC(-163.41) returns -163

☝︎
Important

If you are used to the behaviour of the external function TRUNCATE, please notice that the internal function TRUNC always truncates toward zero, i.e. upward for negative numbers.