Expression functions

col()

col(string $name): Col

Reference to the column with the given name.

A plain PHP string passed to a helper is a literal; col() is how an expression reads a column.

Function in Phibble\Expr
Returns Col
Examples phibble for Laravel developers, phibble

lit()

lit(mixed $value): Lit

Literal value as an expression.

A date or datetime literal is typed as a date when its time of day is midnight, and as a datetime otherwise.

Function in Phibble\Expr
Returns Lit
Throws InvalidArgumentException: when the value is of another type, or a list holds a value that is not a scalar.

call()

call(string $fn, mixed ...$args): Call

Call to any registered function by name, such as call(‘str_sub’, col('s'), 1, 3).

String keys in $args become named options; other arguments are positional. Values that are not expressions are wrapped as literals.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: when the function is not registered, the number of positional arguments is out of range, or a named option is not allowed.

desc()

desc(Expr|string $expr): Desc

Descending sort key for arrange(), the first argument of a ranking function, or order_by.

desc() is rejected anywhere else in an expression.

Function in Phibble\Expr
Returns Desc

Expr->add()

$expr->add(mixed $other): Call

Sum of this expression and $other.

NA gives NA. Adding a period such as days(1) to a date or datetime uses clock arithmetic, and adding seconds or a time to a time gives a time.

Method of Phibble\Expr\Expr
Returns Call
Examples Expressions, Types

Expr->sub()

$expr->sub(mixed $other): Call

Difference of this expression and $other.

NA gives NA. Subtracting a date from a date gives days, a datetime from a datetime gives seconds, and a period from a date or datetime uses clock arithmetic.

Method of Phibble\Expr\Expr
Returns Call
Examples Expressions, Getting started

Expr->mul()

$expr->mul(mixed $other): Call

Product of this expression and $other.

NA gives NA. A period or time multiplied by a number is scaled.

Method of Phibble\Expr\Expr
Returns Call
Examples Getting started, SQL tables

Expr->div()

$expr->div(mixed $other): Call

Quotient of this expression and $other, always a float.

NA gives NA. Division by zero gives Inf or -Inf, and 0 / 0 gives NaN, as in R.

Method of Phibble\Expr\Expr
Returns Call
Examples Expressions, Getting started, SQL tables

Expr->mod()

$expr->mod(mixed $other): Call

Remainder of this expression divided by $other, with the sign of $other.

R’s %% operator: the remainder after floored division. NA gives NA. An integer remainder by zero is NA, and a float remainder by zero NaN.

Method of Phibble\Expr\Expr
Returns Call
Examples Expressions

Expr->pow()

$expr->pow(mixed $other): Call

This expression raised to the power $other, as a float.

R’s ^ operator. NA gives NA.

Method of Phibble\Expr\Expr
Returns Call

Expr->neg()

$expr->neg(): Call

Negation of this expression.

NA gives NA.

Method of Phibble\Expr\Expr
Returns Call

Expr->eq()

$expr->eq(mixed $other): Call

Whether this expression equals $other.

R’s == operator. NA on either side gives NA. Numbers and logicals compare numerically, dates and datetimes by instant, and other values as strings.

Method of Phibble\Expr\Expr
Returns Call
Examples Reading and writing data, Expressions, Getting started

Expr->ne()

$expr->ne(mixed $other): Call

Whether this expression differs from $other.

R’s != operator. NA on either side gives NA. Numbers and logicals compare numerically, dates and datetimes by instant, and other values as strings.

Method of Phibble\Expr\Expr
Returns Call
Examples Getting started

Expr->lt()

$expr->lt(mixed $other): Call

Whether this expression is less than $other.

R’s < operator. NA on either side gives NA. Numbers and logicals compare numerically, dates and datetimes by instant, and other values as strings, byte by byte.

Method of Phibble\Expr\Expr
Returns Call

Expr->le()

$expr->le(mixed $other): Call

Whether this expression is less than or equal to $other.

R’s <= operator. NA on either side gives NA. Numbers and logicals compare numerically, dates and datetimes by instant, and other values as strings, byte by byte.

Method of Phibble\Expr\Expr
Returns Call
Examples Expressions

Expr->gt()

$expr->gt(mixed $other): Call

Whether this expression is greater than $other.

R’s > operator. NA on either side gives NA. Numbers and logicals compare numerically, dates and datetimes by instant, and other values as strings, byte by byte.

Method of Phibble\Expr\Expr
Returns Call
Examples Expressions, Types, Getting started

Expr->ge()

$expr->ge(mixed $other): Call

Whether this expression is greater than or equal to $other.

R’s >= operator. NA on either side gives NA. Numbers and logicals compare numerically, dates and datetimes by instant, and other values as strings, byte by byte.

Method of Phibble\Expr\Expr
Returns Call
Examples Expressions

Expr->and()

$expr->and(mixed $other): Call

Logical AND of this expression and $other.

R’s & operator, with three-valued logic: false wins over NA, and NA with true gives NA.

Method of Phibble\Expr\Expr
Returns Call
Examples Expressions, Getting started

Expr->or()

$expr->or(mixed $other): Call

Logical OR of this expression and $other.

R’s | operator, with three-valued logic: true wins over NA, and NA with false gives NA.

Method of Phibble\Expr\Expr
Returns Call
Examples Expressions

Expr->not()

$expr->not(): Call

Logical negation of this expression.

R’s ! operator. NA gives NA.

Method of Phibble\Expr\Expr
Returns Call
Examples Expressions, phibble

Expr->isNa()

$expr->isNa(): Call

Whether each value is NA.

NaN counts as NA. Equivalent to is_na().

Method of Phibble\Expr\Expr
Returns Call
Examples phibble

Expr->isIn()

$expr->isIn(array $values): Call

Whether each value is one of the given values.

R’s %in% operator. Dates, datetimes, and times compare by value. NA matches only when the list holds null. The result is never NA.

Method of Phibble\Expr\Expr
Returns Call
Throws InvalidArgumentException: when a value is another type, or the list mixes scalars with temporal values or times with dates.
Examples Expressions, SQL tables

Expr->between()

$expr->between(mixed $low, mixed $high): Call

Whether each value lies between $low and $high, inclusive.

NA in the value or either bound gives NA. Equivalent to between().

Method of Phibble\Expr\Expr
Returns Call
Examples Getting started, SQL tables

Expr->desc()

$expr->desc(): Desc

Descending sort key on this expression, for arrange(), the first argument of a ranking function, or order_by.

Equivalent to desc().

Method of Phibble\Expr\Expr
Returns Desc

is_na()

is_na(mixed $x): Call

Whether each value is NA.

NaN counts as NA.

Function in Phibble\Expr
Returns Call

if_else()

if_else(    mixed $condition,    mixed $true,    mixed $false,    mixed ...$options,): Call

Value of $true where the condition holds and of $false where it does not.

Function in Phibble\Expr
Returns Call

case_when()

case_when(mixed ...$args): Call

Value paired with the first condition that holds, as case_when(cond1, value1, cond2, value2, ..., default: value).

Conditions are tested in order per row; an NA condition does not match.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: when the positional arguments do not form condition and value pairs.

coalesce()

coalesce(mixed ...$args): Call

First value that is not NA among the arguments, row by row.

NaN counts as NA and is skipped, as in is_na() and R’s coalesce().

Function in Phibble\Expr
Returns Call

between()

between(mixed $x, mixed $low, mixed $high): Call

Whether each value lies between $low and $high, inclusive.

The result is NA where $x, $low, or $high is NA.

Function in Phibble\Expr
Returns Call

na_if()

na_if(mixed $x, mixed $y): Call

Values of $x, with NA where $x equals $y.

Function in Phibble\Expr
Returns Call

near()

near(mixed $x, mixed $y, mixed ...$options): Call

Whether $x and $y are equal within a tolerance.

The result is NA where either value is NA.

Function in Phibble\Expr
Returns Call

abs()

abs(mixed $x): Call

Absolute value.

Function in Phibble\Expr
Returns Call

sqrt()

sqrt(mixed $x): Call

Square root.

The square root of a negative number is NaN.

Function in Phibble\Expr
Returns Call

exp()

exp(mixed $x): Call

Exponential function, e raised to the power $x.

Function in Phibble\Expr
Returns Call

log()

log(mixed $x, mixed ...$options): Call

Logarithm, natural by default.

The logarithm of 0 is -Inf, and of a negative number NaN.

Function in Phibble\Expr
Returns Call

log10()

log10(mixed $x): Call

Base-10 logarithm.

The logarithm of 0 is -Inf, and of a negative number NaN.

Function in Phibble\Expr
Returns Call

round()

round(mixed $x, mixed ...$options): Call

Value rounded to a number of decimal digits.

Rounding follows R 4.0 and later: the candidate nearer the stored double wins, and exact ties go to the even digit, so round(2.675, digits: 2) is 2.67. Integers are returned unchanged when digits is 0 or more. SQL backends evaluate it in memory.

Function in Phibble\Expr
Returns Call

floor()

floor(mixed $x): Call

Largest whole number not greater than the value, as a float.

Function in Phibble\Expr
Returns Call

ceiling()

ceiling(mixed $x): Call

Smallest whole number not less than the value, as a float.

Function in Phibble\Expr
Returns Call

as_int()

as_int(mixed $x): Call

Values converted to integers.

R’s as.integer().

Function in Phibble\Expr
Returns Call

as_float()

as_float(mixed $x): Call

Values converted to floats.

R’s as.double().

Function in Phibble\Expr
Returns Call

as_string()

as_string(mixed $x): Call

Values converted to strings.

R’s as.character(). SQL backends evaluate it in memory.

Function in Phibble\Expr
Returns Call

as_bool()

as_bool(mixed $x): Call

Values converted to logicals.

R’s as.logical(). SQL backends evaluate it in memory.

Function in Phibble\Expr
Returns Call

n()

n(): Call

Number of rows in the group.

Function in Phibble\Expr
Returns Call
Examples phibble for Laravel developers, phibble

sum()

sum(mixed $x, mixed ...$options): Call

Sum of the values.

The result is NA when a value is NA, unless na_rm is true. The sum is an integer when every value is an integer or logical, and 0 for no values. The sum of times is a time.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: at evaluation, when the values are dates or datetimes.

mean()

mean(mixed $x, mixed ...$options): Call

Mean of the values.

The result is NA when a value is NA, unless na_rm is true, and NaN for no values. The mean of dates is a date, of datetimes a datetime, and of times a time.

Function in Phibble\Expr
Returns Call
Examples phibble for Laravel developers, phibble

median()

median(mixed $x, mixed ...$options): Call

Median of the values.

The result is NA when a value is NA, unless na_rm is true, and NA for no values. The median of dates is a date, of datetimes a datetime, and of times a time.

Function in Phibble\Expr
Returns Call
Examples phibble

min()

min(mixed $x, mixed ...$options): Call

Smallest of the values.

The result is NA when a value is NA, unless na_rm is true, NaN when a value is NaN, and Inf for no values. Strings compare byte by byte.

Function in Phibble\Expr
Returns Call

max()

max(mixed $x, mixed ...$options): Call

Largest of the values.

The result is NA when a value is NA, unless na_rm is true, NaN when a value is NaN, and -Inf for no values. Strings compare byte by byte.

Function in Phibble\Expr
Returns Call
Examples phibble for Laravel developers

sd()

sd(mixed $x, mixed ...$options): Call

Sample standard deviation of the values.

The divisor is n - 1, and the result is NA for fewer than two values. The result is NA when a value is NA, unless na_rm is true. Dates are measured in days, and datetimes and times in seconds.

Function in Phibble\Expr
Returns Call

var_()

var_(mixed $x, mixed ...$options): Call

Sample variance of the values.

R’s var(); the trailing underscore avoids PHP’s reserved word. The divisor is n - 1, and the result is NA for fewer than two values. The result is NA when a value is NA, unless na_rm is true. Dates are measured in days, and datetimes and times in seconds.

Function in Phibble\Expr
Returns Call

quantile()

quantile(mixed $x, mixed $p, mixed ...$options): Call

Sample quantile of the values at probability $p.

Uses R’s default method (type 7), interpolating between order statistics. The quantile of datetimes is a datetime, and of times a time.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: at evaluation, when a value is NA and na_rm is false, or when the values are dates.

iqr()

iqr(mixed $x, mixed ...$options): Call

Interquartile range of the values: the 0.75 quantile minus the 0.25 quantile.

R’s IQR(). Quantiles use R’s default method (type 7). The result is NA for no values. Dates are measured in days, and datetimes and times in seconds.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: at evaluation, when a value is NA and na_rm is false.

n_distinct()

n_distinct(mixed ...$args): Call

Number of distinct values, or of distinct combinations across several arguments.

NA counts as a distinct value unless na_rm is true.

Function in Phibble\Expr
Returns Call

first()

first(mixed $x, mixed ...$options): Call

First value in the group.

Function in Phibble\Expr
Returns Call

last()

last(mixed $x, mixed ...$options): Call

Last value in the group.

Function in Phibble\Expr
Returns Call

nth()

nth(mixed $x, mixed $n, mixed ...$options): Call

Value at position $n in the group.

Function in Phibble\Expr
Returns Call

any()

any(mixed $x, mixed ...$options): Call

Whether any value is true.

With NA present and na_rm false, the result is true when some value is true, and NA otherwise. The result is false for no values.

Function in Phibble\Expr
Returns Call

all()

all(mixed $x, mixed ...$options): Call

Whether every value is true.

With NA present and na_rm false, the result is false when some value is false, and NA otherwise. The result is true for no values.

Function in Phibble\Expr
Returns Call

lag()

lag(mixed $x, mixed ...$options): Call

Value from n rows earlier in the group.

Function in Phibble\Expr
Returns Call

lead()

lead(mixed $x, mixed ...$options): Call

Value from n rows later in the group.

Function in Phibble\Expr
Returns Call

row_number()

row_number(mixed $x = null): Call

Row number within the group, or the rank of each value with ties broken by row order.

With no argument, rows are numbered 1 to n in their order. With an argument, NA values get NA, and a factor column ranks by level order.

Function in Phibble\Expr
Returns Call
Throws ArgumentCountError: when given more than one argument.

min_rank()

min_rank(mixed $x): Call

Rank of each value, ties sharing the lowest rank, with gaps after ties.

NA values get NA. A factor column ranks by level order.

Function in Phibble\Expr
Returns Call

dense_rank()

dense_rank(mixed $x): Call

Rank of each value, ties sharing a rank, with no gaps after ties.

NA values get NA. A factor column ranks by level order.

Function in Phibble\Expr
Returns Call

percent_rank()

percent_rank(mixed $x): Call

Minimum rank rescaled to the range 0 to 1: (min_rank - 1) / (m - 1), where m is the number of non-NA values.

NA values get NA. With one non-NA value, the result is NaN.

Function in Phibble\Expr
Returns Call

cume_dist()

cume_dist(mixed $x): Call

Cumulative distribution: the share of non-NA values less than or equal to each value.

NA values get NA.

Function in Phibble\Expr
Returns Call

ntile()

ntile(mixed $x = null, ?int $n = null): Call

Bucket number from 1 to n, splitting the ordered values into n groups as evenly as possible.

Earlier buckets take the extra rows when the sizes differ. NA values get NA. Without $x, rows are bucketed in row order.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: when n is not given.
Throws ArgumentCountError: when given more than two arguments.

cumsum()

cumsum(mixed $x): Call

Cumulative sum in row order.

Once a value is NA, every later result is NA.

Function in Phibble\Expr
Returns Call

cumprod()

cumprod(mixed $x): Call

Cumulative product in row order.

Once a value is NA, every later result is NA. SQL backends evaluate it in memory.

Function in Phibble\Expr
Returns Call

cummean()

cummean(mixed $x): Call

Cumulative mean in row order.

Once a value is NA, every later result is NA.

Function in Phibble\Expr
Returns Call

cummin()

cummin(mixed $x): Call

Cumulative minimum in row order.

Once a value is NA, every later result is NA.

Function in Phibble\Expr
Returns Call

cummax()

cummax(mixed $x): Call

Cumulative maximum in row order.

Once a value is NA, every later result is NA.

Function in Phibble\Expr
Returns Call

cumall()

cumall(mixed $x): Call

Whether every value so far, in row order, is true.

Once a value is false, every later result is false. After an NA, results are NA until a false value appears.

Function in Phibble\Expr
Returns Call

cumany()

cumany(mixed $x): Call

Whether any value so far, in row order, is true.

Once a value is true, every later result is true. After an NA, results are NA until a true value appears.

Function in Phibble\Expr
Returns Call

consecutive_id()

consecutive_id(mixed ...$args): Call

Run identifier that starts at 1 and increases each time the value, or combination of values, changes from the previous row.

SQL backends evaluate it in memory.

Function in Phibble\Expr
Returns Call

Expr::of()

Expr::of(mixed $value): Expr

PHP value wrapped as a literal expression; an expression is returned unchanged.

Static method of Phibble\Expr\Expr
Returns Expr
Throws InvalidArgumentException: when the value is not one lit() accepts.

Expr::fromArray()

Expr::fromArray(array $node): Expr

Expression rebuilt from the array form that toArray() returns.

Static method of Phibble\Expr\Expr
Returns Expr
Throws InvalidArgumentException: when a node has an unknown type, a literal is invalid, or a call does not fit the function registry.
Examples Expressions

Expr->toArray()

$expr->toArray(): array

JSON-friendly description of the expression tree.

Expr::fromArray() rebuilds the expression from it.

Method of Phibble\Expr\Expr
Returns array<string, mixed>
Examples Expressions

Expr->columns()

$expr->columns(): array

Names of the columns the expression reads, in order of first use.

Method of Phibble\Expr\Expr
Returns list<string>
Examples Expressions