Skip to content

QuickCheck generators

The generator library here is used for specifying random values. The library is a generator combinator library, meaning that the generators compose to make ever-more expressive generators.

In general, whenever a generator is expected as an argument to another generator, a new generator is created. For example, .qch.g.list is a generator that specifies random lists. It can optionally take another generator as an argument to specify the domain of the list. Any generator would work here, including .qch.g.list itself.

// Random Q lists
.qch.g.list[]

// Random lists of booleans
.qch.g.list .qch.g.boolean[]

// Random lists of lists of booleans
.qch.g.list .qch.g.list .qch.g.boolean[]

// Random lists of tables with an x column of lists of tables with a y column of booleans
.qch.g.reify .qch.g.list .qch.g.table ([] x: enlist .qch.g.list .qch.g.table ([] y: enlist .qch.g.boolean[] ))

.qch.g.any

A generator for a value of a random base type.

Example:

 .qch.g.reify .qch.g.any[]

.qch.g.bool

A generator for random booleans.

Example:

 .qch.g.reify .qch.g.bool[]

.qch.g.boolean

A generator for random booleans.

Example:

 .qch.g.reify .qch.g.boolean[]

.qch.g.byte

A generator for random bytes.

Note - will NOT generate nulls/infinities. For this, see .qch.g.messy.*.

Example: Any random byte

 .qch.g.reify .qch.g.byte[]

Example: Random bytes less than 0x55

 .qch.g.reify .qch.g.byte 0x55

.qch.g.char

A generator for random characters.

Example:

 .qch.g.reify .qch.g.char[]

.qch.g.compound

Generates random nested data but converts the type to a kdb+ compound data type by serializing and deserializing the data. The result is data that appears to be normal nested data but has a type value of 77h + type x

Parameter:

Name Type Description
x .qch.genS Generator seed Generator definition

Returns:

Type Description
.qch.genS Compound data generator Generator definition

Example: Generating random compound data

 data: .qch.g.reify .qch.g.compound[]
 /=> 15:20:30 08:24:51 16:26:25
 /=> 23:47:09 07:21:02 21:51:49 21:32:36 08:08:02
 /=> 15:54:15 23:28:13 16:15:22 11:24:38 11:55:21 14:08:34
 /=> `second$()
 /=> 22:16:37 14:09:14 21:24:53 04:36:38 16:20:03 15:49:10 18:15:49
 /=> ..

 type data
 /=> 95h

Example: Generating compound byte data

 data: .qch.g.reify .qch.g.compound .qch.g.byte[]
 /=> 0xb5113ba623
 /=> 0x00fbdac5d9bc1c96049fba474046c98dc24f88
 /=> 0x60d0342808
 /=> 0xa0d57c013ff5041cebeb65844eae
 /=> 0x8be2ef457bfc3a
 /=> ..

 type data
 /=> 81h

.qch.g.const

A generator for generating constant values.

Example: Constant 5s

 .qch.g.reify .qch.g.const 5

.qch.g.date

A generator for random dates.

Note - will NOT generate nulls/infinities. For this, see .qch.g.messy.*.

Example:

 .qch.g.reify .qch.g.date[]

Example:

 .qch.g.reify .qch.g.date 2012.12.31

.qch.g.datetime

A generator for random datetimes.

Note - will NOT generate nulls/infinities. For this, see .qch.g.messy.*.

Example:

 .qch.g.reify .qch.g.datetime[]

Example:

 .qch.g.reify .qch.g.datetime 2012.12.31T23:59:59.999

.qch.g.dict

A generator for random dictionaries

Example: Random dictionaries

 .qch.g.reify .qch.g.dict[]
 /=> foahnn | 0x6a
 /=> lde    | 14:10:15
 /=> jipolcm| 2276.03.28D19:29:46.168452096

Example: Random dictionaries of specified keys and types

 .qch.g.reify .qch.g.dict `a`b`c!(.qch.g.char[]; .qch.g.list .qch.g.boolean[]; .qch.g.int[])
 /=> a| "v"
 /=> b| 110b
 /=> c| -134832122i

.qch.g.elements

A generator that randomly samples from a list of values

Example: 

 .qch.g.reify .qch.g.elements (1; `hi; `a`b!1 2)
 /=> 1

Example: 

 .qch.g.reify .qch.g.list .qch.g.elements (1; `hi; `a`b!1 2)
 /=> `a`b!1 2
 /=> `hi
 /=> 1
 /=> `hi
 /=> 1
 /=> `hi
 /=> `a`b!1 2
 /=> `hi
 /=> `a`b!1 2
 /=> `hi
 /=> 1
 /=> `a`b!1 2

.qch.g.enum

Constructs a generator for random enumerated symbols. All symbols are enumerated against a global sym vector.

Parameter:

Name Type Description
range string | symbol | null Range of symbols to generate

Returns:

Type Description
.qch.genS A enumeration generator Generator definition

Example: Any random enumerated value

 .qch.g.reify .qch.g.enum[]
 /=> `sym$`ddfij

Example: An enumerated value of length 8

 .qch.g.reify .qch.g.enum 8
 /=> `sym$`mieldlnd

.qch.g.float

A generator for random floats.

Note - will NOT generate nulls/infinities. For this, see .qch.g.messy.*.

Example: Random floats

 .qch.g.reify .qch.g.float[]

Example: Floats less than 500

 .qch.g.reify .qch.g.float 500f

.qch.g.guid

A generator for random GUIDs.

Example: Random GUIDs

 .qch.g.reify .qch.g.guid[]
 /=> 3c4dcb4f-cfbd-6902-e6ff-143a01109013

.qch.g.int

A generator for random ints.

Note - will NOT generate nulls/infinities. For this, see .qch.g.messy.*.

Example: Random ints

 .qch.g.reify .qch.g.int[]

Example: Ints less than 500

 .qch.g.reify .qch.g.int 500

.qch.g.integer

A generator for random integers (shorts, ints, or longs).

Note - will NOT generate nulls/infinities. For this, see .qch.g.messy.*.

Example: Random integers

 .qch.g.reify .qch.g.integer[]

.qch.g.keyed

Generator for a random keyed table

Example: Random keyed tables

 .qch.g.reify .qch.g.keyed[]

 /=> bjkjm      dkkin      | haono lobcj        eibac                                kldpc               
 /=> ----------------------| ----------------------------------------------------------------------------
 /=> 2223.11.08 -176583628 | 1     9.383562e+37 e417caff-59f9-4cd3-5f48-76fa2cdc9791 -471413405933135178 
 /=> 2202.05.16 -1247002427| 0     6.835657e+37 6f53f082-97ab-d300-1a00-685041531f7b -3870884166007458545
 /=> 2207.02.21 -1309403346| 0     9.480811e+37 96dd94d1-b951-eb84-ac5c-9c2a3214f784 -3387762304318492719
 /=> 2282.10.22 1561366720 | 0     1.867861e+37 a0b16096-a462-5eff-09dc-61f2e753d689 766242245343837302  
 /=> 2056.01.06 -204003469 | 1     7.917941e+37 50bfd09c-9caf-17a6-4bbd-e467abd9353a 8565158336067688102

Example: Random keyed tables from a schema

 .qch.g.reify .qch.g.keyed ([a: enlist .qch.g.int[]] b:enlist .qch.g.list .qch.g.boolean[])

 /=> a          | b                   
 /=> -----------| --------------------
 /=> -1404973722| 111001010b          
 /=> -1558646847| 110010000001b       
 /=> -1056169914| 0111001011111110b   
 /=> -2061464593| 111111b             
 /=> 1700923440 | 0011011101011100011b

.qch.g.list

Generator for lists of any other generator.

Example: Random lists (homogeneous and heterogeneous)

 .qch.g.reify .qch.g.list[]

 /=> 04:10 19:22 14:58 22:24 19:59 19:51 01:33

Example: Random lists of integers

 .qch.g.reify .qch.g.list .qch.g.int[]

 /=> 151062153 -544442381 -1198138497 -53500579 890403070

Example: Random lists of lists of booleans

 .qch.g.reify .qch.g.list .qch.g.list .qch.g.boolean[]

 /=> 100b
 /=> 1011010b
 /=> 010111100111b
 /=> 0000011111110b
 /=> 1000001110b

.qch.g.listOfOver

Generator for lists of at least a given size of any other generator.

Example: Random lists of integers greater than length 2

 .qch.g.reify .qch.g.listOfOver[2] .qch.g.int[]

 /=> 151062153 -544442381 -1198138497 -53500579 890403070

Example: Random lists of non-empty lists of booleans

 .qch.g.reify .qch.g.list .qch.g.listOfOver[0] .qch.g.boolean[]

 /=> 100b
 /=> 1011010b
 /=> 010111100111b
 /=> 0000011111110b
 /=> 1000001110b

.qch.g.listn

Generator for lists of a given size of any other generator.

Example: Random lists of 5 integers less than 500

 .qch.g.reify .qch.g.listn[5] .qch.g.int 500

 /=> 274 139 36 171 338i

Example: Random lists of 3x3 matrices of booleans

 .qch.g.reify .qch.g.list .qch.g.listn[3] .qch.g.listn[3] .qch.g.boolean[]

 /=> 111b 110b 011b
 /=> 001b 000b 110b
 /=> 001b 001b 100b
 /=> 010b 010b 100b

.qch.g.long

A generator for random longs.

Note - will NOT generate nulls/infinities. For this, see .qch.g.messy.*.

Example: Random longs

 .qch.g.reify .qch.g.long[]

Example: Longs less than 500

 .qch.g.reify .qch.g.long 500

.qch.g.maxSize

Set the max size of a generator

Example: Lists of at-most 100 booleans

 .qch.g.reify .qch.g.maxSize[100] .qch.g.list .qch.g.boolean[]

 /=> 0000000011000100101110101110101011100110000010b

.qch.g.minute

A generator for random minutes.

Note - will NOT generate nulls/infinities. For this, see .qch.g.messy.*.

Example:

 .qch.g.reify .qch.g.minute[]

Example:

 .qch.g.reify .qch.g.minute 25:00

.qch.g.month

A generator for random months.

Note - will NOT generate nulls/infinities. For this, see .qch.g.messy.*.

Example:

 .qch.g.reify .qch.g.month[]

Example:

 .qch.g.reify .qch.g.month 2012.12m

.qch.g.nested

Constructs a generator for creating a list of vectors of data. The type of the vector will be the same.

Parameter:

Name Type Description
arb .qch.genS Generator to use as seed Generator definition

Returns:

Type Description
.qch.genS Nested data generator Generator definition

Example: Generating random nested data

 .qch.g.reify .qch.g.nested[]
 /=> 1020533141 2038304737 -2001980136 1197013848i
 /=> 1770832780 -910248685i
 /=> 589771609 -1553480334 266104978 -393366211 -1865821815i
 /=> 64733367 -434499523 418052461 89774811  
 /=> 2134963136 -1585171842 -1497061815 596552950 1299989849i
 /=> ..

Example: Generating nested strings

 .qch.g.reify .qch.g.nested .qch.g.char[]
 /=> "kabxluajuhqz"
 /=> "jmancm"
 /=> "aey"
 /=> ""
 /=> "kckrosuzh"
 /=> ..

.qch.g.new

Create a new generator to generate custom values. Requires three fields: see examples below.

Example: A generator with shrinking support

 myGen: .qch.g.new (
     // niladic function creating a random value
     {rand 10}; // random int
     // shrinking function
     {20?x}; // 20 random values smaller than x
     // less-than function for comparing to shrunk values in size
     <)

 .qch.g.reify myGen
 /=> 4

 .qch.summary .qch.check .qch.forall [myGen] {x=x}
 /=> "OK, passed 100 tests."

Example: A generator with no shrinking support

 myGen: .qch.g.new (
     // niladic function creating a random value
     {rand 10}; // random int
     // shrinking function
     ::; 
     // less-than function 
     ::)

 .qch.g.reify myGen
 /=> 7

 .qch.summary .qch.check .qch.forall [myGen] {x=x}
 /=> "OK, passed 100 tests."

.qch.g.null

A generator for random nulls.

.qch.g.number

A generator for random numeric values (short, int, long, real, or float).

Note - will NOT generate nulls/infinities. For this, see .qch.g.messy.*.

Example: 

 .qch.g.reify .qch.g.number[]
 /=> 352745i

.qch.g.oneof

A generator for randomly sampling from a list of other generators.

Example: Either a character or an int less than 500

 .qch.g.reify .qch.g.oneof (.qch.g.char[]; .qch.g.int 500)

Example: Either an int, or an int null or infinity

 .qch.g.reify .qch.g.oneof (.qch.g.int[]; .qch.g.const 0Ni; .qch.g.const 0Wi; .qch.g.const -0Wi)

.qch.g.oneof_w

A generator for randomly sampling from a list of other generators with weights on the sampling frequencies.

Example: An int 80% of the time, a character 20% of the time

 .qch.g.reify .qch.g.oneof_w[(.qch.g.char[]; .qch.g.int 500)] 20 80

Example: Usually an int, but occasionally an int null or infinity

 .qch.g.reify .qch.g.oneof_w [(.qch.g.int[]; .qch.g.const 0Ni; .qch.g.const 0Wi; .qch.g.const -0Wi)] 85 5 5 5

.qch.g.range.float

A generator for floats within a given range.

Example:

 .qch.g.reify .qch.g.range.float[50;100]

.qch.g.range.int

A generator for ints within a given range.

Example:

 .qch.g.reify .qch.g.range.int[50;100]

.qch.g.range.long

A generator for longs within a given range.

Example:

 .qch.g.reify .qch.g.range.long[50;100]

.qch.g.range.real

A generator for reals within a given range.

Example:

 .qch.g.reify .qch.g.range.real[50;100]

.qch.g.range.short

A generator for shorts within a given range.

Example:

 .qch.g.reify .qch.g.range.short[50;100]

.qch.g.real

A generator for random reals.

Note - will NOT generate nulls/infinities. For this, see .qch.g.messy.*.

Example: Random reals

 .qch.g.reify .qch.g.real[]

Example: Reals less than 500

 .qch.g.reify .qch.g.real 500

.qch.g.reify

Given any generator, return a concrete random value described by the generator. This is useful for testing generators before using them within .qch properties.

.qch.g.second

A generator for random seconds.

Note - will NOT generate nulls/infinities. For this, see .qch.g.messy.*.

Example:

 .qch.g.reify .qch.g.second[]

Example:

 .qch.g.reify .qch.g.time 12:00:00

.qch.g.short

A generator for random shorts.

Note - will NOT generate nulls/infinities. For this, see .qch.g.messy.*.

Example: Random shorts

 .qch.g.reify .qch.g.short[]

Example: Shorts less than 500

 .qch.g.reify .qch.g.short 500

.qch.g.symbol

A generator for random symbols.

Example: Random symbols

 .qch.g.reify .qch.g.symbol[]
 /=> `phmici

Example: Symbol of length 3 (can be specified to a length of 8)

 .qch.g.reify .qch.g.symbol 3
 `fmm

.qch.g.table

A generator for random tables.

Example: Random tables

 .qch.g.reify .qch.g.table[]

 /=> efdmh        iggdd                   gcgkm       
 /=> -------------------------------------------------
 /=> 4.524037e+37 2184.10.25T02:00:08.623 6.000541e+36
 /=> 1.240279e+38 2075.01.30T16:55:30.308 1.269743e+38
 /=> 5.251156e+35 2221.09.19T22:34:27.187 2.194081e+37
 /=> 6.122624e+37 2260.07.07T02:24:18.372 1.103271e+38
 /=> 3.799086e+37 2088.07.16T16:39:00.285 2.699894e+37
 /=> 1.208169e+38 2204.05.19T03:12:56.340 7.899556e+37
 /=> 3.141901e+37 2193.12.07T17:06:00.222 4.478858e+36

Example: Tables from a given schema

 .qch.g.reify .qch.g.table ([] x:enlist .qch.g.int[]; y:enlist .qch.g.dict[])

 /=> x           y
 /=> --------------------------------------------------------------...
 /=> -1573632087 `dkfemae`a`f`hm`pn!(12:08;2053.01.05D03:49:57.9802...
 /=> -1418157304 `kgl`mnkp`gl`ek`h`ophnmj`cph`pfcegf`k`kbkdlcj`pnoa...
 /=> 912063864   `gopmbcm`jkfmkk`klla`ikef`aicdi`npjbdkk`ded`ip`gpa...
 /=> -1686696290 `odneane`h!(04:47;15:51:03.060)                   ...
 /=> -1913423816 `ndcdod`miokb`aalkjj`hninggm`ohie!(2.304558e+37e;2...
 /=> -1590432310 `kiioda`odplhnp`mdkjodh`mjaan`meai`ncfl`cngjig`mij...
 /=> 401050771   `kflb`dojceig`bf`nanflif`oggelof`ijman`f`no`ig`eke...
 /=> -68902089   `joldn`egcg`goindlk`capp`kmhbh`imjac`pdcejn`cnc`jg...
 /=> -116753778  `cn`mfef`eglk`dcdikk`eko`nel`lcpl`bgafdji`do`bffn`...
 /=> -1964238123 `ibie`n`femm`nad`iled`kolc`pefkd`hmbknan`pebbbfa`b...
 /=> 670859816   `ngo`cmhmdf`ndjlhmd`m`epehbl`p`bce`eiin`eebhdmf`m`...
 /=> 1840155645  `mjc`laije`cahak`md`lbjma`mmlkmf!(16:40;7.13068e+3...
 /=> 1289980260  `kegdem`jd`idiad`c`jejkp`p`h`p`iic`d`hgee`ga`c`mh`...
 /=> -1358539171 `np`en`hcck`jhfd`pbmf`nldm`c`lknifc`jfpl`of`j`k`la...
 /=> -984014185  `icl`kk`la`edhhkm`edgblp`jpdeckl!(0D09:27:35.29826...
 /=> -1646344682 `dimk`bplmaa`dggckag`lco`nph`fnbblb`gemjjca`l`aibj...

Example: Keyed tables from a given schema

 .qch.g.reify .qch.g.table ([k1: enlist .qch.g.symbol[]; 
                             k2: enlist .qch.g.long[]] 
                                 x: enlist .qch.g.int[]; 
                                 y:enlist .qch.g.list .qch.g.char[])

 /=> k1     k2                  | x           y                    
 /=> ---------------------------| ---------------------------------
 /=> gkmo   -4620228702888752122| -596722939  "zbveiddit"          
 /=> p      -8969560743393333501| 1622635350  "phwngtrg"           
 /=> hnid   2290267908964463926 | -1067967729 "rxbdfwrmirybvgx"    
 /=> miim   3174895780893159393 | 455416790   "agmosdfcjlepqdvdjei"
 /=> fcdbco 5744985942359303171 | -205496694  "bqxzfkft"           
 /=> cb     -585435820506416102 | -1561250000 "nzdif"              
 /=> okianf 6464196016496855392 | 604935528   ""                   
 /=> cfap   3576779043742497448 | 894171413   "pbszohjnpmxtkts"    
 /=> bmhpe  7796861097321068210 | 1864374805  "zeszerbqlsy"

.qch.g.time

A generator for random times.

Note - will NOT generate nulls/infinities. For this, see .qch.g.messy.*.

Example:

 .qch.g.reify .qch.g.time[]

Example:

 .qch.g.reify .qch.g.time 12:00:00.000

.qch.g.timespan

A generator for random timespans.

Note - will NOT generate nulls/infinities. For this, see .qch.g.messy.*.

Example:

 .qch.g.reify .qch.g.timespan[]

Example:

 .qch.g.reify .qch.g.timespan 12:00:00.000000000

.qch.g.timestamp

A generator for random timestamps

Note - will NOT generate nulls/infinities. For this, see .qch.g.messy.*.

Example:

 .qch.g.reify .qch.g.timestamp[]

Example:

 .qch.g.reify .qch.g.timestamp 2020.12.31D23:59:59.999999999

.qch.g.tuple

A generator for tuples of a given description.

Example:

 .qch.g.reify .qch.g.tuple (.qch.g.char[]; .qch.g.list .qch.g.bool[]; .qch.g.symbol[])
 /=> ("e"; 001010111b; `emfambc)

.qch.g.unique

Returns the distinct results from the given generator

Parameter:

Name Type Description
gen .qch.genS Seed generator to get values from Generator definition

Returns:

Type Description
.qch.genS Generator definition

Example: Generating unique integers

 .qch.g.reify .qch.g.unique .qch.g.list .qch.g.int[5]
 /=> 3 0 4 1 2i

.qch.g.uniqueOfOver

Generator for a list of at least a given length of unique items.

Example:

 count distinct .qch.g.reify .qch.g.uniqueOfOver[20] .qch.g.symbol[]
 26

.qch.g.uniquen

Generates unique random data that is the same size as the data originally generated by the given generator

Parameter:

Name Type Description
gen .qch.genS Seed generator to get values from Generator definition

Returns:

Type Description
.qch.genS Generator definition

Example: Generating a unique list of 5 integers

 .qch.g.reify .qch.g.uniquen .qch.g.listn[5] .qch.g.int[]
 /=> 7 3 4 5 8i

.qch.g.vector

A generator wrapper around Q random number generation. This is much faster than generating vectors using .qch.g.listn.

Example: 20 random values between 0 and 500

 .qch.g.reify .qch.g.vector[20;500]
 /=> 452 314 81 332 193 110 210 410 245 278 446 425 143 487 145 225 242 153 127 388