Create a Polars expression from an R object

Description

The as_polars_expr() function creates a polars expression from various R objects. This function is used internally by various polars functions that accept expressions. In most cases, users should use pl$lit() instead of this function, which is a shorthand for as_polars_expr(x, as_lit = TRUE). (In other words, this function can be considered as an internal implementation to realize the lit function of the Polars API in other languages.)

Usage

as_polars_expr(x, ...)

# Default S3 method:
as_polars_expr(x, ..., keep_series = FALSE)

# S3 method for class 'polars_expr'
as_polars_expr(x, ..., structify = FALSE)

# S3 method for class 'character'
as_polars_expr(x, ..., as_lit = FALSE)

# S3 method for class 'raw'
as_polars_expr(x, ..., raw_as_binary = TRUE)

# S3 method for class ''NULL''
as_polars_expr(x, ...)

Arguments

x An R object.

… Additional arguments passed to the methods.

keep_series A logical value indicating whether to treat the object as a Series or scalar value. If TRUE, the output is ensured to be a Series literal even if the length of the object is 1.

structify A logical. If TRUE, convert multi-column expressions to a single struct expression by calling pl$struct(). Otherwise (default), done nothing.

as_lit A logical value indicating whether to treat vector as literal values or not. This argument is always set to TRUE when calling this function from pl$lit(), and expects to return literal values. See examples for details.

raw_as_binary A logical value indicating whether to convert raw vector to a Binary type scalar. If TRUE (default), the output is a Binary type scalar instead of UInt8 type literal.

Details

Because R objects are typically mapped to Series, this function often calls as_polars_series() internally. However, unlike R, Polars has scalars of length 1, so if an R object is converted to a Series of length 1, this function get the first value of the Series and convert it to a scalar literal. If you want to implement your own conversion from an R class to a Polars object, define an S3 method for as_polars_series() instead of this function.

Default S3 method

Create a Series by calling as_polars_series() and then convert that Series to an Expr. If the length of the Series is 1, it will be converted to a scalar value.

Additional arguments … are passed to as_polars_series().

S3 method for character

If the as_lit argument is FALSE (default), this function will call pl$col() and the character vector is treated as column names. Otherwise, the default method is called.

S3 method for raw

If the raw_as_binary argument is TRUE (default), the raw vector is converted to a Binary type scalar. Otherwise, the default method is called.

S3 method for `NULL`

NULL is converted to a Null type null literal.

Value

A polars expression

Examples

library("polars")

# character
# as_lit = FALSE (default)
as_polars_expr("a") # Same as `pl$col("a")`

#> col("a")

as_polars_expr(c("a", "b")) # Same as `pl$col("a", "b")`

#> cols(["a", "b"])

# as_lit = TRUE
as_polars_expr(character(0), as_lit = TRUE)

#> Series[literal]

as_polars_expr("a", as_lit = TRUE)

#> "a"

as_polars_expr(NA_character_, as_lit = TRUE)

#> null

as_polars_expr(c("a", "b"), as_lit = TRUE)

#> Series[literal]

# raw
as_polars_expr(as.raw(1))

#> b"\x01"

as_polars_expr(as.raw(1), raw_as_binary = FALSE)

#> 1

as_polars_expr(charToRaw("foo"))

#> b"foo"

as_polars_expr(charToRaw("foo"), raw_as_binary = FALSE)

#> Series[literal]

# NULL
as_polars_expr(NULL)

#> null

# default method (for integer)
as_polars_expr(integer(0))

#> Series[literal]

as_polars_expr(1L)

#> 1

as_polars_expr(NA_integer_)

#> null

as_polars_expr(c(1L, 2L))

#> Series[literal]

# default method (for double)
as_polars_expr(double(0))

#> Series[literal]

as_polars_expr(1)

#> 1.0

as_polars_expr(NA_real_)

#> null

as_polars_expr(c(1, 2))

#> Series[literal]

# default method (for list)
as_polars_expr(list())

#> Series[literal]

as_polars_expr(list(1))

#> [1.0]

as_polars_expr(list(1, 2))

#> Series[literal]

# default method (for Date)
as_polars_expr(as.Date(integer(0)))

#> Series[literal]

as_polars_expr(as.Date("2021-01-01"))

#> 2021-01-01

as_polars_expr(as.Date(c("2021-01-01", "2021-01-02")))

#> Series[literal]

# default method (for Series)
as_polars_series(1) |>
  as_polars_expr()

#> 1.0

# polars_expr
as_polars_expr(pl$col("a", "b"))

#> cols(["a", "b"])

as_polars_expr(pl$col("a", "b"), structify = TRUE)

#> cols(["a", "b"]).as_struct()