# Licensed to the Apache Software Foundation (ASF) under one

# or more contributor license agreements. See the NOTICE file

# distributed with this work for additional information

# regarding copyright ownership. The ASF licenses this file

# to you under the Apache License, Version 2.0 (the

# "License"); you may not use this file except in compliance

# with the License. You may obtain a copy of the License at

#

# http://www.apache.org/licenses/LICENSE-2.0

#

# Unless required by applicable law or agreed to in writing,

# software distributed under the License is distributed on an

# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY

# KIND, either express or implied. See the License for the

# specific language governing permissions and limitations

# under the License.

"""User functions for operating on :py:class:`~datafusion.expr.Expr`."""

from __future__ import annotations

from datafusion._internal import functions as f

from datafusion.expr import (

CaseBuilder,

Expr,

WindowFrame,

SortExpr,

sort_list_to_raw_sort_list,

expr_list_to_raw_expr_list,

)

from datafusion.context import SessionContext

from datafusion.common import NullTreatment

from typing import Any, Optional

import pyarrow as pa

__all__ = [

"abs",

"acos",

"acosh",

"alias",

"approx_distinct",

"approx_median",

"approx_percentile_cont",

"approx_percentile_cont_with_weight",

"array",

"array_agg",

"array_append",

"array_cat",

"array_concat",

"array_dims",

"array_distinct",

"array_element",

"array_except",

"array_extract",

"array_has",

"array_has_all",

"array_has_any",

"array_indexof",

"array_intersect",

"array_join",

"array_length",

"array_ndims",

"array_pop_back",

"array_pop_front",

"array_position",

"array_positions",

"array_prepend",

"array_push_back",

"array_push_front",

"array_remove",

"array_remove_all",

"array_remove_n",

"array_repeat",

"array_replace",

"array_replace_all",

"array_replace_n",

"array_resize",

"array_slice",

"array_sort",

"array_to_string",

"array_union",

"arrow_typeof",

"ascii",

"asin",

"asinh",

"atan",

"atan2",

"atanh",

"avg",

"bit_and",

"bit_length",

"bit_or",

"bit_xor",

"bool_and",

"bool_or",

"btrim",

"case",

"cbrt",

"ceil",

"char_length",

"character_length",

"chr",

"coalesce",

"col",

"concat",

"concat_ws",

"corr",

"cos",

"cosh",

"cot",

"count",

"count_star",

"covar",

"covar_pop",

"covar_samp",

"current_date",

"current_time",

"date_bin",

"date_part",

"date_trunc",

"datepart",

"datetrunc",

"decode",

"degrees",

"digest",

"encode",

"ends_with",

"exp",

"factorial",

"find_in_set",

"first_value",

"flatten",

"floor",

"from_unixtime",

"gcd",

"in_list",

"initcap",

"isnan",

"iszero",

"last_value",

"lcm",

"left",

"length",

"levenshtein",

"list_append",

"list_dims",

"list_distinct",

"list_element",

"list_except",

"list_extract",

"list_indexof",

"list_intersect",

"list_join",

"list_length",

"list_ndims",

"list_position",

"list_positions",

"list_prepend",

"list_push_back",

"list_push_front",

"list_remove",

"list_remove_all",

"list_remove_n",

"list_replace",

"list_replace_all",

"list_replace_n",

"list_resize",

"list_slice",

"list_sort",

"list_to_string",

"list_union",

"ln",

"log",

"log10",

"log2",

"lower",

"lpad",

"ltrim",

"make_array",

"make_date",

"max",

"md5",

"mean",

"median",

"min",

"named_struct",

"nanvl",

"now",

"nth_value",

"nullif",

"octet_length",

"order_by",

"overlay",

"pi",

"pow",

"power",

"radians",

"random",

"range",

"regexp_like",

"regexp_match",

"regexp_replace",

"regr_avgx",

"regr_avgy",

"regr_count",

"regr_intercept",

"regr_r2",

"regr_slope",

"regr_sxx",

"regr_sxy",

"regr_syy",

"repeat",

"replace",

"reverse",

"right",

"round",

"rpad",

"rtrim",

"sha224",

"sha256",

"sha384",

"sha512",

"signum",

"sin",

"sinh",

"split_part",

"sqrt",

"starts_with",

"stddev",

"stddev_pop",

"stddev_samp",

"string_agg",

"strpos",

"struct",

"substr",

"substr_index",

"substring",

"sum",

"tan",

"tanh",

"to_hex",

"to_timestamp",

"to_timestamp_micros",

"to_timestamp_millis",

"to_timestamp_seconds",

"to_unixtime",

"translate",

"trim",

"trunc",

"upper",

"uuid",

"var",

"var_pop",

"var_samp",

"var_sample",

"when",

# Window Functions

"window",

"lead",

"lag",

"row_number",

"rank",

"dense_rank",

"percent_rank",

"cume_dist",

"ntile",

]

def isnan(expr: Expr) -> Expr:

"""Returns true if a given number is +NaN or -NaN otherwise returns false."""

return Expr(f.isnan(expr.expr))

def nullif(expr1: Expr, expr2: Expr) -> Expr:

"""Returns NULL if expr1 equals expr2; otherwise it returns expr1.

This can be used to perform the inverse operation of the COALESCE expression.

"""

return Expr(f.nullif(expr1.expr, expr2.expr))

def encode(input: Expr, encoding: Expr) -> Expr:

"""Encode the ``input``, using the ``encoding``. encoding can be base64 or hex."""

return Expr(f.encode(input.expr, encoding.expr))

def decode(input: Expr, encoding: Expr) -> Expr:

"""Decode the ``input``, using the ``encoding``. encoding can be base64 or hex."""

return Expr(f.decode(input.expr, encoding.expr))

def array_to_string(expr: Expr, delimiter: Expr) -> Expr:

"""Converts each element to its text representation."""

return Expr(f.array_to_string(expr.expr, delimiter.expr))

def array_join(expr: Expr, delimiter: Expr) -> Expr:

"""Converts each element to its text representation.

This is an alias for :py:func:`array_to_string`.

"""

return array_to_string(expr, delimiter)

def list_to_string(expr: Expr, delimiter: Expr) -> Expr:

"""Converts each element to its text representation.

This is an alias for :py:func:`array_to_string`.

"""

return array_to_string(expr, delimiter)

def list_join(expr: Expr, delimiter: Expr) -> Expr:

"""Converts each element to its text representation.

This is an alias for :py:func:`array_to_string`.

"""

return array_to_string(expr, delimiter)

def in_list(arg: Expr, values: list[Expr], negated: bool = False) -> Expr:

"""Returns whether the argument is contained within the list ``values``."""

values = [v.expr for v in values]

return Expr(f.in_list(arg.expr, values, negated))

def digest(value: Expr, method: Expr) -> Expr:

"""Computes the binary hash of an expression using the specified algorithm.

Standard algorithms are md5, sha224, sha256, sha384, sha512, blake2s,

blake2b, and blake3.

"""

return Expr(f.digest(value.expr, method.expr))

def concat(*args: Expr) -> Expr:

"""Concatenates the text representations of all the arguments.

NULL arguments are ignored.

"""

args = [arg.expr for arg in args]

return Expr(f.concat(args))

def concat_ws(separator: str, *args: Expr) -> Expr:

"""Concatenates the list ``args`` with the separator.

``NULL`` arguments are ignored. ``separator`` should not be ``NULL``.

"""

args = [arg.expr for arg in args]

return Expr(f.concat_ws(separator, args))

def order_by(expr: Expr, ascending: bool = True, nulls_first: bool = True) -> SortExpr:

"""Creates a new sort expression."""

return SortExpr(expr.expr, ascending=ascending, nulls_first=nulls_first)

def alias(expr: Expr, name: str) -> Expr:

"""Creates an alias expression."""

return Expr(f.alias(expr.expr, name))

def col(name: str) -> Expr:

"""Creates a column reference expression."""

return Expr(f.col(name))

def count_star(filter: Optional[Expr] = None) -> Expr:

"""Create a COUNT(1) aggregate expression.

This aggregate function will count all of the rows in the partition.

If using the builder functions described in ref:`_aggregation` this function ignores

the options ``order_by``, ``distinct``, and ``null_treatment``.

Args:

filter: If provided, only count rows for which the filter is True

"""

return count(Expr.literal(1), filter=filter)

def case(expr: Expr) -> CaseBuilder:

"""Create a case expression.

Create a :py:class:`~datafusion.expr.CaseBuilder` to match cases for the

expression ``expr``. See :py:class:`~datafusion.expr.CaseBuilder` for

detailed usage.

"""

return CaseBuilder(f.case(expr.expr))

def when(when: Expr, then: Expr) -> CaseBuilder:

"""Create a case expression that has no base expression.

Create a :py:class:`~datafusion.expr.CaseBuilder` to match cases for the

expression ``expr``. See :py:class:`~datafusion.expr.CaseBuilder` for

detailed usage.

"""

return CaseBuilder(f.when(when.expr, then.expr))

def window(

name: str,

args: list[Expr],

partition_by: list[Expr] | None = None,

order_by: list[Expr | SortExpr] | None = None,

window_frame: WindowFrame | None = None,

ctx: SessionContext | None = None,

) -> Expr:

"""Creates a new Window function expression.

This interface will soon be deprecated. Instead of using this interface,

users should call the window functions directly. For example, to perform a

lag use::

df.select(functions.lag(col("a")).partition_by(col("b")).build())

"""

args = [a.expr for a in args]

partition_by = expr_list_to_raw_expr_list(partition_by)

order_by_raw = sort_list_to_raw_sort_list(order_by)

window_frame = window_frame.window_frame if window_frame is not None else None

return Expr(f.window(name, args, partition_by, order_by_raw, window_frame, ctx))

# scalar functions

def abs(arg: Expr) -> Expr:

"""Return the absolute value of a given number.

Returns:

--------

Expr

A new expression representing the absolute value of the input expression.

"""

return Expr(f.abs(arg.expr))

def acos(arg: Expr) -> Expr:

"""Returns the arc cosine or inverse cosine of a number.

Returns:

--------

Expr

A new expression representing the arc cosine of the input expression.

"""

return Expr(f.acos(arg.expr))

def acosh(arg: Expr) -> Expr:

"""Returns inverse hyperbolic cosine."""

return Expr(f.acosh(arg.expr))

def ascii(arg: Expr) -> Expr:

"""Returns the numeric code of the first character of the argument."""

return Expr(f.ascii(arg.expr))

def asin(arg: Expr) -> Expr:

"""Returns the arc sine or inverse sine of a number."""

return Expr(f.asin(arg.expr))

def asinh(arg: Expr) -> Expr:

"""Returns inverse hyperbolic sine."""

return Expr(f.asinh(arg.expr))

def atan(arg: Expr) -> Expr:

"""Returns inverse tangent of a number."""

return Expr(f.atan(arg.expr))

def atanh(arg: Expr) -> Expr:

"""Returns inverse hyperbolic tangent."""

return Expr(f.atanh(arg.expr))

def atan2(y: Expr, x: Expr) -> Expr:

"""Returns inverse tangent of a division given in the argument."""

return Expr(f.atan2(y.expr, x.expr))

def bit_length(arg: Expr) -> Expr:

"""Returns the number of bits in the string argument."""

return Expr(f.bit_length(arg.expr))

def btrim(arg: Expr) -> Expr:

"""Removes all characters, spaces by default, from both sides of a string."""

return Expr(f.btrim(arg.expr))

def cbrt(arg: Expr) -> Expr:

"""Returns the cube root of a number."""

return Expr(f.cbrt(arg.expr))

def ceil(arg: Expr) -> Expr:

"""Returns the nearest integer greater than or equal to argument."""

return Expr(f.ceil(arg.expr))

def character_length(arg: Expr) -> Expr:

"""Returns the number of characters in the argument."""

return Expr(f.character_length(arg.expr))

def length(string: Expr) -> Expr:

"""The number of characters in the ``string``."""

return Expr(f.length(string.expr))

def char_length(string: Expr) -> Expr:

"""The number of characters in the ``string``."""

return Expr(f.char_length(string.expr))

def chr(arg: Expr) -> Expr:

"""Converts the Unicode code point to a UTF8 character."""

return Expr(f.chr(arg.expr))

def coalesce(*args: Expr) -> Expr:

"""Returns the value of the first expr in ``args`` which is not NULL."""

args = [arg.expr for arg in args]

return Expr(f.coalesce(*args))

def cos(arg: Expr) -> Expr:

"""Returns the cosine of the argument."""

return Expr(f.cos(arg.expr))

def cosh(arg: Expr) -> Expr:

"""Returns the hyperbolic cosine of the argument."""

return Expr(f.cosh(arg.expr))

def cot(arg: Expr) -> Expr:

"""Returns the cotangent of the argument."""

return Expr(f.cot(arg.expr))

def degrees(arg: Expr) -> Expr:

"""Converts the argument from radians to degrees."""

return Expr(f.degrees(arg.expr))

def ends_with(arg: Expr, suffix: Expr) -> Expr:

"""Returns true if the ``string`` ends with the ``suffix``, false otherwise."""

return Expr(f.ends_with(arg.expr, suffix.expr))

def exp(arg: Expr) -> Expr:

"""Returns the exponential of the argument."""

return Expr(f.exp(arg.expr))

def factorial(arg: Expr) -> Expr:

"""Returns the factorial of the argument."""

return Expr(f.factorial(arg.expr))

def find_in_set(string: Expr, string_list: Expr) -> Expr:

"""Find a string in a list of strings.

Returns a value in the range of 1 to N if the string is in the string list

``string_list`` consisting of N substrings.

The string list is a string composed of substrings separated by ``,`` characters.

"""

return Expr(f.find_in_set(string.expr, string_list.expr))

def floor(arg: Expr) -> Expr:

"""Returns the nearest integer less than or equal to the argument."""

return Expr(f.floor(arg.expr))

def gcd(x: Expr, y: Expr) -> Expr:

"""Returns the greatest common divisor."""

return Expr(f.gcd(x.expr, y.expr))

def initcap(string: Expr) -> Expr:

"""Set the initial letter of each word to capital.

Converts the first letter of each word in ``string`` to uppercase and the remaining

characters to lowercase.

"""

return Expr(f.initcap(string.expr))

def instr(string: Expr, substring: Expr) -> Expr:

"""Finds the position from where the ``substring`` matches the ``string``.

This is an alias for :py:func:`strpos`.

"""

return strpos(string, substring)

def iszero(arg: Expr) -> Expr:

"""Returns true if a given number is +0.0 or -0.0 otherwise returns false."""

return Expr(f.iszero(arg.expr))

def lcm(x: Expr, y: Expr) -> Expr:

"""Returns the least common multiple."""

return Expr(f.lcm(x.expr, y.expr))

def left(string: Expr, n: Expr) -> Expr:

"""Returns the first ``n`` characters in the ``string``."""

return Expr(f.left(string.expr, n.expr))

def levenshtein(string1: Expr, string2: Expr) -> Expr:

"""Returns the Levenshtein distance between the two given strings."""

return Expr(f.levenshtein(string1.expr, string2.expr))

def ln(arg: Expr) -> Expr:

"""Returns the natural logarithm (base e) of the argument."""

return Expr(f.ln(arg.expr))

def log(base: Expr, num: Expr) -> Expr:

"""Returns the logarithm of a number for a particular ``base``."""

return Expr(f.log(base.expr, num.expr))

def log10(arg: Expr) -> Expr:

"""Base 10 logarithm of the argument."""

return Expr(f.log10(arg.expr))

def log2(arg: Expr) -> Expr:

"""Base 2 logarithm of the argument."""

return Expr(f.log2(arg.expr))

def lower(arg: Expr) -> Expr:

"""Converts a string to lowercase."""

return Expr(f.lower(arg.expr))

def lpad(string: Expr, count: Expr, characters: Expr | None = None) -> Expr:

"""Add left padding to a string.

Extends the string to length length by prepending the characters fill (a

space by default). If the string is already longer than length then it is

truncated (on the right).

"""

characters = characters if characters is not None else Expr.literal(" ")

return Expr(f.lpad(string.expr, count.expr, characters.expr))

def ltrim(arg: Expr) -> Expr:

"""Removes all characters, spaces by default, from the beginning of a string."""

return Expr(f.ltrim(arg.expr))

def md5(arg: Expr) -> Expr:

"""Computes an MD5 128-bit checksum for a string expression."""

return Expr(f.md5(arg.expr))

def nanvl(x: Expr, y: Expr) -> Expr:

"""Returns ``x`` if ``x`` is not ``NaN``. Otherwise returns ``y``."""

return Expr(f.nanvl(x.expr, y.expr))

def octet_length(arg: Expr) -> Expr:

"""Returns the number of bytes of a string."""

return Expr(f.octet_length(arg.expr))

def overlay(

string: Expr, substring: Expr, start: Expr, length: Expr | None = None

) -> Expr:

"""Replace a substring with a new substring.

Replace the substring of string that starts at the ``start``'th character and

extends for ``length`` characters with new substring.

"""

if length is None:

return Expr(f.overlay(string.expr, substring.expr, start.expr))

return Expr(f.overlay(string.expr, substring.expr, start.expr, length.expr))

def pi() -> Expr:

"""Returns an approximate value of π."""

return Expr(f.pi())

def position(string: Expr, substring: Expr) -> Expr:

"""Finds the position from where the ``substring`` matches the ``string``.

This is an alias for :py:func:`strpos`.

"""

return strpos(string, substring)

def power(base: Expr, exponent: Expr) -> Expr:

"""Returns ``base`` raised to the power of ``exponent``."""

return Expr(f.power(base.expr, exponent.expr))

def pow(base: Expr, exponent: Expr) -> Expr:

"""Returns ``base`` raised to the power of ``exponent``.

This is an alias of :py:func:`power`.

"""

return power(base, exponent)

def radians(arg: Expr) -> Expr:

"""Converts the argument from degrees to radians."""

return Expr(f.radians(arg.expr))

def regexp_like(string: Expr, regex: Expr, flags: Expr | None = None) -> Expr:

"""Find if any regular expression (regex) matches exist.

Tests a string using a regular expression returning true if at least one match,

false otherwise.

"""

if flags is not None:

flags = flags.expr

return Expr(f.regexp_like(string.expr, regex.expr, flags))

def regexp_match(string: Expr, regex: Expr, flags: Expr | None = None) -> Expr:

"""Perform regular expression (regex) matching.

Returns an array with each element containing the leftmost-first match of the

corresponding index in ``regex`` to string in ``string``.

"""

if flags is not None:

flags = flags.expr

return Expr(f.regexp_match(string.expr, regex.expr, flags))

def regexp_replace(

string: Expr, pattern: Expr, replacement: Expr, flags: Expr | None = None

) -> Expr:

"""Replaces substring(s) matching a PCRE-like regular expression.

The full list of supported features and syntax can be found at

<https://docs.rs/regex/latest/regex/#syntax>

Supported flags with the addition of 'g' can be found at

<https://docs.rs/regex/latest/regex/#grouping-and-flags>

"""

if flags is not None:

flags = flags.expr

return Expr(f.regexp_replace(string.expr, pattern.expr, replacement.expr, flags))

def repeat(string: Expr, n: Expr) -> Expr:

"""Repeats the ``string`` to ``n`` times."""

return Expr(f.repeat(string.expr, n.expr))

def replace(string: Expr, from_val: Expr, to_val: Expr) -> Expr:

"""Replaces all occurrences of ``from_val`` with ``to_val`` in the ``string``."""

return Expr(f.replace(string.expr, from_val.expr, to_val.expr))

def reverse(arg: Expr) -> Expr:

"""Reverse the string argument."""

return Expr(f.reverse(arg.expr))

def right(string: Expr, n: Expr) -> Expr:

"""Returns the last ``n`` characters in the ``string``."""

return Expr(f.right(string.expr, n.expr))

def round(value: Expr, decimal_places: Expr = Expr.literal(0)) -> Expr:

"""Round the argument to the nearest integer.

If the optional ``decimal_places`` is specified, round to the nearest number of

decimal places. You can specify a negative number of decimal places. For example

``round(lit(125.2345), lit(-2))`` would yield a value of ``100.0``.

"""

return Expr(f.round(value.expr, decimal_places.expr))

def rpad(string: Expr, count: Expr, characters: Expr | None = None) -> Expr:

"""Add right padding to a string.

Extends the string to length length by appending the characters fill (a space

by default). If the string is already longer than length then it is truncated.

"""

characters = characters if characters is not None else Expr.literal(" ")

return Expr(f.rpad(string.expr, count.expr, characters.expr))

def rtrim(arg: Expr) -> Expr:

"""Removes all characters, spaces by default, from the end of a string."""

return Expr(f.rtrim(arg.expr))

def sha224(arg: Expr) -> Expr:

"""Computes the SHA-224 hash of a binary string."""

return Expr(f.sha224(arg.expr))

def sha256(arg: Expr) -> Expr:

"""Computes the SHA-256 hash of a binary string."""

return Expr(f.sha256(arg.expr))

def sha384(arg: Expr) -> Expr:

"""Computes the SHA-384 hash of a binary string."""

return Expr(f.sha384(arg.expr))

def sha512(arg: Expr) -> Expr:

"""Computes the SHA-512 hash of a binary string."""

return Expr(f.sha512(arg.expr))

def signum(arg: Expr) -> Expr:

"""Returns the sign of the argument (-1, 0, +1)."""

return Expr(f.signum(arg.expr))

def sin(arg: Expr) -> Expr:

"""Returns the sine of the argument."""

return Expr(f.sin(arg.expr))

def sinh(arg: Expr) -> Expr:

"""Returns the hyperbolic sine of the argument."""

return Expr(f.sinh(arg.expr))

def split_part(string: Expr, delimiter: Expr, index: Expr) -> Expr:

"""Split a string and return one part.

Splits a string based on a delimiter and picks out the desired field based

on the index.

"""

return Expr(f.split_part(string.expr, delimiter.expr, index.expr))

def sqrt(arg: Expr) -> Expr:

"""Returns the square root of the argument."""

return Expr(f.sqrt(arg.expr))

def starts_with(string: Expr, prefix: Expr) -> Expr:

"""Returns true if string starts with prefix."""

return Expr(f.starts_with(string.expr, prefix.expr))

def strpos(string: Expr, substring: Expr) -> Expr:

"""Finds the position from where the ``substring`` matches the ``string``."""

return Expr(f.strpos(string.expr, substring.expr))

def substr(string: Expr, position: Expr) -> Expr:

"""Substring from the ``position`` to the end."""

return Expr(f.substr(string.expr, position.expr))

def substr_index(string: Expr, delimiter: Expr, count: Expr) -> Expr:

"""Returns an indexed substring.

The return will be the ``string`` from before ``count`` occurrences of

``delimiter``.

"""

return Expr(f.substr_index(string.expr, delimiter.expr, count.expr))

def substring(string: Expr, position: Expr, length: Expr) -> Expr:

"""Substring from the ``position`` with ``length`` characters."""

return Expr(f.substring(string.expr, position.expr, length.expr))

def tan(arg: Expr) -> Expr:

"""Returns the tangent of the argument."""

return Expr(f.tan(arg.expr))

def tanh(arg: Expr) -> Expr:

"""Returns the hyperbolic tangent of the argument."""

return Expr(f.tanh(arg.expr))

def to_hex(arg: Expr) -> Expr:

"""Converts an integer to a hexadecimal string."""

return Expr(f.to_hex(arg.expr))

def now() -> Expr:

"""Returns the current timestamp in nanoseconds.

This will use the same value for all instances of now() in same statement.

"""

return Expr(f.now())

def to_timestamp(arg: Expr, *formatters: Expr) -> Expr:

"""Converts a string and optional formats to a ``Timestamp`` in nanoseconds.

For usage of ``formatters`` see the rust chrono package ``strftime`` package.

[Documentation here.](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)

"""

if formatters is None:

return f.to_timestamp(arg.expr)

formatters = [f.expr for f in formatters]

return Expr(f.to_timestamp(arg.expr, *formatters))

def to_timestamp_millis(arg: Expr, *formatters: Expr) -> Expr:

"""Converts a string and optional formats to a ``Timestamp`` in milliseconds.

See :py:func:`to_timestamp` for a description on how to use formatters.

"""

return Expr(f.to_timestamp_millis(arg.expr, *formatters))

def to_timestamp_micros(arg: Expr, *formatters: Expr) -> Expr:

"""Converts a string and optional formats to a ``Timestamp`` in microseconds.

See :py:func:`to_timestamp` for a description on how to use formatters.

"""

return Expr(f.to_timestamp_micros(arg.expr, *formatters))

def to_timestamp_nanos(arg: Expr, *formatters: Expr) -> Expr:

"""Converts a string and optional formats to a ``Timestamp`` in nanoseconds.

See :py:func:`to_timestamp` for a description on how to use formatters.

"""

return Expr(f.to_timestamp_nanos(arg.expr, *formatters))

def to_timestamp_seconds(arg: Expr, *formatters: Expr) -> Expr:

"""Converts a string and optional formats to a ``Timestamp`` in seconds.

See :py:func:`to_timestamp` for a description on how to use formatters.

"""

return Expr(f.to_timestamp_seconds(arg.expr, *formatters))

def to_unixtime(string: Expr, *format_arguments: Expr) -> Expr:

"""Converts a string and optional formats to a Unixtime."""

args = [f.expr for f in format_arguments]

return Expr(f.to_unixtime(string.expr, *args))

def current_date() -> Expr:

"""Returns current UTC date as a Date32 value."""

return Expr(f.current_date())

def current_time() -> Expr:

"""Returns current UTC time as a Time64 value."""

return Expr(f.current_time())

def datepart(part: Expr, date: Expr) -> Expr:

"""Return a specified part of a date.

This is an alias for :py:func:`date_part`.

"""

return date_part(part, date)

def date_part(part: Expr, date: Expr) -> Expr:

"""Extracts a subfield from the date."""

return Expr(f.date_part(part.expr, date.expr))

def date_trunc(part: Expr, date: Expr) -> Expr:

"""Truncates the date to a specified level of precision."""

return Expr(f.date_trunc(part.expr, date.expr))

def datetrunc(part: Expr, date: Expr) -> Expr:

"""Truncates the date to a specified level of precision.

This is an alias for :py:func:`date_trunc`.

"""

return date_trunc(part, date)

def date_bin(stride: Expr, source: Expr, origin: Expr) -> Expr:

"""Coerces an arbitrary timestamp to the start of the nearest specified interval."""

return Expr(f.date_bin(stride.expr, source.expr, origin.expr))