# QforMortals/built in functions

# Built-in Functions

## Overview

The set of built-in functions in q is rich and powerful. In this chapter, we group functions as follows. A *string function* takes a string and returns a string. An *aggregate function* takes a list and returns an atom. A *uniform function* takes a list and returns a list of the same count. A mathematical function takes numeric arguments and returns a numeric argument derives by some numerical calculation.

Note that these categories are not mutually exclusive. For example, some mathematical functions are also aggregate functions.

## String Functions

The basic string functions perform the usual string manipulations on a list of char. There are also powerful functions that are unique to q.

### like

The dyadic `like` performs pattern matching on its first string argument (*source*) according to the pattern in its string second argument. It returns a boolean result indicating whether the pattern is matched.

The pattern is expressed as a mix of regular characters with special formatting characters. The special chars are "?", "*", the pair "![" and "]", and "^" enclosed in square brackets.

The special character "?" represents an arbitrary single character in the pattern.

"fan" like "f?n" 1b "fun" like "f?n" 1b "foP" like "f?p" 0b

The special character "*" represents an arbitrary sequence of characters in the pattern.

"how" like "h*" 1b "hercules" like "h*" 1b "wealth" like "*h" 1b "flight" like "*h*" 1b "Jones" like "J?ne*" 1b "Joynes" like "J?ne*" 0b

The special character pair "![" and "]" enclose a sequence of alternatives for a single character match.

"flap" like "fl[ao]p" 1b "flip" like "fl[ao]p" 0b "459-0609" like "[09][09][09]-0[09][09][09]" 1b "459-0609" like "[09][09][09]-1[09][09][09]" 0b

The special character "^" is used in conjunction with "![" and "]" to indicate that the enclosed sequence of characters are disallowed. For example, to test whether a string ends in a numeric character,

"M26d" like "*[^09]" 1b "Joe999" like "*[^09]" 0b

### lower

The monadic `lower` takes a char or string argument and returns the result of converting any alpha characters to lower case.

lower "A" "a" lower "a Bc42De" "a bc42de"

### ltrim

The monadic `ltrim` takes a string argument and returns the result of removing leading blanks.

ltrim " abc " "abc "

You can also apply `ltrim` to a non-blank char,

ltrim "a" "a"

### rtrim

The monadic `rtrim` takes a string argument and returns the result of removing trailing blanks.

rtrim " abc " " abc"

You can also apply `rtrim` to a non-blank char,

rtrim "a" "a"

### ss

The dyadic `ss` ("string search") performs the same pattern matching as like on its first string argument (*source*) according to the pattern in its string second argument. However, the result of `ss` is a list containing the position(s) of the matches of the pattern in *source*.

"Now is the time for all good men to come to" ss "me" 13 29 38 "fun" ss "f?n" ,0

If no matches are found, an empty int list is returned.

"aa" ss "z" `int$()

### string

The monadic `string` can be applied to any q entity to produce a textual representation of the entity. For scalars, lists and functions, the result of `string` is a list of char that does not contain any q formatting characters. Following are some examples,

string 42 "42" string 6*7 "42" string 42422424242j "42422424242" string `Zaphod "Zaphod" f:{[x] x*x} string f "{[x] x*x}"

The next example demonstrates that `string` is not atomic, because the result of applying it to an atom is a *list* of char.

string "4" ,"4"

The next example may be surprising.

string 0x42 "42"

To see why, recall that a string can be parsed into q data using Cast ($) with the appropriate upper-case type domain character. Now, converting to a string and parsing from a string should be inverse maps, in that their composite returns the original input value. That is, we should find,

"X"$string 0x42 0x42

Thus, the behavior of `string` is determined by that of parse.

"X"$"42" 0x42

Comparing these two results, we see that the result of `string` on a `byte` must not contain the format characterless. This reasoning works for other types as well.

Although `string` is not atomic (it returns a list from an atom), it does act like an atomic function in that its application is extended item-wise to a list.

string 42 98 ("42";"98") string 1 2 3 (,"1";,"2";,"3") string "Beeblebrox" (,"B";,"e";,"e";,"b";,"l";,"e";,"b";,"r";,"o";,"x") string(42; `life; ("the"; 0x42)) ("42";"life";((,"t";,"h";,"e");"42"))

Considering a list as a mapping, we see that `string` acts on the range of the mapping. By thinking of a dictionary as a generalized list, we conclude that the action of `string` on a dictionary should also apply to its range.

d:1 2 3!100 101 102 string d 1 2 3!("100";"101";"102")

A table is the flip of a column dictionary, so we expect `string` to operate on the range of the column dictionary.

t:([] a:1 2 3; b:`a`b`c) string t +`a`b!((,"1";,"2";,"3");(,"a";,"b";,"c"))

Finally, a keyed table is a dictionary, so we expect `string` to operate on the value table.

kt:([k:1 2 3] c:100 101 102) string kt (+(,`k)!,1 2 3)!+(,`c)!,("100";"101";"102")

### sv

The basic form of dyadic `sv` ("string from vector") takes a char as its left operand and a list of strings (*source*) as its right operand. It returns a string that is the concatenation of the strings in *source*, separated by the specified char.

";" sv("Now";"is";"the";"time";"") "Now;is;the;time;"

When `sv` is used with an empty symbol as its left operand and a list of symbols as its right operand (*source*), the result is a symbol in which the items in *source* are concatenated with a separating dot.

` sv `qalib`stat `qalib.stat

This is useful for q directory names.

When `sv` is used with an empty symbol as its left operand and a symbol right operand (*source*) whose first item is a file handle, the result is a symbol in which the items in *source* are concatenated with a separating forward-slash. This is useful for fully qualified q path names.

` sv `:/q`tutorial`draft1 `:/q/tutorial/draft1

When `sv` is used with an int left operand (*base*) that is greater than 1, together with a right operand of a simple list of place values expressed in *base*, the result is an int representing the converted base 10 value.

2 sv 101010b 42 10 sv 1 2 3 4 2 12342 256 sv 0x001092 4242

More precisely, the last version ofsvevaluates the polynomial,where d is the list of digits, n is the count of d, and b is the base. Thus, the following expressions are valid,

- (d![n]*b exp n) + ... +d![0]

10 sv 1 2 3 11 2 12412 -10 sv 2 1 5 195

### trim

The monadic `trim` takes a string argument and returns the result of removing leading and trailing blanks.

trim " abc " " abc"

The functiontrimis equivalent to,

{ltrim rtrim x}

You can also apply `trim` to a non-blank char,

trim "a" "a"

### upper

The monadic `upper` takes a char or string argument and returns the result of converting any alpha characters to upper case.

upper "a" "A" upper "a Bc42De" "A BC42DE"

### vs

The dyadic `vs` ("vector from string") takes a char as its left operand and a string (*source*) as its right operand. It returns a list of strings containing the tokens of *source* as delimited by the specified char.

" " vs "Now is the time " ("Now";"is";"the";"time";"")

When `vs` is used with an empty symbol as its left operand and a symbol right operand (*source*) containing separating dots, it returns a simple symbol list obtained by splitting *source* along the dots.

` vs `qalib.stat `qalib`stat

When `vs` is used with an empty symbol as its left operand and a symbol representing a fully qualified file name as the right operand, it returns a simple list of symbols in which the first item is the path and the second item is the file name.

` vs `:/q/tutorial/draft `:/q/tutorial`draft

Note that in the last usage, `vs` is not exactly the inverse of `sv`.

When `vs` is used with a null of binary type as the left operand and an int value as the right operand (*source*), it returns a simple list whose items comprise the digits of the corresponding binary representation of *source*.

0x00 vs 4242 0x00001092 0b vs 42 00000000000000000000000000101010b

The last expression shows the internal representation of special values.

0b vs 0W 01111111111111111111111111111111b 0b vs -0W 10000000000000000000000000000001b

## Mathematical Functions

The mathematical functions perform the basic mathematical operations necessary for calculations. Their implementations are efficient.

### acos

The monadic `acos` is the mathematical inverse of `cos`. For a float argument between -1 and 1, it returns the float between 0 and π whose cosine is the argument.

sqrt 2:1.414213562373095 acos 1 0f acos sqrt2 0n acos -1 3.141592653589793 acos 0 1.570796326794897

### asin

The monadic `asin` is the mathematical inverse of `sin`. For a float argument between -1 and 1, it returns the float between –π/2 and π/2 whose sine is the argument.

sqrt 2:1.414213562373095 asin 0 0f asin sqrt2%2 0.7853982 asin 1 1.570796 asin -1 -1.570796326794897

### atan

The monadic `atan` is the mathematical inverse of `tan`. For a float argument, it returns the float between –π/2 and π/2 whose tangent is the argument.

sqrt 2:1.414213562373095 atan 0 0f atan sqrt2 0.9553166181245093 atan 1 0.7853981633974483

### cor

The dyadic `cor` takes two numeric lists of the same count and returns a float equal to the mathematical correlation between the items of the two arguments.

23 -11 35 0 cor 42 21 73 39 0.9070229

The functioncoris equivalent to,

{cov[x;y]%dev[x]*dev y}

### cos

The monadic `cos` takes a float argument and returns the mathematical cosine of the argument.

pi:3.141592653589793 cos 0 1f cos pi%3 0.5000000000000001 cos pi%2 6.123032e-017 cos pi -1f

### cov

The dyadic `cov` takes a numeric atom or list in both arguments and returns a float equal to the mathematical covariance between the items of the two arguments. If both arguments are lists, they must have the same count.

98 cov 42 0f 23 -11 35 0 cov 42 21 73 39 308.4375

The functioncovis equivalent to,

{avg[x*y]-avg[x]*avg y}

### cross

The binary `cross` takes atoms or lists as arguments and returns their Cartesian product—that is, the set of all pairs drawn from the two arguments.

1 2 cross `a`b`c ((1;`a);(1;`b);(1;`c);(2;`a);(2;`b);(2;`c))

Thecrossoperator is equivalent to the function,

{x,\:/:y}'

### sin

The monadic `sin` takes a float argument and returns the mathematical sine of the argument.

pi:3.141592653589793 sin 0 0f sin pi%4 0.7071068 sin pi%2 1f sin pi 1.224606e-016

### tan

The monadic `tan` takes a float argument and returns the mathematical tangent of the argument.

The valuetan xis(sin x)%cos x

pi:3.141592653589793 tan 0 0f tan pi%8 0.4142136 tan pi%4 1f tan pi%2 1.633178e+016 tan pi -1.224606e-016

### var

The monadic `var` takes a scalar or numeric list and returns a float equal to the mathematical variance of the items.

var 42 0f var 42 45 37 38 10.25

The functionvaris equivalent to

{[x] (avg[x*x]) - (avg[x])*(avg[x])}

### wavg

The dyadic `wavg` takes two numeric lists of the same count and returns the average of the second argument weighted by the first argument. The result is always of type float.

1 2 3 4 wavg 500 400 300 200 300f

The expressionw wavg bis equivalent to,

(sum w*a)%sum w

In our example,

(sum (1 2 3 4)*500 400 300 200)%sum 1 2 3 4 300f

It is possible to apply `wavg` to a nested list provided all sublists of both arguments conform. In this context, the result conforms to the sublists and the weighted average is calculated recursively across the sublists.

(1 2;3 4) wavg (500 400; 300 200) 350 266.6667 ((1;2 3);(4;5 6)) wavg ((600;500 400);(300;200 100)) (360f;28A1.7143 200)

### wsum

The dyadic `wsum` takes two numeric lists of the same count and returns the sum of the second argument weighted by the first argument. The result is always of type float.

1 2 3 4 wsum 500 400 300 200 3000f

The expressionw wsum bis equivalent to,

sum w*a

In our example,

sum (1 2 3 4)*500 400 300 200 3000

It is possible to apply `wsum` to a nested list provided all sublists of both arguments conform. In this context, the result conforms to the sublists and the weighted sum is calculated recursively across the sublists.

(1 2;3 4) wsum (500 400;300 200) 1400 1600 ((1;2 3);(4;5 6)) wsum ((600;500 400);(300;200 100)) (1800;2000 1800)

## Aggregate Functions

An aggregate function operates on a list and returns an atom. Aggregates are especially useful with grouping in select expressions.

### all

The monadic `all` takes a scalar or list of numeric type and returns the result of `&` applied across the items.

all 1b 1b all 100100b 0b all 10 20 30 10

### any

The monadic `any` takes a scalar or list of numeric type and returns the result of `|` applied across the items.

any 1b 1b any 100100b 1b any 2001.01.01 2006.10.13 2006.10.13

### avg

The monadic `avg` takes a scalar, list, dictionary or table of numeric type and returns the arithmetic average. The result is always of type float.

avg 42 42.0 avg 1 2 3 4 5 3f avg `a`b`c!10 20 40 20f

It is possible to apply `avg` to a nested list provided the sublists conform. In this context, the result conforms to the sublists and the average is calculated recursively on the sublists.

avg (1 2; 100 200; 1000 2000) 367 734f avg ((1 2;3 4); (100 200;300 400)) (50.5 101;151.5 202)

For tables, the result is a dictionary that maps the column names to their value averages.

show t c1 c2 ------ 1.1 5 2.2 4 3.3 3 4.4 2 show avg t c1| 2.75 c2| 3.5

### dev

The monadic `dev` takes a scalar, list, or dictionary of numeric type and returns the standard deviation. For result is a float.

dev 42 0f dev 42 45 37 38 3.201562 dev `a`b`c!10 20 40 12.47219

The functiondevis equivalent to

{[x] sqrt[var[x]]}

### med

The monadic `med` takes a list, dictionary or table of numeric type and returns the statistical median.

For lists and dictionaries, the result is a float.

med 42 21 73 39 40.5 med `a`b`c!10 20 40 20f

The functionmedis equivalent to,

{$[n:count x;.5*sum x[rank x]@floor .5*n-1 0;0n]}

For tables, the result is a dictionary mapping the column names to their value medians.

show t c1 c2 ------ 1.1 5 2.2 4 3.3 3 4.4 2 show med t c1| 2.75 c2| 3.5

### prd

The monadic `prd` takes a scalar, list, dictionary or table of numeric type and returns the arithmetic product.

For scalars, lists and dictionaries the result has the type of its argument.

prd 42 42 prd 1.1 2.2 3.3 4.4 5.5 193.2612 prd `a`b`c!10 20 40 60

It is possible to apply `prd` to a nested list provided the sublists conform. In this case, the result conforms to the sublists and the product is calculated recursively on the sublists.

prd (1 2; 100 200; 1000 2000) 100000 800000 prd ((1 2;3 4); (100 200;300 400)) (100 400;900 1600)

For tables, the result is a dictionary that maps the column names to the products.

show t c1 c2 ------ 1.1 5 2.2 4 3.3 3 4.4 2 show prd t c1| 35.1384 c2| 120

### sum

The monadic `sum` takes a scalar, list, dictionary or table of numeric type and returns the arithmetic sum.

For scalars, lists and dictionaries the result has the type of its argument.

sum 42 42 sum 1.1 2.2 3.3 4.4 5.5 16.5 sum `a`b`c!10 20 40 60

It is possible to apply `sum` to a nested list provided the sublists conform. In this case, the result conforms to the sublists and the sum is calculated recursively on the sublists.

sum (1 2; 100 200; 1000 2000) 1101 2202 sum ((1 2;3 4); (100 200;300 400)) (101 202;303 404)

For tables, the result is a dictionary that maps the column names to the sums.

show t c1 c2 ------ 1.1 5 2.2 4 3.3 3 4.4 2 show sum t c1| 11 c2| 14

## Uniform Functions

Uniform functions operate on lists and return lists of the same shape. They are useful in select expressions.

### deltas

The uniform `deltas` takes as its argument (*source*) a scalar, list, dictionary or table of numeric type and returns the difference of each item from its predecessor.

deltas 42 42 deltas 1 2 3 4 5 1 1 1 1 1 deltas 96.25 93.25 58.25 73.25 89.50 84.00 84.25 96.25 -3 -35 15 16.25 -5.5 0.25 deltas `a`b`c!10 20 40 `a`b`c!10 10 20 show t c1 c2 ------ 1.1 5 2.2 4 3.3 3 4.4 2 show deltas t c1 c2 ------ 1.1 5 1.1 -1 1.1 -1 1.1 -1

As the third example shows, the result ofdeltascontains the initial item ofsourcein its initial position. This may be inconsistent with the behavior of similar functions in other languages or libraries that return 0 in the initial position. The alternate behavior can be achieved with the expression

1_deltas (1#x),x

In our example above,

1_deltas (1#x),x:96.25 93.25 58.25 73.25 89.50 84.00 84.25 0 -3 -35 15 16.25 -5.5 0.25

### fills

The uniform `fills` takes as its argument (*source*) a scalar, list, dictionary or table of numeric type and returns a copy of the *source* in which non-null items are propagated forward to fill nulls.

fills 42 42 fills 1 0N 3 0N 5 1 1 3 3 5 fills `a`b`c`d`e`f!10 0N 30 0N 0N 60 `a`b`c`d`e`f!10 10 30 30 30 60 show tt c1 c2 ----- 1 a b 3 d show fills tt c1 c2 ----- 1 a 1 b 3 b 3 d

**Note**: Initial nulls are not affected by `fills`.

fills 0n 0n 3 0n 5 0n 0n 3 3 5

### mavg

The uniform dyadic `mavg` takes as its first argument an int (*length*) and as its second argument (*source*) a numeric list. It returns the moving average of *source*, where the average is calculated over *length* consecutive items.

For items in the source at position less than *length*-1, the average is calculated from the initial item. For *length* 1, the result is the source converted to `float`. For *length* less than or equal to 0 it returns nulls.

2 mavg 1 2 3 4 5 1 1.5 2.5 3.5 4.5 3 mavg 1 2 3 4 5 1 1.5 2 3 4

### maxs

The uniform `maxs` takes as its argument (*source*) a scalar, list, dictionary or table and returns the cumulative maximum of the *source* items.

maxs 42 42 maxs 1 2 5 4 10 1 2 5 5 10 maxs "Beeblebrox" "Beeelllrrx" maxs `a`b`c`d!10 30 20 40 `a`b`c`d!10 30 30 40 show t c1 c2 ------ 1.1 5 2.2 4 3.3 3 4.4 2 show maxs t c1 c2 ------ 1.1 5 2.2 5 3.3 5 4.4 5

### mcount

The uniform dyadic mcount takes as its first argument an int (length) and as its second argument (source) a numeric list. It returns the moving count of source, obtained by applying count over length consecutive items. For positions less than length-1, count is applied only through that position.

This function is most useful in computing other moving quantities.

For example.

3 mcount 10 20 30 40 50 1 2 3 3 3

For length less than or equal to 0 the result is all zeroes

### mdev

The uniform dyadic mdev takes as its first argument an int (length) and as its second argument (source) a numeric list. It returns the moving standard deviation of source, obtained by applying dev over length consecutive items. For positions less than length-1, dev is applied only through that position.

In the following example, the first item in the result is the standard deviation of itself only; the second result item is the standard deviation of the first two source items; all other items reflect the standard deviation of the item at the position along with its two predecessors.

3 mdev 10 20 30 40 50 0 5 8.164966 8.164966 8.164966

For length less than or equal to 0 the result is all nulls.

### mins

The uniform `mins` takes as its argument (*source*) a scalar, list, dictionary or table and returns the cumulative minimum of the *source* items.

mins 42 42 mins 10 4 5 1 2 10 4 4 1 1 mins "Beeblebrox" "BBBBBBBBBB" mins `a`b`c`d!40 10 30 20 `a`b`c`d!40 10 10 10 show t c1 c2 ------ 1.1 5 2.2 4 3.3 3 4.4 2 show mins d a| 10 b| 10 c| 10

### mmax

The uniform dyadic mmax takes as its first argument an int (length) and as its second argument (source) a numeric list. It returns the moving maximum of source, obtained by applying max over length consecutive items. For positions less than length-1, max is applied only through that position.

In the following example, the first item in the result is the max of itself only; the second result item is the sumaxm of the first two source items; all other items reflect the max of the item at the position along with its two predecessors.

3 mmax 20 10 30 50 40 20 20 30 50 50

For length less than or equal to 0 the result is source.

### mmin

The uniform dyadic mmin takes as its first argument an int (length) and as its second argument (source) a numeric list. It returns the moving minimum of source, obtained by applying min over length consecutive items. For positions less than length-1, min is applied only through that position.

In the following example, the first item in the result is the min of itself only; the second result item is the min of the first two source items; all other items reflect the min of the item at the position along with its two predecessors.

3 mmin 20 10 30 50 40 20 10 10 10 30

For length less than or equal to 0 the result is source.

### msum

The uniform dyadic msum takes as its first argument an int (length) and as its second argument (source) a numeric list. It returns the moving sum of source, obtained by applying sum over length consecutive items. For positions less than length-1, sum is applied only through that position.

In the following example, the first item in the result is the sum of itself only; the second result item is the sum of the first two source items; all other items reflect the sum of the item at the position along with its two predecessors.

3 msum 10 20 30 40 50 10 30 60 90 120

For length less than or equal to 0 the result is all zeroes.

### next

The uniform `next` takes as its argument (*source*) a scalar, list or table of numeric type and returns the *source* shifted one position to the left with no wrapping. The last item of the result is a null matching the type of *source*.

next 42 42 next 1 2 3 4 5 2 3 4 5 0N show t c1 c2 ------ 1.1 5 2.2 4 3.3 3 4.4 2 show next t c1 c2 ------ 2.2 4 3.3 3 4.4 2

### prds

The uniform `prds` takes as its argument (*source*) a scalar, list, dictionary or table of numeric type and returns the cumulative product of the *source* items.

prds 42 42 prds 1 2 3 4 5 1 2 6 24 120 prds `a`b`c!10 20 40 `a`b`c!10 200 8000 show t c1 c2 ------ 1.1 5 2.2 4 3.3 3 4.4 2 show prds t c1 c2 ----------- 1.1 5 2.42 20 7.986 60 35.1384 120

### prev

The uniform `prev` takes as its argument (*source*) a scalar, list, dictionary or table of numeric type and returns the *source* shifted one position to the right with no wrapping. The initial item of the result is a null matching the type of *source*.

prev 42 42 prev 1 2 3 4 5 0N 1 2 3 4 prev `a`b`c!10 20 40 `a`b`c!0N 10 20 show t c1 c2 ------ 1.1 5 2.2 4 3.3 3 4.4 2 show prev t c1 c2 ------ 1.1 5 2.2 4 3.3 3

### rank

The uniform `rank` takes as its argument (*source*) a list, dictionary or table of numeric type and returns the order of each item in the *source* under an ascending sort.

rank 5 2 3 1 4 4 1 2 0 3 rank `a`b`c`e`f! 5 2 3 1 4 4 1 2 0 3

For tables and keyed tables, the result is a list with the rank of the records under ascending sort of the first column or the key column.

show tt c1 c2 ------ 2.2 1 1.1 2 3.3 3 5.5 4 4.4 5 show rank tt 1 0 2 4 3 show kt k | d ---| - 103| 1 102| 2 101| 3 105| 4 104| 5 rank kt 2 1 0 4 3

### ratios

The uniform `ratios` takes as its argument (*source*) a scalar, list, dictionary or table of numeric type and returns the ratios of each item to its predecessor as float values.

ratios 42 42 ratios 1 2 3 4 5 1 2 1.5 1.333333 1.25 ratios 96.25 93.25 58.25 73.25 89.50 84.00 84.25 96.25 0.9688312 0.6246649 1.257511 1.221843 0.9385475 1.002976 deltas `a`b`c!10 20 40 `a`b`c!10 2 2f show t c1 c2 ------ 1.1 5 2.2 4 3.3 3 4.4 2 show ratios t c1 c2 ------------------ 1.1 5 2 0.8 1.5 0.75 1.333333 0.6666667

As the second example shows, the result ofratioscontains the initial item ofsourcein its initial position. This may be inconsistent with the behavior of similar functions in other languages or libraries that return 1 in the initial position. The alternate behavior can be achieved with the expression.

1,ratios 1_x

In our example above,

1,ratios 1_x:96.25 93.25 58.25 73.25 89.50 84.00 84.25 (1;93.25;0.6246649;1.257511;1.221843;0.9385475;1.002976)

### rotate

The uniform dyadic `rotate` takes as its first argument an int (*length*) and as its second argument (*source*) a numeric list or table. It returns the source shifted *length* positions to the left with wrapping if *length* is positive, or *length* positions to the right with wrapping if *length* is negative. For *length* 0, it returns the source.

2 rotate 1 2 3 4 5 3 4 5 1 2 -2 rotate 1 2 3 4 5 4 5 1 2 3 show t c1 c2 ------ 1.1 5 2.2 4 3.3 3 4.4 2 show 2 rotate t c1 c2 ------ 3.3 3 4.4 2 1.1 5 2.2 4

### sums

The uniform `sums` takes as its argument (*source*) a scalar, list, dictionary or table of numeric type and returns the cumulative sum of the *source* items.

sums 42 42 sums 1 2 3 4 5 1 3 6 10 15 sums `a`b`c!10 20 40 `a`b`c!10 30 70 show t c1 c2 ------ 1.1 5 2.2 4 3.3 3 4.4 2 show sums t c1 c2 ------ 1.1 5 3.3 9 6.6 12 11 14

### xbar

The uniform dyadic `xbar` takes as its first argument a non-negative numeric atom (*width*) and a second argument (*source*) that is a numeric list, dictionary or table. It returns an entity that conforms to *source*, in which each item of *source* is mapped to the largest multiple of the *width* that is less than or equal to that item. The type of the result is that of the *width* parameter.

3 xbar 2 7 12 17 22 0 6 12 15 21 5.5 xbar 59.25 53.75 81.00 96.25 93.25 58.25 73.25 89.50 84.00 84.25 55 49.5 77 93.5 88 55 71.5 88 82.5 82.5 15 xbar `a`b`c!10 20 40 `a`b`c!0 15 30 show t c1 c2 ------ 1.1 5 2.2 4 3.3 3 4.4 2 show 2 xbar t c1 c2 ----- 0 4 2 4 2 2 4 2

It is possible to apply `xbar` to a nested list. In this context, the result conforms to *source* and the *interval width* mapping is applied recursively to the sublists.

5 xbar ((11;21 31);201 301) ((10;20 30);200 300)

### xprev

The dyadic xprev takes an int as its first argument (shift) and is uniform in its second argument (source), which can be a list a dictionary or a table. It returns a result that conforms to source.

When shift is 0 or positive, each entity in source is shifted shift positions forward in the result, with the initial shift entries null filled.

2 xprev 10 20 30 40 0N 0N 10 20 2 xprev `a`b`c`d!10 20 40 80 ```a`b!0N 0N 10 20 t:([]c1:`a`b`c`d;c2:10 20 30 40) 2 xprev t +`c1`c2!(```a`b;0N 0N 10 20)

When shift is negative, the result is a copy of source with the initial shift entries null filled.

-2 xprev 10 20 30 40 0N 0N 30 40

### xrank

The binary xrank is uniform in its right operand (source), which is a list, dictionary, table or keyed table whose values are sortable. The left operand is a positive int (quantile). It returns a list of int containing the quantile of the source distribution to which each item of source belongs. The analysis is applied to the range of a dictionary and the first column of a table.

For example, by choosing quantile to be 4, xrank determines into which quartile each item of source falls.

4 xrank 30 10 40 20 90 1 0 2 0 3 4 xrank `a`b`c`d`e!30 10 40 20 90 1 0 2 0 3 t:([]c1:30 10 40 20 90;c1:`a`b`c`d`e) 4 xrank t 1 0 2 0 3

Choosing quantile to be 100 gives per cetile ranaking.

## Miscellaneous Functions

We collect here the built-in functions that don’t fit into any of the previously defined categories.

### bin

The dyadic `bin` takes a simple list of items (*target*) in strictly increasing order as its first argument and is atomic in its second argument (*token*). Loosely speaking, the result of bin is the position at which *token* would fall in *target*.

More precisely, the result is -1 if *token* is less than the first item in *target*. Otherwise, the result is the position of the right-most item of *target* that is less than or equal to *token*; this reduces to the found position if the token is in *target*. If *token* is greater than the last item in *target*, the result is the count of *target*

For large ordered lists, the binary search performed bybinis generally more efficient than the linear search algorithm used byin.

Some examples with simple lists,

1 2 3 4 bin 3 2 "xyz" bin "a" -1 1.0 2.0 3.0 bin 0.0 2.0 2.5 3.0 -1 1 1 2

Observe that the type of *token* must strictly match that of *target*.

1 2 3 bin 1.5 'type

We can apply `bin` to a dictionary to perform reverse lookup, provided the dictionary domain is in increasing order. When *source* is a dictionary, `bin` takes a *token* whose type matches that of the dictionary range. The result is null if *token* is less than every item of the range. Otherwise, the result is the right-most domain element whose corresponding range element is less than or equal to *token*.

Note that the result reduces to the corresponding domain item if *token* is found in *target*, and it reduces to the last domain item if *token* is greater than every range item.

d:10 20 30!`first`second`third d bin `second 20 d bin `missing 10 d bin `zero 30 d bin `aaa 0N

Because a table is a list of records, we expect `bin` to return the row number of a record and it does.

show t a b --- 1 a 2 b 3 c t bin `a`b!(2;`b) 1

As always, the record can be abbreviated to the list of row values.

t bin (1;`a) 0 t bin (0;`z) 0N

Observe that a record that is not found results in a null result.

Finally, since a keyed table is a dictionary, `bin` will perform a reverse lookup on a record of the value table, which can be abbreviated to a list of row values.

show kt k| c -| --- 1| 100 2| 101 3| 102 kt bin (enlist `c)!enlist 101 (,`k)!,2 kt bin 101 (,`k)!,2

While the items of the first argument ofbinshould be in strictly increasing order for the result to meaningful, this condition is not enforced. The results ofbinwhen the first argument is not strictly increasing are predictable but not particularly useful.

### count

The monadic `count` returns the number of entities in its argument. Its domain comprises scalars, lists, dictionaries, tables and keyed tables. It returns the non-negative integer representing the number of elements of its argument.

count 3 1 count 10 20 30 3 count `a`b`c`d!10 20 30 40 4 count ([] a:10 20 30; b:1.1 2.2 3.3) 3 count ([k:10 20] c:`one`two) 2

You cannot usecountto determine whether an entity is a scalar or list since scalars and singletons both have count 1.

count 3 1 count enlist 3 1

This test is accomplished instead by testing the sign of the type of the entity with signum.

Do you know why they call it count? Because it loves to count!! Nyah, ha, ha, ha, ha. Vun, and two, and three, and....

### cut (_)

When the first argument of dyadic `_` is a list of non-negative int and the second argument (*source*) is a list, it produces a new list obtained by cutting the *source* into sublists at the positions indicated in the first argument,

An example will make this clear.

0 3_100 200 300 400 500 (100 200 300;400 500)

Each sublist includes the items from the beginning cut position up to, but not including, the next cut position. The final cut includes the items to the end of the *source*. Observe that if the left argument does not begin with 0, the initial items of the *source* will not be included in the result.

2 4_2006.01 2006.02 2006.03 2006.04 2006.05 2006.06 (2006.03 2006.04;2006.05 2006.06)

When the right operand of cut is a dictionary (*source*) and the left operand of cut is a list of key values whose type matches *source*, the result is a dictionary obtained by removing the specified key-value pairs from the target.

For example,

d:1 2 3!`a`b`c (enlist 42) _ d 1 2 3!`a`b`c (enlist 2) _ d 1 3!`a`c 1 3 _ d (,2)!,`b (enlist 32) _ d 1 2 3!`a`b`c 1 2 3 _ d (`int$())!`symbol$()

The operand must be a list, so a single key value must be enlisted.

### delete (_)

When the first argument of dyadic _ is a list or a dictionary (*source*) and the second argument is a position in the list or an item in the domain of the dictionary, the result is a new entity obtained by deleting the specified item from the *source*.

Whitespace is required on both sides of_when it is used as cut

L: 101 102 103 104 105 L _ 2 101 102 104 105 d:`a`b`c`d!101 102 103 104 d _ `b `a`c`d!101 103 104

Since a table is a list, delete can be applied by row number.

t:([]c1:1 2 3;c2:101 102 103;c3:`x`y`z) show t c1 c2 c3 --------- 1 101 x 2 102 y 3 103 z show t _ 1 c1 c2 c3 --------- 1 101 x 3 103 z

Since a keyed table is a dictionary, delete can be applied by key value.

kt:([k:101 102 103]c:`one`two`three) show kt k | c ---| ----- 101| one 102| two 103| three show kt _ 102 k | c ---| ----- 101| one 103| three

### distinct

The monadic function `distinct` returns the distinct entities in its argument. For a list, it returns the distinct items in the list, in order of first occurrence.

distinct 1 2 3 2 3 4 6 4 3 5 6 1 2 3 4 6 5

For a table, `distinct` returns a table comprising the distinct records of the argument, in the order of first occurrence.

show tdup a b ------------ 1 washington 2 adams 3 jefferson 2 adams 1 wasington show distinct tdup a b ------------ 1 washington 2 adams 3 jefferson 1 wasington

Observe that all fields of the records must be identical for the records to be considered identical. Otherwise put, if any field differs, the records are distinct.

As of this writing (Oct 2006),distinctproduces unpredictable results for a scalar argument.

distinct 42 37 distinct 42 39

### drop (_)

When the first argument of the dyadic `_` is an int and the second argument (*source*) is a list, the result is a new list created via removal from *source*. A positive integer in the first argument indicate that the removal occurs from the beginning of the *source*, whereas a negative integer in the first argument indicates that the removal occurs from the end of the *source*.

The *source* can be a list, a dictionary, a table or a keyed table.

2_10 20 30 40 30 40 -3_`one`two`three`four`five `one`two 2_`a`b`c`d!10 20 30 40 `c`d!30 40 show -1_([] a:10 20 30 40; b:1.1 2.2 3.3 4.4) a b ------ 40 4.4 show 2_([k:10 20 30] c:`one`two`three) k | c --| ----- 30| three

The result of drop is of the same type and shape as *source* and is never a scalar.

1_42 67 ,67

In the degenerate case, the result is an empty entity derived from the *source*.

4_10 20 30 40 `int$() 3_`a`b`c`d!10 20 30 40 (`symbol$())!`int$() show 4_([] a:10 20 30 40; b:1.1 2.2 3.3 4.4) a b --- show 3_([k:10 20 30] c:`one`two`three) k| c -| -

### except

The dyadic `except` takes a simple list (*target*) as its first argument and returns a list containing the items of *target* that are not in its second argument, which can be a scalar or a list. The returned items are in the order of their first occurrence in *target*.

1 2 3 4 3 2 except 2 1 3 4 3 1 2 3 4 3 2 except 1 2 10 3 4 3 "Now is the time_" except "_" "Now is the time"

The result of `except` is always a list.

1 2 except 1 ,2 1 2 except 2 1 `int$()

### fill (^)

The dyadic `fill` takes an atom as its first argument and a list (*target*) as its second argument and returns a list obtained by substituting the first argument for every occurrence of null in *target*.

42^1 2 3 0N 5 0N 1 2 3 42 5 42 ";"^"Now is the time" "Now;is;the;time" `NULL^`First`Second``Fourth `First`Second`NULL`Fourth

Observe that the action of fill is recursive—i.e., it is applied to sublists of the target.

42^(1;0N;(100;200 0N)) (1;42;(100;200 42))

### find (?)

When the first argument (*target*) of `?` is a simple list, find is atomic in the second argument (*source*) and returns the positions in *target* of the initial occurrence of each item of *source*.

The simplest case is when *source* is a scalar.

100 99 98 87 96?98 2 "Now is the time"?"t" 7

If *source* is not found in *target*, find returns the count of *target*—i.e., the position one past the last element.

`one`two`three?`four 3

In this context, find is atomic in its second argument, so it is extended item-wise to a *source* list.

"Now is the time"?"the" 7 8 9

Note that find always returns the position of the * first* occurrence of each atom.

"Now is the time"?"time" 7 4 13 9

When the first argument (*target*) of find is a general list, find considers both elements to be general lists and attempts to locate the second argument (*source*) in the target, returning the position where it is found or the count of *target* if not found.

(1 2;3 4)?3 4 1

Observe that find only compares items at the top level of the two arguments and does not look for nested items,

((0;1 2);3 4;5 6)?1 2 3 ((0;1 2);3 4;5 6)?(1;(2;3 4)) 3

When the first argument (*target*) of find is a dictionary, find represents reverse lookup and is atomic in the second argument (*source*). In other words, find returns the domain item mapping to *source* if *source* is in the range, or a null appropriate to the domain type otherwise.

d 1 2 3!100 101 102 d?101 2 d?99 0N d?102 100 3 1

When the first argument (*target*) of find is a table and the second argument (*source*) is a record of the target, find returns the position of *source* if it is in *target*, or the count of *target* otherwise.

show t a b --- 1 a 2 b 3 c t?`a`b!(2;`b) 1

As usual with records, you can abbreviate the record to its row values.

t?(3;`c) 2

When the first argument (*target*) of find is a keyed table, since a keyed table is a dictionary, find performs a reverse lookup on a record from the value table.

show kt k| c -| --- 1| 100 2| 101 3| 102 kt?`c!101 (,`k)!,2

As usual, a record of the value table can be abbreviated to its row values.

kt?102 (,`k)!,3

### flip

The monadic function `flip` takes a rectangular list, a column dictionary or a table as its argument (*source*). The result is the transpose of *source*.

When *source* is a rectangular list, the items are rearranged so that the first two indices in indexing at depth are effectively reversed. For example,

L:(1 2 3; (10 20; 100 200; 1000 2000)) L[1;0] 10 20 FL:flip L FL ((1;10 20);(2;100 200);(3;1000 2000)) FL[0;1] 10 20

When *source* is a column dictionary, the result is a table with the given column names and values. Row and column access are effectively reversed, but no data is rearranged.

d:(`a`b`c!1 2 3;1.1 2.2 3.3;("one";"two";"three")) show d a| 1 2 3 b| 1.1 2.2 3.3 c| one two three d[`b;0] 1.1 t:flip d show t a b c ----------- 1 1.1 one 2 2.2 two 3 3.3 three t[0;`b] 1.1

When *source* is a table, the result is the underlying column dictionary. Row and column access are effectively reversed, but no data is rearranged.

t:([]a:1 2 3;b:1.1 2.2 3.3;c:("one";"two";"three")) show t a b c ----------- 1 1.1 one 2 2.2 two 3 3.3 three t[1;`c] "two" d:flip t show d a| 1 2 3 b| 1.1 2.2 3.3 c| one two three d[`c;1] "two"

### in

The dyadic function `in` is atomic in its first argument (*source*) and takes a second argument that is an atom or list. It returns a boolean result that indicates whether the *source* appears in the second argument. The comparison is strict with regard to type.

3 in 8 0b 42 in 0 6 7 42 98 1b "cat" in "abcdefg" 110b `zap in `zaphod`beeblebrox 0b 2 in 0 2 4j 'type

### inter

The dyadic `inter` can be applied to lists, dictionaries and tables. It returns an entity of the same type as its arguments, containing those elements of the first argument that appear in the second argument.

1 1 2 3 inter 1 2 3 4 1 1 2 3 "ab cd " inter " bc f" "b c "

Observe that the items of the first argument appear first in the result.

Lists are not sets and the operation ofinteron lists is not the same as intersection of sets. In particular, the result ofinterdoes not comprise the distinct items common to the two arguments. One consequence is that the expression

(x inter y)~y inter x

is __not__ true in general.

When applied to dictionaries, `inter` returns the set of range items that are mapped from the common domain items.

d1:1 2 3!100 200 300 d2:2 4 6!200 400 600 d1 inter d2 ,200

Tables that have the same columns can participate in `inter`. The result is a table with the records that are common to the two tables.

show t1 a b -------- 1 first 2 second 3 third show t2 a b -------- 2 second 4 fourth 6 sixth show t1 inter t2 a b -------- 2 second

### join (,)

The dyadic join (`,`) can take many different combinations of parameters.

When both operands are either lists or atoms, the result is a list with the item(s) of the left operand followed by the item(s) of the right operand.

2,3 2 3 `a,`b`c `a`b`c "xy","z" "xyz" 1.1 2.2,3 4 (1.1;2.2;3;4)

Observe that the result is a general list unless all items are of a homogeneous type.

When both operands are dictionaries, the result is the merge of the dictionaries using upsert semantics. The domain of the result is the (set theoretic) union of the two domains. Range assignment of the right operand prevails on common domain items.

d1:1 2 3!`a`b`c d2:3 4 5!`cc`d`e d1,d2 1 2 3 4 5!`a`b`cc`d`e

When both operands are tables having the same column names and types, the result is a table in which the records of the right operand are appended to those of the left operand.

t1:([]a:1 2 3;b:`x`y`z) show t1 a b --- 1 x 2 y 3 z t2:([]a:3 4;b:`yy`z) q)show t2 a b ---- 3 yy 4 z show t1,t2 a b ---- 1 x 2 y 3 z 3 yy 4 z

When both operands are keyed tables having the same key and value columns, the result is a keyed table in which the records of the left operand are upserted by those of the right operand.

kt1:([k:1 2 3]v:`a`b`c) show kt1 k| v -| - 1| a 2| b 3| c kt2:([k:3 4]v:`cc`d) show kt2 k| v -| -- 3| cc 4| d show kt1,kt2 k| v -| -- 1| a 2| b 3| cc 4| d

### null

The atomic function `null` takes a list (*source*) and returns a binary list comprising the result of testing each item in *source* against null.

null 1 2 3 0N 5 0N 000101b null `a`b``d```f 0010110b

Since `null` is atomic, it is applied recursively to sublists.

null (1 2;3 0N) (00b;01b)

It is useful to combine `where` with `null` to obtain the positions of the null items.

where null 1 2 3 0N 5 0N 3 5

When applied to a dictionary (*source*), `null` returns a dictionary in which each item in the *source* range is replaced with the result of testing the item against null.

null 1 2 3!100 0N 300 1 2 3!010

The action of `null` on a table (*source*) is explained by recalling that the table as a flipped column dictionary. Based on the action of `null` on a dictionary, we expect the result of `null` on a table is a new table in which each column value in the source is replaced with the result of testing the value against null.

tnull +`a`b!(1 0N 3;0N 200 300) null tnull +`a`b!(010b;100b)

Similarly, we expect `null` to operate on a keyed table by returning a new keyed table whose value table entries are the result of testing those of the source against null.

show ktnull k | col ---| ----- 101| first 102| 103| third `show null ktnull k | col ---| --- 101| 0 102| 1 103| 0

### rand (?)

The dyadic function `?` is overloaded to have different meanings. In the case where both arguments are numeric scalars, `?` returns a list of random numbers. More specifically, the first argument must be of integer type, and the second argument can by any numeric value. In this context, `?` returns a list of pseudo-random numbers of count given by first argument.

In case the second argument is a positive number of floating point type and the first argument is positive, the result is a list of random float selected * with* replacement from the range between 0 (inclusive) and the second argument (exclusive).

5?4.2 3.778553 1.230056 1.572286 0.517468 0.07107598

In case the second argument is of integer type and the first argument is positive, the result is a list of random integers selected * with* replacement from the range between 0 (inclusive) and the second argument (exclusive).

10?5 1 2 0 3 4 4 4 0 3 1 10?5 0 2 1 0 2 4 2 3 4 0 1+10?5 4 2 3 3 3 2 1 1 5 3

The last example shows how to select random integers between 1 and 5. More generally, for integers i and j, where i<j, and any integer n, the idiom,

i+n?j+1-i

selects n random integers between i and j inclusive.

i:3 j:7 n:10 i+n?j+1-i 3 4 5 7 7 5 4 4 7 4

In case the second argument is of integer type and the first argument is negative, the result is a list of random integers selected * without* replacement from the range between 0 (inclusive) and the second argument (exclusive). Since the selected values are not replaced, the absolute value of the first argument cannot exceed the second argument

-3?5 2 3 0 -5?5 4 1 2 0 3 -6?5 'length

### raze

The monadic `raze` takes a list or dictionary (*source*) and returns the entity derived from the source by eliminating the top-most level of nesting.

raze (1 2;`a`b) (1;2;`a;`b)

One way to envision the action of `raze` is to write the source list in general form, then remove the parentheses directly beneath the outer-most enclosing pair.

raze ((1;2);(`a;`b)) (1;2;`a;`b)

Observe that `raze` only removes the top-most level of nesting and does __not__ apply recursively to sublists.

raze ((1 2;3 4);(5;(6 7;8 9))) (1 2;3 4;5;(6 7;8 9))

If *source* is not nested, the result is the source.

raze 1 2 3 4 1 2 3 4

When `raze` is applied to an atom, the result is a list.

raze 42 ,42

When `raze` is applied to a dictionary, the result is `raze` applied to the range.

dd:`a`b`c!(1 2; 3 4 5;6) raze dd 1 2 3 4 5 6

### reshape (#)

When the first argument of the dyadic `#` is a list (*shape*) of two positive int, the result reshapes the source into a rectangular list according to *shape*. Specifically, the count of the result in dimension i is given by the item in position i in *shape*. The elements are taken from the beginning of the source.

A simple example makes this clear.

2 3#1 2 3 4 5 6 (1 2 3;4 5 6)

As in the case of take, if the number of elements in the source exceeds what is necessary to form the result, trailing elements are ignored.

2 2#`a`b`c`d`e`f`g`h (`a`b;`c`d)

Similarly, if the number of elements in the source is less than necessary to form the result, the extraction resumes from the initial item of the source; this process is repeated until the result is complete.

5 4#"Now is the time" ("Now ";"is t";"he t";"imeN";"ow i")

### reverse

The monadic reverse inverts the order of the constituents of its argument. In the case of an atom, it simply returns the argument.

reverse 42 42

In the case of a list, the result is a list in which the items are in reverse order of the argument.

reverse 1 2 3 4 5 5 4 3 2 1

For nested lists, the reversal takes place only at the topmost level.

reverse (1 2 3; "abc"; `Four`Score`and`Seven) (`Four`Score`and`Seven;"abc";1 2 3)

In the case of an empty list, `reverse` returns the argument.

reverse () ()

In the case of a dictionary, `reverse` inverts both the domain and range lists.

reverse`a`b`c!1 2 3 `c`b`a!3 2 1

In the case of a table, `reverse` inverts the order of the records.

show t eid | name iq ----| -------------- 1001| Dent 42 1002| Beeblebrox 98 1003| Prefect 126 show reverse t eid | name iq ----| -------------- 1003| Prefect 126 1002| Beeblebrox 98 1001| Dent 42

Since a keyed table is a dictionary, `reverse` inverts both the domain and range tables, effectively inverting the row order.

show kt k| c -| --- 1| 100 2| 101 3| 102 show reverse kt k| c -| --- 3| 102 2| 101 1| 100

### sublist

The dyadic function `sublist` retrieves a sublist of contiguous items from a list. The left operand is a simple list of two ints: the first item is the starting position (*start*); the second item is the number of items to retrieve (*count*). The right operand (*target*) is a list or dictionary.

If *target* is a list, the result is a list comprising *count* items from *target* beginning with *start*.

L:1 2 3 4 5 1 3 sublist L 2 3 4

If *target* is a dictionary, the result is a dictionary whose domain comprises *count* items from the *target* domain beginning with *start*, and whose range is the corresponding items in the *target* range.

d:`a`b`c`d`e!1 2 3 4 5 1 3 sublist d `b`c`d!2 3 4

Since a table is a list of records, `sublist` applies to the rows of a table.

t:([]c1:`a`b`c`d`e;c2:1 2 3 4 5) show 1 3 sublist t c1 c2 ----- b 2 c 3 d 4

Since a keyed table is a dictionary, `sublist` can be applied to the key table.

kt:([k:`a`b`c`d`e]c1:1 2 3 4 5) show 1 3 sublist kt k| c1 -| -- b| 2 c| 3 d| 4

### take (#)

When the first argument of the dyadic `#` is an int scalar, it creates a new entity via extraction from its second argument (*source*) as specified by its left argument. A positive integer in the left argument indicates that the extraction occurs from the beginning of the *source*, whereas a negative integer in the left argument indicates that the extraction occurs from the end of the *source*.

The *source* can be an atom, a list, a dictionary, a table or a keyed table.

2#3 3 3 -1#10 20 30 40 ,40 -2#`a`b`c`d!10 20 30 40 `c`d!30 40 show 3#([] a:10 20 30 40; b:1.1 2.2 3.3 4.4) a b ------ 10 1.1 20 2.2 30 3.3 show 1#([k:10 20 30] c:`one`two`three) k | c --| --- 10| one

The result of take is of the same type and shape as the *source*, except the result is never a scalar.

1#42 ,42

If the number of elements in *source* exceeds what is necessary to form the result, trailing elements are ignored.

4#`a`b`c`d`e`f`g`h (`a`b`c`d)

If the number of elements in *source* is less than necessary to form the result, the extraction resumes from the starting point of the *source* list; this process is repeated until the result is filled.

5#98 99 98 99 98 99 98 -7#`a`b`c `c`a`b`c`a`b`c

In the degenerate case, the result is an empty entity with the same type(s) as the source.

0#42 `int$() 0#10 20 30 40 `int$() 0#`a`b`c`d!10 20 30 40 (`symbol$())!`int$() show 0#([] a:10 20 30 40; b:1.1 2.2 3.3 4.4) a b --- show 0#([k:10 20 30] c:`one`two`three) k| c -| -

Since the result of0#is a list, we can use this construct as shorthand to initialize an empty value column with a definite type in a table definition. This ensures that only values of the specified type can be inserted into the column. For example,

([] a:0#0; b:0#`) +`a`b!(`int$();`symbol$())

defines an empty table whose first column is of type int and whose second column is of type symbol.

### til

The monadic `til` returns a list of the integers from 0 to n-1, where its argument n is a positive, non-zero integer.

til 4 0 1 2 3

The result of `til` is always a list. So,

til 1 ,0

Generating sequences is simple with `til`.

2*til 10 0 2 4 6 8 10 12 14 16 18 20+til 5 20 21 22 23 24 0.5*til 10 0 0.5 1 1.5 2 2.5 3 3.5 4 4.5

The function `til` is useful for extracting sublists from a list. The idiom

L[i+til n]

extracts from the list `L` the sublist of length n starting with the element in position i. For example,

L:10 20 30 40 50 60 70 i:2 n:3 L[i+til n] 30 40 50 60

Similarly, the idiom

L[i+til j+1-i]

extracts the sublist from positions i through j, inclusive. With `L` and `i` as above,

j:5 L[i+til j+1-i] 20 30 40 50 60

In the second idiom, omitting the increment-by-one retrieves one less item than you probably intend. This is an easy error to make.

These idioms are useful for extracting substrings.

s:"abcdefg" i:1 n:2 j:4 s[i+til n] "bc" s[i+til j+1-i] "bcde"

You can also use the built-in functionsublistto retrieve substrings.

The value of `til 0` is the empty `int` list

til 0 int$()

{{{1}}}

L~L[til count L]

is true for every list `L`. Both these expression remain valid in the degenerate case of the empty list and count 0.

### union

The dyadic `union` can be applied to lists and tables. It returns an entity of the same type as its arguments containing the distinct elements from both arguments.

1 union 2 3 1 2 3 1 2 union 2 3 1 2 3 1 1 3 union 1 2 3 1 1 3 2 "a good time" union "was had by all" "a godtimewshbyl"

Observe that the items of the first argument appear first in the result.

Tables that have the same columns can participate in `union`. The result is a table with the distinct records from the combination of the two tables.

t1:([]a:1 2 3 4;b:`first`second`third`fourth) t2:([]a:2 4 6;b:`dos`cuatro`seis) show t1 a b -------- 1 first 2 second 3 third 4 fourth show t2 a b -------- 2 dos 4 cuatro 6 seis show t1 union t2 a b -------- 1 first 2 second 3 third 4 fourth 2 dos 4 cuatro 6 seis

As of this writing (Oct 2006),uniondoes not apply to dictionaries or keyed tables.

### value

The function `value` has two uses. When applied to a dictionary, `value` returns the range of the dictionary.

d `a`b`c!1 2 3 value d 1 2 3

Therefore, for a keyed table, `value` returns the value table.

show kt k | c1 ---| -- 101| a 102| b 103| c show value kt c1 -- a b c

When `value` is applied to a string, it passes the string through the q interpreter and returns the result.

value "6*7" 42 value "{x*x} til 10" 0 1 4 9 16 25 36 49 64 81 z:98.6 value"z" 98.6 value "a:6;b:7;c:a*b" 42 a 6 b 7 c 42

This use of thevaluefunction is a very powerful feature that allows q code to be written and executed on the fly. If abused, it can quickly lead to unmaintainable code. (The spellchecker suggests "unmentionable" instead of "unmaintainable." How did it know?)

A common use of `value` is to convert a symbol containing the name of a q entity into the value associated with the entity.

a:42 s:`a value `a 42 value s 42

### where

The monadic `where` takes a boolean list and returns a list of int comprising the positions in the argument having value `1b`.

where 00110101b 2 3 5 7

This is useful when the boolean list is generated by a test on a list.

L:"Now;is;the;time" where L=";" 3 6 10 L[where L=";"]:" " L "Now is the time"

The behavior of the where phrase of the select template is related to thewherefunction. It limits the selection to table rows in the positions in which the values of the where expression are not zero. Since the expression involves test(s) on column value(s), the where phrase effectively selects the rows satisfying its condition, just as in SQL.

### within

The dyadic function `within` is atomic in its first argument (*source*) and takes a second argument that is a list of two items which have underlying numeric values. It returns a boolean value representing whether *source* is strictly between the two items of the second argument.

3 within 2 5 0b 100 within 0 100 0b "c" within "az" 1b 2006.11.19 2007.07.04 2008.08.12 within 2007.01.01 2007.12.31 010b

Observe that `within` is type tolerant, in the sense that the types of its arguments do not need to match, provided both arguments have underlying numeric values.

0x42 within (30h; 100j) 1b 100 within "aj" 1b

It is also possible to apply `within` to symbols since they have lexicographic order.

`ab within `a`z 1b

The expressionx within (a;b)is equivalent to

(a<x)&x<b

Thus, if the items of the second argument are not in increasing order, the result of `within` will always be `0b`.

5 within 6 2 0b

Prev: Commands, Next: References

©2006 Kx Systems, Inc. and Continuux LLC. All rights reserved.