This page was generated
January  28,  2016
4:08  AM
XQuery & XSLT Built-In & Modules Function Reference

Built-In: Math

The math built-in functions.
Function Summary
math:acos Returns the arc cosine of x, in radians, in the range from 0 to pi (inclusive).
math:asin Returns the arc sine of x, in radians, in the range from -pi/2 to +pi/2 (inclusive).
math:atan Returns the arc tangent of x, in radians.
math:atan2 Returns the arc tangent of y/x, in radians, in the range from -pi/2 to +pi/2 (inclusive), using the signs of y and x to determine the apropriate quadrant.
math:ceil Returns the smallest integer greater than or equal to x.
math:correlation Returns the Pearson correlation coefficient of a data set.
math:cos Returns the cosine of x, in the range from -1 to +1 (inclusive).
math:cosh Returns the hyperbolic cosine of x.
math:cot Returns the cotangent of x.
math:covariance Returns the sample covariance of a data set.
math:covariance-p Returns the population covariance of a data set.
math:degrees Returns numeric expression converted from radians to degrees.
math:exp Returns e (approximately 2.71828182845905) to the xth power.
math:fabs Returns the absolute value of x.
math:floor Returns the largest integer less than or equal to x.
math:fmod Returns the remainder of x/y.
math:frexp Returns x broken up into mantissa and exponent, where x = mantissa*2^exponent.
math:ldexp Returns x*2^i.
math:linear-model Returns a linear model that fits the given data set.
math:linear-model-coeff Returns the coefficients of the linear model.
math:linear-model-intercept Returns the intercept of the linear model.
math:linear-model-rsquared Returns the R^2 value of the linear model.
math:log Returns the base-e logarithm of x.
math:log10 Returns the base-10 logarithm of x.
math:median Returns the median of a sequence of values.
math:mode Returns the mode of a sequence.
math:modf Returns x broken up into fraction and integer.
math:percent-rank Returns the rank of a value in a data set as a percentage of the data set.
math:percentile Returns a sequence of percentile(s) given a sequence of percentage(s).
math:pi Returns the value of pi.
math:pow Returns x^y.
math:radians Returns numeric expression converted from degrees to radians.
math:rank Returns the rank of a value in a data set.
math:sin Returns the sine of x, in the range from -1 to +1 (inclusive).
math:sinh Returns the hyperbolic sine of x.
math:sqrt Returns the square root of x.
math:stddev Returns the sample standard deviation of a sequence of values.
math:stddev-p Returns the standard deviation of a population.
math:tan Returns the tangent of x.
math:tanh Returns the hyperbolic tangent of x, in the range from -1 to +1 (inclusive).
math:trunc Returns the number truncated to a certain number of decimal places.
math:variance Returns the sample variance of a sequence of values.
math:variance-p Returns the population variance of a sequence of values.
Function Detail
math:acos(
$x as xs:double
)  as   xs:double
Summary:

Returns the arc cosine of x, in radians, in the range from 0 to pi (inclusive).

Parameters:
$x : The fraction to be evaluated. Must be in the range of -1 to +1 (inclusive).

Example:
  math:acos(.5)

  => 1.0471975511966

math:asin(
$x as xs:double
)  as   xs:double
Summary:

Returns the arc sine of x, in radians, in the range from -pi/2 to +pi/2 (inclusive).

Parameters:
$x : The fraction to be evaluated. Must be in the range of -1 to +1 (inclusive).

Example:
  math:asin(.5)

  => 0.523598775598299

math:atan(
$x as xs:double
)  as   xs:double
Summary:

Returns the arc tangent of x, in radians. in the range from -pi/2 to +pi/2 (inclusive).

Parameters:
$x : The floating point number to be evaluated.

Example:
  math:atan(3.14159)

  => 1.26262701154934

math:atan2(
$y as xs:double,
$x as xs:double
)  as   xs:double
Summary:

Returns the arc tangent of y/x, in radians, in the range from -pi/2 to +pi/2 (inclusive), using the signs of y and x to determine the apropriate quadrant.

Parameters:
$y : The floating point dividend.
$x : The floating point divisor.

Example:
  math:atan2(36.23, 5.234) 

  => 1.42732303452594 
  

math:ceil(
$x as xs:double
)  as   xs:double
Summary:

Returns the smallest integer greater than or equal to x.

Parameters:
$x : The floating point number to be evaluated.

Example:
  math:ceil(36.00001) 

  => 37

math:correlation(
$arg as json:array*
)  as   xs:double?
Summary:

Returns the Pearson correlation coefficient of a data set. The size of the input array should be 2. The function eliminates all pairs for which either the first element or the second element is empty. After the elimination, if the length of the input is less than 2, the function returns the empty sequence. After the elimination, if the standard deviation of the first column or the standard deviation of the second column is 0, the function returns the empty sequence.

Parameters:
$arg : The input data set. Each array should contain a pair of values.

Example:
  let $array :=
    for $i in (1 to 10)
    let $j := 2*$i
    return json:to-array(($i,$j))

  return math:correlation($array)

  => 1
Example:
  xquery version "1.0-ml";

  (:
     This query assumes range indexes with positions are
     configured in the database for both xval and yval. It
     generates some sample data and then performs the
     aggregation in a separate transaction.
  :)
  for $i in (1 to 10)
  let $j := 2*$i
  let $uri := concat($i, ".xml")
  return
    xdmp:document-insert($uri, {$i}{$j});

  cts:correlation(
    cts:element-reference(xs:QName("yval")),
    cts:element-reference(xs:QName("xval")))

  => 1

math:cos(
$x as xs:double
)  as   xs:double
Summary:

Returns the cosine of x, in the range from -1 to +1 (inclusive).

Parameters:
$x : The floating point number to be evaluated.

Example:
  math:cos(11) 

  => 0.00442569798805079

math:cosh(
$x as xs:double
)  as   xs:double
Summary:

Returns the hyperbolic cosine of x.

Parameters:
$x : The floating point number to be evaluated.

Example:
  math:cosh(11)

  => 29937.0708659498
  

math:cot(
$x as xs:double
)  as   xs:double
Summary:

Returns the cotangent of x.

Parameters:
$x : The floating point number to be evaluated.

Example:
 cot(19.5)

  => 1.3142239

math:covariance(
$arg as json:array*
)  as   xs:double?
Summary:

Returns the sample covariance of a data set. The size of the input array should be 2. The function eliminates all pairs for which either the first element or the second element is empty. After the elimination, if the length of the input is less than 2, the function returns the empty sequence.

Parameters:
$arg : The input data set. Each array should contain a pair of values.

Example:
  let $array :=
    for $i in (1 to 10)
    let $j := 2*$i
    return json:to-array(($i,$j))

  return math:covariance($array)

  => 18.3333333333333
Example:
  xquery version "1.0-ml";

  (:
     This query assumes range indexes with positions are
     configured in the database for both xval and yval. It
     generates some sample data and then performs the
     aggregation in a separate transaction.
  :)
  for $i in (1 to 10)
  let $j := 2*$i
  let $uri := concat($i, ".xml")
  return
    xdmp:document-insert($uri, {$i}{$j});

  cts:covariance(
    cts:element-reference(xs:QName("yval")),
    cts:element-reference(xs:QName("xval")))

  => 18.3333333333333

math:covariance-p(
$arg as json:array*
)  as   xs:double?
Summary:

Returns the population covariance of a data set. The size of the input array should be 2. The function eliminates all pairs for which either the first element or the second element is empty. After the elimination, if the length of the input is 0, the function returns the empty sequence.

Parameters:
$arg : The input data set. Each array should contain a pair of values.

Example:
  let $array :=
    for $i in (1 to 10)
    let $j := 2*$i
    return json:to-array(($i,$j))

  return math:covariance-p($array)

  => 16.5
Example:
  xquery version "1.0-ml";

  (:
     This query assumes range indexes with positions are
     configured in the database for both xval and yval. It
     generates some sample data and then performs the
     aggregation in a separate transaction.
  :)
  for $i in (1 to 10)
  let $j := 2*$i
  let $uri := concat($i, ".xml")
  return
    xdmp:document-insert($uri, {$i}{$j});

  cts:covariance-p(
    cts:element-reference(xs:QName("yval")),
    cts:element-reference(xs:QName("xval")))

  => 16.5

math:degrees(
$x as xs:double
)  as   xs:double
Summary:

Returns numeric expression converted from radians to degrees.

Parameters:
$x : An angle expressed in radians.

Example:
  degrees(pi/2)

  => 90

math:exp(
$x as xs:double
)  as   xs:double
Summary:

Returns e (approximately 2.71828182845905) to the xth power.

Parameters:
$x : The exponent to be evaluated.

Example:
  math:exp(.01) 

  => 1.01005016708417

math:fabs(
$x as xs:double
)  as   xs:double
Summary:

Returns the absolute value of x.

Parameters:
$x : The floating point number to be evaluated.

Example:
  math:fabs(4.013)

  => 4.013

math:floor(
$x as xs:double
)  as   xs:double
Summary:

Returns the largest integer less than or equal to x.

Parameters:
$x : The floating point number to be evaluated.

Example:
  math:floor(4.013)

  => 4

math:fmod(
$x as xs:double,
$x as xs:double
)  as   xs:double
Summary:

Returns the remainder of x/y.

Parameters:
$x : The floating point dividend.
$x : The floating point divisor.

Example:
  math:fmod(10, 3)

  => 1

math:frexp(
$x as xs:double
)  as   (xs:double,xs:integer)
Summary:

Returns x broken up into mantissa and exponent, where x = mantissa*2^exponent.

Parameters:
$x : The exponent to be evaluated.

Example:
  math:frexp(10) 

  => 0.625
     4

math:ldexp(
$y as xs:double,
$i as xs:integer
)  as   xs:double
Summary:

Returns x*2^i.

Parameters:
$y : The floating-point number to be multiplied.
$i : The exponent integer.

Example:
  math:ldexp(1.333, 10)

  => 1364.992

math:linear-model(
$arg as json:array*
)  as   math:linear-model?
Summary:

Returns a linear model that fits the given data set. The size of the input array should be 2, as currently only simple linear regression model is supported. The first element of the array should be the value of the dependent variable while the other element should be the value of the independent variable.

The function eliminates all pairs for which either the first element or the second element is empty. After the elimination, if the length of the input is less than 2, the function returns the empty sequence. After the elimination, if the standard deviation of the independent variable is 0, the function returns a linear model with intercept = the mean of the dependent variable, coefficients = NaN and r-squared = NaN. After the elimination, if the standard deviation of the dependent variable is 0, the function returns a linear model with r-squared = NaN.

For the version of this function that uses Range Indexes, see cts:linear-model.


Parameters:
$arg : The input data set. Each array should contain a pair of values.

Example:
let $array :=
    for $i in (1 to 10)
    let $j := 2*$i + 1
    return json:to-array(($j,$i))
return math:linear-model($array)
=>
math:linear-model(
  <math:linear-model intercept="1" coefficients="2" rsquared="1"
        xmlns:xs="http://www.w3.org/2001/XMLSchema" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:math="http://marklogic.com/xdmp/math"/>)
Example:
xquery version "1.0-ml";
  (:
     This query uses the cts version of this function.
     This query assumes range indexes of type unsignedLong
     with positions are configured in the database for both 
     xval and yval. It generates some sample data and then 
     performs the aggregation in a separate transaction.
  :)
for $i in (1 to 10)
let $j := 2*$i + 1
let $uri := concat($i, ".xml")
return
   xdmp:document-insert($uri, <a><xval>{$i}</xval><yval>{$j}</yval></a>);

cts:linear-model(
    (cts:element-reference(xs:QName("yval"), ("type=unsignedLong")),
    cts:element-reference(xs:QName("xval"), ("type=unsignedLong"))))
=>
math:linear-model(
  <math:linear-model intercept="1" coefficients="2" rsquared="1" 
        xmlns:xs="http://www.w3.org/2001/XMLSchema" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:math="http://marklogic.com/xdmp/math"/>)

math:linear-model-coeff(
$linear-model as math:linear-model
)  as   xs:double*
Summary:

Returns the coefficients of the linear model. Currently only simple linear regression model is supported so the return should contain only one coefficient (also called "slope").

Parameters:
$linear-model : A linear model.

Example:
  let $array :=
    for $i in (1 to 10)
    let $j := 2*$i + 1
    return json:to-array(($j,$i))
  let $lm := math:linear-model($array)
  return math:linear-model-coeff($lm)

  => 2

math:linear-model-intercept(
$linear-model as math:linear-model
)  as   xs:double
Summary:

Returns the intercept of the linear model.

Parameters:
$linear-model : A linear model.

Example:
  let $array :=
    for $i in (1 to 10)
    let $j := 2*$i + 1
    return json:to-array(($j,$i))
  let $lm := math:linear-model($array)
  return math:linear-model-intercept($lm)

  => 1

math:linear-model-rsquared(
$linear-model as math:linear-model
)  as   xs:double
Summary:

Returns the R^2 value of the linear model.

Parameters:
$linear-model : A linear model.

Example:
  let $array :=
    for $i in (1 to 10)
    let $j := 2*$i + 1
    return json:to-array(($j,$i))
  let $lm := math:linear-model($array)
  return math:linear-model-rsquared($lm)

  => 1

math:log(
$x as xs:double
)  as   xs:double
Summary:

Returns the base-e logarithm of x.

Parameters:
$x : The floating point number to be evaluated.

Example:
  math:log(1000))

  => 6.90775527898214

math:log10(
$x as xs:double
)  as   xs:double
Summary:

Returns the base-10 logarithm of x.

Parameters:
$x : The floating point number to be evaluated.

Example:
  math:log10(1000)) 

  => 3

math:median(
$arg as xs:double*
)  as   xs:double?
Summary:

Returns the median of a sequence of values. The function returns the empty sequence if the input is the empty sequence.

Parameters:
$arg : The sequence of values.

Example:
  math:median((2, 3, 1, 1.1, 2.2, 4))

  => 2.1

math:mode(
$arg as xs:anyAtomicType*,
[$options as xs:string*]
)  as   xs:anyAtomicType*
Summary:

Returns the mode of a sequence. The mode is the value that occurs most frequently in a data set. If no value occurs more than once in the data set, the function returns the empty sequence. If the input is the empty sequence, the function returns the empty sequence.

Note that a data set can have multiple “modes”. The order of multiple modes in the returned sequence is undefined.

Also note that values from a lexicon lookup are repeated cts:frequency times before calculating the mode.

The function can be used on numeric values, xs:yearMonthDuration, xs:dayTimeDuration, xs:string, xs:anyURI, xs:date, xs:dateTime, xs:time, and cts:point.


Parameters:
$arg : The sequence of values.
$options (optional): Options. The default is ().

Options include:

"collation=URI"
Applies only when $arg is of the xs:string type. If no specified, the default collation is used.
"coordinate-system=name"
Applies only when $arg is of the cts:point type. If no specified, the default coordinate system is used.

Example:
  math:mode((1,2,2,3,2,3,4,6,7,7,7))

  => 2 7

math:modf(
$x as xs:double
)  as   (xs:double,xs:double)
Summary:

Returns x broken up into fraction and integer. x = fraction+integer.

Parameters:
$x : The floating point number to be evaluated.

Example:
  math:modf(1.333)

  => 0.333
     1

math:percent-rank(
$arg as xs:anyAtomicType*,
$value as xs:anyAtomicType,
[$options as xs:string*]
)  as   xs:double?
Summary:

Returns the rank of a value in a data set as a percentage of the data set. If the given value is not equal to any item in the sequence, the function returns the empty sequence. See math:rank.

Parameters:
$arg : The sequence of values.
$value : The value to be "ranked".
$options (optional): Options. The default is ().

Options include:

"ascending"(default)
Rank the value as if the sequence was sorted in ascending order.
"descending"
Rank the value as if the sequence was sorted in descending order.
"collation=URI"
Applies only when $arg is of the xs:string type. If no specified, the default collation is used.
"coordinate-system=name"
Applies only when $arg is of the cts:point type. If no specified, the default coordinate system is used.

Example:
  math:percent-rank((1, 7, 5, 5, 10, 9),9)

  => 0.833333333333333

math:percentile(
$arg as xs:double*,
$p as xs:double*
)  as   xs:double*
Summary:

Returns a sequence of percentile(s) given a sequence of percentage(s). The function returns the empty sequence if either $arg or $p is the empty sequence.

Parameters:
$arg : The sequence of values to calculate the percentile(s) on.
$p : The sequence of percentage(s).

Example:
  math:percentile((2, 3, 1, 1.1, 2.2, 4),(0.25,0.75))

  => 1.05 3.5

math:pi(  ) as  xs:double
Summary:

Returns the value of pi.

Example:
  math:pi()

  => 3.14159265358979323946

math:pow(
$x as xs:double,
$y as xs:double
)  as   xs:double
Summary:

Returns x^y.

Parameters:
$x : The floating-point base number.
$y : The exponent to be applied to x.

Example:
  math:pow(2, 10)

  => 1024

math:radians(
$x as xs:double
)  as   xs:double
Summary:

Returns numeric expression converted from degrees to radians.

Parameters:
$x : An angle expressed in degrees.

Example:
  radians(90)

  => 1.5707963267949

math:rank(
$arg as xs:anyAtomicType*,
$arg as xs:anyAtomicType,
[$options as xs:string*]
)  as   xs:integer?
Summary:

Returns the rank of a value in a data set. Ranks are skipped in the event of ties. If the given value is not equal to any item in the sequence, the function returns the empty sequence. The function can be used on numeric values, xs:yearMonthDuration, xs:dayTimeDuration, xs:string, xs:anyURI, xs:date, xs:dateTime, xs:time, and cts:point.

Parameters:
$arg : The sequence of values.
$arg : The value to be "ranked".
$options (optional): Options. The default is ().

Options include:

"ascending"(default)
Rank the value as if the sequence was sorted in ascending order.
"descending"
Rank the value as if the sequence was sorted in descending order.
"collation=URI"
Applies only when $arg is of the xs:string type. If no specified, the default collation is used.
"coordinate-system=name"
Applies only when $arg is of the cts:point type. If no specified, the default coordinate system is used.

Example:
  math:rank((1, 7, 5, 5, 10, 9),9)

  => 5

math:sin(
$x as xs:double
)  as   xs:double
Summary:

Returns the sine of x, in the range from -1 to +1 (inclusive).

Parameters:
$x : The floating point number to be evaluated.

Example:
  math:sin(1.95)

  => 0.928959715003869

math:sinh(
$x as xs:double
)  as   xs:double
Summary:

Returns the hyperbolic sine of x.

Parameters:
$x : The floating point number to be evaluated.

Example:
  math:sinh(1.95) 

  => 3.44320675450139

math:sqrt(
$x as xs:double
)  as   xs:double
Summary:

Returns the square root of x.

Parameters:
$x : The floating point number to be evaluated.

Example:
  math:sqrt(4) 

  => 2

math:stddev(
$arg as xs:double*
)  as   xs:double?
Summary:

Returns the sample standard deviation of a sequence of values. The function returns the empty sequence if the length of the input sequence is less than 2.

Parameters:
$arg : The sequence of values.

Example:
  math:stddev((122, 100, 23))

  => 51.9839718887787

math:stddev-p(
$arg as xs:double*
)  as   xs:double?
Summary:

Returns the standard deviation of a population. The function returns the empty sequence if the input is the empty sequence.

Parameters:
$arg : The sequence of values.

Example:
  math:stddev-p((122, 100, 23))

  => 42.4447353102308

math:tan(
$x as xs:double
)  as   xs:double
Summary:

Returns the tangent of x.

Parameters:
$x : The floating point number to be evaluated.

Example:
  math:tan(19.5) 

  => 0.760905351982977

math:tanh(
$x as xs:double
)  as   xs:double
Summary:

Returns the hyperbolic tangent of x, in the range from -1 to +1 (inclusive).

Parameters:
$x : The floating point number to be evaluated.

Example:
  math:tanh(.95) 

  => 0.739783051274004

math:trunc(
$arg as numeric?,
$n as xs:integer
)  as   numeric?
Summary:

Returns the number truncated to a certain number of decimal places. If type of $arg is one of the four numeric types xs:float, xs:double, xs:decimal or xs:integer the type of the result is the same as the type of $arg. If the type of $arg is a type derived from one of the numeric types, the result is an instance of the base numeric type.

For xs:float and xs:double arguments, if the argument is positive infinity, then positive infinity is returned. If the argument is negative infinity, then negative infinity is returned. If the argument is positive zero, then positive zero is returned. If the argument is negative zero, then negative zero is returned.


Parameters:
$arg : A numeric value to truncate.
$n : The numbers of decimal places to truncate to. The default is 0. Negative values cause that many digits to the left of the decimal point to be truncated.

Example:
math:trunc(125.815)	returns 125
math:trunc(125.815, 0) returns 125
math:trunc(125.815, 1) returns 125.8
math:trunc(125.815, 2) returns 125.81
math:trunc(125.815, 3) returns 125.815
math:trunc(-125.815, 2) returns -125.81
math:trunc(125.815, -1) returns 120
math:trunc(125.815, -2) returns 100
math:trunc(125.815, -3) returns 0

math:variance(
$arg as xs:double*
)  as   xs:double?
Summary:

Returns the sample variance of a sequence of values. The function returns the empty sequence if the length of the input sequence is less than 2.

Parameters:
$arg : The sequence of values.

Example:
  math:variance((122, 100, 23))

  => 2702.33333333333

math:variance-p(
$arg as xs:double*
)  as   xs:double?
Summary:

Returns the population variance of a sequence of values. The function returns the empty sequence if the input is the empty sequence.

Parameters:
$arg : The sequence of values.

Example:
  math:variance-p((122, 100, 23))

  => 1801.55555555555