String and date functions · phibble

Expression functions in Phibble\Expr for text, patterns, dates, datetimes, and periods, following stringr and lubridate.

Strings

`str_length()`

str_length(mixed $x): Call

Number of characters in the string.

Characters are Unicode code points. NA gives NA.

Parameter	Type	Default	Description
`$x`	`mixed`		A string expression or literal.

Function in Phibble\Expr
Returns Call

`str_lower()`

str_lower(mixed $x): Call

String in lower case.

Alias of str_to_lower().

Parameter	Type	Default	Description
`$x`	`mixed`		A string expression or literal.

Function in Phibble\Expr
Returns Call

`str_upper()`

str_upper(mixed $x): Call

String in upper case.

Alias of str_to_upper().

Parameter	Type	Default	Description
`$x`	`mixed`		A string expression or literal.

Function in Phibble\Expr
Returns Call

`str_to_lower()`

str_to_lower(mixed $x): Call

String in lower case, by Unicode rules.

Parameter	Type	Default	Description
`$x`	`mixed`		A string expression or literal.

Function in Phibble\Expr
Returns Call

`str_to_upper()`

str_to_upper(mixed $x): Call

String in upper case, by Unicode rules.

Parameter	Type	Default	Description
`$x`	`mixed`		A string expression or literal.

Function in Phibble\Expr
Returns Call

`str_to_title()`

str_to_title(mixed $x): Call

String in title case.

The string is lowercased, then each letter that follows a character other than a letter, digit, or apostrophe is uppercased. SQL backends evaluate it in memory when it reads a column.

Parameter	Type	Default	Description
`$x`	`mixed`		A string expression or literal.

Function in Phibble\Expr
Returns Call

`str_trim()`

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

String with leading and trailing white space removed.

All Unicode white space is removed, as in stringr. SQL backends evaluate it in memory.

Parameter	Type	Default	Description
`$x`	`mixed`		A string expression or literal.
`...$options`	`mixed`		Named options: side (string, default ‘both’) is ‘left’, ‘right’, or ‘both’.

Function in Phibble\Expr
Returns Call

`str_squish()`

str_squish(mixed $x): Call

String with white space trimmed from both ends and each inner run collapsed to one space.

Parameter	Type	Default	Description
`$x`	`mixed`		A string expression or literal.

Function in Phibble\Expr
Returns Call

`str_pad()`

str_pad(mixed $x, mixed $width, mixed ...$options): Call

String padded to at least $width characters.

Width counts Unicode code points; a string already at least that wide is unchanged. With side ‘both’, the extra padding goes on the right.

Parameter	Type	Description
`$x`	`mixed`	A string expression or literal.
`$width`	`mixed`	The minimum width.
`...$options`	`mixed`	Named options: side (string, default ‘left’) is ‘left’, ‘right’, or ‘both’; pad (string, default ’ ’) is one character of display width 1.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: when pad is not one character of width 1, as in stringr: when the call is built for a literal pad, otherwise at evaluation. At evaluation, when side is not ‘left’, ‘right’, or ‘both’.

`str_trunc()`

str_trunc(mixed $x, mixed $width, mixed ...$options): Call

String truncated to at most $width characters, ellipsis included.

Width counts Unicode code points; a string that fits is unchanged.

Parameter	Type	Description
`$x`	`mixed`	A string expression or literal.
`$width`	`mixed`	The maximum width.
`...$options`	`mixed`	Named options: side (string, default ‘right’) is the side to cut, ‘right’, ‘left’, or ‘center’; ellipsis (string, default ‘…’) marks the cut.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: at evaluation, when side is not ‘right’, ‘left’, or ‘center’.

`str_sub()`

str_sub(mixed $x, mixed $start, mixed $end = -1): Call

Substring from position $start to position $end, inclusive.

Positions are 1-based characters; negative positions count from the end, so -1 is the last character. The result is NA where any argument is NA.

Parameter	Type	Default	Description
`$x`	`mixed`		A string expression or literal.
`$start`	`mixed`		The first position.
`$end`	`mixed`	`-1`	The last position; the default, -1, is the end of the string.

Function in Phibble\Expr
Returns Call

`paste()`

paste(mixed ...$args): Call

Arguments joined into one string with a separator.

NA is written as “NA”.

Parameter	Type	Default	Description
`...$args`	`mixed`		One or more expressions or literals, then named options: sep (string, default ’ ’) is the separator.

Function in Phibble\Expr
Returns Call

`paste0()`

paste0(mixed ...$args): Call

Arguments joined into one string with no separator.

NA is written as “NA”.

Parameter	Type	Default	Description
`...$args`	`mixed`		One or more expressions or literals.

Function in Phibble\Expr
Returns Call

Patterns

`fixed()`

fixed(mixed $pattern): Call

Pattern that matches its text literally.

An empty fixed() pattern gives NA in the functions that take it.

Parameter	Type	Default	Description
`$pattern`	`mixed`		The literal text to match.

Function in Phibble\Expr
Returns Call

`regex()`

regex(mixed $pattern, mixed ...$options): Call

Regular-expression pattern with options.

Patterns are PCRE and match by Unicode code point.

Parameter	Type	Default	Description
`$pattern`	`mixed`		The regular expression, without delimiters.
`...$options`	`mixed`		Named options: ignore_case (bool, default false) matches without regard to case.

Function in Phibble\Expr
Returns Call

`str_detect()`

str_detect(mixed $x, mixed $pattern, mixed ...$options): Call

Whether the string contains a match for the pattern.

A plain string pattern is a regular expression; wrap it in fixed() to match literal text. NA gives NA, as does an empty fixed() pattern.

Parameter	Type	Description
`$x`	`mixed`	A string expression or literal.
`$pattern`	`mixed`	A regular expression, `fixed()`, or `regex()`.
`...$options`	`mixed`	Named options: negate (bool, default false) inverts the result.

Function in Phibble\Expr
Returns Call

`str_starts()`

str_starts(mixed $x, mixed $pattern, mixed ...$options): Call

Whether the string starts with a match for the pattern.

A plain string pattern is a regular expression; wrap it in fixed() to match literal text. NA gives NA, as does an empty fixed() pattern.

Parameter	Type	Description
`$x`	`mixed`	A string expression or literal.
`$pattern`	`mixed`	A regular expression, `fixed()`, or `regex()`.
`...$options`	`mixed`	Named options: negate (bool, default false) inverts the result.

Function in Phibble\Expr
Returns Call

`str_ends()`

str_ends(mixed $x, mixed $pattern, mixed ...$options): Call

Whether the string ends with a match for the pattern.

A plain string pattern is a regular expression; wrap it in fixed() to match literal text. NA gives NA, as does an empty fixed() pattern.

Parameter	Type	Description
`$x`	`mixed`	A string expression or literal.
`$pattern`	`mixed`	A regular expression, `fixed()`, or `regex()`.
`...$options`	`mixed`	Named options: negate (bool, default false) inverts the result.

Function in Phibble\Expr
Returns Call

`str_count()`

str_count(mixed $x, mixed $pattern): Call

Number of matches of the pattern in the string.

NA gives NA, as does an empty fixed() pattern.

Parameter	Type	Default	Description
`$x`	`mixed`		A string expression or literal.
`$pattern`	`mixed`		A regular expression, `fixed()`, or `regex()`.

Function in Phibble\Expr
Returns Call

`str_extract()`

str_extract(mixed $x, mixed $pattern): Call

First match of the pattern in the string.

The result is NA when there is no match. SQL backends evaluate it in memory when it reads a column.

Parameter	Type	Default	Description
`$x`	`mixed`		A string expression or literal.
`$pattern`	`mixed`		A regular expression, `fixed()`, or `regex()`.

Function in Phibble\Expr
Returns Call

`str_extract_all()`

str_extract_all(mixed $x, mixed $pattern): Call

Every match of the pattern in the string, as a list.

NA gives a list holding one NA. SQL backends evaluate it in memory when it reads a column.

Parameter	Type	Default	Description
`$x`	`mixed`		A string expression or literal.
`$pattern`	`mixed`		A regular expression, `fixed()`, or `regex()`.

Function in Phibble\Expr
Returns Call

`str_replace()`

str_replace(mixed $x, mixed $pattern, mixed $replacement): Call

String with the first match of the pattern replaced.

In a regular-expression replacement, \1 to \9 refer to capture groups, and $ is literal. An NA replacement gives NA where the pattern matches.

Parameter	Type	Description
`$x`	`mixed`	A string expression or literal.
`$pattern`	`mixed`	A regular expression, `fixed()`, or `regex()`.
`$replacement`	`mixed`	The replacement string.

Function in Phibble\Expr
Returns Call

`str_replace_all()`

str_replace_all(mixed $x, mixed $pattern, mixed $replacement): Call

String with every match of the pattern replaced.

In a regular-expression replacement, \1 to \9 refer to capture groups, and $ is literal. An NA replacement gives NA where the pattern matches.

Parameter	Type	Description
`$x`	`mixed`	A string expression or literal.
`$pattern`	`mixed`	A regular expression, `fixed()`, or `regex()`.
`$replacement`	`mixed`	The replacement string.

Function in Phibble\Expr
Returns Call

`str_split()`

str_split(mixed $x, mixed $pattern): Call

Pieces of the string split at each match of the pattern, as a list.

An empty fixed() pattern splits into characters. NA gives a list holding one NA. SQL backends evaluate it in memory when it reads a column.

Parameter	Type	Default	Description
`$x`	`mixed`		A string expression or literal.
`$pattern`	`mixed`		A regular expression, `fixed()`, or `regex()`.

Function in Phibble\Expr
Returns Call

`str_split_i()`

str_split_i(mixed $x, mixed $pattern, mixed $i): Call

Piece $i of the string split at each match of the pattern.

The result is NA when $i is 0 or out of range. SQL backends evaluate it in memory when it reads a column.

Parameter	Type	Description
`$x`	`mixed`	A string expression or literal.
`$pattern`	`mixed`	A regular expression, `fixed()`, or `regex()`.
`$i`	`mixed`	The 1-based piece number; a negative number counts from the end.

Function in Phibble\Expr
Returns Call

Parsing dates

`ymd()`

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

Date parsed from text with year, month, and day in that order.

Digits may run together (20240131) or be separated by any non-digits. Invalid input gives NA. SQL backends evaluate it in memory when it reads a column.

Parameter	Type	Default	Description
`$x`	`mixed`		A string expression or literal.
`...$options`	`mixed`		Named options: tz (string, default none) parses to a datetime at midnight in that time zone; without it, the result is a date.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: at evaluation, when tz is not a known time zone.

`dmy()`

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

Date parsed from text with day, month, and year in that order.

Digits may run together (31012024) or be separated by any non-digits. Invalid input gives NA. SQL backends evaluate it in memory when it reads a column.

Parameter	Type	Default	Description
`$x`	`mixed`		A string expression or literal.
`...$options`	`mixed`		Named options: tz (string, default none) parses to a datetime at midnight in that time zone; without it, the result is a date.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: at evaluation, when tz is not a known time zone.

`mdy()`

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

Date parsed from text with month, day, and year in that order.

Digits may run together (01312024) or be separated by any non-digits. Invalid input gives NA. SQL backends evaluate it in memory when it reads a column.

Parameter	Type	Default	Description
`$x`	`mixed`		A string expression or literal.
`...$options`	`mixed`		Named options: tz (string, default none) parses to a datetime at midnight in that time zone; without it, the result is a date.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: at evaluation, when tz is not a known time zone.

`ymd_hms()`

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

Datetime parsed from text with year, month, day, hour, minute, and second in that order.

Seconds may have a fraction. Invalid input, and a local time the zone skips, give NA. SQL backends evaluate it in memory when it reads a column.

Parameter	Type	Default	Description
`$x`	`mixed`		A string expression or literal.
`...$options`	`mixed`		Named options: tz (string, default ‘UTC’) is the time zone of the clock time.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: at evaluation, when tz is not a known time zone.

`dmy_hms()`

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

Datetime parsed from text with day, month, year, hour, minute, and second in that order.

Seconds may have a fraction. Invalid input, and a local time the zone skips, give NA. SQL backends evaluate it in memory when it reads a column.

Parameter	Type	Default	Description
`$x`	`mixed`		A string expression or literal.
`...$options`	`mixed`		Named options: tz (string, default ‘UTC’) is the time zone of the clock time.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: at evaluation, when tz is not a known time zone.

`mdy_hms()`

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

Datetime parsed from text with month, day, year, hour, minute, and second in that order.

Seconds may have a fraction. Invalid input, and a local time the zone skips, give NA. SQL backends evaluate it in memory when it reads a column.

Parameter	Type	Default	Description
`$x`	`mixed`		A string expression or literal.
`...$options`	`mixed`		Named options: tz (string, default ‘UTC’) is the time zone of the clock time.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: at evaluation, when tz is not a known time zone.

`parse_date_time()`

parse_date_time(mixed $x, mixed $orders, mixed ...$options): Call

Datetime parsed from text by the first of the given orders that fits.

Order letters are Y (four-digit year), y (two-digit year: 00 to 68 are 2000s, 69 to 99 1900s), m, d, H, M, and S; spaces and the separators - / : _ in an order are ignored. A missing year is 0, a missing month or day is 1, and a missing hour, minute, or second is 0, as in lubridate. Text no order fits gives NA. SQL backends evaluate it in memory when it reads a column.

Parameter	Type	Description
`$x`	`mixed`	A string expression or literal.
`$orders`	`mixed`	One order, such as ‘Ymd HMS’, or a list of orders.
`...$options`	`mixed`	Named options: tz (string, default ‘UTC’) is the time zone of the clock time.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: for an order with a day but no month, which lubridate cannot parse. At evaluation, when an order has another letter, or tz is not a known time zone.

Date parts

`year()`

year(mixed $x): Call

Year of the date or datetime.

Parameter	Type	Default	Description
`$x`	`mixed`		A date or datetime expression.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: at evaluation, when a value is a time.

`quarter()`

quarter(mixed $x): Call

Quarter of the year, from 1 to 4.

Parameter	Type	Default	Description
`$x`	`mixed`		A date or datetime expression.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: at evaluation, when a value is a time.

`month()`

month(mixed $x): Call

Month of the date or datetime, from 1 to 12.

Parameter	Type	Default	Description
`$x`	`mixed`		A date or datetime expression.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: at evaluation, when a value is a time.

`day()`

day(mixed $x): Call

Day of the month, from 1 to 31.

Parameter	Type	Default	Description
`$x`	`mixed`		A date or datetime expression.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: at evaluation, when a value is a time.

`wday()`

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

Day of the week, from 1 to 7.

Parameter	Type	Default	Description
`$x`	`mixed`		A date or datetime expression.
`...$options`	`mixed`		Named options: week_start (int, default 7) is the day numbered 1, from 1 for Monday to 7 for Sunday.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: at evaluation, when a value is a time.

`yday()`

yday(mixed $x): Call

Day of the year, from 1 to 366.

Parameter	Type	Default	Description
`$x`	`mixed`		A date or datetime expression.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: at evaluation, when a value is a time.

`hour()`

hour(mixed $x): Call

Hour of the datetime or time, from 0 to 23.

Parameter	Type	Default	Description
`$x`	`mixed`		A datetime or time expression.

Function in Phibble\Expr
Returns Call

`minute()`

minute(mixed $x): Call

Minute of the datetime or time, from 0 to 59.

Parameter	Type	Default	Description
`$x`	`mixed`		A datetime or time expression.

Function in Phibble\Expr
Returns Call

`second()`

second(mixed $x): Call

Second of the datetime or time, with any fraction.

Parameter	Type	Default	Description
`$x`	`mixed`		A datetime or time expression.

Function in Phibble\Expr
Returns Call

Rounding and differences

`floor_date()`

floor_date(mixed $x, mixed $unit, mixed ...$options): Call

Date or datetime rounded down to the start of its unit.

SQL backends evaluate it in memory when it reads a column.

Parameter	Type	Description
`$x`	`mixed`	A date or datetime expression.
`$unit`	`mixed`	The unit, optionally with a count, such as ‘month’ or ‘15 minutes’: second, minute, hour, day, week, month, bimonth, quarter, or year.
`...$options`	`mixed`	Named options: week_start (int, default 7) is the first day of a week, from 1 for Monday to 7 for Sunday.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: at evaluation, when the unit is unknown.

`ceiling_date()`

ceiling_date(mixed $x, mixed $unit, mixed ...$options): Call

Date or datetime rounded up to the start of the next unit.

A datetime already on a boundary is unchanged; a date moves to the next boundary, as in lubridate. SQL backends evaluate it in memory when it reads a column.

Parameter	Type	Description
`$x`	`mixed`	A date or datetime expression.
`$unit`	`mixed`	The unit, optionally with a count, such as ‘month’ or ‘15 minutes’: second, minute, hour, day, week, month, bimonth, quarter, or year.
`...$options`	`mixed`	Named options: week_start (int, default 7) is the first day of a week, from 1 for Monday to 7 for Sunday.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: at evaluation, when the unit is unknown.

`round_date()`

round_date(mixed $x, mixed $unit, mixed ...$options): Call

Date or datetime rounded to the nearer of floor_date() and ceiling_date().

A value halfway between rounds up. SQL backends evaluate it in memory when it reads a column.

Parameter	Type	Description
`$x`	`mixed`	A date or datetime expression.
`$unit`	`mixed`	The unit, optionally with a count, such as ‘month’ or ‘15 minutes’: second, minute, hour, day, week, month, bimonth, quarter, or year.
`...$options`	`mixed`	Named options: week_start (int, default 7) is the first day of a week, from 1 for Monday to 7 for Sunday.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: at evaluation, when the unit is unknown.

`difftime()`

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

Difference $x - $y between two dates or datetimes, as a float in the given units.

The result is NA where either value is NA.

Parameter	Type	Description
`$x`	`mixed`	A date or datetime expression.
`$y`	`mixed`	A date or datetime expression.
`...$options`	`mixed`	Named options: units (string, default ‘days’) is ‘secs’, ‘mins’, ‘hours’, ‘days’, or ‘weeks’.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: at evaluation, when units is another value.

Periods

`seconds()`

seconds(mixed $n): Call

Period of $n seconds, to add to or subtract from a date or datetime.

A fraction of a second is kept. A date plus seconds is a datetime.

Parameter	Type	Default	Description
`$n`	`mixed`		The number of seconds.

Function in Phibble\Expr
Returns Call

`minutes()`

minutes(mixed $n): Call

Period of $n minutes, to add to or subtract from a date or datetime.

A date plus minutes is a datetime.

Parameter	Type	Default	Description
`$n`	`mixed`		The number of minutes, a whole number.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: for a fractional count, as in lubridate.

`hours()`

hours(mixed $n): Call

Period of $n hours, to add to or subtract from a date or datetime.

A date plus hours is a datetime.

Parameter	Type	Default	Description
`$n`	`mixed`		The number of hours, a whole number.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: for a fractional count, as in lubridate.

`days()`

days(mixed $n): Call

Period of $n days, to add to or subtract from a date or datetime.

Days are calendar days, so the clock time is kept across a daylight saving change.

Parameter	Type	Default	Description
`$n`	`mixed`		The number of days, a whole number.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: for a fractional count, as in lubridate.

`weeks()`

weeks(mixed $n): Call

Period of $n weeks, to add to or subtract from a date or datetime.

Parameter	Type	Default	Description
`$n`	`mixed`		The number of weeks, a whole number.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: for a fractional count, as in lubridate.

`months()`

months(mixed $n): Call

Period of $n months, to add to or subtract from a date or datetime.

A result that lands on a day the month lacks, such as January 31 plus one month, is NA, as in lubridate.

Parameter	Type	Default	Description
`$n`	`mixed`		The number of months, a whole number.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: for a fractional count, as in lubridate.

`years()`

years(mixed $n): Call

Period of $n years, to add to or subtract from a date or datetime.

A result that lands on a day the year lacks, such as February 29 plus one year, is NA, as in lubridate.

Parameter	Type	Default	Description
`$n`	`mixed`		The number of years, a whole number.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: for a fractional count, as in lubridate.

Time zones and the clock

`with_tz()`

with_tz(mixed $x, mixed $tz): Call

Same instant shown in another time zone.

SQL backends evaluate it in memory when it reads a column.

Parameter	Type	Default	Description
`$x`	`mixed`		A datetime expression.
`$tz`	`mixed`		The time zone name, such as ‘America/New_York’.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: at evaluation, when the time zone is unknown.

`force_tz()`

force_tz(mixed $x, mixed $tz): Call

Same clock time in another time zone, which changes the instant.

A clock time the zone skips, in a daylight saving gap, gives NA. SQL backends evaluate it in memory when it reads a column.

Parameter	Type	Default	Description
`$x`	`mixed`		A datetime expression.
`$tz`	`mixed`		The time zone name, such as ‘America/New_York’.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: at evaluation, when the time zone is unknown.

`today()`

today(mixed ...$options): Call

Current date.

Parameter	Type	Default	Description
`...$options`	`mixed`		Named options: tz (string, default ‘UTC’) is the time zone whose calendar gives the date.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: at evaluation, when tz is not a known time zone.

`now()`

now(mixed ...$options): Call

Current date and time.

Parameter	Type	Default	Description
`...$options`	`mixed`		Named options: tz (string, default ‘UTC’) is the time zone of the result.

Function in Phibble\Expr
Returns Call
Throws InvalidArgumentException: at evaluation, when tz is not a known time zone.

`Clock::freeze()`

Clock::freeze(?DateTimeImmutable $at): void

Fix the time that today() and now() read. Null restores the system clock.

Parameter	Type	Default	Description
`$at`	`?DateTimeImmutable`

Static method of Phibble\Expr\Clock

`Clock::now()`

Clock::now(): DateTimeImmutable

The current time in UTC, or the frozen time.

Static method of Phibble\Expr\Clock
Returns DateTimeImmutable