Skip to main content

Type Cast Functions

Some operators expect their operands to have a certain data type. For example, logical operators expect their operands to be boolean values, and the arithmetic operators expect their operands to be numeric values. If an operation is performed with operands of other types, an automatic conversion to the expected types is tried. This is called implicit type casting. It helps to avoid query aborts.

Type casts can also be performed upon request by invoking a type cast function. This is called explicit type casting. C8QL offers several functions for this. Each of the these functions takes an operand of any data type and returns a result value with the type corresponding to the function name. For example, TO_NUMBER() will return a numeric value.

TO_BOOL()​

TO_BOOL(value) → bool

Take an input value of any type and convert it into the appropriate boolean value.

  • value (any): input of arbitrary type
  • returns bool (boolean):
    • null is converted to false
    • Numbers are converted to true, except for 0, which is converted to false
    • Strings are converted to true if they are non-empty, and to false otherwise
    • Arrays are always converted to true (even if empty)
    • Objects / documents are always converted to true

It's also possible to use double negation to cast to boolean:

!!1 // true
!!0 // false
!!-0.0 // false
not not 1 // true
!!"non-empty string" // true
!!"" // false

TO_BOOL() is preferred however, because it states the intention clearer.

TO_NUMBER()​

TO_NUMBER(value) → number

Take an input value of any type and convert it into a numeric value.

  • value (any): input of arbitrary type

  • returns number (number):

    • null and false are converted to the value 0

    • true is converted to 1

    • Numbers keep their original value

    • Strings are converted to their numeric equivalent if the string contains a valid representation of a number. Whitespace at the start and end of the string is allowed. String values that do not contain any valid representation of a number will be converted to the number 0.

    • An empty array is converted to 0, an array with one member is converted into the result of TO_NUMBER() for its sole member. An array with two or more members is converted to the number 0.

    • An object / document is converted to the number 0.

      A unary plus will also cast to a number, but TO_NUMBER() is the preferred way:


+'5' // 5 +[8] // 8 +[8,9] // 0 +{} // 0

```
A unary minus works likewise, except that a numeric value is also negated:
```js

-'5' // -5 -[8] // -8 -[8,9] // 0 -{} // 0

```

TO_STRING()​

TO_STRING(value) → str

Take an input value of any type and convert it into a string value.

  • value (any): input of arbitrary type
  • returns str (string):
    • null is converted to an empty string ""
    • false is converted to the string "false", true to the string "true"
    • Numbers are converted to their string representations. This can also be a scientific notation (e.g. "2e-7")
    • Arrays and objects / documents are converted to string representations, which means JSON-encoded strings with no additional whitespace
TO_STRING(null) // ""
TO_STRING(true) // "true"
TO_STRING(false) // "false"
TO_STRING(123) // "123"
TO_STRING(+1.23) // "1.23"
TO_STRING(-1.23) // "-1.23"
TO_STRING(0.0000002) // "2e-7"
TO_STRING( [1, 2, 3] ) // "[1,2,3]"
TO_STRING( { foo: "bar", baz: null } ) // "{\"foo\":\"bar\",\"baz\":null}"

TO_ARRAY()​

TO_ARRAY(value) → array

Take an input value of any type and convert it into an array value.

  • value (any): input of arbitrary type
  • returns array (array):
    • null is converted to an empty array
    • Boolean values, numbers and strings are converted to an array containing the original value as its single element
    • Arrays keep their original value
    • Objects / documents are converted to an array containing their attribute values as array elements, just like VALUES()
TO_ARRAY(null) // []
TO_ARRAY(false) // [false]
TO_ARRAY(true) // [true]
TO_ARRAY(5) // [5]
TO_ARRAY("foo") // ["foo"]
TO_ARRAY([1, 2, "foo"]) // [1, 2, "foo"]
TO_ARRAY({foo: 1, bar: 2, baz: [3, 4, 5]}) // [1, 2, [3, 4, 5]]

TO_LIST()​

TO_LIST(value) → array

This is an alias for TO_ARRAY().