Typed parameters¶
A q function signature tells you how many arguments a function takes and what they are called. With the pattern matching that kdb+ 4.1 added, it can also say what type each argument must be, and how a list argument unpacks into names. peachq supports both, in the standard syntax.
q)quote:{[sym:`s;size:`j;price:`f] (sym;size;price)}
q)quote[`IBM;100;1.5]
`IBM
100
1.5
q)quote[`IBM;100;1]
'type
| feature | syntax | status |
|---|---|---|
| type checks | {[x:`j;y:`f] … } |
supported |
| list patterns | {[x;(m;n)] … } |
supported |
| null pattern | {[x;] … } |
supported |
| filter functions | {[x:check] … } |
not supported |
| defaults, varargs, named apply | {[x;y=10] … }, {[...rest] … }, .[f;`x`y!1 2] |
not supported |
Type checks¶
Annotate a parameter with : and a type symbol.
Type checking is exact. A float is not accepted where a long is declared, and a long is not accepted where a float is declared: there is no automatic widening. If you want a float parameter, pass a float:
Atoms and lists¶
Lowercase means an atom and uppercase means a list:
This is worth understanding before you annotate: an annotation narrows a function. An
unannotated q function often works on both atoms and vectors, and declaring `j gives that
up.
Iterators are unaffected, because they pass atoms:
Annotate where you want the narrowing: boundaries, public entry points, anything called from somewhere you cannot see. Leave general-purpose internal functions unannotated.
Type symbols¶
The type character is the standard one, lowercase for an atom and uppercase for a list:
| symbol | type | symbol | type | symbol | type | ||
|---|---|---|---|---|---|---|---|
`b |
boolean | `e |
real | `d |
date | ||
`g |
guid | `f |
float | `z |
datetime | ||
`x |
byte | `c |
char | `n |
timespan | ||
`h |
short | `s |
symbol | `u |
minute | ||
`i |
int | `p |
timestamp | `v |
second | ||
`j |
long | `m |
month | `t |
time |
There is no character for a table, a dictionary, a general list or a function, so those parameters go unannotated. A type position takes exactly one type character: an unknown character, a list of characters or a type name is rejected when the function is defined.
List patterns¶
A parameter can be a list pattern in parentheses. The argument is unpacked into the names, which are local to the function, as any parameter is.
Patterns nest, and a name inside a pattern can carry a type check of its own:
The same patterns work on the left of an assignment, where they need parentheses:
The null pattern¶
An empty slot in the parameter list is the null pattern: the function takes that argument and ignores it.
Errors¶
| you get | when |
|---|---|
'parse |
the signature itself is not valid, reported when the function is defined |
'type |
an argument does not match its declared type |
'length |
a list argument has a different count from its list pattern |
'rank |
too many arguments |
A bad type character is a load-time error: it cannot reach production, because the file will not load.
Not supported¶
| not supported | write this instead |
|---|---|
filter functions, {[x:tempCheck] … } |
validate on the first line of the body |
defaults, {[x;y=10] … } |
test for the argument in the body, or define a projection |
varargs, {[...rest] … } |
compose with enlist: v:('[{x};enlist]) makes v[1;2;3] give 1 2 3 |
named apply, .[f;`x`y!1 2] |
pass a dictionary as one argument and index it |
| dictionary and table patterns | index the dictionary or table in the body |
Portability¶
Type checks and list patterns use the pattern syntax that kdb+ 4.1 introduced. A function annotated with type checks, such as this one, uses no PeachQ-specific syntax: