Document the builtin MarkLogic mod functions.

xquery version "1.0-ml" encoding "UTF-8";
(:~
 : MarkLogic math functions
 :
 : @see https://docs.marklogic.com/math
 :
 : This documentation includes material copied from or derived from the XPath and
 : XQuery Functions and Operators 3.1 specifications. Copyright © 2017 W3C®
 : (MIT, ERCIM, Keio, Beihang).
 :)
module namespace math = "http://marklogic.com/xdmp/math";

declare namespace a = "http://reecedunn.co.uk/xquery/annotations";
declare namespace o = "http://reecedunn.co.uk/xquery/options";

declare option o:requires "marklogic/5.0";

(:~
 : Returns an approximation to the mathematical constant π.
 :
 : This function returns the xs:double value whose lexical
 : representation is 3.14159265358979e0.
 :)
declare %a:since("marklogic", "6.0") %a:until("marklogic", "7.0", "math:pi#0") function math:PI() as xs:double external;
(:~
 : Returns the arc cosine of the argument.
 :
 : The result is the arc cosine of $arg, as defined in the IEEE
 : 754-2008 specification of the acos function applied to 64-bit binary
 : floating point values. The result is in the range zero to +π radians.
 :
 :
Notes

 :
 : If $arg is outside the domain of the function, that is the
 : absolute value is greater than one, or if an overflow or underflow occurs,
 : the dynamic error XDMP-DOMAIN is produced.
 :
 : If $arg is NaN, then the result is NaN.
 :
 : In other cases the result is an xs:double value representing an
 : angle θ in radians in the range 0 <= θ <= +π.
 :)
declare %a:since("marklogic", "5.0") function math:acos($arg as xs:double) as xs:double external;
(:~
 : Returns the arc sine of the argument.
 :
 : The result is the arc sine of $arg, as defined in the IEEE
 : 754-2008 specification of the asin function applied to 64-bit binary
 : floating point values. The result is in the range -π/2 to +π/2 radians.
 :
 :
Notes

 :
 : If $arg is outside the domain of the function, that is the
 : absolute value is greater than one, or if an overflow or underflow occurs,
 : the dynamic error XDMP-DOMAIN is produced.
 :
 : If $arg is positive or negative zero, or NaN, the result
 : is $arg.
 :
 : In other cases the result is an xs:double value representing an
 : angle θ in radians in the range -π/2 <= θ <= +π/2.
 :)
declare %a:since("marklogic", "5.0") function math:asin($arg as xs:double) as xs:double external;
(:~
 : Returns the arc tangent of the argument.
 :
 : The result is the arc tangent of $arg, as defined in the IEEE
 : 754-2008 specification of the atan function applied to 64-bit binary floating
 : point values. The result is in the range -π/2 to +π/2 radians.
 :
 :
Notes

 :
 : If $arg is positive or negative infinity, the result is
 : positive or negative π/2.
 :
 : If $arg is positive or negative zero, the result is
 : $arg.
 :
 : If $arg is NaN, then the result is NaN.
 :
 : In other cases the result is an xs:double value representing an
 : angle θ in radians in the range -π/2 <= θ <= +π/2.
 :)
declare %a:since("marklogic", "5.0") function math:atan($arg as xs:double) as xs:double external;
(:~
 : Returns the angle in radians subtended at the origin by the point on a plane
 : with coordinates (x, y) and the positive x-axis.
 :
 : The result is the value of atan2(y, x) as defined in the IEEE
 : 754-2008 specification of the atan2 function applied to 64-bit
 : binary floating point values. The result is in the range -π to +π radians.
 :
 :
Notes

 :
 : If either argument is NaN then the result is NaN.
 :
 : If $y is positive or negative, and $x is positive
 : and finite, then (subject to rules for overflow, underflow and approximation)
 : the value of math:atan2($y, $x) is math:atan($y div $x).
 :
 : If $y is positive and $x is negative and finite,
 : then (subject to the same caveats) the value of math:atan2($y, $x)
 : is math:atan($y div $x) + math:pi().
 :
 : If $y is negative and $x is negative and finite,
 : then (subject to the same caveats) the value of math:atan2($y, $x)
 : is math:atan($y div $x) - math:pi().
 :)
declare %a:since("marklogic", "5.0") function math:atan2($y as xs:double, $x as xs:double) as xs:double external;
(:~
 : Rounds $arg upwards to a whole number.
 :
 : The function returns the smallest (closest to negative infinity) number with
 : no fractional part that is not less than the value of $arg.
 :
 : If the argument is positive zero, then positive zero is returned. If the
 : argument is negative zero, then negative zero is returned. If the argument
 : is less than zero and greater than -1, negative zero is returned.
 :)
declare %a:since("marklogic", "5.0") %a:see-also("xpath-functions", "1.0-20070123", "fn:ceil") function math:ceil($arg as xs:double) as xs:double external;
declare %a:since("marklogic", "6.0") function math:correlation($arg as json:array*) as xs:double? external;
(:~
 : Returns the cosine of the argument. The argument is an angle in radians.
 :
 : The result is the cosine of $θ (which is treated as an angle in
 : radians) as defined in the IEEE 754-2008 specification of the cos
 : function applied to 64-bit binary floating point values.
 :
 :
Notes

 :
 : If $θ is positive or negative zero, the result is $θ.
 :
 : If $θ is positive or negative infinity, the dynamic error
 : XDMP-DOMAIN is produced.
 :
 : If $θ is NaN, then the result is NaN.
 :
 : Otherwise the result is always in the range -1.0e0 to +1.0e0.
 :)
declare %a:since("marklogic", "5.0") function math:cos($θ as xs:double) as xs:double external;
declare %a:since("marklogic", "5.0") function math:cosh($x as xs:double) as xs:double external;
declare %a:since("marklogic", "6.0") function math:cot($x as xs:double) as xs:double external;
declare %a:since("marklogic", "6.0") function math:covariance($arg as json:array*) as xs:double? external;
declare %a:since("marklogic", "6.0") function math:covariance-p($arg as json:array*) as xs:double? external;
(:~
 : Returns the radians argument in degrees.
 :
 : This function converts $arg, specified in radians, to degrees.
 :
 :
Notes

 :
 : If $arg is NaN, positive or negative zero, or
 : positive or negative infinity, then the result is the same as the argument.
 :
 : Otherwise, the result is the argument divided by π/180.
 :
 :
Notes

 :
 : The result is not wrapped, so math:degrees(math:pi() * 4) is
 : 720.
 :)
declare %a:since("marklogic", "6.0") function math:degrees($arg as xs:double) as xs:double external;
(:~
 : Returns the value of ex.
 :
 : The result is the mathematical constant e raised to the power of
 : $arg, as defined in the IEEE 754-2008 specification of the
 : exp function applied to 64-bit binary floating point values.
 :)
declare %a:since("marklogic", "5.0") function math:exp($arg as xs:double) as xs:double external;
(:~
 : Returns the absolute value of $arg.
 :
 : If $arg is negative the function returns -$arg,
 : otherwise it returns $arg.
 :
 : If the argument is positive zero or negative zero, then positive zero is
 : returned. If the argument is positive or negative infinity, positive
 : infinity is returned.
 :)
declare %a:since("marklogic", "5.0") %a:see-also("xpath-functions", "1.0-20070123", "fn:abs") function math:fabs($x as xs:double) as xs:double external;
(:~
 : Rounds $arg downwards to a whole number.
 :
 : The return is the largest (closest to positive infinity) number with no
 : fractional part that is not greater than the value of $arg.
 :
 : If the argument is positive zero, then positive zero is returned. If the
 : argument is negative zero, then negative zero is returned.
 :)
declare %a:since("marklogic", "5.0") function math:floor($arg as xs:double) as xs:double external;
(:~
 : Returns the remainder of dividing x by y.
 :
 : This function returns the value of the expression $x mod $y.
 :
 : If $y is 0e0, the dynamic error XDMP-DOMAIN is
 : produced instead of the FOAR0001 division by zero dynamic error that
 : mod raises.
 :)
declare %a:since("marklogic", "5.0") function math:fmod($x as xs:double, $y as xs:double) as xs:double external;
declare %a:since("marklogic", "5.0") function math:frexp($x as xs:double) as (xs:double, xs:integer) external;
declare %a:since("marklogic", "5.0") function math:ldexp($y as xs:double, $i as xs:integer) as xs:double external;
declare %a:since("marklogic", "6.0") function math:linear-model($arg as json:array*) as math:linear-model? external;
declare %a:since("marklogic", "6.0") function math:linear-model-coeff($linear-model as math:linear-model) as xs:double* external;
declare %a:since("marklogic", "6.0") function math:linear-model-intercept($linear-model as math:linear-model) as xs:double external;
declare %a:since("marklogic", "6.0") function math:linear-model-rsquared($linear-model as math:linear-model) as xs:double external;
(:~
 : Returns the natural logarithm of the argument.
 :
 : The result is the natural logarithm of $arg, as defined in the
 : IEEE 754-2008 specification of the log function applied to
 : 64-bit binary floating point values.
 :)
declare %a:since("marklogic", "5.0") function math:log($arg as xs:double) as xs:double external;
(:~
 : Returns the base-ten logarithm of the argument.
 :
 : The result is the base-10 logarithm of $arg, as defined in the
 : IEEE 754-2008 specification of the log10 function applied to
 : 64-bit binary floating point values.
 :)
declare %a:since("marklogic", "5.0") function math:log10($arg as xs:double) as xs:double external;
declare %a:since("marklogic", "6.0") function math:median($arg as xs:double*) as xs:double? external;
declare %a:since("marklogic", "6.0") function math:mode($arg as xs:anyAtomicType*) as xs:anyAtomicType* external;
declare %a:since("marklogic", "6.0") function math:mode($arg as xs:anyAtomicType*, $options as xs:string*) as xs:anyAtomicType* external;
(:~
 : Returns the fraction and integral part of the argument.
 :
 : This function returns a two value sequence, where the first value is the
 : fraction of $arg and the second value is the integral part
 : of $arg.
 :
 : This function is equivalent to ($arg mod 1, math:floor($arg)).
 :)
declare %a:restrict-until("return", "marklogic", "8.0", "(xs:double,xs:double)")
        %a:restrict-since("return", "marklogic", "8.0", "(xs:double,xs:integer)")
        %a:since("marklogic", "5.0") function math:modf($arg as xs:double) as (xs:double,(xs:double|xs:integer)) external;
declare %a:since("marklogic", "6.0") function math:percent-rank($arg as xs:anyAtomicType*, $value as xs:anyAtomicType) as xs:double? external;
declare %a:since("marklogic", "6.0") function math:percent-rank($arg as xs:anyAtomicType*, $value as xs:anyAtomicType, $options as xs:string*) as xs:double? external;
declare %a:since("marklogic", "6.0") function math:percentile($arg as xs:double*, $p as xs:double*) as xs:double* external;
(:~
 : Returns an approximation to the mathematical constant π.
 :
 : This function was replaced by math:pi() in MarkLogic 7.0.
 :
 : This function returns the xs:double value whose lexical
 : representation is 3.14159265358979e0.
 :)
declare %a:since("marklogic", "7.0") function math:pi() as xs:double external;
(:~
 : Returns the value of xy.
 :
 : The result is the value of $x raised to the power of $y
 : as defined in the IEEE 754-2008 specification of the pow function
 : applied to two 64-bit binary floating point values.
 :)
declare %a:since("marklogic", "5.0") function math:pow($x as xs:double, $y as xs:double) as xs:double external;
(:~
 : Returns the degrees argument in radians.
 :
 : This function converts $arg, specified in degrees, to radians.
 :
 :
Notes

 :
 : If $arg is NaN, positive or negative zero, or
 : positive or negative infinity, then the result is the same as the argument.
 :
 : Otherwise, the result is the argument multiplied by π/180.
 :
 :
Notes

 :
 : The result is not wrapped, so math:radians(720) is
 : math:pi() * 4.
 :)
declare %a:since("marklogic", "6.0") function math:radians($x as xs:double) as xs:double external;
declare %a:since("marklogic", "6.0") function math:rank($arg1 as xs:anyAtomicType*, $arg2 as xs:anyAtomicType) as xs:integer? external;
declare %a:since("marklogic", "6.0") function math:rank($arg1 as xs:anyAtomicType*, $arg2 as xs:anyAtomicType, $options as xs:string*) as xs:integer? external;
(:~
 : Returns the sine of the argument. The argument is an angle in radians.
 :
 : The result is the sine of $θ (which is treated as an angle in
 : radians) as defined in the IEEE 754-2008 specification of the sin
 : function applied to 64-bit binary floating point values.
 :
 :
Notes

 :
 : If $θ is positive or negative zero, the result is $θ.
 :
 : If $θ is positive or negative infinity, the dynamic error
 : XDMP-DOMAIN is produced.
 :
 : If $θ is NaN, then the result is NaN.
 :
 : Otherwise the result is always in the range -1.0e0 to +1.0e0.
 :)
declare %a:since("marklogic", "5.0") function math:sin($θ as xs:double) as xs:double external;
declare %a:since("marklogic", "5.0") function math:sinh($x as xs:double) as xs:double external;
(:~
 : Returns the non-negative square root of the argument.
 :
 : The result is the mathematical non-negative square root of $arg
 : as defined in the IEEE 754-2008 specification of the squareRoot
 : function applied to 64-bit binary floating point values.
 :
 :
Notes

 :
 : If $arg is positive or negative zero, positive infinity, or
 : NaN, then the result is $arg. (Negative zero is
 : the only case where the result can have negative sign.)
 :
 : If $arg is negative infinity, the dynamic error
 : XDMP-DOMAIN is produced.
 :)
declare %a:since("marklogic", "5.0") function math:sqrt($x as xs:double) as xs:double external;
declare %a:since("marklogic", "6.0") function math:stddev($arg as xs:double*) as xs:double? external;
declare %a:since("marklogic", "6.0") function math:stddev-p($arg as xs:double*) as xs:double? external;
(:~
 : Returns the tangent of the argument. The argument is an angle in radians.
 :
 : The result is the tangent of $θ (which is treated as an angle in
 : radians) as defined in the IEEE 754-2008 specification of the tan
 : function applied to 64-bit binary floating point values.
 :
 :
Notes

 :
 : If $θ is positive or negative zero, the result is $θ.
 :
 : If $θ is positive or negative infinity, the dynamic error
 : XDMP-DOMAIN is produced.
 :
 : If $θ is NaN, then the result is NaN.
 :)
declare %a:since("marklogic", "5.0") function math:tan($θ as xs:double) as xs:double external;
declare %a:since("marklogic", "5.0") function math:tanh($x as xs:double) as xs:double external;
declare %a:since("marklogic", "8.0") function math:trunc($arg as xs:numeric?) as xs:numeric? external;
declare %a:since("marklogic", "6.0") function math:trunc($arg as xs:numeric?, $n as xs:integer) as xs:numeric? external;
declare %a:since("marklogic", "6.0") function math:variance($arg as xs:double*) as xs:double? external;
declare %a:since("marklogic", "6.0") function math:variance-p($arg as xs:double*) as xs:double? external;

xquery version "1.0-ml" encoding "UTF-8";
(:~
 : MarkLogic math functions
 :
 : @see https://docs.marklogic.com/math
 :
 : This documentation includes material copied from or derived from the XPath and
 : XQuery Functions and Operators 3.1 specifications. Copyright © 2017 W3C®
 : (MIT, ERCIM, Keio, Beihang).
 :)
module namespace math = "http://marklogic.com/xdmp/math";

declare namespace a = "http://reecedunn.co.uk/xquery/annotations";
declare namespace o = "http://reecedunn.co.uk/xquery/options";

declare option o:requires "marklogic/5.0";

(:~
 : Returns an approximation to the mathematical constant π.
 :
 : This function returns the xs:double value whose lexical
 : representation is 3.14159265358979e0.
 :)
declare %a:since("marklogic", "6.0") %a:until("marklogic", "7.0", "math:pi#0") function math:PI() as xs:double external;
(:~
 : Returns the arc cosine of the argument.
 :
 : The result is the arc cosine of $arg, as defined in the IEEE
 : 754-2008 specification of the acos function applied to 64-bit binary
 : floating point values. The result is in the range zero to +π radians.
 :
 :
Notes

 :
 : If $arg is outside the domain of the function, that is the
 : absolute value is greater than one, or if an overflow or underflow occurs,
 : the dynamic error XDMP-DOMAIN is produced.
 :
 : If $arg is NaN, then the result is NaN.
 :
 : In other cases the result is an xs:double value representing an
 : angle θ in radians in the range 0 <= θ <= +π.
 :)
declare %a:since("marklogic", "5.0") function math:acos($arg as xs:double) as xs:double external;
(:~
 : Returns the arc sine of the argument.
 :
 : The result is the arc sine of $arg, as defined in the IEEE
 : 754-2008 specification of the asin function applied to 64-bit binary
 : floating point values. The result is in the range -π/2 to +π/2 radians.
 :
 :
Notes

 :
 : If $arg is outside the domain of the function, that is the
 : absolute value is greater than one, or if an overflow or underflow occurs,
 : the dynamic error XDMP-DOMAIN is produced.
 :
 : If $arg is positive or negative zero, or NaN, the result
 : is $arg.
 :
 : In other cases the result is an xs:double value representing an
 : angle θ in radians in the range -π/2 <= θ <= +π/2.
 :)
declare %a:since("marklogic", "5.0") function math:asin($arg as xs:double) as xs:double external;
(:~
 : Returns the arc tangent of the argument.
 :
 : The result is the arc tangent of $arg, as defined in the IEEE
 : 754-2008 specification of the atan function applied to 64-bit binary floating
 : point values. The result is in the range -π/2 to +π/2 radians.
 :
 :
Notes

 :
 : If $arg is positive or negative infinity, the result is
 : positive or negative π/2.
 :
 : If $arg is positive or negative zero, the result is
 : $arg.
 :
 : If $arg is NaN, then the result is NaN.
 :
 : In other cases the result is an xs:double value representing an
 : angle θ in radians in the range -π/2 <= θ <= +π/2.
 :)
declare %a:since("marklogic", "5.0") function math:atan($arg as xs:double) as xs:double external;
(:~
 : Returns the angle in radians subtended at the origin by the point on a plane
 : with coordinates (x, y) and the positive x-axis.
 :
 : The result is the value of atan2(y, x) as defined in the IEEE
 : 754-2008 specification of the atan2 function applied to 64-bit
 : binary floating point values. The result is in the range -π to +π radians.
 :
 :
Notes

 :
 : If either argument is NaN then the result is NaN.
 :
 : If $y is positive or negative, and $x is positive
 : and finite, then (subject to rules for overflow, underflow and approximation)
 : the value of math:atan2($y, $x) is math:atan($y div $x).
 :
 : If $y is positive and $x is negative and finite,
 : then (subject to the same caveats) the value of math:atan2($y, $x)
 : is math:atan($y div $x) + math:pi().
 :
 : If $y is negative and $x is negative and finite,
 : then (subject to the same caveats) the value of math:atan2($y, $x)
 : is math:atan($y div $x) - math:pi().
 :)
declare %a:since("marklogic", "5.0") function math:atan2($y as xs:double, $x as xs:double) as xs:double external;
(:~
 : Rounds $arg upwards to a whole number.
 :
 : The function returns the smallest (closest to negative infinity) number with
 : no fractional part that is not less than the value of $arg.
 :
 : If the argument is positive zero, then positive zero is returned. If the
 : argument is negative zero, then negative zero is returned. If the argument
 : is less than zero and greater than -1, negative zero is returned.
 :)
declare %a:since("marklogic", "5.0") %a:see-also("xpath-functions", "1.0-20070123", "fn:ceil") function math:ceil($arg as xs:double) as xs:double external;
declare %a:since("marklogic", "6.0") function math:correlation($arg as json:array*) as xs:double? external;
(:~
 : Returns the cosine of the argument. The argument is an angle in radians.
 :
 : The result is the cosine of $θ (which is treated as an angle in
 : radians) as defined in the IEEE 754-2008 specification of the cos
 : function applied to 64-bit binary floating point values.
 :
 :
Notes

 :
 : If $θ is positive or negative zero, the result is $θ.
 :
 : If $θ is positive or negative infinity, the dynamic error
 : XDMP-DOMAIN is produced.
 :
 : If $θ is NaN, then the result is NaN.
 :
 : Otherwise the result is always in the range -1.0e0 to +1.0e0.
 :)
declare %a:since("marklogic", "5.0") function math:cos($θ as xs:double) as xs:double external;
declare %a:since("marklogic", "5.0") function math:cosh($x as xs:double) as xs:double external;
declare %a:since("marklogic", "6.0") function math:cot($x as xs:double) as xs:double external;
declare %a:since("marklogic", "6.0") function math:covariance($arg as json:array*) as xs:double? external;
declare %a:since("marklogic", "6.0") function math:covariance-p($arg as json:array*) as xs:double? external;
(:~
 : Returns the radians argument in degrees.
 :
 : This function converts $arg, specified in radians, to degrees.
 :
 :
Notes

 :
 : If $arg is NaN, positive or negative zero, or
 : positive or negative infinity, then the result is the same as the argument.
 :
 : Otherwise, the result is the argument divided by π/180.
 :
 :
Notes

 :
 : The result is not wrapped, so math:degrees(math:pi() * 4) is
 : 720.
 :)
declare %a:since("marklogic", "6.0") function math:degrees($arg as xs:double) as xs:double external;
(:~
 : Returns the value of ex.
 :
 : The result is the mathematical constant e raised to the power of
 : $arg, as defined in the IEEE 754-2008 specification of the
 : exp function applied to 64-bit binary floating point values.
 :)
declare %a:since("marklogic", "5.0") function math:exp($arg as xs:double) as xs:double external;
(:~
 : Returns the absolute value of $arg.
 :
 : If $arg is negative the function returns -$arg,
 : otherwise it returns $arg.
 :
 : If the argument is positive zero or negative zero, then positive zero is
 : returned. If the argument is positive or negative infinity, positive
 : infinity is returned.
 :)
declare %a:since("marklogic", "5.0") %a:see-also("xpath-functions", "1.0-20070123", "fn:abs") function math:fabs($x as xs:double) as xs:double external;
(:~
 : Rounds $arg downwards to a whole number.
 :
 : The return is the largest (closest to positive infinity) number with no
 : fractional part that is not greater than the value of $arg.
 :
 : If the argument is positive zero, then positive zero is returned. If the
 : argument is negative zero, then negative zero is returned.
 :)
declare %a:since("marklogic", "5.0") function math:floor($arg as xs:double) as xs:double external;
declare %a:since("marklogic", "5.0") function math:fmod($x as xs:double, $y as xs:double) as xs:double external;
declare %a:since("marklogic", "5.0") function math:frexp($x as xs:double) as (xs:double, xs:integer) external;
declare %a:since("marklogic", "5.0") function math:ldexp($y as xs:double, $i as xs:integer) as xs:double external;
declare %a:since("marklogic", "6.0") function math:linear-model($arg as json:array*) as math:linear-model? external;
declare %a:since("marklogic", "6.0") function math:linear-model-coeff($linear-model as math:linear-model) as xs:double* external;
declare %a:since("marklogic", "6.0") function math:linear-model-intercept($linear-model as math:linear-model) as xs:double external;
declare %a:since("marklogic", "6.0") function math:linear-model-rsquared($linear-model as math:linear-model) as xs:double external;
(:~
 : Returns the natural logarithm of the argument.
 :
 : The result is the natural logarithm of $arg, as defined in the
 : IEEE 754-2008 specification of the log function applied to
 : 64-bit binary floating point values.
 :)
declare %a:since("marklogic", "5.0") function math:log($arg as xs:double) as xs:double external;
(:~
 : Returns the base-ten logarithm of the argument.
 :
 : The result is the base-10 logarithm of $arg, as defined in the
 : IEEE 754-2008 specification of the log10 function applied to
 : 64-bit binary floating point values.
 :)
declare %a:since("marklogic", "5.0") function math:log10($arg as xs:double) as xs:double external;
declare %a:since("marklogic", "6.0") function math:median($arg as xs:double*) as xs:double? external;
declare %a:since("marklogic", "6.0") function math:mode($arg as xs:anyAtomicType*) as xs:anyAtomicType* external;
declare %a:since("marklogic", "6.0") function math:mode($arg as xs:anyAtomicType*, $options as xs:string*) as xs:anyAtomicType* external;
declare %a:restrict-until("return", "marklogic", "8.0", "(xs:double,xs:double)")
        %a:restrict-since("return", "marklogic", "8.0", "(xs:double,xs:integer)")
        %a:since("marklogic", "5.0") function math:modf($x as xs:double) as (xs:double,(xs:double|xs:integer)) external;
declare %a:since("marklogic", "6.0") function math:percent-rank($arg as xs:anyAtomicType*, $value as xs:anyAtomicType) as xs:double? external;
declare %a:since("marklogic", "6.0") function math:percent-rank($arg as xs:anyAtomicType*, $value as xs:anyAtomicType, $options as xs:string*) as xs:double? external;
declare %a:since("marklogic", "6.0") function math:percentile($arg as xs:double*, $p as xs:double*) as xs:double* external;
(:~
 : Returns an approximation to the mathematical constant π.
 :
 : This function was replaced by math:pi() in MarkLogic 7.0.
 :
 : This function returns the xs:double value whose lexical
 : representation is 3.14159265358979e0.
 :)
declare %a:since("marklogic", "7.0") function math:pi() as xs:double external;
(:~
 : Returns the value of xy.
 :
 : The result is the value of $x raised to the power of $y
 : as defined in the IEEE 754-2008 specification of the pow function
 : applied to two 64-bit binary floating point values.
 :)
declare %a:since("marklogic", "5.0") function math:pow($x as xs:double, $y as xs:double) as xs:double external;
(:~
 : Returns the degrees argument in radians.
 :
 : This function converts $arg, specified in degrees, to radians.
 :
 :
Notes

 :
 : If $arg is NaN, positive or negative zero, or
 : positive or negative infinity, then the result is the same as the argument.
 :
 : Otherwise, the result is the argument multiplied by π/180.
 :
 :
Notes

 :
 : The result is not wrapped, so math:radians(720) is
 : math:pi() * 4.
 :)
declare %a:since("marklogic", "6.0") function math:radians($x as xs:double) as xs:double external;
declare %a:since("marklogic", "6.0") function math:rank($arg1 as xs:anyAtomicType*, $arg2 as xs:anyAtomicType) as xs:integer? external;
declare %a:since("marklogic", "6.0") function math:rank($arg1 as xs:anyAtomicType*, $arg2 as xs:anyAtomicType, $options as xs:string*) as xs:integer? external;
(:~
 : Returns the sine of the argument. The argument is an angle in radians.
 :
 : The result is the sine of $θ (which is treated as an angle in
 : radians) as defined in the IEEE 754-2008 specification of the sin
 : function applied to 64-bit binary floating point values.
 :
 :
Notes

 :
 : If $θ is positive or negative zero, the result is $θ.
 :
 : If $θ is positive or negative infinity, the dynamic error
 : XDMP-DOMAIN is produced.
 :
 : If $θ is NaN, then the result is NaN.
 :
 : Otherwise the result is always in the range -1.0e0 to +1.0e0.
 :)
declare %a:since("marklogic", "5.0") function math:sin($θ as xs:double) as xs:double external;
declare %a:since("marklogic", "5.0") function math:sinh($x as xs:double) as xs:double external;
(:~
 : Returns the non-negative square root of the argument.
 :
 : The result is the mathematical non-negative square root of $arg
 : as defined in the IEEE 754-2008 specification of the squareRoot
 : function applied to 64-bit binary floating point values.
 :
 :
Notes

 :
 : If $arg is positive or negative zero, positive infinity, or
 : NaN, then the result is $arg. (Negative zero is
 : the only case where the result can have negative sign.)
 :
 : If $arg is negative infinity, the dynamic error
 : XDMP-DOMAIN is produced.
 :)
declare %a:since("marklogic", "5.0") function math:sqrt($x as xs:double) as xs:double external;
declare %a:since("marklogic", "6.0") function math:stddev($arg as xs:double*) as xs:double? external;
declare %a:since("marklogic", "6.0") function math:stddev-p($arg as xs:double*) as xs:double? external;
(:~
 : Returns the tangent of the argument. The argument is an angle in radians.
 :
 : The result is the tangent of $θ (which is treated as an angle in
 : radians) as defined in the IEEE 754-2008 specification of the tan
 : function applied to 64-bit binary floating point values.
 :
 :
Notes

 :
 : If $θ is positive or negative zero, the result is $θ.
 :
 : If $θ is positive or negative infinity, the dynamic error
 : XDMP-DOMAIN is produced.
 :
 : If $θ is NaN, then the result is NaN.
 :)
declare %a:since("marklogic", "5.0") function math:tan($θ as xs:double) as xs:double external;
declare %a:since("marklogic", "5.0") function math:tanh($x as xs:double) as xs:double external;
declare %a:since("marklogic", "8.0") function math:trunc($arg as xs:numeric?) as xs:numeric? external;
declare %a:since("marklogic", "6.0") function math:trunc($arg as xs:numeric?, $n as xs:integer) as xs:numeric? external;
declare %a:since("marklogic", "6.0") function math:variance($arg as xs:double*) as xs:double? external;
declare %a:since("marklogic", "6.0") function math:variance-p($arg as xs:double*) as xs:double? external;


Fixed link formatting for navigating between xquery files. Experiments with updating menu.

declare default element namespace "http://www.w3.org/1999/xhtml";

import module namespace logx="http://cefn.com/logx" at "lib/logx.xq";

logx:webpage(
    for $doc in $logx:collection return $doc//h1
)

declare default element namespace "http://www.w3.org/1999/xhtml";

import module namespace log="http://cefn.com/readinglog/log" at "lib/log.xq";

log:webpage(
    for $doc in $log:collection return $doc//h1
)


[MOD] DBA, Table: missing values. Closes #1600

(:~
 : Provides HTML components.
 :
 : @author Christian Grün, BaseX Team, 2014-18
 :)
module namespace html = 'dba/html';

import module namespace options = 'dba/options' at 'options.xqm';
import module namespace session = 'dba/session' at 'session.xqm';
import module namespace util = 'dba/util' at 'util.xqm';

(: Number formats. :)
declare variable $html:NUMBER := ('decimal', 'number', 'bytes');

(:~
 : Extends the specified table rows with the page template.
 : @param  $rows  tr elements
 : @return HTML page
 :)
declare function html:wrap(
  $rows  as element(tr)+
) as element(html) {
  html:wrap(map { }, $rows)
};

(:~
 : Extends the specified table rows with the page template.
 : The following options can be specified:
 :

 :
header: page headers

 :
error: error string

 :
css: CSS files

 :
scripts: JavaScript files

 :

 : @param  $options  options
 : @param  $rows     tr elements
 : @return page
 :)
declare function html:wrap(
  $options  as map(*),
  $rows     as element(tr)+
) as element(html) {
  let $header := head($options?header) ! util:capitalize(.)
  let $user := $session:VALUE
  return

      <meta charset="utf-8"/>
      <title>DBA{ ($header, tail($options?header)) ! (' » ' || .) }</title>
      <meta name="description" content="Database Administration"/>
      <meta name="author" content="BaseX Team, 2014-18"/>
      <link rel="stylesheet" type="text/css" href="static/style.css"/>
      { $options?css ! <link rel="stylesheet" type="text/css" href="static/{ . }"/> }

};


Comment fix.

Comment fix.

xquery version "3.0";

(:
 : Copyright 2006-2011 The FLWOR Foundation.
 :
 : Licensed under the Apache License, Version 2.0 (the "License");
 : you may not use this file except in compliance with the License.
 : You may obtain a copy of the License at
 :
 : http://www.apache.org/licenses/LICENSE-2.0
 :
 : Unless required by applicable law or agreed to in writing, software
 : distributed under the License is distributed on an "AS IS" BASIS,
 : WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 : See the License for the specific language governing permissions and
 : limitations under the License.
 :)

(:===========================================================================:)

(:~
 : This module provides an XQuery API to full-text functions.
 : For general information about Zorba's implementation of the
 : XQuery and XPath Full Text 1.0 specification
 : as well as instructions for building an installing a thesaurus,
 : see the Full Text Thesaurus documentation.
 :
Notes on languages

 : To refer to paricular human languages,
 : Zorba uses both the
 : ISO 639-1
 : and
 : ISO 639-2
 : languages codes.
 : Note that Zorba supports only a subset of the
 : complete list of language codes
 : and not every function supports the same subset.
 :

 : Most functions in this module take a language as a parameter
 : using the
 : xs:language
 : XML schema data type.
 :
Notes on stemming

 : The stem() functions return the
 : stem
 : of a word.
 : In Zorba,
 : the stem of a word itself, however, is not guaranteed to be a word.
 : It is best to consider a stem as an opaque byte sequence.
 : All that is guaranteed about a stem is that,
 : for a given word,
 : the stem of that word will always be the same byte sequence.
 : Hence,
 : you sould never compare the result of one of the stem()
 : functions against a non-stemmed string,
 : for example:
 :

 :  if ( ft:stem( "apples" ) eq "apple" )             ** WRONG **
 :

 : Instead do:
 :

 :  if ( ft:stem( "apples" ) eq ft:stem( "apple" ) )  ** CORRECT **
 :

 :
Notes on the thesaurus

 : The thesaurus-lookup() functions have "levels"
 : and "relationship" parameters.
 : The values for these are implementation-defined.
 : Zorba's default implementation uses the
 : WordNet lexical database,
 : version 3.0.
 :

 : In WordNet,
 : the number of "levels" that two phrases are apart
 : are how many hierarchical meanings apart they are.
 : For example,
 : "canary" is 5 levels away from "vertebrate"
 : (carary > finch > oscine > passerine > bird > vertebrate).
 :

 : When using the WordNet implementation,
 : Zorba supports all of the relationships (and their abbreviations)
 : specified by
 : ISO 2788
 : and
 : ANSI/NISO Z39.19-2005
 : with the exceptions of "HN" (history note)
 : and "X SN" (see scope note for).
 : These relationships are:
 :

 :

 :      Rel.
 :      Meaning
 :      WordNet Rel.
 :

 :

 :      BT
 :      broader term
 :      hypernym
 :

 :

 :      BTG
 :      broader term generic
 :      hypernym
 :

 :

 :      BTI
 :      broader term instance
 :      instance hypernym
 :

 :

 :      BTP
 :      broader term partitive
 :      part meronym
 :

 :

 :      NT
 :      narrower term
 :      hyponym
 :

 :

 :      NTG
 :      narrower term generic
 :      hyponym
 :

 :

 :      NTI
 :      narrower term instance
 :      instance hyponym
 :

 :

 :      NTP
 :      narrower term partitive
 :      part holonym
 :

 :

 :      RT
 :      related term
 :      also see
 :

 :

 :      SN
 :      scope note
 :      n/a
 :

 :

 :      TT
 :      top term
 :      hypernym
 :

 :

 :      UF
 :      non-preferred term
 :      n/a
 :

 :

 :      USE
 :      preferred term
 :      n/a
 :

 :

 : Note that you can specify relationships
 : either by their abbreviation
 : or their meaning.
 : Relationships are case-insensitive.
 :
 : In addition to the
 : ISO 2788
 : and
 : ANSI/NISO Z39.19-2005
 : relationships,
 : Zorba also supports all of the relationships offered by WordNet.
 : These relationships are:
 :

 :

 :      Relationship
 :      Meaning
 :

 :

 :      also see
 :
 :        A word that is related to another,
 :        e.g., for "varnished" (furniture)
 :        one should also see "finished."
 :
 :

 :

 :      antonym
 :
 :        A word opposite in meaning to another,
 :        e.g., "light" is an antonym for "heavy."
 :
 :

 :

 :      attribute
 :
 :        A noun for which adjectives express values,
 :        e.g., "weight" is an attribute
 :        for which the adjectives "light" and "heavy"
 :        express values.
 :
 :

 :

 :      cause
 :
 :        A verb that causes another,
 :        e.g., "show" is a cause of "see."
 :
 :

 :

 :      derivationally related form
 :
 :        A word that is derived from a root word,
 :        e.g., "metric" is a derivationally related form of "meter."
 :
 :

 :

 :      derived from adjective
 :
 :        An adverb that is derived from an adjective,
 :        e.g., "correctly" is derived from the adjective "correct."
 :
 :

 :

 :      entailment
 :
 :        A verb that presupposes another,
 :        e.g., "snoring" entails "sleeping."
 :
 :

 :

 :      hypernym
 :
 :        A word with a broad meaning that more specific words fall under,
 :        e.g., "meal" is a hypernym of "breakfast."
 :
 :

 :

 :      hyponym
 :
 :        A word of more specific meaning than a general term applicable to it,
 :        e.g., "breakfast" is a hyponym of "meal."
 :
 :

 :

 :      instance hypernym
 :
 :        A word that denotes a category of some specific instance,
 :        e.g., "author" is an instance hypernym of "Asimov."
 :
 :

 :

 :      instance hyponym
 :
 :        A term that donotes a specific instance of some general category,
 :        e.g., "Asimov" is an instance hyponym of "author."
 :
 :

 :

 :      member holonym
 :
 :        A word that denotes a collection of individuals,
 :        e.g., "faculty" is a member holonym of "professor."
 :
 :

 :

 :      member meronym
 :
 :        A word that denotes a member of a larger group,
 :        e.g., a "person" is a member meronym of a "crowd."
 :
 :

 :

 :      part holonym
 :
 :        A word that denotes a larger whole comprised of some part,
 :        e.g., "car" is a part holonym of "engine."
 :
 :

 :

 :      part meronym
 :
 :        A word that denotes a part of a larger whole,
 :        e.g., an "engine" is part meronym of a "car."
 :
 :

 :

 :      participle of verb
 :
 :        An adjective that is the participle of some verb,
 :        e.g., "breaking" is the participle of the verb "break."
 :
 :

 :

 :      pertainym
 :
 :        An adjective that classifies its noun,
 :        e.g., "musical" is a pertainym in "musical instrument."
 :
 :

 :

 :      similar to
 :
 :        Similar, though not necessarily interchangeable, adjectives.
 :        For example, "shiny" is similar to "bright",
 :        but they have subtle differences.
 :
 :

 :

 :      substance holonym
 :
 :        A word that denotes a larger whole containing some constituent
 :        substance, e.g., "bread" is a substance holonym of "flour."
 :
 :

 :

 :      substance meronym
 :
 :        A word that denotes a constituant substance of some larger whole,
 :        e.g., "flour" is a substance meronym of "bread."
 :
 :

 :

 :      verb group
 :
 :        A verb that is a member of a group of similar verbs,
 :        e.g., "live" is in the verb group
 :        of "dwell", "live", "inhabit", etc.
 :
 :

 :

 :
Notes on tokenization

 : For general information about Zorba's implementation of tokenization,
 : including what constitutes a token,
 : see the Full Text Tokenizer documentation.
 : @author Paul J. Lucas
 :)
module namespace ft = "http://www.zorba-xquery.com/modules/full-text";

import schema namespace ft-schema =
  "http://www.zorba-xquery.com/modules/full-text";

declare namespace err = "http://www.w3.org/2005/xqt-errors";
declare namespace zerr = "http://www.zorba-xquery.com/errors";

declare namespace ver = "http://www.zorba-xquery.com/options/versioning";
declare option ver:module-version "2.0";

(:===========================================================================:)

(:~
 : Predeclared constant for the Danish
 : xs:language.
 :)
declare variable $ft:lang-da as xs:language := xs:language("da");

(:~
 : Predeclared constant for the German
 : xs:language.
 :)
declare variable $ft:lang-de as xs:language := xs:language("de");

(:~
 : Predeclared constant for the English
 : xs:language.
 :)
declare variable $ft:lang-en as xs:language := xs:language("en");

(:~
 : Predeclared constant for the Spanish
 : xs:language.
 :)
declare variable $ft:lang-es as xs:language := xs:language("es");

(:~
 : Predeclared constant for the Finnish
 : xs:language.
 :)
declare variable $ft:lang-fi as xs:language := xs:language("fi");

(:~
 : Predeclared constant for the French
 : xs:language.
 :)
declare variable $ft:lang-fr as xs:language := xs:language("fr");

(:~
 : Predeclared constant for the Hungarian
 : xs:language.
 :)
declare variable $ft:lang-hu as xs:language := xs:language("hu");

(:~
 : Predeclared constant for the Italian
 : xs:language.
 :)
declare variable $ft:lang-it as xs:language := xs:language("it");

(:~
 : Predeclared constant for the Dutch
 : xs:language.
 :)
declare variable $ft:lang-nl as xs:language := xs:language("nl");

(:~
 : Predeclared constant for the Norwegian
 : xs:language.
 :)
declare variable $ft:lang-no as xs:language := xs:language("no");

(:~
 : Predeclared constant for the Portuguese
 : xs:language.
 :)
declare variable $ft:lang-pt as xs:language := xs:language("pt");

(:~
 : Predeclared constant for the Romanian
 : xs:language.
 :)
declare variable $ft:lang-ro as xs:language := xs:language("ro");

(:~
 : Predeclared constant for the Russian
 : xs:language.
 :)
declare variable $ft:lang-ru as xs:language := xs:language("ru");

(:~
 : Predeclared constant for the Swedish
 : xs:language.
 :)
declare variable $ft:lang-sv as xs:language := xs:language("sv");

(:~
 : Predeclared constant for the Turkish
 : xs:language.
 :)
declare variable $ft:lang-tr as xs:language := xs:language("tr");

(:===========================================================================:)

(:~
 : Gets the current compare options.
 :
 : @return said compare options.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-current-compare-options-1.xq
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-current-compare-options-2.xq
 :)
declare function ft:current-compare-options()
  as element(ft-schema:compare-options) external;

(:~
 : Gets the current
 : language:
 : either the language specified by the
 : declare ft-option using
 : language
 : statement (if any)
 : or the one returned by ft:host-lang() (if none).
 :
 : @return said language.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-current-lang-true-1.xq
 :)
declare function ft:current-lang()
  as xs:language external;

(:~
 : Gets the host's current
 : language.
 : The "host" is the computer on which Zorba is running.
 : The host's current language is obtained as follows:
 :

 :

 :      For *nix systems:
 :

 :

 :          If setlocale(3) returns non-null,
 :          the language corresponding to that locale is used.
 :

 :

 :          Else, if the LANG environment variable is set,
 :          that language is ued.
 :

 :

 :          Otherwise, there is no default language.
 :

 :

 :

 :

 :      For Windows systems,
 :      the language corresponding to the locale returned by the
 :      GetLocaleInfo()
 :      function is used.
 :

 :

 :
 : @return said language.
 :)
declare function ft:host-lang()
  as xs:language external;

(:~
 : Checks whether the given
 : language
 : is supported for stemming.
 :
 : @param $lang The language to check.
 : @return true only if the language is supported.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-is-stem-lang-es-supported-true.xq
 :)
declare function ft:is-stem-lang-supported( $lang as xs:language )
  as xs:boolean external;

(:~
 : Checks whether the given word is a stop-word.
 :
 : @param $word The word to check.
 : @param $lang The
 : language
 : of $word.
 : @return true only if $word is a stop-word.
 : @error err:FTST0009 if $lang is not supported.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-is-stop-word-true-1.xq
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-is-stop-word-true-3.xq
 :)
declare function ft:is-stop-word( $word as xs:string, $lang as xs:language )
  as xs:boolean external;

(:~
 : Checks whether the given word is a stop-word.
 :
 : @param $word The word to check.
 : The word's language
 : is assumed to be the one returned by ft:current-lang().
 : @return true only if $word is a stop-word.
 : @error err:FTST0009 if ft:current-lang() is not supported.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-is-stop-word-true-2.xq
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-is-stop-word-true-4.xq
 :)
declare function ft:is-stop-word( $word as xs:string )
  as xs:boolean external;

(:~
 : Checks whether the given
 : language
 : is supported for stop words.
 :
 : @param $lang The language to check.
 : @return true only if the language is supported.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-is-stop-word-lang-en-supported-true.xq
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-is-stop-word-lang-supported-false-1.xq
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-is-stop-word-lang-supported-false-2.xq
 :)
declare function ft:is-stop-word-lang-supported( $lang as xs:language )
  as xs:boolean external;

(:~
 : Checks whether the given
 : language
 : is supported for look-up using the default thesaurus.
 :
 : @param $lang The language to check.
 : @return true only if the language is supported.
 :)
declare function ft:is-thesaurus-lang-supported( $lang as xs:language )
  as xs:boolean external;

(:~
 : Checks whether the given
 : language
 : is supported for look-up using the thesaurus specified by the given URI.
 :
 : @param $uri The URI specifying the thesaurus to use.
 : @param $lang The language to check.
 : @return true only if the language is supported.
 : @error err:FTST0018 if $uri refers to a thesaurus
 : that is not found in the statically known thesauri.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-is-thesaurus-lang-supported-true-1.xq
 :)
declare function ft:is-thesaurus-lang-supported( $uri as xs:string,
                                                 $lang as xs:language )
  as xs:boolean external;

(:~
 : Checks whether the given
 : language
 : is supported for tokenization.
 :
 : @param $lang The language to check.
 : @return true only if the language is supported.
 :)
declare function ft:is-tokenizer-lang-supported( $lang as xs:language )
  as xs:boolean external;

(:~
 : Stems the given word.
 :
 : @param $word The word to stem.
 : @param $lang The
 : language
 : of $word.
 : @return the stem of $word.
 : @error err:FTST0009 if $lang is not supported.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-stem-1.xq
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-stem-2.xq
 :)
declare function ft:stem( $word as xs:string, $lang as xs:language )
  as xs:string external;

(:~
 : Stems the given word.
 :
 : @param $word The word to stem.
 : The word's language
 : is assumed to be the one returned by ft:current-lang().
 : @return the stem of $word.
 : @error err:FTST0009 if ft:current-lang() is not supported.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-stem-3.xq
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-stem-4.xq
 :)
declare function ft:stem( $word as xs:string )
  as xs:string external;

(:~
 : Strips all diacritical marks from all characters.
 :
 : @param $string The string to strip diacritical marks from.
 : @return $string with diacritical marks stripped.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-strip-diacritics-1.xq
 :)
declare function ft:strip-diacritics( $string as xs:string )
  as xs:string external;

(:~
 : Looks-up the given phrase in the default thesaurus.
 :
 : @param $phrase The phrase to look up.
 : The phrase's
 : language
 : is assumed to be the one returned by ft:current-lang().
 : @return the related phrases if $phrase is found in the
 : thesaurus or the empty sequence if not.
 : @error err:FTST0009 if ft:current-lang() is not supported.
 : @error zerr:ZXQP8401 if the thesaurus data file's version is not supported
 : by the currently running version of Zorba.
 : @error zerr:ZXQP8402 if the thesaurus data file's endianness does not match
 : that of the CPU on which Zorba is currently running.
 : @error zerr:ZXQP8403 if there was an error reading the thesaurus data.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-thesaurus-lookup-1.xq
 :)
declare function ft:thesaurus-lookup( $phrase as xs:string )
  as xs:string* external;

(:~
 : Looks-up the given phrase in the thesaurus specified by the given URI.
 :
 : @param $uri The URI specifying the thesaurus to use.
 : @param $phrase The phrase to look up.
 : @param $lang The
 : language
 : of $phrase.
 : @return the related phrases if $phrase is found in the
 : thesaurus or the empty sequence if not.
 : @error err:FTST0009 if $lang is not supported.
 : @error err:FTST0018 if $uri refers to a thesaurus
 : that is not found in the statically known thesauri.
 : @error zerr:ZOSE0001 if the thesaurus data file could not be found.
 : @error zerr:ZOSE0002 if the thesaurus data file is not a plain file.
 : @error zerr:ZXQP8401 if the thesaurus data file's version is not supported
 : by the currently running version of Zorba.
 : @error zerr:ZXQP8402 if the thesaurus data file's endianness does not match
 : that of the CPU on which Zorba is currently running.
 : @error zerr:ZXQP8403 if there was an error reading the thesaurus data file.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-thesaurus-lookup-2.xq
 :)
declare function ft:thesaurus-lookup( $uri as xs:string, $phrase as xs:string,
                                      $lang as xs:language )
  as xs:string* external;

(:~
 : Looks-up the given phrase in a thesaurus.
 :
 : @param $uri The URI specifying the thesaurus to use.
 : @param $phrase The phrase to look up.
 : The phrase's
 : language
 : is assumed to be the one the one returned by ft:current-lang().
 : @return the related phrases if $phrase is found in the
 : thesaurus or the empty sequence if not.
 : @error err:FTST0009 if ft:current-lang() is unsupported.
 : @error err:FTST0018 if $uri refers to a thesaurus
 : that is not found in the statically known thesauri.
 : @error zerr:ZOSE0001 if the thesaurus data file could not be found.
 : @error zerr:ZOSE0002 if the thesaurus data file is not a plain file.
 : @error zerr:ZXQP8401 if the thesaurus data file's version is not supported
 : by the currently running version of Zorba.
 : @error zerr:ZXQP8402 if the thesaurus data file's endianness does not match
 : that of the CPU on which Zorba is currently running.
 : @error zerr:ZXQP8403 if there was an error reading the thesaurus data file.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-thesaurus-lookup-3.xq
 :)
declare function ft:thesaurus-lookup( $uri as xs:string, $phrase as xs:string )
  as xs:string* external;

(:~
 : Looks-up the given phrase in a thesaurus.
 :
 : @param $uri The URI specifying the thesaurus to use.
 : @param $phrase The phrase to look up.
 : @param $lang The
 : language
 : of $phrase.
 : @param $relationship The relationship the results are to have to
 : $phrase.
 : @return the related phrases if $phrase is found in the
 : thesaurus or the empty sequence if not.
 : @error err:FTST0018 if $uri refers to a thesaurus
 : that is not found in the statically known thesauri.
 : @error err:FTST0009 if $lang is not supported.
 : @error zerr:ZOSE0001 if the thesaurus data file could not be found.
 : @error zerr:ZOSE0002 if the thesaurus data file is not a plain file.
 : @error zerr:ZXQP8401 if the thesaurus data file's version is not supported
 : by the currently running version of Zorba.
 : @error zerr:ZXQP8402 if the thesaurus data file's endianness does not match
 : that of the CPU on which Zorba is currently running.
 : @error zerr:ZXQP8403 if there was an error reading the thesaurus data file.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-thesaurus-lookup-4.xq
 :)
declare function ft:thesaurus-lookup( $uri as xs:string, $phrase as xs:string,
                                      $lang as xs:language,
                                      $relationship as xs:string )
  as xs:string* external;

(:~
 : Looks-up the given phrase in a thesaurus.
 :
 : @param $uri The URI specifying the thesaurus to use.
 : @param $phrase The phrase to look up.
 : @param $lang The
 : language
 : of $phrase.
 : @param $relationship The relationship the results are to have to
 : $phrase.
 : @param $level-least The minimum number of levels within the thesaurus to be
 : travers$ed.
 : @param $level-most The maximum number of levels within the thesaurus to be
 : traversed.
 : @return the related phrases if $phrase is found in the
 : thesaurus or the empty sequence if not.
 : @error err:FOCA0003 if either $level-least or
 : $level-most is either negative or too large.
 : @error err:FTST0018 if $uri refers to a thesaurus
 : that is not found in the statically known thesauri.
 : @error err:FTST0009 if $lang is not supported.
 : @error zerr:ZOSE0001 if the thesaurus data file could not be found.
 : @error zerr:ZOSE0002 if the thesaurus data file is not a plain file.
 : @error zerr:ZXQP8401 if the thesaurus data file's version is not supported
 : by the currently running version of Zorba.
 : @error zerr:ZXQP8402 if the thesaurus data file's endianness does not match
 : that of the CPU on which Zorba is currently running.
 : @error zerr:ZXQP8403 if there was an error reading the thesaurus data file.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-thesaurus-lookup-5.xq
 :)
declare function ft:thesaurus-lookup( $uri as xs:string, $phrase as xs:string,
                                      $lang as xs:language,
                                      $relationship as xs:string,
                                      $level-least as xs:integer,
                                      $level-most as xs:integer )
  as xs:string* external;

(:~
 : Tokenizes the given node and all of its decendants.
 :
 : @param $node The node to tokenize.
 : @param $lang The default
 : language
 : of $node.
 : @return a (possibly empty) sequence of tokens.
 : @error err:FTST0009 if $lang is not supported.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-tokenize-node-1.xq
 :)
declare function ft:tokenize-node( $node as node(), $lang as xs:language )
  as element(ft-schema:token)* external;

(:~
 : Tokenizes the given node and all of its descendants.
 :
 : @param $node The node to tokenize.
 : The node's default
 : language
 : is assumed to be the one returned by ft:current-lang().
 : @return a (possibly empty) sequence of tokens.
 : @error err:FTST0009 if ft:current-lang() is not supported.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-tokenize-node-2.xq
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-tokenize-node-3.xq
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-tokenize-node-4.xq
 :)
declare function ft:tokenize-node( $node as node() )
  as element(ft-schema:token)* external;

(:~
 : Tokenizes the set of nodes comprising $includes (and all of its
 : descendants) but excluding $excludes (and all of its
 : descendants), if any.
 :
 : @param $includes The set of nodes (and its descendants) to include.
 : The default
 : language
 : is assumed to be the one returned by ft:current-lang().
 : @param $excludes The set of nodes (and its descendants) to exclude.
 : @return a (possibly empty) sequence of tokens.
 : @error err:FTST0009 if ft:current-lang() is not supported.
 :)
declare function ft:tokenize-nodes( $includes as node()+,
                                    $excludes as node()* )
  as element(ft-schema:token)* external;

(:~
 : Tokenizes the set of nodes comprising $includes (and all of its
 : descendants) but excluding $excludes (and all of its
 : descendants), if any.
 :
 : @param $includes The set of nodes (and its descendants) to include.
 : @param $excludes The set of nodes (and its descendants) to exclude.
 : @param $lang The default
 : language
 : for nodes.
 : @return a (possibly empty) sequence of tokens.
 : @error err:FTST0009 if $lang is not supported.
 :)
declare function ft:tokenize-nodes( $includes as node()+,
                                    $excludes as node()*,
                                    $lang as xs:language )
  as element(ft-schema:token)* external;

(:~
 : Tokenizes the given string.
 :
 : @param $string The string to tokenize.
 : @param $lang The
 : language
 : of $string.
 : @return a (possibly empty) sequence of tokens.
 : @error err:FTST0009 if $lang is not supported.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-tokenize-string-1.xq
 :)
declare function ft:tokenize-string( $string as xs:string,
                                     $lang as xs:language )
  as xs:string* external;

(:~
 : Tokenizes the given string.
 :
 : @param $string The string to tokenize.
 : The string's
 : language
 : is assumed to be the one returned by ft:current-lang().
 : @return a (possibly empty) sequence of tokens.
 : @error err:FTST0009 if ft:current-lang() is not supported.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-tokenize-string-2.xq
 :)
declare function ft:tokenize-string( $string as xs:string )
  as xs:string* external;

(:~
 : Gets properties of the tokenizer for the given
 : language.
 :
 : @param $lang The language of the tokenizer to get the properties of.
 : @return said properties.
 : @error err:FTST0009 if $lang is not supported.
 : tokenization specifically.
 :)
declare function ft:tokenizer-properties( $lang as xs:language )
  as element(ft-schema:tokenizer-properties) external;

(:~
 : Gets properties of the tokenizer for the
 : language
 : returned by ft:current-lang().
 :
 : @return said properties.
 : @error err:FTST0009 if ft:current-lang() is not supported.
 :)
declare function ft:tokenizer-properties()
  as element(ft-schema:tokenizer-properties) external;

(:===========================================================================:)

(: vim:set et sw=2 ts=2: :)

xquery version "3.0";

(:
 : Copyright 2006-2011 The FLWOR Foundation.
 :
 : Licensed under the Apache License, Version 2.0 (the "License");
 : you may not use this file except in compliance with the License.
 : You may obtain a copy of the License at
 :
 : http://www.apache.org/licenses/LICENSE-2.0
 :
 : Unless required by applicable law or agreed to in writing, software
 : distributed under the License is distributed on an "AS IS" BASIS,
 : WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 : See the License for the specific language governing permissions and
 : limitations under the License.
 :)

(:===========================================================================:)

(:~
 : This module provides an XQuery API to full-text functions.
 : For general information about Zorba's implementation of the
 : XQuery and XPath Full Text 1.0 specification
 : as well as instructions for building an installing a thesaurus,
 : see the Full Text Thesaurus documentation.
 :
Notes on languages

 : To refer to paricular human languages,
 : Zorba uses both the
 : ISO 639-1
 : and
 : ISO 639-2
 : languages codes.
 : Note that Zorba supports only a subset of the
 : complete list of language codes
 : and not every function supports the same subset.
 :

 : Most functions in this module take a language as a parameter
 : using the
 : xs:language
 : XML schema data type.
 :
Notes on stemming

 : The stem() functions return the
 : stem
 : of a word.
 : In Zorba,
 : the stem of a word itself, however, is not guaranteed to be a word.
 : It is best to consider a stem as an opaque byte sequence.
 : All that is guaranteed about a stem is that,
 : for a given word,
 : the stem of that word will always be the same byte sequence.
 : Hence,
 : you sould never compare the result of one of the stem()
 : functions against a non-stemmed string,
 : for example:
 :

 :  if ( ft:stem( "apples" ) eq "apple" )             ** WRONG **
 :

 : Instead do:
 :

 :  if ( ft:stem( "apples" ) eq ft:stem( "apple" ) )  ** CORRECT **
 :

 :
Notes on the thesaurus

 : The thesaurus-lookup() functions have "levels"
 : and "relationship" parameters.
 : The values for these are implementation-defined.
 : Zorba's default implementation uses the
 : WordNet lexical database,
 : version 3.0.
 :

 : In WordNet,
 : the number of "levels" that two phrases are apart
 : are how many hierarchical meanings apart they are.
 : For example,
 : "canary" is 5 levels away from "vertebrate"
 : (carary > finch > oscine > passerine > bird > vertebrate).
 :

 : When using the WordNet implementation,
 : Zorba supports all of the relationships (and their abbreviations)
 : specified by
 : ISO 2788
 : and
 : ANSI/NISO Z39.19-2005
 : with the exceptions of "HN" (history note)
 : and "X SN" (see scope note for).
 : These relationships are:
 :

 :

 :      Rel.
 :      Meaning
 :      WordNet Rel.
 :

 :

 :      BT
 :      broader term
 :      hypernym
 :

 :

 :      BTG
 :      broader term generic
 :      hypernym
 :

 :

 :      BTI
 :      broader term instance
 :      instance hypernym
 :

 :

 :      BTP
 :      broader term partitive
 :      part meronym
 :

 :

 :      NT
 :      narrower term
 :      hyponym
 :

 :

 :      NTG
 :      narrower term generic
 :      hyponym
 :

 :

 :      NTI
 :      narrower term instance
 :      instance hyponym
 :

 :

 :      NTP
 :      narrower term partitive
 :      part holonym
 :

 :

 :      RT
 :      related term
 :      also see
 :

 :

 :      SN
 :      scope note
 :      n/a
 :

 :

 :      TT
 :      top term
 :      hypernym
 :

 :

 :      UF
 :      non-preferred term
 :      n/a
 :

 :

 :      USE
 :      preferred term
 :      n/a
 :

 :

 : Note that you can specify relationships
 : either by their abbreviation
 : or their meaning.
 : Relationships are case-insensitive.
 :
 : In addition to the
 : ISO 2788
 : and
 : ANSI/NISO Z39.19-2005
 : relationships,
 : Zorba also supports all of the relationships offered by WordNet.
 : These relationships are:
 :

 :

 :      Relationship
 :      Meaning
 :

 :

 :      also see
 :
 :        A word that is related to another,
 :        e.g., for "varnished" (furniture)
 :        one should also see "finished."
 :
 :

 :

 :      antonym
 :
 :        A word opposite in meaning to another,
 :        e.g., "light" is an antonym for "heavy."
 :
 :

 :

 :      attribute
 :
 :        A noun for which adjectives express values,
 :        e.g., "weight" is an attribute
 :        for which the adjectives "light" and "heavy"
 :        express values.
 :
 :

 :

 :      cause
 :
 :        A verb that causes another,
 :        e.g., "show" is a cause of "see."
 :
 :

 :

 :      derivationally related form
 :
 :        A word that is derived from a root word,
 :        e.g., "metric" is a derivationally related form of "meter."
 :
 :

 :

 :      derived from adjective
 :
 :        An adverb that is derived from an adjective,
 :        e.g., "correctly" is derived from the adjective "correct."
 :
 :

 :

 :      entailment
 :
 :        A verb that presupposes another,
 :        e.g., "snoring" entails "sleeping."
 :
 :

 :

 :      hypernym
 :
 :        A word with a broad meaning that more specific words fall under,
 :        e.g., "meal" is a hypernym of "breakfast."
 :
 :

 :

 :      hyponym
 :
 :        A word of more specific meaning than a general term applicable to it,
 :        e.g., "breakfast" is a hyponym of "meal."
 :
 :

 :

 :      instance hypernym
 :
 :        A word that denotes a category of some specific instance,
 :        e.g., "author" is an instance hypernym of "Asimov."
 :
 :

 :

 :      instance hyponym
 :
 :        A term that donotes a specific instance of some general category,
 :        e.g., "Asimov" is an instance hyponym of "author."
 :
 :

 :

 :      member holonym
 :
 :        A word that denotes a collection of individuals,
 :        e.g., "faculty" is a member holonym of "professor."
 :
 :

 :

 :      member meronym
 :
 :        A word that denotes a member of a larger group,
 :        e.g., a "person" is a member meronym of a "crowd."
 :
 :

 :

 :      part holonym
 :
 :        A word that denotes a larger whole comprised of some part,
 :        e.g., "car" is a part holonym of "engine."
 :
 :

 :

 :      part meronym
 :
 :        A word that denotes a part of a larger whole,
 :        e.g., an "engine" is part meronym of a "car."
 :
 :

 :

 :      participle of verb
 :
 :        An adjective that is the participle of some verb,
 :        e.g., "breaking" is the participle of the verb "break."
 :
 :

 :

 :      pertainym
 :
 :        An adjective that classifies its noun,
 :        e.g., "musical" is a pertainym in "musical instrument."
 :
 :

 :

 :      similar to
 :
 :        Similar, though not necessarily interchangeable, adjectives.
 :        For example, "shiny" is similar to "bright",
 :        but they have subtle differences.
 :
 :

 :

 :      substance holonym
 :
 :        A word that denotes a larger whole containing some constituent
 :        substance, e.g., "bread" is a substance holonym of "flour."
 :
 :

 :

 :      substance meronym
 :
 :        A word that denotes a constituant substance of some larger whole,
 :        e.g., "flour" is a substance meronym of "bread."
 :
 :

 :

 :      verb group
 :
 :        A verb that is a member of a group of similar verbs,
 :        e.g., "live" is in the verb group
 :        of "dwell", "live", "inhabit", etc.
 :
 :

 :

 :
Notes on tokenization

 : For general information about Zorba's implementation of tokenization,
 : including what constitutes a token,
 : see the Full Text Tokenizer documentation.
 : @author Paul J. Lucas
 :)
module namespace ft = "http://www.zorba-xquery.com/modules/full-text";

import schema namespace ft-schema =
  "http://www.zorba-xquery.com/modules/full-text";

declare namespace err = "http://www.w3.org/2005/xqt-errors";
declare namespace zerr = "http://www.zorba-xquery.com/errors";

declare namespace ver = "http://www.zorba-xquery.com/options/versioning";
declare option ver:module-version "2.0";

(:===========================================================================:)

(:~
 : Predeclared constant for the Danish
 : xs:language.
 :)
declare variable $ft:lang-da as xs:language := xs:language("da");

(:~
 : Predeclared constant for the German
 : xs:language.
 :)
declare variable $ft:lang-de as xs:language := xs:language("de");

(:~
 : Predeclared constant for the English
 : xs:language.
 :)
declare variable $ft:lang-en as xs:language := xs:language("en");

(:~
 : Predeclared constant for the Spanish
 : xs:language.
 :)
declare variable $ft:lang-es as xs:language := xs:language("es");

(:~
 : Predeclared constant for the Finnish
 : xs:language.
 :)
declare variable $ft:lang-fi as xs:language := xs:language("fi");

(:~
 : Predeclared constant for the French
 : xs:language.
 :)
declare variable $ft:lang-fr as xs:language := xs:language("fr");

(:~
 : Predeclared constant for the Hungarian
 : xs:language.
 :)
declare variable $ft:lang-hu as xs:language := xs:language("hu");

(:~
 : Predeclared constant for the Italian
 : xs:language.
 :)
declare variable $ft:lang-it as xs:language := xs:language("it");

(:~
 : Predeclared constant for the Dutch
 : xs:language.
 :)
declare variable $ft:lang-nl as xs:language := xs:language("nl");

(:~
 : Predeclared constant for the Norwegian
 : xs:language.
 :)
declare variable $ft:lang-no as xs:language := xs:language("no");

(:~
 : Predeclared constant for the Portuguese
 : xs:language.
 :)
declare variable $ft:lang-pt as xs:language := xs:language("pt");

(:~
 : Predeclared constant for the Romanian
 : xs:language.
 :)
declare variable $ft:lang-ro as xs:language := xs:language("ro");

(:~
 : Predeclared constant for the Russian
 : xs:language.
 :)
declare variable $ft:lang-ru as xs:language := xs:language("ru");

(:~
 : Predeclared constant for the Swedish
 : xs:language.
 :)
declare variable $ft:lang-sv as xs:language := xs:language("sv");

(:~
 : Predeclared constant for the Turkish
 : xs:language.
 :)
declare variable $ft:lang-tr as xs:language := xs:language("tr");

(:===========================================================================:)

(:~
 : Gets the current compare options.
 :
 : @return said compare options.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-current-compare-options-1.xq
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-current-compare-options-2.xq
 :)
declare function ft:current-compare-options()
  as element(ft-schema:compare-options) external;

(:~
 : Gets the current
 : language:
 : either the language specified by the
 : declare ft-option using
 : language
 : statement (if any)
 : or the one returned by ft:host-lang() (if none).
 :
 : @return said language.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-current-lang-true-1.xq
 :)
declare function ft:current-lang()
  as xs:language external;

(:~
 : Gets the host's current
 : language.
 : The "host" is the computer on which Zorba is running.
 : The host's current language is obtained as follows:
 :

 :

 :      For *nix systems:
 :

 :

 :          If setlocale(3) returns non-null,
 :          the language corresponding to that locale is used.
 :

 :

 :          Else, if the LANG environment variable is set,
 :          that language is ued.
 :

 :

 :          Otherwise, there is no default language.
 :

 :

 :

 :

 :      For Windows systems,
 :      the language corresponding to the locale returned by the
 :      GetLocaleInfo()
 :      function is used.
 :

 :

 :
 : @return said language.
 :)
declare function ft:host-lang()
  as xs:language external;

(:~
 : Checks whether the given
 : language
 : is supported for stemming.
 :
 : @param $lang The language to check.
 : @return true only if the language is supported.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-is-stem-lang-es-supported-true.xq
 :)
declare function ft:is-stem-lang-supported( $lang as xs:language )
  as xs:boolean external;

(:~
 : Checks whether the given word is a stop-word.
 :
 : @param $word The word to check.
 : @param $lang The
 : language
 : of $word.
 : @return true only if $word is a stop-word.
 : @error err:FTST0009 if $lang is not supported.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-is-stop-word-true-1.xq
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-is-stop-word-true-3.xq
 :)
declare function ft:is-stop-word( $word as xs:string, $lang as xs:language )
  as xs:boolean external;

(:~
 : Checks whether the given word is a stop-word.
 :
 : @param $word The word to check.
 : The word's language
 : is assumed to be the one returned by ft:current-lang().
 : @return true only if $word is a stop-word.
 : @error err:FTST0009 if ft:current-lang() is not supported.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-is-stop-word-true-2.xq
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-is-stop-word-true-4.xq
 :)
declare function ft:is-stop-word( $word as xs:string )
  as xs:boolean external;

(:~
 : Checks whether the given
 : language
 : is supported for stop words.
 :
 : @param $lang The language to check.
 : @return true only if the language is supported.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-is-stop-word-lang-en-supported-true.xq
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-is-stop-word-lang-supported-false-1.xq
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-is-stop-word-lang-supported-false-2.xq
 :)
declare function ft:is-stop-word-lang-supported( $lang as xs:language )
  as xs:boolean external;

(:~
 : Checks whether the given
 : language
 : is supported for look-up using the default thesaurus.
 :
 : @param $lang The language to check.
 : @return true only if the language is supported.
 :)
declare function ft:is-thesaurus-lang-supported( $lang as xs:language )
  as xs:boolean external;

(:~
 : Checks whether the given
 : language
 : is supported for look-up using the thesaurus specified by the given URI.
 :
 : @param $uri The URI specifying the thesaurus to use.
 : @param $lang The language to check.
 : @return true only if the language is supported.
 : @error err:FTST0018 if $uri refers to a thesaurus
 : that is not found in the statically known thesauri.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-is-thesaurus-lang-supported-true-1.xq
 :)
declare function ft:is-thesaurus-lang-supported( $uri as xs:string,
                                                 $lang as xs:language )
  as xs:boolean external;

(:~
 : Checks whether the given
 : language
 : is supported for tokenization.
 :
 : @param $lang The language to check.
 : @return true only if the language is supported.
 :)
declare function ft:is-tokenizer-lang-supported( $lang as xs:language )
  as xs:boolean external;

(:~
 : Stems the given word.
 :
 : @param $word The word to stem.
 : @param $lang The
 : language
 : of $word.
 : @return the stem of $word.
 : @error err:FTST0009 if $lang is not supported.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-stem-1.xq
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-stem-2.xq
 :)
declare function ft:stem( $word as xs:string, $lang as xs:language )
  as xs:string external;

(:~
 : Stems the given word.
 :
 : @param $word The word to stem.
 : The word's language
 : is assumed to be the one returned by ft:current-lang().
 : @return the stem of $word.
 : @error err:FTST0009 if ft:current-lang() is not supported.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-stem-3.xq
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-stem-4.xq
 :)
declare function ft:stem( $word as xs:string )
  as xs:string external;

(:~
 : Strips all diacritical marks from all characters.
 :
 : @param $string The string to strip diacritical marks from.
 : @return $string with diacritical marks stripped.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-strip-diacritics-1.xq
 :)
declare function ft:strip-diacritics( $string as xs:string )
  as xs:string external;

(:~
 : Looks-up the given phrase in the default thesaurus.
 :
 : @param $phrase The phrase to look up.
 : The phrase's
 : language
 : is assumed to be the one returned by ft:current-lang().
 : @return the related phrases if $phrase is found in the
 : thesaurus or the empty sequence if not.
 : @error err:FTST0009 if ft:current-lang() is not supported.
 : @error zerr:ZXQP8401 if the thesaurus data file's version is not supported
 : by the currently running version of Zorba.
 : @error zerr:ZXQP8402 if the thesaurus data file's endianness does not match
 : that of the CPU on which Zorba is currently running.
 : @error zerr:ZXQP8403 if there was an error reading the thesaurus data.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-thesaurus-lookup-1.xq
 :)
declare function ft:thesaurus-lookup( $phrase as xs:string )
  as xs:string* external;

(:~
 : Looks-up the given phrase in the thesaurus specified by the given URI.
 :
 : @param $uri The URI specifying the thesaurus to use.
 : @param $phrase The phrase to look up.
 : @param $lang The
 : language
 : of $phrase.
 : @return the related phrases if $phrase is found in the
 : thesaurus or the empty sequence if not.
 : @error err:FTST0009 if $lang is not supported.
 : @error err:FTST0018 if $uri refers to a thesaurus
 : that is not found in the statically known thesauri.
 : @error zerr:ZOSE0001 if the thesaurus data file could not be found.
 : @error zerr:ZOSE0002 if the thesaurus data file is not a plain file.
 : @error zerr:ZXQP8401 if the thesaurus data file's version is not supported
 : by the currently running version of Zorba.
 : @error zerr:ZXQP8402 if the thesaurus data file's endianness does not match
 : that of the CPU on which Zorba is currently running.
 : @error zerr:ZXQP8403 if there was an error reading the thesaurus data file.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-thesaurus-lookup-2.xq
 :)
declare function ft:thesaurus-lookup( $uri as xs:string, $phrase as xs:string,
                                      $lang as xs:language )
  as xs:string* external;

(:~
 : Looks-up the given phrase in a thesaurus.
 :
 : @param $uri The URI specifying the thesaurus to use.
 : @param $phrase The phrase to look up.
 : The phrase's
 : language
 : is assumed to be the one the one returned by ft:current-lang().
 : @return the related phrases if $phrase is found in the
 : thesaurus or the empty sequence if not.
 : @error err:FTST0009 if ft:current-lang() is unsupported.
 : @error err:FTST0018 if $uri refers to a thesaurus
 : that is not found in the statically known thesauri.
 : @error zerr:ZOSE0001 if the thesaurus data file could not be found.
 : @error zerr:ZOSE0002 if the thesaurus data file is not a plain file.
 : @error zerr:ZXQP8401 if the thesaurus data file's version is not supported
 : by the currently running version of Zorba.
 : @error zerr:ZXQP8402 if the thesaurus data file's endianness does not match
 : that of the CPU on which Zorba is currently running.
 : @error zerr:ZXQP8403 if there was an error reading the thesaurus data file.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-thesaurus-lookup-3.xq
 :)
declare function ft:thesaurus-lookup( $uri as xs:string, $phrase as xs:string )
  as xs:string* external;

(:~
 : Looks-up the given phrase in a thesaurus.
 :
 : @param $uri The URI specifying the thesaurus to use.
 : @param $phrase The phrase to look up.
 : @param $lang The
 : language
 : of $phrase.
 : @param $relationship The relationship the results are to have to
 : $phrase.
 : @return the related phrases if $phrase is found in the
 : thesaurus or the empty sequence if not.
 : @error err:FTST0018 if $uri refers to a thesaurus
 : that is not found in the statically known thesauri.
 : @error err:FTST0009 if $lang is not supported.
 : @error zerr:ZOSE0001 if the thesaurus data file could not be found.
 : @error zerr:ZOSE0002 if the thesaurus data file is not a plain file.
 : @error zerr:ZXQP8401 if the thesaurus data file's version is not supported
 : by the currently running version of Zorba.
 : @error zerr:ZXQP8402 if the thesaurus data file's endianness does not match
 : that of the CPU on which Zorba is currently running.
 : @error zerr:ZXQP8403 if there was an error reading the thesaurus data file.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-thesaurus-lookup-4.xq
 :)
declare function ft:thesaurus-lookup( $uri as xs:string, $phrase as xs:string,
                                      $lang as xs:language,
                                      $relationship as xs:string )
  as xs:string* external;

(:~
 : Looks-up the given phrase in a thesaurus.
 :
 : @param $uri The URI specifying the thesaurus to use.
 : @param $phrase The phrase to look up.
 : @param $lang The
 : language
 : of $phrase.
 : @param $relationship The relationship the results are to have to
 : $phrase.
 : @param $level-least The minimum number of levels within the thesaurus to be
 : travers$ed.
 : @param $level-most The maximum number of levels within the thesaurus to be
 : traversed.
 : @return the related phrases if $phrase is found in the
 : thesaurus or the empty sequence if not.
 : @error err:FOCA0003 if either $level-least or
 : $level-most is either negative or too large.
 : @error err:FTST0018 if $uri refers to a thesaurus
 : that is not found in the statically known thesauri.
 : @error err:FTST0009 if $lang is not supported.
 : @error zerr:ZOSE0001 if the thesaurus data file could not be found.
 : @error zerr:ZOSE0002 if the thesaurus data file is not a plain file.
 : @error zerr:ZXQP8401 if the thesaurus data file's version is not supported
 : by the currently running version of Zorba.
 : @error zerr:ZXQP8402 if the thesaurus data file's endianness does not match
 : that of the CPU on which Zorba is currently running.
 : @error zerr:ZXQP8403 if there was an error reading the thesaurus data file.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-thesaurus-lookup-5.xq
 :)
declare function ft:thesaurus-lookup( $uri as xs:string, $phrase as xs:string,
                                      $lang as xs:language,
                                      $relationship as xs:string,
                                      $level-least as xs:integer,
                                      $level-most as xs:integer )
  as xs:string* external;

(:~
 : Tokenizes the given node and all of its decendants.
 :
 : @param $node The node to tokenize.
 : @param $lang The default
 : language
 : of $node.
 : @return a (possibly empty) sequence of tokens.
 : @error err:FTST0009 if $lang is not supported.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-tokenize-node-1.xq
 :)
declare function ft:tokenize-node( $node as node(), $lang as xs:language )
  as element(ft-schema:token)* external;

(:~
 : Tokenizes the given node and all of its descendants.
 :
 : @param $node The node to tokenize.
 : The node's default
 : language
 : is assumed to be the one returned by ft:current-lang().
 : @return a (possibly empty) sequence of tokens.
 : @error err:FTST0009 if ft:current-lang() is not supported.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-tokenize-node-2.xq
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-tokenize-node-3.xq
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-tokenize-node-4.xq
 :)
declare function ft:tokenize-node( $node as node() )
  as element(ft-schema:token)* external;

(:~
 : Tokenizes the set of nodes comprising $includes and (all of its
 : descendants) but excluding $excludes (and all of its
 : descendants), if any.
 :
 : @param $includes The set of nodes (and its descendants) to include.
 : The default
 : language
 : is assumed to be the one returned by ft:current-lang().
 : @param $excludes The set of nodes (and its descendants) to exclude.
 : @return a (possibly empty) sequence of tokens.
 : @error err:FTST0009 if ft:current-lang() is not supported.
 :)
declare function ft:tokenize-nodes( $includes as node()+,
                                    $excludes as node()* )
  as element(ft-schema:token)* external;

(:~
 : Tokenizes the set of nodes comprising $includes and (all of its
 : descendants) but excluding $excludes (and all of its
 : descendants), if any.
 :
 : @param $includes The set of nodes (and its descendants) to include.
 : @param $excludes The set of nodes (and its descendants) to exclude.
 : @param $lang The default
 : language
 : for nodes.
 : @return a (possibly empty) sequence of tokens.
 : @error err:FTST0009 if $lang is not supported.
 :)
declare function ft:tokenize-nodes( $includes as node()+,
                                    $excludes as node()*,
                                    $lang as xs:language )
  as element(ft-schema:token)* external;

(:~
 : Tokenizes the given string.
 :
 : @param $string The string to tokenize.
 : @param $lang The
 : language
 : of $string.
 : @return a (possibly empty) sequence of tokens.
 : @error err:FTST0009 if $lang is not supported.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-tokenize-string-1.xq
 :)
declare function ft:tokenize-string( $string as xs:string,
                                     $lang as xs:language )
  as xs:string* external;

(:~
 : Tokenizes the given string.
 :
 : @param $string The string to tokenize.
 : The string's
 : language
 : is assumed to be the one returned by ft:current-lang().
 : @return a (possibly empty) sequence of tokens.
 : @error err:FTST0009 if ft:current-lang() is not supported.
 : @example test/rbkt/Queries/zorba/fulltext/ft-module-tokenize-string-2.xq
 :)
declare function ft:tokenize-string( $string as xs:string )
  as xs:string* external;

(:~
 : Gets properties of the tokenizer for the given
 : language.
 :
 : @param $lang The language of the tokenizer to get the properties of.
 : @return said properties.
 : @error err:FTST0009 if $lang is not supported.
 : tokenization specifically.
 :)
declare function ft:tokenizer-properties( $lang as xs:language )
  as element(ft-schema:tokenizer-properties) external;

(:~
 : Gets properties of the tokenizer for the
 : language
 : returned by ft:current-lang().
 :
 : @return said properties.
 : @error err:FTST0009 if ft:current-lang() is not supported.
 :)
declare function ft:tokenizer-properties()
  as element(ft-schema:tokenizer-properties) external;

(:===========================================================================:)

(: vim:set et sw=2 ts=2: :)