The Standard Library (stdlib)

Broad collection of Rel relations that perform essential and commonly used tasks.

^Date

^Date(n, d)

Create a Date, d, representing the date at day n of the proleptic Gregorian calendar.

Example:

def output(d) = ^Date(734503, d)
//output> 2012-01-01

For more details, see the rel:base:^Date docstring.

^Date

^Date[year in Int, month in Int, day in Int]

Create a Date from its three components: year, month and day. The three arguments are required to be Int64.

^Date

^Date[dt in DateTime, tz in String]

Create a Date from a DateTime, with timezone tz.

The timezone argument is necessary for the Date because DateTime is an instant of time that is timezone independent. For different locations on earth (timezones), a DateTime has different dates.

^DateTime

^DateTime(n, dt)

Create a DateTime, dt, representing the date at millisecond n of the proleptic Gregorian calendar.

Example:

def output(dt) = ^DateTime(63568386000000, dt)
//output> 2015-05-27T05:00:00.000Z

For more details, see the rel:base:^DateTime docstring.

^DateTime

^DateTime[year, month, day, hour, minute, second, millisecond, tz in String]

Create a DateTime from a year, month, day, hour, minute, second, and millisecond.

The timezone argument tz is necessary to correctly interpret what instant in time this is.

There can be multiple DateTime values for one set of arguments: for example, with the ending of daylight saving time at 2am, every time between 1am and 2am occurs twice and has two corresponding instants of time.

For part values that are out of range, there are no tuples (there is no error).

^DateTime

^DateTime[date, hour, minute, second, millisecond, tz in String]

Create a DateTime from a date, hour, minute, second, and millisecond.

This constructor uses the year, month, and day from the date and then constructs a DateTime in the same way as the constructor with all parts as arguments.

^DateTime

^DateTime[year, month, day, tz in String]

Create a DateTime for the given year, month, and day, with the time components all set to 0. The resulting DateTime is the first millisecond for the given date and time zone tz.

See the ^DateTime constructor with time components as arguments for more details.

^DateTime

^DateTime[date in Date, tz in String]

Create a DateTime for the given Date, with the time components all set to 0. The resulting DateTime is the first millisecond of the given Date and time zone tz.

See the ^DateTime constructor with time components as arguments for more details.

^Day

^Day[n]

Create a period of n days.

^FilePos

^FilePos(y, x)

Brings the value type constructor ^FilePos from the module rel:base into the global namespace. For more details, see the rel:base:^FilePos docstring.

^Hour

^Hour[n]

Create a period of n hours.

^Microsecond

^Microsecond[n]

Create a period of n microseconds.

^Millisecond

^Millisecond[n]

Create a period of n milliseconds.

^Minute

^Minute[n]

Create a period of n minutes.

^Month

^Month[n]

Create a period of n months.

^Nanosecond

^Nanosecond[n]

Create a period of n nanoseconds.

^Second

^Second[n]

Create a period of n seconds.

^Week

^Week[n]

Create a period of n weeks.

^Year

^Year[n]

Create a period of n years.

⇒

F implies G
F ⇒ G
G ⇐ F

Logical implication, for boolean (arity 0, true or false) arguments F and G.

¬

not F
¬F

Logical negation, for boolean (arity 0, true or false) argument F.

∧

F and G
F ∧ G

Logical and (conjunction).

∨

F or G
F ∨ G

Logical or (disjunction), for boolean (arity 0, true or false) arguments F and G.

≢

F ≢ G

Relational inequality, see equal.

abs

abs[x]

The absolute value of x.

Examples:

abs[-2] = 2
abs[-2.0] = 2.0

acos

acos[x]
acos(x, ac)

Arccosine of x. ac is the arccosine of x given in radians.

Parameters

Explanation

Defined for x between -1 and 1 (inclusive). The value of ac ranges from 0 to π.

Arccosine is sometimes called “inverse cosine.”

Only 64-bit float and 64-bit integer values for x are supported.

Examples

Calculate the arccosine of 0:

def output = acos[0]
//output> 1.5707963267948966

Calculate the arccosine of -1 using full expression:

def output(x) = acos(-1, x)
//output> 3.141592653589793

Confirm that 1.5707963267948966 is the arccosine of 0:

def output = acos(0, 1.5707963267948966)
//output> ()  // true

See Also

sin, cos, asin, asinh, acosh, sinh, cosh, and haversine.

acosh

acosh[x]
acosh(x, ach)

Hyperbolic arccosine. ach is the hyperbolic arccosine of x.

Parameters

Explanation

Defined for x >= 1.

Hyperbolic arccosine is sometimes called “inverse hyperbolic cosine.”

Only 64-bit float and 64-bit integer values for x are supported.

Examples

Calculate the hyperbolic arccosine of 90:

def output = acosh[90]
//output> 5.192925985263684

Calculate the hyperbolic arccosine of 180 using full expression:

def output(x) = acosh(180, x)
//output> 5.886096315311465

Confirm that 5.192925985263684 is the hyperbolic arccosine of 90:

def output = acosh(90, 5.192925985263684)
//output> ()  // true

See Also

sin, cos, asin, acos, asinh, acosh, sinh, and haversine.

acot

acot[x]
acot(x, act)

Arccotangent. act is the arccotangent of x.

Parameters

Explanation

Arccotangent is sometimes called “inverse cotangent.”

Only 64-bit float and 64-bit integer values for x are supported.

Examples

Calculate the arccotangent of 1:

def output = acot[1]
//output> 0.7853981633974483

Calculate the arccotangent of -1 using full expression:

def output(x) = acot(-1, x)
//output = -0.7853981633974483

Confirm that 0.7853981633974483 is the arccotangent of 1:

def output = acot(1, 0.7853981633974483)
//output> ()  // true

See Also

tan, atan, atan2, cot, tanh, and atanh.

add

add[x, y]
add(x, y, s)
x + y

Addition of two numbers. Addition of a DateTime/Date, x, with a time duration y.

Parameters

Numeric Data

Not all numeric values can be mixed with each other. The following combinations work:

Two of the three arguments need to be grounded. Valid grounding combinations are as follows:

• x and y.
• x and s.
• y and s.

Time Data

The following combinations work:

Two of the three arguments need to be grounded. Valid grounding combinations are as follows:

• x and y.
• x and s.
• y and s.

Explanation

Addition evaluates the sum of x and y and assigns it to s. In procedural languages, usually x and y are given. In Rel — a declarative language — addition can be thought of as a mapping where x and y are the keys and s is the value, which is functionally dependent on x and y.

However, with addition — add(x, y, s) — it is sufficient to know any two of the three arguments. The third one can always be inferred. Usually x and y are given, but knowing x and s is enough to infer y.

Examples

Addition of Numbers

Add two integers using +:

def output = 1 + 2
//output> 3

Add an integer and a float using add:

def output = add[1, 2.5]
//output> 3.5

Add two floats using full expression:

def output(x) = add(1.7, 2.8, x)
//output> 4.5

Add integer to a rational:

def output = 1 + rational[16][2, 3]
//output> 5/3

Addition of Time

Add time to a timestamp:

def output:tomorrow = datetime_now + ^Day[1]
def output:next_hour = datetime_now + ^Hour[1]

Add weeks to a date:

def output = 2022-12-24 + ^Week[2]
//output> 2023-01-07

Add seconds together:

def output = ^Second[1] + ^Second[2]
//output> 3

See Also

subtract, divide, and multiply.

Any

Any(x)

Holds for any x, where x exists. (Any functions as a wildcard.)

Example:

Integrity constraint that tests whether x is of any type:

def R = (1, 3) ; (1, "foo")
 
ic any_ic {subset(R, (Int, Any) )}

approx_eq

approx_eq(tolerance, x, y)

Approximate equality. Use to compare scalar numbers and check if x and y are within the absolute tolerance (tolerance) of each other.

Parameters

Explanation

“approximately equal” is defined as number values being within the absolute tolerance (tolerance) of each other, or non-number values being equal.

The parameter tolerance stands for the absolute tolerance and must be of type SignedInt[64] or Floating[64]. Also, tolerance must be a positive number; negative numbers will return false

x and y should be of the exact same data type. For example, x and y can be of type FixedDecimal or Rational, but types must have the same bits and precision.

If x or y is not a number, approx_eq defaults to eq.

Examples

Approximate equality determined as true:

def output = approx_eq(0.05, 0.1, 0.15)
//output> ()  // true

Approximate equality determined as false:

def output = approx_eq(0.01, 0.1, 0.15)
//output>    // false

See Also

equal, eq, approx_equal, and full_relation_approx_equal.

approx_equal

approx_equal(tolerance, R, S)

Approximate relational equality. To hold true, the values in the last column of R must be approximately equal to values in the last column of S given the same key (prefix).

Parameters

Explanation

Two relations R and S are considered “relationally approximately equal” when for each tuple (k..., x) in S there exists a tuple (k..., y) in R where x and y are considered approximately equal. This approximate equality is symmetric and holds equally true when the places of R and S are swapped.

See approx_eq for the details about approximate equality between two data values.

The parameter tolerance stands for the absolute tolerance and must be of type SignedInt[64] or Floating[64]. tolerance must be a positive number; negative numbers will evaluate to false.

Keys must match for approx_equal to be true.

All values of the last column in R and S must be of the exact same data type. For example, the values can all be of type FixedDecimal or Rational, but types must have the same bits and precision. Otherwise, approx_equal evaluates to false.

Note the correspondence between approx_equal and equal: approx_equal(0, R, S) if and only if equal(R, S).

approx_equal applies only to the values in the last column in R and S. That is, if the values are not within tolerance, approx_equal will evaluate to false even if other arguments in the relations are within tolerance. If full relation comparison functionality is required, see full_relation_approx_equal.

Examples

Approximate relational equality determined as true:

def salary1 = {("John", 10.0) ; ("Mary", 20.0); ("Paul", 17.0) ; ("Peter", 15.0) }
def salary2 = {("John", 9.99) ; ("Mary", 20.01); ("Paul", 17.0) ; ("Peter", 15.0) }
 
def output = approx_equal(0.1, salary1, salary2)
//output> ()  // true

Approximate relational equality determined as false:

def salary1 = {("John", 10.0) ; ("Mary", 20.0); ("Paul", 17.0) ; ("Peter", 15.0) }
def salary2 = {("John", 11.0) ; ("Mary", 21.0); ("Paul", 17.0) ; ("Peter", 15.0) }
 
def output = approx_equal(0.1, salary1, salary2)
//output>    // false

Approximate relational equality determined as false because keys are different:

def salary1 = {("John", 10.0) ; ("Mary", 20.0); ("Paul", 17.0) ; ("Peter", 15.0) }
def salary3 = {("John", 9.99) ; ("Ben", 20.0); ("Paul", 17.0) ; ("Peter", 15.0) }
 
def output = approx_equal(0.1, salary1, salary3)
//output>    // false

Approximate relational equality determined as false, even though the first arguments are within tolerance:

def coordinates1 = (1.0, 2.0); (3.0, 6.0)
def coordinates2 = (1.0000001, 2.0); (2.9999999, 6.0000001)
 
def output = approx_equal(0.001, coordinates1, coordinates2)
//output>    // false

See Also

full_relation_approx_equal, approx_eq, equal, and eq.

argmax

argmax[R]
argmax(R, am)

For a relation R, find the tuples whose last elements are largest and return those tuples with the last element omitted.

Parameters

Explanation

If tuples in R contain keys and values, argmax returns all the keys for the largest value. Typically, argmax is used when the last elements of each tuple are numeric.

argmax is typically used with relations whose shortest tuple has length two since. Note that, for all unary relations, argmax results in a relation containing an empty tuple.

Examples

Find key for largest value of R:

def R = {("A", 7.5); ("B", 8.6); ("C", 9.7); ("D", 7.5)}
def output(am) = argmax(R, am)
//output> "C"

Find key for largest value of R where values are rationals:

def R = {("A", rational[64, 8, 3]); ("B", rational[64, 9, 7]); ("C", rational[64, 11, 4]); ("D", rational[64, 8, 3])}
def output = argmax[R]
//output> "C"

Find the teams with the largest aggregated salary:

def salary = {("Burrow", 11,515,044); ("Chase", 18,211,606); ("Allen", 77,289,124); ("Diggs", 45,466,111)}
def member = {("Bengals", "Burrow"); ("Bengals", "Chase"); ("Bills", "Allen"); ("Bills", "Diggs")}
def team = {"Bengals"; "Bills"}
def output = argmax[d in team: sum[salary[p] for p in member[d]]]
//output> "Bengals"

See Also

argmin, maximum, min, argmax, sum, product, and average.

ArgMax

ArgMax[R]

Please use argmax[R]. Deprecates in near future

argmin

argmin[R]
argmin(R, am)

For a relation R, find the tuples whose last elements are smallest and return those tuples with the last element omitted.

Parameters

Explanation

If tuples in R contain keys and values, argmin returns all the keys for the largest value. Typically, argmin is used when the last elements of each tuple are numeric.

argmin is typically used with relations whose shortest tuple has length two since. Note that, for all unary relations, argmin results in a relation containing an empty tuple.

Examples

Find key for smallest value of R:

def R = {("A", 7.5); ("B", 8.6); ("C", 9.7); ("D", 7.5)}
def output(am) = argmin(R, am)
//output> "A"
//        "C"

Find key for smallest value of R where values are rationals:

def R = {("A", rational[64, 8, 3]); ("B", rational[64, 9, 7]); ("C", rational[64, 11, 4]); ("D", rational[64, 7, 3])}
def output = argmin[R]
//output> "B"

Find key for smallest value of R with tuples of various arity:

def R = {("A", 7.5); ("B", 8.6); ("C", "W", 9.7); ("D", "X", 7.5)}
def output = argmin[R]
//output> "A"
//        "D", "X"

Find the teams with the smallest aggregated salary:

def salary = {("Burrow", 11,515,044); ("Chase", 18,211,606); ("Allen", 77,289,124); ("Diggs", 45,466,111)}
def member = {("Bengals", "Burrow"); ("Bengals", "Chase"); ("Bills", "Allen"); ("Bills", "Diggs")}
def team = {"Bengals"; "Bills"}
def output = argmin[d in team: sum[salary[p] for p in member[d]]]
//output> "Bills"

See Also

argmax, minimum, min, argmax, sum, product, and average.

ArgMin

ArgMin[R]

Please use argmin[R]. Deprecates in near future

arity

arity[R]

The arity of a relation. In some cases, it can be an over-approximation.

Arity is a higher-order relation that is always evaluated at compile-time.

Examples:

def output = arity[3]
//output> 1
def output = arity[{1; 2; 3}]
//output> 1
def output = arity[(1, 2)]
//output> 2
def output = arity[add]
//output> 3
def output = arity[{1; 2; (1,2)}]
//output> 1
//        2

Arity can be used to do meta-programming in logic. For example, the following abstraction verbalize implements specific cases using arity.

Examples:

@inline def verbalize[R] = "nullary", arity[R] = 0;
                           "unary", arity[R] = 1;
                           "binary", arity[R] = 2
def output = verbalize[true]
//output> "nullary"
def output = verbalize[1]
//output> "unary"

Arity can be used in higher-order abstractions to check at compile-time that they are used correctly.

Arity can be used in integrity constraints to state expectation on EDB or IDB relations. Because arity is evaluated at compile-time, it can catch mistakes in the logic before the logic executes.

Example:

def p = (1, 2, 3)
ic { arity[p] = 3 }

Note that there is a difference between R(_, _) and arity(R) = 2. The first requires R to be non-empty, which is a run-time property of R.

asin

asin[x]
asin(x, as)

Arcsine of x. ac is the arcsine of x given in radians.

Parameters

Explanation

Defined for x between -1 and 1 (inclusive). The value of as ranges from -π/2 to π/2.

Only 64-bit float and 64-bit integer values for x are supported.

Arcsine is sometimes called “inverse sine.”

Examples

Calculate the arcsine of 1:

def output = asin[1]
//output> 1.5707963267948966

Calculate the arcsine of -.5 using full expression:

def output(x) = asin(-.5, x)
//output> -0.5235987755982989

Confirm that 1.5707963267948966 is the arcsine of 1:

def output = asin(1, 1.5707963267948966)
//output> ()  // true

See Also

sin, cos, acos, asinh, acosh, sinh, cosh, and haversine.

asinh

asinh[x]
asinh(x, ash)

Hyperbolic arcsine. ash is the hyperbolic arcsine of x.

Parameters

Explanation

Hyperbolic arcsine is sometimes called “inverse hyperbolic sine.”

Only 64-bit float and 64-bit integer values for x are supported.

Examples

Calculate the hyperbolic arcsine of 10:

def output = asinh[10]
//output> 2.99822295029797

Calculate the hyperbolic arcsine of -1 using full expression:

def output(x) = asinh(-1, x)
//output> -0.881373587019543

Confirm that 2.99822295029797 is the hyperbolic arcsine of 10:

def output = asinh(10, 2.99822295029797)
//output> ()  // true

See Also

sin, cos, asin, acos, acosh, sinh, cosh, and haversine.

atan

atan[x]
atan(x, at)

Arctangent. at is the arctangent of x in radians.

Parameters

Explanation

Arctangent is sometimes called “inverse tangent.”

Only 64-bit float and 64-bit integer values for x are supported.

Examples

Calculate the arctangent of π/4:

def output = atan[pi_float64/4]
//output> 0.6657737500283538

Convert degrees to radians and calculate arctangent using full expression:

def x = deg2rad[90]
def output(at) = atan(x, at)
//output> 1.0038848218538872

Confirm that 0.6657737500283538 is the tangent of π/4:

def output = atan(pi_float64/4, 0.6657737500283538)
//output> ()  // true

See Also

tan, atan2, cot, acot, tanh, and atanh.

atan2

atan2[y, x]
atan2(y, x, at)

Arctangent. at is the arctangent of the quotient y/x in radians.

Parameters

Explanation

Arctangent is sometimes called “inverse tangent.” The parameters x and y can be thought of as the $x$ and $y$ coordinates of the 2D point $(x, y)$.

Examples

Calculate the arctangent of 50:

def output = atan2[100, 2.0]
//output> 1.550798992821746

See Also

atan, tan, cot, acot, tanh, and atanh.

atanh

atanh[x]
atanh(x, ath)

Hyperbolic arctangent. ath is the hyperbolic arctangent of x.

Parameters

Explanation

Hyperbolic arctangent is sometimes called “inverse hyperbolic tangent.”

Only 64-bit float and 64-bit integer values for x are supported.

Examples

Calculate the hyperbolic arctangent of -.7:

def output = atanh[-.7]
//output> -0.8673005276940532

Calculate the hyperbolic arctangent of .7 using full expression:

def output(x) = atanh(.7, x)
//output> 0.8673005276940532

Confirm that -0.8673005276940532 is the hyperbolic arctangent of -.7:

def output = atanh(-.7, -0.8673005276940532)
//output> ()  // true

See Also

tan, atan, atan2, cot, acot, tanh, and atanh.

auto_number

auto_number[R]

DEPRECATED

This function is deprecated and should be avoided. It will be removed soon.

AutoNumber a relation.

auto_number takes a relation R(xs...) and produces a relation R(xs..., i) where i is a distinct AutoNumberValue index.

Note that auto_number can give different results each time it is called.

Example:

def sample = 'a'
def output = auto_number[sample]
//output> ('a', AutoNumberValue(0x12))
 
def sample = {'a'; 'b'; 'c'}
def output = auto_number[sample]
//output> ('a', AutoNumberValue(0x132))
//        ('b', AutoNumberValue(0x133))
//        ('c', AutoNumberValue(0x134))

AutoNumber

AutoNumber(x)

DEPRECATED

This function is deprecated and should be avoided. It will be removed soon.

Test if the given value is an AutoNumberValue.

average

average[R]
average(R, m)

The average (arithmetic mean) of a relation R. average is an alias for mean. For details, see the docstring for mean.

bigint

bigint[i]

Create a BigInteger value from the given integer.

Examples:

string[factorial[bigint[50]]] = "30414093201713378043612608166064768844377641568960512000000000000"

bigint_int64_convert

Convert a BigInteger to an Int64.

Examples:

bigint_int64_convert[bigint[50]] = 50

bitwise_and

bitwise_and[x, y]
bitwise_and(x, y, z)

Bitwise and of two integers.

Parameters

Not all numeric values can be mixed with each other. The following combinations work:

Examples

Bitwise and of 3 and 2:

def output = bitwise_and[3, 2]
//output> 2

Bitwise and of two unsigned integers using full expression:

def output(z) = bitwise_and(0x11100, 0x00101, z)
//output> 256

Bitwise and of unsigned and signed integers:

def output = bitwise_and[0x010b, -265]
//output> 3  // is an UnsignedInt[16]

See Also

bitwise_or, bitwise_xor, bitwise_left_shift, bitwise_right_shift, bitwise_unsigned_right_shift, and bitwise_not.

bitwise_left_shift

bitwise_left_shift[x, y]
bitwise_left_shift(x, y, z)

Bitwise left shift of an integer x by y bits.

Parameters

Not all numeric values can be mixed with each other. The following combinations work:

Explanation

The type of shift done depends on the type of x. If x is signed, bitwise_left_shift performs a signed left shift (also known as an “arithmetic left shift”). If x is unsigned, bitwise_left_shift performs an unsigned left shift (also known as a “logical left shift”).

Examples

Bitwise left shift of 8 by 1 bit:

def output = bitwise_left_shift[8, 1]
//output> 16

Bitwise left shift of 1 by 10 bits using full expression:

def output(z) = bitwise_left_shift(1, 10, z)
//output> 1024

Bitwise left shift of 0xf by 1 bit:

def output = bitwise_left_shift[0xF, 1]
//output> 30

Bitwise left shift of unsigned integer:

def output = bitwise_left_shift[uint[64, 4028], 1]
//output> 8056

See Also

bitwise_and, bitwise_or, bitwise_xor, bitwise_right_shift, bitwise_unsigned_right_shift, and bitwise_not.

bitwise_not

bitwise_not[x]
bitwise_not(x, z)

Bitwise not of an integer.

Parameters

Not all numeric values can be mixed with each other. The following combinations work:

Examples

Bitwise not of -9:

def output = bitwise_not[-9]
//output> 8

Bitwise not of 8 using full expression:

def output(z) = bitwise_not(8, z)
//output> -9

Bitwise not of 0x00011:

def output = bitwise_not[0x00011]
//output> 4294967278

See Also

bitwise_and, bitwise_or, bitwise_xor, bitwise_left_shift, bitwise_right_shift, and bitwise_unsigned_right_shift.

bitwise_or

bitwise_or[x, y]
bitwise_or(x, y, z)

Bitwise or of two integers.

Parameters

Not all numeric values can be mixed with each other. The following combinations work:

Examples

def output = bitwise_or[3, 2]
//output> 3

Bitwise or of 0x00011 and 0x11100 using full expression:

def output(z) = bitwise_or(0x00011, 0x11100, z)
//output> 69905

Bitwise xor of two unsigned integers:

def output = bitwise_or[uint[64, 1024], uint[64, 2048]]
//output> 3072

See Also

bitwise_and, bitwise_xor, bitwise_left_shift, bitwise_right_shift, bitwise_unsigned_right_shift, and bitwise_not.

bitwise_right_shift

bitwise_right_shift[x, y]
bitwise_right_shift(x, y, z)

Bitwise right shift of an integer x by y bits that preserves the sign.

Parameters

Not all numeric values can be mixed with each other. The following combinations work:

Examples

Bitwise right shift of 1024 by 1 bit:

def output = bitwise_right_shift[1024, 1]
//output> 512

Bitwise right shift of -1024 by 1 bit using full expression:

def output(z) = bitwise_right_shift(-1024, 1, z)
//output> -512

Bitwise right shift of unsigned integer by 2 bits:

def output = bitwise_right_shift[uint[64, 2048], 2]
//output> 512

See Also

bitwise_and, bitwise_or, bitwise_xor, bitwise_left_shift, bitwise_unsigned_right_shift, and bitwise_not.

bitwise_unsigned_right_shift

bitwise_unsigned_right_shift[x, y]
bitwise_unsigned_right_shift(x, y, z)

Bitwise unsigned right shift of an integer by y bits.

Parameters

Not all numeric values can be mixed with each other. The following combinations work:

Examples

Bitwise unsigned right shift of 8 by 1 bit:

def output = bitwise_unsigned_right_shift[8, 1]
//output> 4

Bitwise unsigned right shift of -8 by 2 bits:

def output(z) = bitwise_unsigned_right_shift(-8, 2, z)
//output> 4611686018427387902

Bitwise unsigned right shift of unsigned integer by 3 bits:

def output = bitwise_unsigned_right_shift[uint[64, 8], 3]
//output> 1

See Also

bitwise_and, bitwise_or, bitwise_xor, bitwise_left_shift, bitwise_right_shift, and bitwise_not.

bitwise_xor

bitwise_xor[x, y]
bitwise_xor(x, y, z)

Bitwise xor (exclusive or) of two integers.

Parameters

Not all numeric values can be mixed with each other. The following combinations work:

Examples

Bitwise xor of 3 and 2:

def output = bitwise_xor[3, 2]
//output> 1  // is a SignedInt[64]

Bitwise xor of 0x00011 and 0x11100 using full expression:

def output(z) = bitwise_xor(0x00011, 0x11100, z)
//output> 69905

Bitwise xor of two unsigned integers:

def output = bitwise_xor[uint[64, 1024], uint[64, 2048]]
//output> 3072

See Also

bitwise_and, bitwise_or, bitwise_left_shift, bitwise_right_shift, bitwise_unsigned_right_shift, and bitwise_not.

Boolean

Boolean(x)

Holds if x is a Boolean.

Example:

def json = parse_json["""{"a": true, "b": false}"""]
def output(x) = json(:a, x) and Boolean(x)

boolean_and

boolean_and(x, y, z)

Logical AND operator for the Boolean data type.

Example:

def output(x, y, z) = boolean_and(x, y, z) and boolean_true(z)

boolean_false

boolean_false(x)

Holds if x is a Boolean of value false.

boolean_not

boolean_not(x,y)

Negation(not) operator for the Boolean data type. Example:

def output(x, y) = boolean_not(x, y) and boolean_false(x)

boolean_or

boolean_or(x, y, z)

Logical or operator for the Boolean data type. Example:

def output(x, y, z) = boolean_or(x, y, z) and boolean_false(z)

boolean_true

boolean_true(x)

Holds if x is a Boolean of value true.

bottom

bottom[k, R]
bottom(k, R, index, x...)

Select the bottom k tuples of relation R according to the sort order of R and add enumeration.

Parameters

Explanation

bottom is reverse_sort restricted to the last k tuples of R. bottom puts the tuples of R in lexicographical order and then limits the result to the last k tuples. The index indicates the tuples of R in reverse order. For details on lexicographical ordering — particularly across data types — see enumerate.

Simlar to reverse_sort, bottom takes a relation R(x...) and produces a relation with the tuples (index, x...), where the first element of each tuple (index) is an integer index that enumerates the bottom k tuples in the original relation R.

Examples

Apply bottom to a relation with arity-1 tuples:

def output =  bottom[2, {'a'; 'b'; 'c'; 'd'}]
//output> (1, 'd')
//        (2, 'c')

Apply bottom to a relation with arity-2 tuples:

def R = {('a', 1); ('b', 2); ('c', 3); ('d', 4); ('e', 5)}
def output = bottom[3, R]
//output> 1, e, 5
//        2, d, 4
//        3, c, 3

See Also

top, enumerate, sort, and reverse_sort.

byte

byte[str]
byte[str, i]
byte(str, i, b)

Indexes into a string at byte position i, mapping each position i to a byte b, as a UInt8 value.

If a string contains Unicode characters, the byte at index i might be only a partial character. Be careful with your indexing logic.

Both i and b can be optionally bound externally. When only str is bound, this is the mapping from each index to its corresponding byte.

Examples: Indexing into a known byte index:

byte["abcd", 2] = 0x62
byte["中文例子", 2] = 0xb8

Abstracting over the byte index:

equal(byte["中文"],
        { 1, 0xe4;
          2, 0xb8;
          3, 0xad;
          4, 0xe6;
          5, 0x96;
          6, 0x87; })
equal((i : byte["awesome", i](0x65)), {3; 7})

capture_group_by_index

capture_group_by_index[regex, input_string, offset]

A set of capture groups, each of the form (index, substring), where index is the capture group index, and substring is the first regex match in input_string, starting at the character index specified by offset. regex can be a string or a pattern.

Offsets (character indexes) start at 1.

Example:

capture_group_by_index["(\\d+):(\\d+)",
    "Appointment from  12:45 to 1:30",
    19]

is equal to

{(1, "12"); (2, "45")}

capture_group_by_name

capture_group_by_name[regex, input_string, offset]

A set of capture groups, each of the form (name, substring), where name is the capture group name, and substring is the first regex match in input_string, starting at the character index specified by offset. regex can be a string or a pattern.

Offsets (character indexes) start at 1.

Each capture group should have a unique name.

Example:

capture_group_by_name["(?<hour>\\d+):(?<minute>\\d+)",
    "Appointment from 12:45 to 1:30",
    19]

is equal to

(("hour","12"); ("minute","45"))

cart

cart[R, S]
R × S

Cartesian product.

Examples:

def output = 1 ✕ 2
//output> (1,2)
def output = {1; 2} ✕ {3; 4}
//output> (1,3)
//        (1,4)
//        (2,3)
//        (2,4)

cbrt

cbrt[x]

The cube root of x.

Example:

cbrt[27] = 3.0

ceil

ceil[x]
ceil(x, c)

Round up to the nearest integer.

Parameters

Return type is the same as x.

Explanation

For positive x, ceil rounds away from 0. For negative x, ceil rounds toward 0.

Examples

Calculate ceil for positive float:

def output = ceil[4.5]
//output> 5.0

Calculate ceil for negative float using full expression:

def output(c) = ceil(-4.5, c)
//output> -4.0

Calculate ceil for rational:

def output = ceil[rational[64, 8, 3]]
//output> 3/1

See Also

floor, floor_to_int, trunc, trunc_to_int, and round.

char

char[str]
char[str, i]
char(str, i, c)

Indexes into a string at (Int) position i, mapping each index i to the i-th character, c.

Since this is indexed using character positions, the characters will always be whole Unicode characters.

A character is also known as a “Code Point” in the Unicode specification.

Both i and c can be optionally bound externally. When only str is bound, this is the mapping from each character index to its corresponding character.

Examples:

Indexing into a known character index:

char["abcd", 2] = 'b'
char["中文例子", 2] = '文'

Abstracting over the character index:

equal(char["中文"],
        { 1, "中"; 2, "文" })
equal((i : char["awesome", i]('e')), {3; 7})

Char

Char(x)

Holds if x is of type Char, which has a Unicode character as its value and is specified with single quotes.

Examples:

Integrity constraint that tests whether x is of type Char:

def R = 't'
 
ic mychar_ic(x in R)
    Char(x)
}

Schema defined in a relation using Char:

def myrelation(x in Char, y in Int) {
    x = 'a' and y = 123
}
 
def output = myrelation
//output> (a, 123)

clamp

clamp[low, high, value]
clamp(low, high, value, clamped)

Limit value to a range between low and high. The parameter clamped contains the “clamped” result.

Parameters

Explanation

The resulting value clamped is equivalant to value as long as it is within the lower and upper bounds. If value lies outside of these bounds, then clamped will take on the value of the bound that is closest to value. In mathematical terms, this reads:

For example, if low and high are of type Float, value should also be of type Float.

Note that relations never contain duplicates. If value is a relation with multiple values lower than low (or higher than high), clamp[low, high, value] will contain only once the value low (high).

Examples

Clamp relation with integer values:

def low = 1
def high = 4
def value = {-4; 2; 7}
def output = clamp[low, high, value]
//output> 1
//        2
//        4

Clamp relation with rationals. Note that relations never contain duplicates, thus only low and high values are included in output.

def low = rational[64, 7, 27]
def high = rational[64, 26, 27]
def value = {rational[64, 1, 27]; rational[64, 6, 27]; rational[64, 31, 27]}
def output = clamp[low, high, value]
//output> 7/27
//        26/27

See Also

range

complement

complement[R]

The complement of the relation R.

concat

concat[val1, val2]

String concatenation of two arbitrary values

Example:

concat["a", "b"] = "ab"
concat["a", 'b'] = "ab"
concat['a', "b"] = "ab"
concat['a', 'b'] = "ab"
concat["a_", 1] = "a_1"
concat[1, 3.14] = "13.14"

contains

contains(s, substring)

True iff the second argument, substring, occurs as a substring in the first argument, s.

Examples:

contains("Rel is cool!", "Rel is cool!")        // true
contains("Rel is cool!", " is coo")             // true
contains("Rel is cool!", 'c')                   // true
contains("Rel is cool!", 'C')                   // false

cos

cos[x]
cos(x, c)

Cosine of of x, where x is an angle given in radians.

Explanation

Defined for non-infinite x.

Only 64-bit float and 64-bit integer values for x are supported.

Examples

Calculate the cosine of π/6:

def output = cos[pi_float64/6]
//output> 0.8660254037844387

Calculate the cosine of π/4 using full expression:

def output(x) = cos(pi_float64/4, x)
//output> 0.7071067811865476

Confirm that 0.5000000000000001 is the cosine of π/3:

def output = cos(pi_float64/3, 0.5000000000000001)
//output> ()  // true

See Also

sin, asin, acos, asinh, acosh, sinh, cosh, and haversine.

cosh

cosh[x]
cosh(x, ch)

Hyperbolic cosine. ch is the hyperbolic cosine of x.

Parameters

Explanation

Only 64-bit float and 64-bit integer values for x are supported.

Examples

Calculate the hyperbolic cosine of 1:

def output = cosh[1]
//output> 1.5430806348152437

Calculate the hyperbolic cosine of -7 using full expression:

def output(x) = cosh(-7, x)
//output> 548.317035155212

Confirm that 1.5430806348152437 is the hyperbolic cosine of 1:

def output = cosh(1, 1.5430806348152437)
//output> ()  // true

See Also

sin, cos, asin, acos, asinh, sinh, cosh, and haversine.

cot

cot[x]
cot(x, ct)

Cotangent. ct is the cotangent of x, where x is in radians.

Parameters

Explanation

Only 64-bit float and 64-bit integer values for x are supported.

Examples

Calculate the cotangent of π/4:

def output = cot[pi_float64/4]
//output> 1.0000000000000002

Convert degrees to radians and calculate cotangent using full expression:

def x = deg2rad[90]
def output(t) = cot(x, t)
//output> 6.123233995736766e-17

Confirm that 1.0000000000000002 is the cotangent of π/4:

def output = cot(pi_float64/4, 1.0000000000000002)
//output> ()  // true

See Also

tan, atan, atan2, acot, tanh, and atanh.

count

count[R]
count(R, n)

Count the number n of tuples contained in the relation R.

Parameters

Explanation

The relation count contains the higher-order tuple (R, n) if R is a relation with n tuples.

The form count[R] is generally used to count the number of tuples in a relation R. The form count(R, n) is generally used to test whether R contains n tuples.

If R is empty, count[R] is false. To get 0 instead, use left_override, as in count[R] <++ 0.

Examples

Count the number of tuples in a relation called employees:

def employees = {
    ("jane", 12);
    ("tran", 24);
    ("miguel", 36)
}
 
def output = count[employees]
//output> 3

Count a singleton relation:

def output = count[5]
//output> 1

Test if employees contains three tuples:

def output = count(employees, 3)
//output> ()  // true

See Also

argmax, argmin, average, bottom, top, first, last, max, min, mode, and product.

csv_string

csv_string[R]

The string representation of relation that encodes as CSV using the configuration relation R.

Required keywords are:

• :data: A set of relations mapping a file position, which can be a key of arbitrary length or type, to the corresponding value. This is the data that will be exported. We expect the data relation to be of form: data(:COLUMN_NAME, pos, val) Optional keywords:
• :syntax: A relation containing syntax configuration.

Example using default CSV syntax

def csv_data(:ORDER, pos, v) = ((1,1); (2,2); (3,3))(pos, v)
def csv_data(:LINEITEM, pos, v) = ((1,100); (2,101); (3,102))(pos, v)
def csv_data(:QUANTITY, pos, v) = ((1,2); (2,15); (3,42))(pos, v)
 
def config[:data] =  csv_data
def output = csv_string[config]

Example using custom CSV syntax

def csv_data(:ORDER, pos, v) = ((1,1); (2,2); (3,3))(pos, v)
def csv_data(:LINEITEM, pos, v) = ((1,100); (2,101); (3,102))(pos, v)
def csv_data(:QUANTITY, pos, v) = ((1,2); (2,15); (3,42))(pos, v)
 
def config[:data] =  csv_data
def config[:syntax, :delim] = '\t'
def config[:syntax, :quotechar] = '_'
 
def output = csv_string[config]

current_transaction_id

current_transaction_id

The Transaction ID of the current transaction as an unsigned 128-bit integer.

This is comparable to Snowflake CURRENT_TRANSACTION, SQL Server CURRENT_TRANSACTION_ID, and PostgreSQL txid_current.

Date

Date(x)

Holds if x is a Date.

date_add

date_add[d, period]
d + period

Add a Period to a Date

Example:

def d = parse_date["2021-09-21", "Y-m-d"]
def output = date_add[d, ^Day[20]]
//output> 2021-10-11

date_day

date_day[d]

Day of the month for a Date, as an integer between 1 and 31, inclusive.

Example:

def d = parse_date["2014-10-31", "Y-m-d"]
date_day[d] = 31

date_dayname

date_dayname[d]

Name of week-day (a String, e.g., Friday)

Example:

def t = parse_date["2014-01-31", "Y-m-d"]
def output = date_dayname[t]
//output> "Friday"

date_dayofquarter

date_dayofquarter[d]

Day of quarter

Example:

def d = parse_date["2014-01-31", "Y-m-d"]
date_dayofquarter[d] = 31

date_dayofweek

date_dayofweek[d]

Day of the week for a date, as an integer between 1 and 7, where 1 is Monday and 7 is Sunday. (That is, 5 for Friday.)

Example:

def d = parse_date["2014-01-31", "Y-m-d"]
date_dayofweek[d] = 5

date_dayofweekofmonth

date_dayofweekofmonth[d]

Day of week of month, as an integer (e.g. 2 for second Friday of the month, 1 for the first Tuesday).

Example:

def t = parse_date["2014-01-31", "Y-m-d"]
date_dayofweekofmonth[t] = 5 // fifth Friday of that month

date_dayofyear

date_dayofyear[d]

Day of year

Example:

def t = parse_date["2014-01-31", "Y-m-d"]
def output = date_dayofyear[t]
//output> 31

date_daysinmonth

date_daysinmonth[d]

The number of days in the month for date d

Examples:

def d1 = parse_date["2014-01-30", "Y-m-d"]
date_daysinmonth[t] = 31
def d2 = parse_date["2014-02-11", "Y-m-d"]
date_daysinmonth[d2] = 28
def d = parse_date["2016-02-11", "Y-m-d"]
date_daysinmonth[d] = 29

date_isleapyear

date_isleapyear[d]

True iff the year for date d is a leap year.

Examples:

def notleap = parse_date["2014-01-31", "Y-m-d"]
def leap = parse_date["2016-01-31", "Y-m-d"]
def output = date_isleapyear[notleap]
//output>    // false
def output = date_isleapyear[leap]
//output> ()  // true

date_month

date_month[d]

Month of a Date, as an integer between 1 and 12.

date_monthname

date_monthname[d]

The month name for date d, as a string.

Example:

def t = parse_date["2014-01-31", "Y-m-d"]
date_monthname[t] = "January"

date_quarterofyear

date_quarterofyear[d]

Quarter to year

Example:

def d = parse_date["2014-01-31", "Y-m-d"]
date_quarterofyear[d] = 1

date_subtract

date_subtract[date, period]
date - period

Subtract a Period from a Date, giving another Date.

Example:

def d = parse_date["2021-09-21", "Y-m-d"]
def output = date_subtract[d, ^Day[1000]]
//output> 2018-12-26

date_week

date_week[d]

Week of the year for a Date, as an integer, where the first week is the week that contains the first Thursday of the year. Ranges between 1 and 53, inclusive.

Example:

week[parse_date["2005-01-01", "Y-m-d"]] = 53 // 53rd week of 2004.
week[parse_date["2001-01-01", "Y-m-d"]] = 1

date_year

date_year[d]

Year of a Date, as an integer.

Example:

date_year[parse_date["2020-05-22", "Y-m-d"]]
2020
 
^Year[date_year[parse_date["2020-05-22", "Y-m-d"]]]
(2020 years,)

dates_period_days

dates_period_days[date1, date2]

The difference in days between two dates date2 and date1 as a Day data type.

Example:

def days = dates_period_days[
    2022-05-12,
    2022-05-15
]
 
ic { equal(days, ^Day[3]) }

DateTime

DateTime(x)

Holds if x is a DateTime.

datetime_add

datetime_add[dt, period]
dt + period

Add a Period to a DateTime

Examples:

def dt = parse_datetime["2021-01-01 01:00:00", "Y-m-d H:M:S"]
def output = datetime_add[dt, ^Year[1]]
//output> 2022-01-01T01:00:00.000Z
 
def output = datetime_add[dt, ^Month[13]]
//output> 2022-02-01T01:00:00.000Z
 
def output = datetime_add[dt, ^Hour[1000]]
//output> 2021-02-11T17:00:00.000Z

datetime_day

datetime_day[dt, tz]

Day of the month, for a DateTime. Note that DateTime properties require a timezone string tz.

Example:

datetime_day[unix_epoch, "UTC"] = 1
datetime_day[unix_epoch, "UTC-10"] = 31

datetime_day_UTC

datetime_day_UTC[dt]

Day assuming datetime is in UTC.

datetime_dayname

datetime_dayname[t, tz]

Name of week-day (a string, e.g., Friday)

Example:

def t = parse_datetime["2014-01-31 01:00 +03:00", "YYYY-mm-dd HH:MM zzzz"]
datetime_dayname[t, "+03:00"] = "Friday"

datetime_dayofquarter

datetime_dayofquarter[dt, tz]

Day of quarter

Example:

def t = parse_datetime["2014-01-31 01:00 +03:00", "YYYY-mm-dd HH:MM zzzz"]
datetime_dayofquarter[t, "+03:00"] = 31

datetime_dayofweek

datetime_dayofweek[dt, tz]

Day of week (a number, e.g., 5 for Friday)

Example:

def dt = parse_datetime["2014-01-31 01:00 +03:00", "YYYY-mm-dd HH:MM zzzz"]
datetime_dayofweek[dt, "+03:00"] = 5
datetime_dayofweek[dt, "UTC"] = 4

datetime_dayofweekofmonth

datetime_dayofweekofmonth[dt, tz]

Day of week of month, as an integer (e.g. 2 for second Friday of the month, 1 for the first Tuesday).

Example:

def t = parse_datetime["2014-01-31 01:00 +03:00", "YYYY-mm-dd HH:MM zzzz"]
datetime_dayofweekofmonth[t, "+03:00"] = 5

datetime_dayofyear

datetime_dayofyear[dt, tz]

Day of year

Examples:

def dt = parse_datetime["2014-03-31 01:00 +03:00", "YYYY-mm-dd HH:MM zzzz"]
datetime_dayofyear[dt, "+03:00"] = 90
datetime_dayofyear[dt, "+00:00"] = 89

datetime_daysinmonth

datetime_daysinmonth[dt, tz]

The number of days in a datetime’s month, adjusting for timezone tz.

Examples:

def t = parse_datetime["2014-02-28 23:00 +00:00", "YYYY-mm-dd HH:MM zzzz"]
datetime_daysinmonth[t, "+03:00"] = 31
datetime_daysinmonth[t, "-03:00"] = 28

datetime_hour

datetime_hour[dt, tz]

Hour of a DateTime. Note that DateTime properties require a timezone string tz.

datetime_hour_UTC

datetime_hour_UTC[dt]

Hour assuming datetime is in UTC.

datetime_isleapyear

datetime_isleapyear[dt, tz]

Is it a leap year?

Examples:

def dt = parse_datetime["2014-01-31 01:00 +03:00", "YYYY-mm-dd HH:MM zzzz"]
def output = datetime_isleapyear[dt, "+03:00"]
//output>    // false
 
def dtleap = parse_datetime["2016-01-31 01:00 +03:00", "YYYY-mm-dd HH:MM zzzz"]
def output = datetime_isleapyear[dtleap, "+00:00"]
//output> ()  // true

datetime_minute

datetime_minute[dt, tz]

Minute of a DateTime. Note that DateTime properties require a timezone string tz.

datetime_minute_UTC

datetime_minute_UTC[dt]

Minute assuming datetime is in UTC.

datetime_month

datetime_month[dt, tz]

Month of a DateTime, as an integer between 1 and 12.

Note that DateTime properties require a timezone tz.

Examples:

def dt = parse_datetime["2021-01-01 01:00:00", "Y-m-d H:M:S"]
datetime_month[dt, "Europe/Berlin"] = 1
datetime_month[dt, "America/New_York"] = 12
datetime_month[dt, "-03:00"] = 12

datetime_month_UTC

datetime_month_UTC[dt]

Month assuming datetime is in UTC.

datetime_monthname

datetime_monthname[dt, tz]

The month name

Example:

def t = parse_datetime["2014-01-31 01:00 +03:00", "YYYY-mm-dd HH:MM zzzz"]
datetime_monthname[t, "+03:00"] = "January"

datetime_now

datetime_now

The current UTC time (the start time of the transaction) as a DateTime value.

Example:

def output = datetime_now

datetime_quarterofyear