# 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 of sv evaluates the polynomial,
(d![n]*b exp n) + ... +d![0]
where d is the list of digits, n is the count of d, and b is the base. Thus, the following expressions are valid,
```	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 function trim is 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 function cor is 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 function cov is 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))
```
The cross operator 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 value tan x is (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 function var is 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 expression w wavg b is 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 expression w wsum b is 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 function dev is 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 function med is 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 of deltas contains the initial item of source in 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 of ratios contains the initial item of source in 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 by bin is generally more efficient than the linear search algorithm used by in.

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 of bin should be in strictly increasing order for the result to meaningful, this condition is not enforced. The results of bin when 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 use count to 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
3 jefferson
1 wasington
show distinct tdup
a b
------------
1 washington
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), distinct produces 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 of inter on lists is not the same as intersection of sets. In particular, the result of inter does 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 of 0# 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 function sublist to 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), union does 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 the value function 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 the where function. 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 expression x 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