Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Type Assertions

A type assertion has the form

<expr> . ( <type> )

where <expr> is any expression and <type> is any type. Its value is the value of <expr> when that value has type <type> and is otherwise none, which disappears from a record, array, or map, is dropped from the output of the values operator, and is typically handled with the ?? operator, e.g.,

v.(string) ?? "default"

A type assertion is a postfix operator that binds like the dot operator, so assertions and field accesses may be chained, e.g., a.b.(string) or x.(Push)?.ref.

A value has the asserted type when

  • its type is <type>, including a union, option, or named type, in which case the value keeps its type,
  • <type> is a union type and the value’s type is one of its member types, in which case the value keeps its member type,
  • it is a value of a union type whose member has the asserted type,
  • it is an option value whose some value has the asserted type, or
  • it is a fusion value whose subtype is the asserted type.

An option’s none has an option type, so it’s the value of an assertion of its option type, e.g., x.(option(int64)), and is otherwise none.

Named types are distinct, e.g., a value of type port=uint16 has type port but not type uint16.

Unlike a cast, a type assertion never converts a value, so "1".(int64) is none while "1"::int64 is 1. An error or missing value is passed through rather than becoming none (unless it has the asserted type) so that, e.g., a misspelled field name isn’t hidden by a default value.

Note

A number literal must be parenthesized, e.g., (1).(int64), since 1. is a floating-point literal.

Examples


Assert a type with a default for other types

# spq
values this.(string) ?? "not a string"
# input
"hello"
1
{s:"x"}
# expected output
"hello"
"not a string"
"not a string"

A type assertion doesn’t convert values (unlike a cast)

# spq
values {assert:this.(int64) ?? -1, cast:this::int64}
# input
"1"
2
# expected output
{assert:-1,cast:1}
{assert:2,cast:2}

Assert a union type to accept any of its member types

# spq
values this.(int64|float64) ?? 0
# input
1
2.5
"x"
# expected output
1
2.5
0

The member of a union value and the some value of an option are asserted

# spq
values this.(int64) ?? -1
# input
1::(int64|string)
"a"::(int64|string)
some(2)
none::int64
# expected output
1
-1
2
-1

An option value is asserted as is or on its some value

# spq
values {opt:typeof(this.(option(int64))), val:typeof(this.(int64))}
# input
some(1)
none::int64
# expected output
{opt:<option(int64)>,val:<int64>}
{opt:<option(int64)>,val:<none>}

Select a variant of a sum type and access its fields

# spq
type Push={kind:string,ref:string}
type Watch={kind:string,action:string}
values this::(Push|Watch)
| values this.(Push)?.ref ?? "not a push"
# input
{kind:"Push",ref:"main"}
{kind:"Watch",action:"started"}
# expected output
"main"
"not a push"

A failed assertion is none so it disappears from a record

# spq
values {s:x.(string),n:x.(int64)}
# input
{x:"a"}
{x:1}
# expected output
{s:"a"}
{n:1}