and(left Boolean, right Boolean) Boolean
Clinical Quality Language Release 1 STU2 (w/ Errata) (1.2.1)
This is Clinical Quality Language STU2.1 (1.2 Published w/ Errata) in it's permanent home (it will always be available at this URL). It has been superseded by 1.4.
For a full list of available versions, see the Directory of published versions 
.
| Clinical Decision Support Work Group | Maturity Level: 4 | Ballot Status: STU 2.1 |
This appendix provides a reference for all the system-defined types, operators, and functions that can be used within CQL. It is intended to provide complete semantics for each available type and operator as a companion to the Author’s and Developer’s Guides. The reference is organized by operator category.
For each type, the definition and semantics are provided. Note that because CQL does not define a type declaration syntax, the definitions are expressed in a pseudo-syntax.
For each operator or function, the signature, semantics, and usually an example are provided. Note that for built-in operators, the signature is expressed in a pseudo-syntax intended to clearly define the operator and its parameters. Although the symbolic operators may in general be prefix, infix, or postfix operators, the signatures for each operator are defined using function definition syntax for consistency and ease of representation. For example, the signature for the and operator is given as:
and(left Boolean, right Boolean) BooleanEven though and is an infix operator and would be invoked as in the following expression:
InDemographic and NeedsScreeningDefinition:
simple type AnyDescription:
The Any type is the maximal supertype in the CQL type system, meaning that all types derive from Any, including list, interval, and structured types. In addition, the type of a null result is Any.
Definition:
simple type BooleanDescription:
The Boolean type represents the logical boolean values true and false. The result of logical operations within CQL use the Boolean type, and constructs within the language that expect a conditional result, such as a where clause or conditional expression, expect results of the Boolean type.
Definition:
structured type Code
{
code String,
display String,
system String,
version String
}Description:
The Code type represents single terminology codes within CQL.
Definition:
structured type Concept
{
codes List<Code>,
display String
}Description:
The Concept type represents a single terminological concept within CQL.
Definition:
simple type DateTimeDescription:
The DateTime type represents date and time values with potential uncertainty within CQL.
CQL supports date and time values in the range @0001-01-01T00:00:00.0 to @9999-12-31T23:59:59.999 with a 1 millisecond step size.
Definition:
simple type DecimalDescription:
The Decimal type represents real values within CQL.
CQL supports decimal values in the range -1028-10-8 to 1028-10-8 with a step size of 10-8.
Definition:
simple type IntegerDescription:
The Integer type represents whole number values within CQL.
CQL supports integer values in the range -231 to 231-1 with a step size of 1.
Definition:
structured type Quantity
{
value Decimal
unit String
}Description:
The Quantity type represents quantities with a specified unit within CQL.
Definition:
simple type StringDescription:
The String type represents string values within CQL.
CQL supports string values up to 231-1 characters in length.
For string literals, CQL uses standard escape sequences:
| Escape | Character |
|---|---|
\' |
Single-quote |
\" |
Double-quote |
\r |
Carriage Return |
\n |
Line Feed |
\t |
Tab |
\f |
Form Feed |
\\ |
Backslash |
\uXXXX |
Unicode character, where XXXX is the hexadecimal representation of the character |
Signature:
and (left Boolean, right Boolean) BooleanDescription:
The and operator returns true if both its arguments are true. If either argument is false, the result is false. Otherwise, the result is null.
The following table defines the truth table for this operator:
| TRUE | FALSE | NULL | |
|---|---|---|---|
TRUE |
TRUE |
FALSE |
NULL |
FALSE |
FALSE |
FALSE |
FALSE |
NULL |
NULL |
FALSE |
NULL |
Table 9‑A
Example:
The following examples illustrate the behavior of the and operator:
define IsTrue = true and true
define IsFalse = true and false
define IsAlsoFalse = false and null
define IsNull = true and nullSignature:
implies (left Boolean, right Boolean) BooleanDescription:
The implies operator returns the logical implication of its arguments. This means that if the left operand evaluates to true, this operator returns the boolean evaluation of the right operand. If the left operand evaluates to false, this operator returns true. Otherwise, this operator returns true if the right operand evaluates to true, and null otherwise.
The following table defines the truth table for this operator:
| TRUE | FALSE | NULL | |
|---|---|---|---|
TRUE |
TRUE |
FALSE |
NULL |
FALSE |
TRUE |
TRUE |
TRUE |
NULL |
TRUE |
NULL |
NULL |
Table 9‑A
Signature:
not (argument Boolean) BooleanDescription:
The not operator returns true if the argument is false and false if the argument is true. Otherwise, the result is null.
The following table defines the truth table for this operator:
| NOT | |
|---|---|
TRUE |
FALSE |
FALSE |
TRUE |
NULL |
NULL |
Table 9‑B
Signature:
or (left Boolean, right Boolean) BooleanDescription:
The or operator returns true if either of its arguments are true. If both arguments are false, the result is false. Otherwise, the result is null.
The following table defines the truth table for this operator:
| TRUE | FALSE | NULL | |
|---|---|---|---|
TRUE |
TRUE |
TRUE |
TRUE |
FALSE |
TRUE |
FALSE |
NULL |
NULL |
TRUE |
NULL |
NULL |
Table 9‑C
Example:
The following examples illustrate the behavior of the or operator:
define IsTrue = true or false
define IsAlsoTrue = true or null
define IsFalse = false or false
define IsNull = false or nullSignature:
xor (left Boolean, right Boolean) BooleanDescription:
The xor (exclusive or) operator returns true if one argument is true and the other is false. If both arguments are true or both arguments are false, the result is false. Otherwise, the result is null.
The following table defines the truth table for this operator:
| TRUE | FALSE | NULL | |
|---|---|---|---|
TRUE |
FALSE |
TRUE |
NULL |
FALSE |
TRUE |
FALSE |
NULL |
NULL |
NULL |
NULL |
NULL |
Table 9‑D
Signature:
as<T>(argument Any) T
cast as<T>(argument Any) TDescription:
The as operator allows the result of an expression to be cast as a given target type. This allows expressions to be written that are statically typed against the expected run-time type of the argument.
If the argument is not of the specified type at run-time the result is null.
The cast prefix indicates that if the argument is not of the specified type at run-time then an exception is thrown.
Example:
The following examples illustrate the use of the as operator.
define AllProcedures: [Procedure]
define ImagingProcedures:
AllProcedures P
where P is ImagingProcedure
return P as ImagingProcedure
define RuntimeError:
ImagingProcedures P
return cast P as ObservationSignature:
Children(argument Any) List<Any>Description:
For structured types, the Children operator returns a list of all the values of the elements of the type. List-valued elements are expanded and added to the result individually, rather than as a single list.
For list types, the result is the same as invoking Children on each element in the list and flattening the resulting lists into a single result.
If the source is null, the result is null.
Signature:
convert to<T>(argument Any) TDescription:
The convert operator converts a value to a specific type. The result of the operator is the value of the argument converted to the target type, if possible. Note that use of this operator may result in a run-time exception being thrown if there is no valid conversion from the actual value to the target type.
The following table lists the conversions supported in CQL:
| From\To | Boolean | Integer | Decimal | Quantity | String | Datetime | Time | Code | Concept | List(Code) |
|---|---|---|---|---|---|---|---|---|---|---|
Boolean |
N/A |
- |
- |
- |
Explicit |
- |
- |
- |
- |
- |
Integer |
- |
N/A |
Implicit |
- |
Explicit |
- |
- |
- |
- |
- |
Decimal |
- |
- |
N/A |
- |
Explicit |
- |
- |
- |
- |
- |
Quantity |
- |
- |
- |
N/A |
Explicit |
- |
- |
- |
- |
- |
String |
Explicit |
Explicit |
Explicit |
Explicit |
N/A |
Explicit |
Explicit |
- |
- |
- |
Datetime |
- |
- |
- |
- |
Explicit |
N/A |
- |
- |
- |
- |
Time |
- |
- |
- |
- |
Explicit |
- |
N/A |
- |
- |
- |
Code |
- |
- |
- |
- |
- |
- |
- |
N/A |
Implicit |
- |
Concept |
- |
- |
- |
- |
- |
- |
- |
- |
N/A |
Explicit |
List(Code) |
Implicit |
N/A |
Table 9‑E
For conversions between date/time and string values, ISO-8601 standard format is used:
yyyy-MM-ddThh:mm:ss.fff(Z | +/- hh:mm)
For example, the following are valid string representations for date/time values:
'2014-01-01T14:30:00.0Z' // January 1^st^, 2014, 2:30PM UTC +
'2014-01-01T14:30:00.0-07:00' // January 1^st^, 2014, 2:30PM Mountain Standard (GMT-7:00) +
'T14:30:00.0Z' // 2:30PM UTC +
'T14:30:00.0-07:00' // 2:30PM Mountain Standard (GMT-7:00)For specific semantics for each conversion, refer to the explicit conversion operator documentation.
Signature:
Descendents(argument Any) List<Any>Description:
For structured types, the Descendents operator returns a list of all the values of the elements of the type, recursively. List-valued elements are expanded and added to the result individually, rather than as a single list.
For list types, the result is the same as invoking Descendents on each element in the list and flattening the resulting lists into a single result.
If the source is null, the result is null.
Signature:
is<T>(argument Any) BooleanDescription:
The is operator allows the type of a result to be tested. If the run-time type of the argument is of the type being tested, the result of the operator is true; otherwise, the result is false.
Signature:
ToBoolean(argument String) BooleanDescription:
The ToBoolean operator converts the value of its argument to a Boolean value. The operator accepts the following string representations:
| String Representation | Boolean Value |
|---|---|
true t yes y 1 |
true |
false f no n 0 |
false |
Table 9‑F
Note that the operator will ignore case when interpreting the string as a Boolean value.
If the input cannot be interpreted as a valid Boolean value, a run-time error is thrown.
If the argument is null, the result is null.
Signature:
ToConcept(argument Code) ConceptDescription:
The ToConcept operator converts a value of type Code to a Concept value with the given Code as its primary and only Code. If the Code has a display value, the resulting Concept will have the same display value.
If the argument is null, the result is null.
Signature:
ToDateTime(argument String) DateTimeDescription:
The ToDateTime operator converts the value of its argument to a DateTime value. The operator expects the string to be formatted using the ISO-8601 date/time representation:
YYYY-MM-DDThh:mm:ss.fff(+|-)hh:mm
In addition, the string must be interpretable as a valid date/time value.
For example, the following are valid string representations for date/time values:
'2014-01-01' // January 1^st^, 2014
'2014-01-01T14:30:00.0Z' // January 1^st^, 2014, 2:30PM UTC
'2014-01-01T14:30:00.0-07:00' // January 1^st^, 2014, 2:30PM Mountain Standard (GMT-7:00)If the input string is not formatted correctly, or does not represent a valid date/time value, a run-time error is thrown.
As with date/time literals, date/time values may be specified to any precision. If no timezone is supplied, the timezone of the evaluation request timestamp is assumed.
If the argument is null, the result is null.
Signature:
ToDecimal(argument String) DecimalDescription:
The ToDecimal operator converts the value of its argument to a Decimal value. The operator accepts strings using the following format:
(+|-)?#0(.0#)?Meaning an optional polarity indicator, followed by any number of digits (including none), followed by at least one digit, followed optionally by a decimal point, at least one digit, and any number of additional digits (including none).
Note that the decimal value returned by this operator must be limited in precision and scale to the maximum precision and scale representable for Decimal values within CQL.
If the input string is not formatted correctly, or cannot be interpreted as a valid Decimal value, a run-time error is thrown.
If the argument is null, the result is null.
Signature:
ToInteger(argument String) IntegerDescription:
The ToInteger operator converts the value of its argument to an Integer value. The operator accepts strings using the following format:
(+|-)?#0Meaning an optional polarity indicator, followed by any number of digits (including none), followed by at least one digit.
Note that the integer value returned by this operator must be a valid value in the range representable for Integer values in CQL.
If the input string is not formatted correctly, or cannot be interpreted as a valid Integer value, a run-time error is thrown.
If the argument is null, the result is null.
Signature:
ToQuantity(argument String) QuantityDescription:
The ToQuantity operator converts the value of its argument to a Quantity value. The operator accepts strings using the following format:
(+|-)?#0(.0#)?('<unit>')?Meaning an optional polarity indicator, followed by any number of digits (including none) followed by at least one digit, optionally followed by a decimal point, at least one digit, and any number of additional digits, all optionally followed by a unit designator as a string literal specifying a valid UCUM unit of measure. Spaces are allowed between the quantity value and the unit designator.
Note that the decimal value of the quantity returned by this operator must be a valid value in the range representable for Decimal values in CQL.
If the input string is not formatted correctly, or cannot be interpreted as a valid Quantity value, a run-time error is thrown.
If the argument is null, the result is null.
Signature:
ToString(argument Boolean) String
ToString(argument Integer) String
ToString(argument Decimal) String
ToString(argument Quantity) String
ToString(argument DateTime) String
ToString(argument Time) StringDescription:
The ToString operator converts the value of its argument to a String value. The operator uses the following string representations for each type:
| Type | String Representation |
|---|---|
Boolean |
true |
false |
Integer |
(-)?#0 |
Decimal |
(-)?0.0 |
Quantity |
(-)?0.0 '<unit>' |
DateTime |
YYYY-MM-DDThh:mm:ss.fff(+ |
-)hh:mm |
Time |
Thh:mm:ss.fff(+ |
Table 9‑G
If the argument is null, the result is null.
Signature:
ToTime(argument String) TimeDescription:
The ToTime operator converts the value of its argument to a Time value. The operator expects the string to be formatted using ISO-8601 time representation:
Thh:mm:ss.fff(+|-)hh:mm
In addition, the string must be interpretable as a valid time-of-day value.
For example, the following are valid string representations for time-of-day values:
'T14:30:00.0Z' // 2:30PM UTC
'T14:30:00.0-07:00' // 2:30PM Mountain Standard (GMT-7:00)If the input string is not formatted correctly, or does not represent a valid time-of-day value, a run-time error is thrown.
As with time-of-day literals, time-of-day values may be specified to any precision. If no timezone is supplied, the timezone of the evaluation request timestamp is assumed.
If the argument is null, the result is null.
Signature:
Coalesce<T>(argument1 T, argument2 T) T
Coalesce<T>(argument1 T, argument2 T, argument3 T) T
Coalesce<T>(argument1 T, argument2 T, argument3 T, argument4 T) T
Coalesce<T>(argument1 T, argument2 T, argument3 T, argument4 T, argument5 T) T
Coalesce<T>(arguments List<T>) TDescription:
The Coalesce operator returns the first non-null result in a list of arguments. If all arguments evaluate to null, the result is null.
The static type of the first argument determines the type of the result, and all subsequent arguments must be of that same type.
Signature:
is null(argument Any) BooleanDescription:
The is null operator determines whether or not its argument evaluates to null. If the argument evaluates to null, the result is true; otherwise, the result is false.
Signature:
between(argument Integer, low Integer, high Integer) Boolean
between(argument Decimal, low Decimal, high Decimal) Boolean
between(argument Quantity, low Quantity, high Quantity) Boolean
between(argument DateTime, low DateTime, high DateTime) Boolean
between(argument Time, low Time, high Time) Boolean
between(argument String, low String, high String) BooleanDescription:
The between operator determines whether the first argument is within a given range, inclusive. If the first argument is greater than or equal to the low argument, and less than or equal to the high argument, the result is true, otherwise, the result is false.
For comparisons involving quantities, the dimensions of each quantity must be the same, but not necessarily the unit. For example, units of 'cm' and 'm' are comparable, but units of 'cm2' and 'cm' are not. Attempting to operate on quantities with invalid units will result in a run-time error.
For comparisons involving date/time or time values with imprecision, note that the result of the comparison may be null, depending on whether the values involved are specified to the level of precision used for the comparison.
If any argument is null, the result is null.
Signature:
=<T>(left T, right T) BooleanDescription:
The equal (=) operator returns true if the arguments are equal; false if the arguments are known unequal, and null otherwise. Equality semantics are defined to be value-based.
For simple types, this means that equality returns true if and only if the result of each argument evaluates to the same value.
For decimal values, trailing zeroes are ignored.
For quantities, this means that the dimensions of each quantity must be the same, but not necessarily the unit. For example, units of 'cm' and 'm' are comparable, but units of 'cm2' and 'cm' are not. Attempting to operate on quantities with invalid units will result in a run-time error.
For tuple types, this means that equality returns true if and only if the tuples are of the same type, and the values for all elements by name are equal.
For list types, this means that equality returns true if and only if the lists contain elements of the same type, have the same number of elements, and for each element in the lists, in order, the elements are equal using the same semantics.
For interval types, equality returns true if and only if the intervals are over the same point type, and they have the same value for the starting and ending points of the interval as determined by the Start and End operators.
For comparisons involving date/time or time values with imprecision, note that the result of the comparison may be null, depending on whether the values involved are specified to the level of precision used for the comparison.
If either argument is null, the result is null.
Signature:
~<T>(left T, right T) BooleanDescription:
The ~ operator returns true if the arguments are the same value, or if they are both null; and false otherwise.
For tuple types, this means that two tuple values are equivalent if and only if the tuples are of the same type, and the values for all elements by name are equivalent.
For list types, this means that two list values are equivalent if and only if the lists contain elements of the same type, have the same number of elements, and for each element in the lists, in order, the elements are equivalent.
For interval types, this means that two intervals are equivalent if and only if the intervals are over the same point type, and the starting and ending points of the intervals as determined by the Start and End operators are equivalent.
For Code values, equivalence is defined based on the code and system elements only. The version and display elements are ignored for the purposes of determining Code equivalence.
For Concept values, equivalence is defined as a non-empty intersection of the codes in each Concept.
Note that this operator will always return true or false, even if either or both of its arguments are null, or contain null components.
This operator, and the corresponding notion of equivalence, are used throughout CQL to define the behavior of membership and containment operators such as in, contains, includes, IndexOf(), etc. This provides consistent and intuitive behavior in the presence of missing information in list and membership contexts.
Signature:
>(left Integer, right Integer) Boolean
>(left Decimal, right Decimal) Boolean
>(left Quantity, right Quantity) Boolean
>(left DateTime, right DateTime) Boolean
>(left Time, right Time) Boolean
>(left String, right String) BooleanDescription:
The greater (>) operator returns true if the first argument is greater than the second argument.
For comparisons involving quantities, the dimensions of each quantity must be the same, but not necessarily the unit. For example, units of 'cm' and 'm' are comparable, but units of 'cm2' and 'cm' are not. Attempting to operate on quantities with invalid units will result in a run-time error.
For comparisons involving date/time or time values with imprecision, note that the result of the comparison may be null, depending on whether the values involved are specified to the level of precision used for the comparison.
If either argument is null, the result is null.
Signature:
>=(left Integer, right Integer) Boolean
>=(left Decimal, right Decimal) Boolean
>=(left Quantity, right Quantity) Boolean
>=(left DateTime, right DateTime) Boolean
>=(left Time, right Time) Boolean
>=(left String, right String) BooleanDescription:
The greater or equal (>=) operator returns true if the first argument is greater than or equal to the second argument.
For comparisons involving quantities, the dimensions of each quantity must be the same, but not necessarily the unit. For example, units of 'cm' and 'm' are comparable, but units of 'cm2' and 'cm' are not. Attempting to operate on quantities with invalid units will result in a run-time error.
For comparisons involving date/time or time values with imprecision, note that the result of the comparison may be null, depending on whether the values involved are specified to the level of precision used for the comparison.
If either argument is null, the result is null.
Signature:
<(left Integer, right Integer) Boolean
<(left Decimal, right Decimal) Boolean
<(left Quantity, right Quantity) Boolean
<(left DateTime, right DateTime) Boolean
<(left Time, right Time) Boolean
<(left String, right String) BooleanDescription:
The less (<) operator returns true if the first argument is less than the second argument.
For comparisons involving quantities, the dimensions of each quantity must be the same, but not necessarily the unit. For example, units of 'cm' and 'm' are comparable, but units of 'cm2' and 'cm' are not. Attempting to operate on quantities with invalid units will result in a run-time error.
For comparisons involving date/time or time values with imprecision, note that the result of the comparison may be null, depending on whether the values involved are specified to the level of precision used for the comparison.
If either argument is null, the result is null.
Signature:
<=(left Integer, right Integer) Boolean
<=(left Decimal, right Decimal) Boolean
<=(left Quantity, right Quantity) Boolean
<=(left DateTime, right DateTime) Boolean
<=(left Time, right Time) Boolean
<=(left String, right String) BooleanDescription:
The less or equal (<=) operator returns true if the first argument is less than or equal to the second argument.
For comparisons involving quantities, the dimensions of each quantity must be the same, but not necessarily the unit. For example, units of 'cm' and 'm' are comparable, but units of 'cm2' and 'cm' are not. Attempting to operate on quantities with invalid units will result in a run-time error.
For comparisons involving date/time or time values with imprecision, note that the result of the comparison may be null, depending on whether the values involved are specified to the level of precision used for the comparison.
If either argument is null, the result is null.
Signature:
Abs(argument Integer) Integer
Abs(argument Decimal) Decimal
Abs(argument Quantity) QuantityDescription:
The Abs operator returns the absolute value of its argument.
When taking the absolute value of a quantity, the unit is unchanged.
If the argument is null, the result is null.
Signature:
+(left Integer, right Integer) Integer
+(left Decimal, right Decimal) Decimal
+(left Quantity, right Quantity) QuantityDescription:
The add (+) operator performs numeric addition of its arguments.
When invoked with mixed Integer and Decimal arguments, the Integer argument will be implicitly converted to Decimal.
When adding quantities, the dimensions of each quantity must be the same, but not necessarily the unit. For example, units of 'cm' and 'm' can be added, but units of 'cm2' and 'cm' cannot. The unit of the result will be the most granular unit of either input. Attempting to operate on quantities with invalid units will result in a run-time error.
If either argument is null, the result is null.
Signature:
Ceiling(argument Decimal) IntegerDescription:
The Ceiling operator returns the first integer greater than or equal to the argument.
When invoked with an Integer argument, the argument will be implicitly converted to Decimal.
If the argument is null, the result is null.
Signature:
/(left Decimal, right Decimal) Decimal
/(left Quantity, right Decimal) Quantity
/(left Quantity, right Quantity) QuantityDescription:
The divide (/) operator performs numeric division of its arguments. Note that this operator is Decimal division; for Integer division, use the truncated divide (div) operator.
When invoked with Integer arguments, the arguments will be implicitly converted to Decimal.
For division operations involving quantities, the resulting quantity will have the appropriate unit. For example:
12 'cm2' / 3 'cm'
In this example, the result will have a unit of 'cm'.
If either argument is null, the result is null.
Signature:
Floor(argument Decimal) IntegerDescription:
The Floor operator returns the first integer less than or equal to the argument.
When invoked with an Integer argument, the argument will be implicitly converted to Decimal.
If the argument is null, the result is null.
Signature:
Exp(argument Decimal) DecimalDescription:
The Exp operator raises e to the power of its argument.
When invoked with an Integer argument, the argument will be implicitly converted to Decimal.
If the argument is null, the result is null.
Signature:
Log(argument Decimal, base Decimal) DecimalDescription:
The Log operator computes the logarithm of its first argument, using the second argument as the base.
When invoked with Integer arguments, the arguments will be implicitly converted to Decimal.
If either argument is null, the result is null.
Signature:
Ln(argument Decimal) DecimalDescription:
The Ln operator computes the natural logarithm of its argument.
When invoked with an Integer argument, the argument will be implicitly converted to Decimal.
If the argument is null, the result is null.
Signature:
maximum<T>() TDescription:
The maximum operator returns the maximum representable value for the given type.
The maximum operator is defined for the Integer, Decimal, DateTime, and Time types.
For Integer, maximum returns the maximum signed 32-bit integer, 231 - 1.
For Decimal, maximum returns the maximum representable decimal value, (1037 – 1) / 108 (9999999999999999999999999999.99999999).
For DateTime, maximum returns the maximum representable date/time value, DateTime(9999, 12, 31, 23, 59, 59, 999).
For Time, maximum returns the maximum representable time value, Time(23, 59, 59, 999).
For any other type, attempting to invoke maximum results in an error.
Signature:
minimum<T>() TDescription:
The minimum operator returns the minimum representable value for the given type.
The minimum operator is defined for the Integer, Decimal, DateTime, and Time types.
For Integer, minimum returns the minimum signed 32-bit integer, -231.
For Decimal, minimum returns the minimum representable decimal value, (-1037 – 1) / 108 (-9999999999999999999999999999.99999999).
For DateTime, minimum returns the minimum representable date/time value, DateTime(1, 1, 1, 0, 0, 0, 0).
For Time, minimum returns the minimum representable time value, Time(0, 0, 0, 0).
For any other type, attempting to invoke minimum results in an error.
Signature:
mod(left Integer, right Integer) Integer
mod(left Decimal, right Decimal) DecimalDescription:
The mod operator computes the remainder of the division of its arguments.
When invoked with mixed Integer and Decimal arguments, the Integer argument will be implicitly converted to Decimal.
If either argument is null, the result is null.
Signature:
*(left Integer, right Integer) Integer
*(left Decimal, right Decimal) Decimal
*(left Decimal, right Quantity) Quantity
*(left Quantity, right Decimal) Quantity
*(left Quantity, right Quantity) QuantityDescription:
The multiply (*) operator performs numeric multiplication of its arguments.
When invoked with mixed Integer and Decimal arguments, the Integer argument will be implicitly converted to Decimal.
For multiplication operations involving quantities, the resulting quantity will have the appropriate unit. For example:
12 'cm' * 3 'cm'
3 'cm' * 12 'cm2'In this example, the first result will have a unit of 'cm2', and the second result will have a unit of 'cm3'.
If either argument is null, the result is null.
Signature:
-(argument Integer) Integer
-(argument Decimal) Decimal
-(argument Quantity) QuantityDescription:
The negate (-) operator returns the negative of its argument.
When negating quantities, the unit is unchanged.
If the argument is null, the result is null.
Signature:
predecessor of<T>(argument T) TDescription:
The predecessor operator returns the predecessor of the argument. For example, the predecessor of 2 is 1. If the argument is already the minimum value for the type, a run-time error is thrown.
The predecessor operator is defined for the Integer, Decimal, DateTime, and Time types.
For Integer, predecessor is equivalent to subtracting 1.
For Decimal, predecessor is equivalent to subtracting the minimum precision value for the Decimal type, or 10^-08.
For DateTime and Time values, predecessor is equivalent to subtracting a time-unit quantity for the lowest specified precision of the value. For example, if the DateTime is fully specified, predecessor is equivalent to subtracting 1 millisecond; if the DateTime is specified to the second, predecessor is equivalent to subtracting one second, etc.
If the argument is null, the result is null.
Signature:
^(argument Integer, exponent Integer) Integer
^(argument Decimal, exponent Decimal) DecimalDescription:
The power (^) operator raises the first argument to the power given by the second argument.
When invoked with mixed Integer and Decimal arguments, the Integer argument will be implicitly converted to Decimal.
If either argument is null, the result is null.
Signature:
Round(argument Decimal) Decimal
Round(argument Decimal, precision Integer) DecimalDescription:
The Round operator returns the nearest whole number to its argument. The semantics of round are defined as a traditional round, meaning that a decimal value of 0.5 or higher will round to 1.
When invoked with an Integer argument, the argument will be implicitly converted to Decimal.
If the argument is null, the result is null.
Precision determines the decimal place at which the rounding will occur. If precision is not specified or null, 0 is assumed.
Signature:
-(left Integer, right Integer) Integer
-(left Decimal, right Decimal) Decimal
-(left Quantity, right Quantity) QuantityDescription:
The subtract (-) operator performs numeric subtraction of its arguments.
When invoked with mixed Integer and Decimal arguments, the Integer argument will be implicitly converted to Decimal.
When subtracting quantities, the dimensions of each quantity must be the same, but not necessarily the unit. For example, units of 'cm' and 'm' can be subtracted, but units of 'cm2' and 'cm' cannot. The unit of the result will be the most granular unit of either input. Attempting to operate on quantities with invalid units will result in a run-time error.
If either argument is null, the result is null.
Signature:
successor of<T>(argument T) TDescription:
The successor operator returns the successor of the argument. For example, the successor of 1 is 2. If the argument is already the maximum value for the type, a run-time error is thrown.
The successor operator is defined for the Integer, Decimal, DateTime, and Time types.
For Integer, successor is equivalent to adding 1.
For Decimal, successor is equivalent to adding the minimum precision value for the Decimal type, or 10^-08.
For DateTime and Time values, successor is equivalent to adding a time-unit quantity for the lowest specified precision of the value. For example, if the DateTime is fully specified, successor is equivalent to adding 1 millisecond; if the DateTime is specified to the second, successor is equivalent to adding one second, etc.
If the argument is null, the result is null.
Signature:
Truncate(argument Decimal) IntegerDescription:
The Truncate operator returns the integer component of its argument.
When invoked with an Integer argument, the argument will be implicitly converted to Decimal.
If the argument is null, the result is null.
Signature:
div(left Integer, right Integer) Integer
div(left Decimal, right Decimal) DecimalDescription:
The div operator performs truncated division of its arguments.
When invoked with mixed Integer and Decimal arguments, the Integer argument will be implicitly converted to Decimal.
If either argument is null, the result is null.
Signature:
Combine(source List<String>) String
Combine(source List<String>, separator String) StringDescription:
The Combine operator combines a list of strings, optionally separating each string with the given separator.
If either argument is null, or any element in the source list of strings is null, the result is null.
Signature:
+(left String, right String) String
&(left String, right String) StringDescription:
The concatenate (+ or &) operator performs string concatenation of its arguments.
When using +, if either argument is null, the result is null.
When using &, null arguments are treated as an empty string ('').
Signature:
EndsWith(argument String, suffix String) BooleanDescription:
The EndsWith operator returns true if the given string starts with the given suffix.
If the suffix is the empty string, the result is true.
If either argument is null, the result is null.
Signature:
[](argument String, index Integer) StringDescription:
The indexer ([]) operator returns the character at the indexth position in a string.
Indexes in strings are defined to be 0-based.
If either argument is null, the result is null.
If the index is greater than the length of the string being indexed, the result is null.
Signature:
LastPositionOf(pattern String, argument String) IntegerDescription:
The LastPositionOf operator returns the 0-based index of the last appearance of the given pattern in the given string.
If the pattern is not found, the result is -1.
If either argument is null, the result is null.
Signature:
Length(argument String) IntegerDescription:
The Length operator returns the number of characters in a string.
If the argument is null, the result is null.
Signature:
Lower(argument String) StringDescription:
The Lower operator returns the given string with all characters converted to their lower case equivalents.
Note that the definition of lowercase for a given character is a locale-dependent determination, and is not specified by CQL. Implementations are expected to provide appropriate and consistent handling of locale for their environment.
If the argument is null, the result is null.
Signature:
Matches(argument String, pattern String) BooleanDescription:
The Matches operator returns true if the given string matches the given regular expression pattern. Regular expressions should function consistently, regardless of any culture- and locale-specific settings in the environment, should be case-sensitive, use single line mode, and allow Unicode characters.
If either argument is null, the result is null.
Platforms will typically use native regular expression implementations. These are typically fairly similar, but there will always be small differences. As such, CQL does not prescribe a particular dialect, but recommends the use of the dialect defined as part of XML Schema 1.1 as the dialect most likely to be broadly supported and understood.
Signature:
PositionOf(pattern String, argument String) IntegerDescription:
The PositionOf operator returns the 0-based index of the given pattern in the given string.
If the pattern is not found, the result is -1.
If either argument is null, the result is null.
Signature:
Matches(argument String, pattern String, substitution String) StringDescription:
The ReplaceMatches operator matches the given string using the given regular expression pattern, replacing each match with the given substitution. The substitution string may refer to identified match groups in the regular expression. Regular expressions should function consistently, regardless of any culture- and locale-specific settings in the environment, should be case-sensitive, use single line mode, and allow Unicode characters.
If any argument is null, the result is null.
Platforms will typically use native regular expression implementations. These are typically fairly similar, but there will always be small differences. As such, CQL does not prescribe a particular dialect, but recommends the use of the dialect defined as part of XML Schema 1.1 as the dialect most likely to be broadly supported and understood.
Signature:
Split(stringToSplit String, separator String) List<String>Description:
The Split operator splits a string into a list of strings using a separator.
If the stringToSplit argument is null, the result is null.
If the stringToSplit argument does not contain any appearances of the separator, the result is a list of strings containing one element that is the value of the stringToSplit argument.
Signature:
StartsWith(argument String, prefix String) BooleanDescription:
The StartsWith operator returns true if the given string starts with the given prefix.
If the prefix is the empty string, the result is true.
If either argument is null, the result is null.
Signature:
Substring(stringToSub String, startIndex Integer) String
Substring(stringToSub String, startIndex Integer, length Integer) StringDescription:
The Substring operator returns the string within stringToSub, starting at the 0-based index startIndex, and consisting of length characters.
If length is ommitted, the substring returned starts at startIndex and continues to the end of stringToSub.
If stringToSub or startIndex is null, or startIndex is out of range, the result is null.
Signature:
Upper(argument String) StringDescription:
The Upper operator returns the given string with all characters converted to their upper case equivalents.
Note that the definition of uppercase for a given character is a locale-dependent determination, and is not specified by CQL. Implementations are expected to provide appropriate and consistent handling of locale for their environment.
If the argument is null, the result is null.
Signature:
+(left DateTime, right Quantity) DateTime
+(left Time, right Quantity) TimeDescription:
The add (+) operator returns the value of the given date/time, incremented by the time-valued quantity, respecting variable length periods for calendar years and months.
For DateTime values, the quantity unit must be one of: years, months, weeks, days, hours, minutes, seconds, or milliseconds.
For Time values, the quantity unit must be one of: hours, minutes, seconds, or milliseconds.
The operation is performed by converting the time-based quantity to the highest specified granularity in the date/time value (truncating any resulting decimal portion) and then adding it to the date/time value. For example, the following addition:
DateTime(2014) + 24 months
This example results in the value DateTime(2016) even though the date/time value is not specified to the level of precision of the time-valued quantity.
Note also that this means that if decimals appear in the time-valued quantities, the fractional component will be ignored.
If either argument is null, the result is null.
Signature:
after _precision_ of(left DateTime, right DateTime) Boolean
after _precision_ of(left Time, right Time) BooleanDescription:
The after-precision-of operator compares two date/time values to the specified precision to determine whether the first argument is the after the second argument. Precision must be one of: year, month, week, day, hour, minute, second, or millisecond.
For comparisons involving date/time or time values with imprecision, note that the result of the comparison may be null, depending on whether the values involved are specified to the level of precision used for the comparison.
As with all date/time calculations, comparisons are performed respecting the timezone offset.
If either or both arguments are null, the result is null.
Signature:
before _precision_ of(left DateTime, right DateTime) Boolean +
before _precision_ of(left Time, right Time) BooleanDescription:
The before-precision-of operator compares two date/time values to the specified precision to determine whether the first argument is the before the second argument. Precision must be one of: year, month, week, day, hour, minute, second, or millisecond.
For comparisons involving date/time or time values with imprecision, note that the result of the comparison may be null, depending on whether the values involved are specified to the level of precision used for the comparison.
As with all date/time calculations, comparisons are performed respecting the timezone offset.
If either or both arguments are null, the result is null.
Signature:
DateTime(year Integer) DateTime
DateTime(year Integer, month Integer) DateTime
DateTime(year Integer, month Integer, day Integer) DateTime
DateTime(year Integer, month Integer, day Integer,
hour Integer) DateTime
DateTime(year Integer, month Integer, day Integer,
hour Integer, minute Integer) DateTime
DateTime(year Integer, month Integer, day Integer,
hour Integer, minute Integer, second Integer) DateTime
DateTime(year Integer, month Integer, day Integer,
hour Integer, minute Integer, second Integer, millisecond Integer) DateTime
DateTime(year Integer, month Integer, day Integer,
hour Integer, minute Integer, second Integer, millisecond Integer,
timezoneOffset Decimal) DateTimeDescription:
The DateTime operator constructs a date/time value from the given components.
At least one component other than timezoneOffset must be specified, and no component may be specified at a precision below an unspecified precision. For example, hour may be null, but if it is, minute, second, and millisecond must all be null as well.
If timezoneOffset is not specified, it is defaulted to the timezone offset of the evaluation request.
Signature:
_precision_ from(argument DateTime) Integer
_precision_ from(argument Time) Integer
timezone from(argument DateTime) Decimal
timezone from(argument Time) Decimal
date from(argument DateTime) DateTime
time from(argument DateTime) TimeDescription:
The component-from operator returns the specified component of the argument.
For DateTime values, precision must be one of: year, month, day, hour, minute, second, or millisecond.
For Time values, precision must be one of: hour, minute, second, or millisecond.
If the argument is null, or is not specified to the level of precision being extracted, the result is null.
Signature:
difference in _precision_ between(low DateTime, high DateTime) Integer
difference in _precision_ between(low Time, high Time) IntegerDescription:
The difference-between operator returns the number of boundaries crossed for the specified precision between the first and second arguments. If the first argument is after the second argument, the result is negative. The result of this operation is always an integer; any fractional boundaries are dropped.
For DateTime values, precision must be one of: years, months, weeks, days, hours, minutes, seconds, or milliseconds.
For Time values, precision must be one of: hours, minutes, seconds, or milliseconds.
If either argument is null, the result is null.
Signature:
_duration_ between(low DateTime, high DateTime) Integer
_duration_ between(low Time, high Time) IntegerDescription:
The duration-between operator returns the number of whole calendar periods for the specified precision between the first and second arguments. If the first argument is after the second argument, the result is negative. The result of this operation is always an integer; any fractional periods are dropped.
For DateTime values, duration must be one of: years, months, weeks, days, hours, minutes, seconds, or milliseconds.
For Time values, duration must be one of: hours, minutes, seconds, or milliseconds.
If either argument is null, the result is null.
Signature:
Now() DateTimeDescription:
The Now operator returns the date and time of the start timestamp associated with the evaluation request. Now is defined in this way for two reasons:
The operation will always return the same value within any given evaluation, ensuring that the result of an expression containing Now will always return the same result.
The operation will return the timestamp associated with the evaluation request, allowing the evaluation to be performed with the same timezone information as the data delivered with the evaluation request.
Signature:
same _precision_ as(left DateTime, right DateTime) Boolean
same _precision_ as(left Time, right Time) BooleanDescription:
The same-precision-as operator compares two date/time values to the specified precision for equality. Individual component values are compared starting from the year component down to the specified precision. If all values are specified and have the same value for each component, then the result is true. If a compared component is specified in both dates, but the values are not the same, then the result is false. Otherwise the result is null, as there is not enough information to make a determination.
For DateTime values, precision must be one of: year, month, week, day, hour, minute, second, or millisecond.
For Time values, precision must be one of: hour, minute, second, or millisecond.
For comparisons involving date/time or time values with imprecision, note that the result of the comparison may be null, depending on whether the values involved are specified to the level of precision used for the comparison.
As with all date/time calculations, comparisons are performed respecting the timezone offset.
If either or both arguments are null, the result is null.
Signature:
same _precision_ or after(left DateTime, right DateTime) Boolean
same _precision_ or after(left Time, right Time) BooleanDescription:
The same-precision-or after operator compares two date/time values to the specified precision to determine whether the first argument is the same or after the second argument.
For DateTime values, precision must be one of: year, month, week, day, hour, minute, second, or millisecond.
For Time values, precision must be one of: hour, minute, second, or millisecond.
For comparisons involving date/time or time values with imprecision, note that the result of the comparison may be null, depending on whether the values involved are specified to the level of precision used for the comparison.
As with all date/time calculations, comparisons are performed respecting the timezone offset.
If either or both arguments are null, the result is null.
Signature:
same _precision_ or before(left DateTime, right DateTime) Boolean
same _precision_ or before(left Time, right Time) BooleanDescription:
The same-precision-or before operator compares two date/time values to the specified precision to determine whether the first argument is the same or before the second argument.
For DateTime values, precision must be one of: year, month, week, day, hour, minute, second, or millisecond.
For Time values, precision must be one of: hour, minute, second, or millisecond.
For comparisons involving date/time or time values with imprecision, note that the result of the comparison may be null, depending on whether the values involved are specified to the level of precision used for the comparison.
As with all date/time calculations, comparisons are performed respecting the timezone offset.
If either or both arguments are null, the result is null.
Signature:
-(left DateTime, right Quantity) DateTime
-(left Time, right Quantity) TimeDescription:
The subtract (-) operator returns the value of the given date/time, decremented by the time-valued quantity, respecting variable length periods for calendar years and months.
For DateTime values, the quantity unit must be one of: years, months, weeks, days, hours, minutes, seconds, or milliseconds.
For Time values, the quantity unit must be one of: hours, minutes, seconds, or milliseconds.
The operation is performed by converting the time-based quantity to the highest specified granularity in the date/time value (truncating any resulting decimal portion) and then subtracting it from the date/time value. For example, the following subtraction:
DateTime(2014) - 24 months
This example results in the value DateTime(2012) even though the date/time value is not specified to the level of precision of the time-valued quantity.
Note also that this means that if decimals appear in the time-valued quantities, the fractional component will be ignored.
If either argument is null, the result is null.
Signature:
Time(hour Integer) Time
Time(hour Integer, minute Integer) Time
Time(hour Integer, minute Integer, second Integer) Time
Time(hour Integer, minute Integer, second Integer, millisecond Integer) Time
Time(hour Integer, minute Integer, second Integer, millisecond Integer,
timezoneOffset Decimal) TimeDescription:
The Time operator constructs a time value from the given components.
At least one component other than timezoneOffset must be specified, and no component may be specified at a precision below an unspecified precision. For example, minute may be null, but if it is, second, and millisecond must all be null as well.
If timezoneOffset is not specified, it is defaulted to the timezone offset of the evaluation request.
Signature:
after _precision_ (left Interval<T>, right Interval<T>) Boolean
after _precision_ (left T, right Interval<T>) Boolean
after _precision_ (left Interval<T>, right T) BooleanDescription:
The after operator for intervals returns true if the first interval starts after the second one ends. In other words, if the starting point of the first interval is greater than the ending point of the second interval.
For the point-interval overload, the operator returns true if the given point is greater than the end of the interval.
For the interval-point overload, the operator returns true if the given interval starts after the given point.
This operator uses the semantics described in the Start and End operators to determine interval boundaries.
If precision is specified and the point type is a date/time type, comparisons used in the operation are performed at the specified precision.
If either argument is null, the result is null.
Signature:
before _precision_ (left Interval<T>, right Interval<T>) Boolean
before _precision_ (left T, right Interval<T>) Boolean
before _precision_ (left interval<T>, right T) BooleanDescription:
The before operator for intervals returns true if the first interval ends before the second one starts. In other words, if the ending point of the first interval is less than the starting point of the second interval.
For the point-interval overload, the operator returns true if the given point is less than the start of the interval.
For the interval-point overload, the operator returns true if the given interval ends before the given point.
This operator uses the semantics described in the Start and End operators to determine interval boundaries.
If precision is specified and the point type is a date/time type, comparisons used in the operation are performed at the specified precision.
If either argument is null, the result is null.
Signature:
collapse(argument List<Interval<T>>) List<Interval<T>>Description:
The collapse operator returns the unique set of intervals that completely covers the ranges present in the given list of intervals.
If the list of intervals is empty, the result is empty. If the list of intervals contains a single interval, the result is a list with that interval. If the list of intervals contains nulls, they will be excluded from the resulting list.
If the argument is null, the result is null.
Signature:
contains _precision_ (argument Interval<T>, point T) BooleanDescription:
The contains operator for intervals returns true if the given point is greater than or equal to the starting point of the interval, and less than or equal to the ending point of the interval. For open interval boundaries, exclusive comparison operators are used. For closed interval boundaries, if the interval boundary is null, the result of the boundary comparison is considered true.
If precision is specified and the point type is a date/time type, comparisons used in the operation are performed at the specified precision.
If either argument is null, the result is null.
Signature:
end of(argument Interval<T>) TDescription:
The End operator returns the ending point of an interval.
If the high boundary of the interval is open, this operator returns the predecessor of the high value of the interval. Note that if the high value of the interval is null, the result is null.
If the high boundary of the interval is closed and the high value of the interval is not null, this operator returns the high value of the interval. Otherwise, the result is the maximum value of the point type of the interval.
If the argument is null, the result is null.
Signature:
ends _precision_ (left Interval<T>, right Interval<T>) BooleanDescription:
The ends operator returns true if the first interval ends the second. More precisely, if the starting point of the first interval is greater than or equal to the starting point of the second, and the ending point of the first interval is equal to the ending point of the second.
This operator uses the semantics described in the start and end operators to determine interval boundaries.
If precision is specified and the point type is a date/time type, comparisons used in the operation are performed at the specified precision.
If either argument is null, the result is null.
Signature:
=(left Interval<T>, right Interval<T>) BooleanDescription:
The equal (=) operator for intervals returns true if and only if the intervals are over the same point type, and they have the same value for the starting and ending points of the intervals as determined by the Start and End operators.
If either argument is null, the result is null.
Signature:
~(left Interval<T>, right Interval<T>) BooleanDescription:
The ~ operator for intervals returns true if and only if the intervals are over the same point type, and the starting and ending points of the intervals as determined by the Start and End operators are equivalent.
Signature:
except(left Interval<T>, right Interval<T>) Interval<T>Description:
The except operator for intervals returns the set difference of two intervals. More precisely, this operator returns the portion of the first interval that does not overlap with the second. Note that to avoid returning an improper interval, if the second argument is properly contained within the first and does not start or end it, this operator returns null.
If either argument is null, the result is null.
Signature:
in _precision_ (point T, argument Interval<T>) BooleanDescription:
The in operator for intervals returns true if the given point is greater than or equal to the starting point of the interval, and less than or equal to the ending point of the interval. For open interval boundaries, exclusive comparison operators are used. For closed interval boundaries, if the interval boundary is null, the result of the boundary comparison is considered true.
If precision is specified and the point type is a date/time type, comparisons used in the operation are performed at the specified precision.
If either argument is null, the result is null.
Signature:
includes _precision_ (left Interval<T>, right Interval<T>) BooleanDescription:
The includes operator for intervals returns true if the first interval completely includes the second. More precisely, if the starting point of the first interval is less than or equal to the starting point of the second interval, and the ending point of the first interval is greater than or equal to the ending point of the second interval.
This operator uses the semantics described in the Start and End operators to determine interval boundaries.
If precision is specified and the point type is a date/time type, comparisons used in the operation are performed at the specified precision.
If either argument is null, the result is null.
Signature:
included in _precision_ (left Interval<T>, right Interval<T>) BooleanDescription:
The included in operator for intervals returns true if the first interval is completely included in the second. More precisely, if the starting point of the first interval is greater than or equal to the starting point of the second interval, and the ending point of the first interval is less than or equal to the ending point of the second interval.
This operator uses the semantics described in the Start and End operators to determine interval boundaries.
If precision is specified and the point type is a date/time type, comparisons used in the operation are performed at the specified precision.
If either argument is null, the result is null.
Note that during is a synonym for included in and may be used to invoke the same operation whever included in may appear.
Signature:
intersect(left Interval<T>, right Interval<T>) Interval<T>Description:
The intersect operator for intervals returns the intersection of two intervals. More precisely, the operator returns the interval that defines the overlapping portion of both arguments. If the arguments do not overlap, this operator returns null.
If either argument is null, the result is null.
Signature:
meets _precision_ (left Interval<T>, right Interval<T>) Boolean
meets before _precision_ (left Interval<T>, right Interval<T>) Boolean
meets after _precision_ (left Interval<T>, right Interval<T>) BooleanDescription:
The meets operator returns true if the first interval ends immediately before the second interval starts, or if the first interval starts immediately after the second interval ends. In other words, if the ending point of the first interval is equal to the predecessor of the starting point of the second, or if the starting point of the first interval is equal to the successor of the ending point of the second.
The meets before operator returns true if the first interval ends immediately before the second interval starts, while the meets after operator returns true if the first interval starts immediately after the second interval ends.
This operator uses the semantics described in the Start and End operators to determine interval boundaries.
If precision is specified and the point type is a date/time type, comparisons used in the operation are performed at the specified precision.
If either argument is null, the result is null.
Signature:
!=(left Interval<T>, right Interval<T>) : BooleanDescription:
The not equal (!=) operator for intervals returns true if its arguments are not the same value.
The not equal operator is a shorthand for invocation of logical negation (not) of the equal operator.
Signature:
!~(left Interval<T>, right Interval<T>) : BooleanDescription:
The not equivalent (!~) operator for intervals returns true if its arguments are not equivalent.
The not equivalent operator is a shorthand for invocation of logical negation (not) of the equivalent operator.
Signature:
on or after _precision_ (left Interval<T>, right Interval<T>) Boolean
on or after _precision_ (left T, right Interval<T>) Boolean
on or after _precision_ (left Interval<T>, right T) BooleanDescription:
The on or after operator for intervals returns true if the first interval starts on or after the second one ends. In other words, if the starting point of the first interval is greater than or equal to the ending point of the second interval.
For the point-interval overload, the operator returns true if the given point is greater than or equal to the end of the interval.
For the interval-point overload, the operator returns true if the given interval starts on or after the given point.
This operator uses the semantics described in the Start and End operators to determine interval boundaries.
If precision is specified and the point type is a date/time type, comparisons used in the operation are performed at the specified precision.
If either argument is null, the result is null.
Note that this operator can be invoked using either the on or after or the after or on syntax.
Signature:
on or before _precision_ (left Interval<T>, right Interval<T>) Boolean
on or before _precision_ (left T, right Interval<T>) Boolean
on or before _precision_ (left interval<T>, right T) BooleanDescription:
The on or before operator for intervals returns true if the first interval ends on or before the second one starts. In other words, if the ending point of the first interval is less than or equal to the starting point of the second interval.
For the point-interval overload, the operator returns true if the given point is less than or equal to the start of the interval.
For the interval-point overload, the operator returns true if the given interval ends on or before the given point.
This operator uses the semantics described in the Start and End operators to determine interval boundaries.
If precision is specified and the point type is a date/time type, comparisons used in the operation are performed at the specified precision.
If either argument is null, the result is null.
Note that this operator can be invoked using either the on or before or the before or on syntax.
Signature:
overlaps _precision_ (left Interval<T>, right Interval<T>) Boolean
overlaps before _precision_ (left Interval<T>, right Interval<T>) Boolean
overlaps after _precision_ (left Interval<T>, right Interval<T>) BooleanDescription:
The overlaps operator returns true if the first interval overlaps the second. More precisely, if the ending point of the first interval is greater than or equal to the starting point of the second interval, and the starting point of the first interval is less than or equal to the ending point of the second interval.
The operator overlaps before returns true if the first interval overlaps the second and starts before it, while the overlaps after operator returns true if the first interval overlaps the second and ends after it.
This operator uses the semantics described in the Start and End operators to determine interval boundaries.
If precision is specified and the point type is a date/time type, comparisons used in the operation are performed at the specified precision.
If either argument is null, the result is null.
Signature:
point from(argument Interval<T>) : TDescription:
The point from operator extracts the single point from a unit interval. If the argument is not a unit interval, a run-time error is thrown.
If the argument is null, the result is null.
Signature:
properly includes _precision_ (left Interval<T>, right Interval<T>) BooleanDescription:
The properly includes operator for intervals returns true if the first interval completely includes the second and the first interval is strictly larger than the second. More precisely, if the starting point of the first interval is less than or equal to the starting point of the second interval, and the ending point of the first interval is greater than or equal to the ending point of the second interval, and they are not the same interval.
This operator uses the semantics described in the Start and End operators to determine interval boundaries.
If precision is specified and the point type is a date/time type, comparisons used in the operation are performed at the specified precision.
If either argument is null, the result is null.
Signature:
properly included in _precision_ (left Interval<T>, right Interval<T>) BooleanDescription:
The properly included in operator for intervals returns true if the first interval is completely included in the second and the first interval is strictly smaller than the second. More precisely, if the starting point of the first interval is greater than or equal to the starting point of the second interval, and the ending point of the first interval is less than or equal to the ending point of the second interval, and they are not the same interval.
This operator uses the semantics described in the Start and End operators to determine interval boundaries.
If precision is specified and the point type is a date/time type, comparisons used in the operation are performed at the specified precision.
If either argument is null, the result is null.
Note that during is a synonym for included in.
Signature:
start of(argument Interval<T>) TDescription:
The Start operator returns the starting point of an interval.
If the low boundary of the interval is open, this operator returns the successor of the low value of the interval. Note that if the low value of the interval is null, the result is null.
If the low boundary of the interval is closed and the low value of the interval is not null, this operator returns the low value of the interval. Otherwise, the result is the minimum value of the point type of the interval.
If the argument is null, the result is null.
Signature:
starts _precision_ (left Interval<T>, right Interval<T>) BooleanDescription:
The starts operator returns true if the first interval starts the second. More precisely, if the starting point of the first is equal to the starting point of the second interval and the ending point of the first interval is less than or equal to the ending point of the second interval.
This operator uses the semantics described in the Start and End operators to determine interval boundaries.
If precision is specified and the point type is a date/time type, comparisons used in the operation are performed at the specified precision.
If either argument is null, the result is null.
Signature:
union(left Interval<T>, right Interval<T>) Interval<T>Description:
The union operator for intervals returns the union of the intervals. More precisely, the operator returns the interval that starts at the earliest starting point in either argument, and ends at the latest starting point in either argument. If the arguments do not overlap or meet, this operator returns null.
If either argument is null, the result is null.
Signature:
width of(argument Interval<T>) TDescription:
The width operator returns the width of an interval. The result of this operator is equivalent to invoking: (start of argument – end of argument) + point-size.
Note that because CQL defines duration and difference operations for date/time and time valued intervals, width is not defined for intervals of these types.
If the argument is null, the result is null.
Signature:
contains(argument List<T>, element T) BooleanDescription:
The contains operator for lists returns true if the given element is in the list.
This operator uses the notion of equivalence to determine whether or not the element being searched for is equivalent to any element in the list. In particular this means that if the list contains a null, and the element being searched for is null, the result will be true.
If the list argument is null, the result is false.
Signature:
distinct(argument List<T>) List<T>Description:
The distinct operator returns the given list with duplicates eliminated.
This operator uses the notion of equivalence to determine whether two elements in the list are the same for the purposes of duplicate elimination. In particular this means that if the list contains multiple null elements, the result will only contain one null element.
If the argument is null, the result is null.
Signature:
=(left List<T>, right List<T>) BooleanDescription:
The equal (=) operator for lists returns true if and only if the lists have the same element type, and have the same elements by value, in the same order.
If either argument is null, or contains null elements, the result is null.
Signature:
~(left List<T>, right List<T>) BooleanDescription:
The ~ operator for lists returns true if and only if the lists contain elements of the same type, have the same number of elements, and for each element in the lists, in order, the elements are equivalent.
Signature:
except(left List<T>, right List<T>) List<T>Description:
The except operator returns the set difference of two lists. More precisely, the operator returns a list with the elements that appear in the first operand that do not appear in the second operand.
This operator uses the notion of equivalence to determine whether two elements are the same for the purposes of computing the difference.
If the left argument is null, the result is null. else if the right argument is null, the result is the left argument.
Signature:
exists(argument List<T>) BooleanDescription:
The exists operator returns true if the list contains any elements, including null elements.
If the argument is null, the result is false.
Signature:
flatten(argument List<List<T>>) List<T>Description:
The flatten operator flattens a list of lists into a single list.
If the argument is null, the result is null.
Signature:
First(argument List<T>) TDescription:
The First operator returns the first element in a list. The operator is equivalent to invoking the indexer with an index of 0.
If the argument is null, the result is null.
Signature:
in(element T, argument List<T>) BooleanDescription:
The in operator for lists returns true if the given element is in the given list.
This operator uses the notion of equivalence to determine whether or not the element being searched for is equivalent to any element in the list. In particular this means that if the list contains a null, and the element being searched for is null, the result will be true.
If the left argument is null, the result is null. If the right argument is null, the result is false.
Signature:
includes(left List<T>, right List<T>) BooleanDescription:
The includes operator for lists returns true if the first list contains every element of the second list.
This operator uses the notion of equivalence to determine whether or not two elements are the same.
If the left argument is null, the result is false, else if the right argument is null, the result is true.
Note that the order of elements does not matter for the purposes of determining inclusion.
Signature:
included in(left List<T>, right list<T>) BooleanDescription:
The included in operator for lists returns true if every element of the first list is in the second list.
This operator uses the notion of equivalence to determine whether or not two elements are the same.
If the left argument is null, the result is true, else if the right argument is null, the result is false.
Note that the order of elements does not matter for the purposes of determining inclusion.
Signature:
[](argument List<T>, index Integer) TDescription:
The indexer ([]) operator returns the element at the indexth position in a list.
Indexes in lists are defined to be 0-based.
If the index is less than 0, or greater than the number of elements in the list, the result is null.
If either argument is null, the result is null.
Signature:
IndexOf(argument List<T>, element T) IntegerDescription:
The IndexOf operator returns the 0-based index of the given element in the given source list.
The operator uses the notion of equivalence to determine the index. The search is linear, and returns the index of the first element that is equivalent to the element being searched for.
If the list is empty, or no element is found, the result is -1.
If the list argument is null, the result is null.
Signature:
intersect(left List<T>, right List<T>) List<T>Description:
The intersect operator for lists returns the intersection of two lists. More precisely, the operator returns a list containing only the elements that appear in both lists.
This operator uses the notion of equivalence to determine whether or not two elements are the same.
If either argument is null, the result is null.
Signature:
Last(argument List<T>) TDescription:
The Last operator returns the last element in a list. In a list of length N, the operator is equivalent to invoking the indexer with an index of N - 1.
If the argument is null, the result is null.
Signature:
Length(argument List<T>) IntegerDescription:
The Length operator returns the number of elements in a list.
If the argument is null, the result is 0.
Signature:
!=(left List<T>, right List<T>) BooleanDescription:
The not equal (!=) operator for lists returns true if its arguments are not the same value.
The not equal operator is a shorthand for invocation of logical negation (not) of the equal operator.
Signature:
!~(left List<T>, right List<T>) BooleanDescription:
The not equivalent (!~) operator for lists returns true if its arguments are not equivalent.
The not equivalent operator is a shorthand for invocation of logical negation (not) of the equivalent operator.
Signature:
properly includes(left List<T>, right List<T>) BooleanDescription:
The properly includes operator for lists returns true if the first list contains every element of the second list, and the first list is strictly larger than the second list.
This operator uses the notion of equivalence to determine whether or not two elements are the same.
If the left argument is null, the result is false, else if the right argument is null, the result is true if the left argument is not empty.
Note that the order of elements does not matter for the purposes of determining inclusion.
Signature:
properly included in(left List<T>, right list<T>) BooleanDescription:
The properly included in operator for lists returns true if every element of the first list is in the second list and the first list is strictly smaller than the second list.
This operator uses the notion of equivalence to determine whether or not two elements are the same.
If the left argument is null, the result is true if the right argument is not empty. Otherwise, if the right argument is null, the result is false.
Note that the order of elements does not matter for the purposes of determining inclusion.
Signature:
singleton from(argument List<T>) TDescription:
The singleton from operator extracts a single element from the source list. If the source list is empty, the result is null. If the source list contains one element, that element is returned. If the list contains more than one element, a run-time error is thrown.
If the source list is null, the result is null.
Signature:
Skip(argument List<T>, number Integer) List<T>Description:
The Skip operator returns the elements in the list, skipping the first number elements. If the list has less number elements, the result is empty.
If the source list is null, the result is null.
If the number of elements is null, the result is the entire list, no elements are skipped.
If the number of elements is less than zero, the result is an empty list.
Signature:
Tail(argument List<T>) List<T>Description:
The Tail operator returns all but the first element from the given list. If the list is empty, the result is empty.
If the source list is null, the result is null.
Signature:
Take(argument List<T>, number Integer) List<T>Description:
The Take operator returns the first number elements from the given list. If the list has less than number elements, the result only contains the elements in the list.
If the source list is null, the result is null.
If number is null, or 0 or less, the result is an empty list.
Signature:
union(left List<T>, right List<T>) List<T>Description:
The union operator for lists returns a list with all elements from both arguments. Note that duplicates are eliminated during this process; if an element appears in both sources, that element will only appear once in the resulting list.
If either argument is null, the result is null.
Note that the union operator can also be invoked with the symbolic operator (|).
Signature:
AllTrue(argument List<Boolean>) BooleanDescription:
The AllTrue operator returns true if all the non-null elements in the source are true.
If the source contains no non-null elements, true is returned.
If the source is null, the result is true.
Signature:
AnyTrue(argument List<Boolean>) BooleanDescription:
The AnyTrue operator returns true if any non-null element in the source is true.
If the source contains no non-null elements, false is returned.
If the source is null, the result is false.
Signature:
Avg(argument List<Decimal>) Decimal
Avg(argument List<Quantity>) QuantityDescription:
The Avg operator returns the average of the non-null elements in the source.
If the source contains no non-null elements, null is returned.
If the source is null, the result is null.
Signature:
Count(argument List<T>) IntegerDescription:
The Count operator returns the number of non-null elements in the source. If the list contains no non-null elements, the result is 0. If the list is null, the result is 0.
Signature:
Max(argument List<Integer>) Integer
Max(argument List<Decimal>) Decimal
Max(argument List<Quantity>) Quantity
Max(argument List<DateTime>) DateTime
Max(argument List<Time>) Time
Max(argument List<String>) StringDescription:
The Max operator returns the maximum element in the source. Comparison semantics are defined by the comparison operators for the type of value being aggregated.
If the source contains no non-null elements, null is returned.
If the source is null, the result is null.
Signature:
Min(argument List<Integer>) Integer
Min(argument List<Decimal>) Decimal
Min(argument List<Quantity>) Quantity
Min(argument List<DateTime>) DateTime
Min(argument List<Time>) Time
Min(argument List<String>) StringDescription:
The Min operator returns the minimum element in the source. Comparison semantics are defined by the comparison operators for the type of value being aggregated.
If the source contains no non-null elements, null is returned.
If the source is null, the result is null.
Signature:
Median(argument List<Decimal>) Decimal
Median(argument List<Quantity>) QuantityDescription:
The Median operator returns the median of the elements in source.
If the source contains no non-null elements, null is returned.
If the source is null, the result is null.
Signature:
Mode(argument List<T>) TDescription:
The Mode operator returns the statistical mode of the elements in source.
If the source contains no non-null elements, null is returned.
If the source is null, the result is null.
Signature:
PopulationStdDev(argument List<Decimal>) Decimal
PopulationStdDev(argument List<Quantity>) QuantityDescription:
The PopulationStdDev operator returns the statistical standard deviation of the elements in source.
If the source contains no non-null elements, null is returned.
If the source is null, the result is null.
Signature:
PopulationVariance(argument List<Decimal>) Decimal
PopulationVariance(argument List<Quantity>) QuantityDescription:
The PopulationVariance operator returns the statistical population variance of the elements in source.
If the source contains no non-null elements, null is returned.
If the source is null, the result is null.
Signature:
StdDev(argument List<Decimal>) Decimal
StdDev(argument List<Quantity>) QuantityDescription:
The StdDev operator returns the statistical standard deviation of the elements in source.
If the source contains no non-null elements, null is returned.
If the list is null, the result is null.
Signature:
Sum(argument List<Integer>) Integer
Sum(argument List<Decimal>) Decimal
Sum(argument List<Quantity>) QuantityDescription:
The Sum operator returns the sum of non-null elements in the source.
If the source contains no non-null elements, null is returned.
If the list is null, the result is null.
Signature:
Variance(argument List<Decimal>) Decimal
Variance(argument List<Quantity>) QuantityDescription:
The Variance operator returns the statistical variance of the elements in source.
If the source contains no non-null elements, null is returned.
If the source is null, the result is null.
Signature:
AgeInYears() Integer
AgeInMonths() Integer
AgeInWeeks() Integer
AgeInDays() Integer
AgeInHours() Integer
AgeInMinutes() Integer
AgeInSeconds() IntegerDescription:
The Age operators calculate the age of the patient as of now in the precision named in the operator.
If the patient’s birthdate is null, the result is null.
The Age operators are defined in terms of a DateTime duration calculation. This means that if the age of the patient is not specified to the level of precision corresponding to the operator being invoked, the result will be an uncertainty over the range of possible values, potentially causing some comparisons to return null.
Signature:
AgeInYearsAt(asOf DateTime) Integer
AgeInMonthsAt(asOf DateTime) Integer
AgeInWeeksAt(asOf DateTime) Integer
AgeInDaysAt(asOf DateTime) Integer
AgeInHoursAt(asOf DateTime) Integer
AgeInMinutesAt(asOf DateTime) Integer
AgeInSecondsAt(asOf DateTime) IntegerDescription:
The AgeAt operators calculate the age of the patient as of the given date in the precision named in the operator.
If the patient’s birthdate is null, or the asOf argument is null, the result is null.
The AgeAt operators are defined in terms of a DateTime duration calculation. This means that if the age of the patient or the given asOf value are not specified to the level of precision corresponding to the operator being invoked, the will be an uncertainty over the range of possible values, potentially causing some comparisons to return null.
Signature:
CalculateAgeInYears(birthDate DateTime) Integer
CalculateAgeInMonths(birthDate DateTime) Integer
CalculateAgeInWeeks(birthDate DateTime) Integer
CalculateAgeInDays(birthDate DateTime) Integer
CalculateAgeInHours(birthDate DateTime) Integer
CalculateAgeInMinutes(birthDate DateTime) Integer
CalculateAgeInSeconds(birthDate DateTime) IntegerDescription:
The CalculateAge operators calculate the age of a person born on the given birthdate as of now in the precision named in the operator.
If the birthdate is null, the result is null.
The CalculateAge operators are defined in terms of a DateTime duration calculation. This means that if the given birthDate is not specified to the level of precision corresponding to the operator being invoked, the result will be an uncertainty over the range of possible values, potentially causing some comparisons to return null.
Signature:
CalculateAgeInYearsAt(birthDate DateTime, asOf DateTime) Integer
CalculateAgeInMonthsAt(birthDate DateTime, asOf DateTime) Integer
CalculateAgeInWeeksAt(birthDate DateTime, asOf DateTime) Integer
CalculateAgeInDaysAt(birthDate DateTime, asOf DateTime) Integer
CalculateAgeInHoursAt(birthDate DateTime, asOf DateTime) Integer
CalculateAgeInMinutesAt(birthDate DateTime, asOf DateTime) Integer
CalculateAgeInSecondsAt(birthDate DateTime, asOf DateTime) IntegerDescription:
The CalculateAgeAt operators calculate the age of a person born on the given birthdate as of the given date in the precision named in the operator.
If the birthDate is null or the asOf argument is null, the result is null.
The CalculateAgeAt operators are defined in terms of a DateTime duration calculation. This means that if the given birthDate or asOf are not specified to the level of precision corresponding to the operator being invoked, the result will be an uncertainty over the range of possible values, potentially causing some comparisons to return null.
Signature:
=(left Code, right Code) Boolean
=(left Concept, right Concept) BooleanDescription:
The equal (=) operator for Codes and Concepts uses tuple equality semantics. This means that the operator will return true if and only if the values for each element by name are equal.
If either argument is null, or contains any null components, the result is null.
Signature:
~(left Code, right Code) BooleanDescription:
The ~ operator for Code values returns true if the code and system elements are equivalent. The version and display elements are ignored for the purposes of determining Code equivalence.
For Concept values, equivalence is defined as a non-empty intersection of the codes in each Concept. The display element is ignored for the purposes of determining Concept equivalence.
Note that this operator will always return true or false, even if either or both of its arguments are null, or contain null components.
Note carefully that this notion of equivalence is not the same as the notion of equivalence used in terminology: “these codes represent the same concept.” CQL specifically avoids defining terminological equivalence. The notion of equivalence defined here is used to provide consistent and intuitive semantics when dealing with missing information in membership contexts.
Signature:
in(code String, codesystem CodeSystemRef) Boolean
in(code Code, codesystem CodeSystemRef) Boolean
in(concept Concept, codesystem CodeSystemRef) BooleanDescription:
The in (Codesystem) operators determine whether or not a given code is in a particular codesystem. Note that these operators can only be invoked by referencing a defined codesystem.
For the String overload, if the given code system contains a code with an equivalent code element, the result is true.
For the Code overload, if the given code system contains an equivalent code, the result is true.
For the Concept overload, if the given code system contains a code equivalent to any code in the given concept, the result is true.
If the code argument is null, the result is null.
Signature:
in(code String, valueset ValueSetRef) Boolean
in(code Code, valueset ValueSetRef) Boolean
in(concept Concept, valueset ValueSetRef) BooleanDescription:
The in (Valueset) operators determine whether or not a given code is in a particular valueset. Note that these operators can only be invoked by referencing a defined valueset.
For the String overload, if the given valueset contains a code with an equivalent code element, the result is true.
For the Code overload, if the given valueset contains an equivalent code, the result is true.
For the Concept overload, if the given valueset contains a code equivalent to any code in the given concept, the result is true.
If the code argument is null, the result is null.
Signature:
Message(source T, condition Boolean, code String, severity String, message String) TDescription:
The Message operator provides a run-time mechanism for returning messages, warnings, traces, and errors to the calling environment.
The source operator is any type and the result of the operation is the input source; the operation performs no modifications to input. This allows the message operation to appear at any point in any expression of CQL.
The condition is used to determine whether the message is generated and returned to the calling environment. If condition is true, the message is generated. Otherwise, the operation only returns the results and performs no processing at all.
The code provides a coded representation of the error. Note that this is a token (like a string or integer), not a terminology Code.
The severity determines what level of processing should occur for the message that is generated:
Message – The operation produces an informational message that is expected to be made available in some way to the calling environment.
Warning – The operation produces a warning message that is expected to be made conspicuously available to the calling environment, potentially to the end-user of the logic.
Trace – The operation produces an informational message that is expected to be made available to a tracing mechanism such as a debug log in the calling environment. In addition, some representation of the contents of the source parameter should be made available to the tracing mechanism.
Error – The operation produces a run-time error and return the message to the calling environment. This is the only severity that stops evaluation. All other severities continue evaluation of the expression.
If no severity is supplied, a default severity of Message is assumed.
The message is the content of the actual message that is sent to the calling environment.
Note that for Trace severity, the implementation should output the contents of the source parameter as part of the trace message. Because the logic may be operating on patient information, the utmost care should be taken to ensure that appropriate safeguards are in place to avoid logging sensitive information. At a minimum, all PHI should be redacted from these trace messages.