# PropCheck.BasicTypes (PropCheck v1.4.1) View Source

This modules contains all basic type generators from PropEr. It is
automatically available by `use PropCheck`

.

## Acknowledgments

The functions defined here are delegated to the corresponding
definition `proper_types`

. Also most of the documentation is
copied over from there.

# Link to this section Summary

## Types

Floats extend by infinity

Integers extend by infinity

Non negative integers extend by infinity

The internal representation of a basic type in PropEr

The internal representation of a type in PropEr

## Functions

All Elixir terms (that PropEr can produce).

Arity is a byte value, i.e. `integer(0, 255)`

All atoms.

All binaries.

All binaries with a byte size of `length`

.

All bitstrings.

All bitstrings with a bit size of `length`

.

bool is equivalent to `boolean`

The atoms `true`

and `false`

. Instances shrink towards `false`

.

Byte values, i.e. `integer(0, 255)`

Char values (16 bit for some reason), i.e. `integer(0, 0xffff)`

An Erlang string, i.e. `list(char)`

choose is equivalent to `integer(low, high)`

Adds a default value, `default_value`

, to `type`

.

elements is equivalent to `union([..])`

Singleton type consisting only of `value`

.

All lists whose i-th element is an instance of the type at index i of
`list_of_types`

. Also written simply as a list of types.

All floats, i.e. `float(:inf, :inf)`

All floats between `low`

and `high`

, bounds included.

frequency is equivalent to `weighted_union([..])`

All pure functions that map instances of `arg_types`

to instances of
`ret_type`

.

A function with 0 parameters, i.e. `function(0, ret_type)`

A function with 1 parameter, i.e. `function(1, ret_type)`

A function with 2 parameters, i.e. `function(2, ret_type)`

A function with 3 parameters, i.e. `function(3, ret_type)`

A function with 4 parameters, i.e. `function(4, ret_type)`

Small integers (bound by the current value of the `size`

parameter).

All integers, i.e. `integer(:inf, :inf)`

All integers between `low`

and `high`

, bounds included.

Large_int is equivalent to `integer`

List of any types, i.e. `list(any)`

All lists containing elements of type `elem_type`

.

Tuples whose elements are all of type `elem_type`

.

A map whose keys are defined by the generator `k`

and values by the generator `v`

.

Small Small non-negative integers (bound by the current value of the `size`

parameter).

Negative integers, i.e. `integer(:inf, -1)`

This is a predefined constraint that can be applied to random-length list and binary types to ensure that the produced values are never empty.

Non negative floats, i.e. `float(0.0, inf)`

Non negative integers, i.e. `integer(0, :inf)`

Creates a new type which is equivalent to `type`

, but whose instances
are never shrunk by the shrinking subsystem.

Numbers are integers or floats, i.e. `union([integer(), float()])`

oneof is equivalent to `union([..])`

All sorted lists containing elements of type `elem_type`

.

Returns the value associated with `parameter`

, or `:undefined`

in case
`parameter`

is not associated with any value.

Returns the value associated with `parameter`

, or `default`

in case
`parameter`

is not associated with any value.

Strictly positive integers, i.e. `integer(1, :inf)`

A range is equivalent to integers

real is equivalent to `float`

Overrides the `size`

parameter used when generating instances of
`type`

with `new_size`

.

return is equivalent to `exactly`

A type that generates exactly the list `list`

.

Term is a synonym for `any`

timeout values, i.e. `union([non_neg_integer() | :infinity])`

Tuples of any types, i.e. `loose_tuple(any)`

All tuples whose i-th element is an instance of the type at index i of
`list_of_types`

.

The union of all types in `list_of_types`

.

utf8-encoded unbounded size binary

utf8-encoded bounded upper size binary.

Bounded upper size utf8 binary, `codepoint length =< MaxCodePointSize`

.

All lists of length `length`

containing elements of type `elem_type`

.

A specialization of `default/2`

.

A specialization of `union/1`

, where each type in `list_of_types`

is
assigned a frequency.

Associates the atom key `parameter`

with the value `value`

while
generating instances of `type`

.

Similar to `with_parameter/3`

, but accepts a list of
`{parameter, value}`

pairs.

weighted_union(FreqChoices)

# Link to this section Types

## Specs

ext_float() :: float() | :inf

Floats extend by infinity

## Specs

ext_int() :: integer() | :inf

Integers extend by infinity

## Specs

ext_non_neg_integer() :: non_neg_integer() | :inf

Non negative integers extend by infinity

## Specs

frequency() :: pos_integer()

## Specs

raw_type() :: :proper_types.raw_type()

The internal representation of a basic type in PropEr

## Specs

size() :: PropCheck.size()

## Specs

type() :: :proper_types.type()

The internal representation of a type in PropEr

## Specs

value() :: any()

# Link to this section Functions

## Specs

any() :: type()

All Elixir terms (that PropEr can produce).

For reasons of efficiency, functions are never produced as instances of this type.

**CAUTION:** Instances of this type are expensive to produce, shrink and instance-
check, both in terms of processing time and consumed memory. Only use this
type if you are certain that you need it.

## Specs

arity() :: type()

Arity is a byte value, i.e. `integer(0, 255)`

## Specs

atom() :: type()

All atoms.

All atoms used internally by PropEr start with a `:$`

, so
such atoms will never be produced as instances of this type. You should also
refrain from using such atoms in your code, to avoid a potential clash.
Instances shrink towards the empty atom, `:""`

.

## Specs

binary() :: type()

All binaries.

Instances shrink towards the empty binary, `""`

.

## Specs

binary(non_neg_integer()) :: type()

All binaries with a byte size of `length`

.

`length`

must be an Elixir expression that evaluates to a non-negative integer.
Instances shrink towards binaries of zeroes.

## Specs

bitstring() :: type()

All bitstrings.

Instances shrink towards the empty bitstring, `""`

.

## Specs

bitstring(non_neg_integer()) :: type()

All bitstrings with a bit size of `length`

.

`length`

must be an Elixir expression that evaluates to a non-negative integer.
Instances shrink towards bitstrings of zeroes.

## Specs

bool() :: type()

bool is equivalent to `boolean`

## Specs

boolean() :: type()

The atoms `true`

and `false`

. Instances shrink towards `false`

.

## Specs

byte() :: type()

Byte values, i.e. `integer(0, 255)`

## Specs

char() :: type()

Char values (16 bit for some reason), i.e. `integer(0, 0xffff)`

## Specs

char_list() :: type()

An Erlang string, i.e. `list(char)`

## Specs

choose is equivalent to `integer(low, high)`

## Specs

Adds a default value, `default_value`

, to `type`

.

The default serves as a primary shrinking target for instances, while it is also chosen by the random instance generation subsystem half the time.

## Specs

elements is equivalent to `union([..])`

## Specs

Singleton type consisting only of `value`

.

`value`

must be an evaluated term. Also written simply as `value`

.

## Specs

All lists whose i-th element is an instance of the type at index i of
`list_of_types`

. Also written simply as a list of types.

## Specs

float() :: type()

All floats, i.e. `float(:inf, :inf)`

## Specs

All floats between `low`

and `high`

, bounds included.

`low`

and `high`

must be Elixir expressions that evaluate to floats, with
`Low =< high`

. Additionally, `low`

and `high`

may have the value `:inf`

, in
which case they represent minus infinity and plus infinity respectively.
Instances shrink towards 0.0 if `low =< 0.0 =< high`

, or towards the bound
with the smallest absolute value otherwise.

## Specs

frequency is equivalent to `weighted_union([..])`

## Specs

All pure functions that map instances of `arg_types`

to instances of
`ret_type`

.

The syntax `function(arity, ret_type)`

is also acceptable.

## Specs

A function with 0 parameters, i.e. `function(0, ret_type)`

## Specs

A function with 1 parameter, i.e. `function(1, ret_type)`

## Specs

A function with 2 parameters, i.e. `function(2, ret_type)`

## Specs

A function with 3 parameters, i.e. `function(3, ret_type)`

## Specs

A function with 4 parameters, i.e. `function(4, ret_type)`

## Specs

int() :: type()

Small integers (bound by the current value of the `size`

parameter).

Instances shrink towards `0`

.

## Specs

integer() :: type()

All integers, i.e. `integer(:inf, :inf)`

## Specs

All integers between `low`

and `high`

, bounds included.

`low`

and `high`

must be Elixir expressions that evaluate to integers, with
`low =< high`

. Additionally, `low`

and `high`

may have the value `:inf`

, in
which case they represent minus infinity and plus infinity respectively.
Instances shrink towards 0 if `low =< 0 =< high`

, or towards the bound with
the smallest absolute value otherwise.

## Specs

large_int() :: type()

Large_int is equivalent to `integer`

## Specs

list() :: type()

List of any types, i.e. `list(any)`

## Specs

All lists containing elements of type `elem_type`

.

Instances shrink towards the empty list, `[]`

.

## Specs

Tuples whose elements are all of type `elem_type`

.

Instances shrink towards the 0-size tuple, `{}`

.

## Specs

A map whose keys are defined by the generator `k`

and values by the generator `v`

.

## Specs

nat() :: type()

Small Small non-negative integers (bound by the current value of the `size`

parameter).

Instances shrink towards `0`

.

## Specs

neg_integer() :: type()

Negative integers, i.e. `integer(:inf, -1)`

## Specs

This is a predefined constraint that can be applied to random-length list and binary types to ensure that the produced values are never empty.

Use for e.g. `list/0`

, `char_list/0`

, `binary/0`

## Specs

non_neg_float() :: type()

Non negative floats, i.e. `float(0.0, inf)`

## Specs

non_neg_integer() :: type()

Non negative integers, i.e. `integer(0, :inf)`

## Specs

Creates a new type which is equivalent to `type`

, but whose instances
are never shrunk by the shrinking subsystem.

## Specs

number() :: type()

Numbers are integers or floats, i.e. `union([integer(), float()])`

## Specs

oneof is equivalent to `union([..])`

## Specs

All sorted lists containing elements of type `elem_type`

.

Instances shrink towards the empty list, `[]`

.

## Specs

Returns the value associated with `parameter`

, or `:undefined`

in case
`parameter`

is not associated with any value.

Association occurs with calling `with_parameter/3`

or `with_parameters/2`

before.

## Specs

Returns the value associated with `parameter`

, or `default`

in case
`parameter`

is not associated with any value.

Association occurs with calling `with_parameter/3`

or `with_parameters/2`

before.

## Specs

pos_integer() :: type()

Strictly positive integers, i.e. `integer(1, :inf)`

## Specs

A range is equivalent to integers

## Specs

real() :: type()

real is equivalent to `float`

## Specs

Overrides the `size`

parameter used when generating instances of
`type`

with `new_size`

.

Has no effect on size-less types, such as unions.
Also, this will not affect the generation of any internal types contained in
`type`

, such as the elements of a list - those will still be generated
using the test-wide value of `size`

. One use of this function is to modify
types to produce instances that grow faster or slower, like so:

```
iex> quickcheck(forall l <- list(integer()) do
...> length(l) <= 42
...> end)
true
iex> long_list = sized(size, resize(size * 2, list(integer())))
iex> really_long = such_that_maybe l <- long_list, when:
...> length(l) > 42
iex> quickcheck(forall l <- really_long do
...> (length(l) <= 84)
...> |> measure("List length", length l)
...> |> collect(length l)
...> end)
true
```

The above specifies a list type that grows twice as fast as normal lists.

## Specs

return is equivalent to `exactly`

## Specs

A type that generates exactly the list `list`

.

Instances shrink towards shorter sublists of the original list.

## Specs

term() :: type()

Term is a synonym for `any`

## Specs

timeout() :: type()

timeout values, i.e. `union([non_neg_integer() | :infinity])`

## Specs

tuple() :: type()

Tuples of any types, i.e. `loose_tuple(any)`

## Specs

All tuples whose i-th element is an instance of the type at index i of
`list_of_types`

.

Also written simply as a tuple of types.

## Specs

The union of all types in `list_of_types`

.

`list_of_types`

can't be empty.
The random instance generator is equally likely to choose any one of the
types in `list_of_types`

. The shrinking subsystem will always try to shrink an
instance of a type union to an instance of the first type in `list_of_types`

,
thus you should write the simplest case first.

## Specs

utf8() :: type()

utf8-encoded unbounded size binary

## Specs

utf8(ext_non_neg_integer()) :: type()

utf8-encoded bounded upper size binary.

## Specs

utf8(ext_non_neg_integer(), 1..4) :: type()

Bounded upper size utf8 binary, `codepoint length =< MaxCodePointSize`

.

Limiting codepoint size can be useful when applications do not accept full unicode range. For example, MySQL in utf8 encoding accepts only 3-byte unicode codepoints in VARCHAR fields.

If unbounded length is needed, use `:inf`

as first argument.

## Specs

vector(non_neg_integer(), raw_type()) :: type()

All lists of length `length`

containing elements of type `elem_type`

.

`length`

must be an Elixir expression that evaluates to a non-negative integer.

## Specs

A specialization of `default/2`

.

Parameters `default`

and `type`

are
assigned weights to be considered by the random instance generator. The
shrinking subsystem will ignore the weights and try to shrink using the
default value.

## Specs

A specialization of `union/1`

, where each type in `list_of_types`

is
assigned a frequency.

Frequencies must be Elixir expressions that evaluate to positive integers. Types with larger frequencies are more likely to be chosen by the random instance generator. The shrinking subsystem will ignore the frequencies and try to shrink towards the first type in the list.

## Specs

Associates the atom key `parameter`

with the value `value`

while
generating instances of `type`

.

## Specs

Similar to `with_parameter/3`

, but accepts a list of
`{parameter, value}`

pairs.

## Specs

weighted_union(FreqChoices)