Skip to content

The Standard Library (stdlib)

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

^Char

View source
^Char(y, x)

Construct a Char, x, from its corresponding UInt32 value, y.

^Date

View source
^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

View source
^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

View source
^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

View source
^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

View source
^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

View source
^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

View source
^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

View source
^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

View source
^Day[n]

Create a period of n days.

^FilePos

View source
^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

View source
^Hour[n]

Create a period of n hours.

^Microsecond

View source
^Microsecond[n]

Create a period of n microseconds.

^Millisecond

View source
^Millisecond[n]

Create a period of n milliseconds.

^Minute

View source
^Minute[n]

Create a period of n minutes.

^Month

View source
^Month[n]

Create a period of n months.

^Nanosecond

View source
^Nanosecond[n]

Create a period of n nanoseconds.

^Second

View source
^Second[n]

Create a period of n seconds.

^Week

View source
^Week[n]

Create a period of n weeks.

^Year

View source
^Year[n]

Create a period of n years.

¬

View source
not F
¬F

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

View source
F and G
F  G

Logical and (conjunction).

View source
F or G
F  G

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

View source
F  G

Relational inequality, see equal.

abs

View source
abs[x]

The absolute value of x.

Examples:

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

acos

View source
acos[x]
acos(x, ac)

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

Parameters

ParameterTypeDescription
xFloating[64], SignedInt[64]Cosine of ac. Must be grounded.
acFloating[64]Arccosine of x in radians.

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

View source
acosh[x]
acosh(x, ach)

Hyperbolic arccosine. ach is the hyperbolic arccosine of x.

Parameters

ParameterTypeDescription
xFloating[64], SignedInt[64]Hyperbolic cosine of ach. Must be grounded.
achFloating[64]Hyperbolic arccosine of x.

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

View source
acot[x]
acot(x, act)

Arccotangent. act is the arccotangent of x.

Parameters

ParameterTypeDescription
xFloating[64], SignedInt[64]Cotangent of act. Must be grounded.
actFloating[64]Arccotangent of x.

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

View source
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

ParameterTypeDescription
xNumberFirst summand.
yNumberSecond summand.
sNumberSum x + y.

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

xys
NumberSame as xSame as x
Rational, FixedDecimalSignedInt[64]Same as x
SignedInt[64]SignedInt[128], Rational, FixedDecimal, Floating[64]Same as y
SignedInt[128]SignedInt[64]SignedInt[128]
Floating[64]SignedInt[64]Floating[64]

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

ParameterTypeDescription
xDate, DateTime, date period, time periodFirst summand.
yDate, DateTime, date period, time periodSecond summand.
sDate, DateTime, date period, time periodSum x + y.

The following combinations work:

xys
date period, time periodSame date period, time period as xSame date period, time period as x
date period, time periodDateTimeDateTime
DateTimedate period, time periodDateTime
date periodDateDate
Datedate periodDate

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

View source
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

View source
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

ParameterTypeDescription
toleranceSignedInt[64] or Floating[64]Tolerance of the approximation. A positive number. Must be grounded.
xNumberA valid number. Must be the same data type as y. Must be grounded.
yNumberA valid number. Must be the same data type as x. Must be grounded.

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

View source
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

ParameterTypeDescription
toleranceSignedInt[64] or Floating[64]A positive integer or float. Must be grounded.
RRelationA relation with corresponding keys and last elements that can be compared to S. Must be grounded.
SRelationA relation with corresponding keys and last elements that can be compared to R. Must be grounded.

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

View source
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

ParameterTypeDescription
RRelationA relation whose tuples contain key-value pairs. Must be grounded.
amNumberA tuple in R with the largest last element, with last element omitted.

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. 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.