Skip to content

Get a default value of a specific type

Source code

Description

[Experimental] Get a default value of a specific type:

  • Integers and floats are their zero value as default, unless otherwise specified;
  • Temporals are a physical zero as default;
  • pl$Decimal is zero as default;
  • pl$String and pl$Binary are an empty string;
  • pl$List is an empty list, unless otherwise specified;
  • pl$Array is the inner default value repeated over the shape;
  • pl$Struct is the inner default value for all fields;
  • pl$Enum is the first category if it exists;
  • pl$Null and pl$Categorical are null.

Usage

<DataTypeExpr>$default_value(
  n = 1,
  ...,
  numeric_to_one = FALSE,
  num_list_values = 0
)

Arguments

n Number of values in the output.
… These dots are for future extensions and must be empty.
numeric_to_one Use 1 instead of 0 as the default value for numeric types.
num_list_values The amount of values a list contains.

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

See Also

  • as_polars_series(): R -\> Polars type mapping is mostly defined by this function.

Examples

library("polars")

uint32 <- pl$UInt32$to_dtype_expr()
string <- pl$String$to_dtype_expr()
array <- pl$Array(pl$Float64, 2)$to_dtype_expr()

pl$select(
  uint32_default = uint32$default_value(),
  uint32_default_bis = uint32$default_value(numeric_to_one = TRUE),
  string_default = string$default_value(),
  array_default = array$default_value()
)

#> shape: (1, 4)
#> ┌────────────────┬────────────────────┬────────────────┬───────────────┐
#> │ uint32_default ┆ uint32_default_bis ┆ string_default ┆ array_default │
#> │ ---            ┆ ---                ┆ ---            ┆ ---           │
#> │ u32            ┆ u32                ┆ str            ┆ array[f64, 2] │
#> ╞════════════════╪════════════════════╪════════════════╪═══════════════╡
#> │ 0              ┆ 1                  ┆                ┆ [0.0, 0.0]    │
#> └────────────────┴────────────────────┴────────────────┴───────────────┘

# Return more values with `n`
pl$select(uint32_default = uint32$default_value(n = 3))

#> shape: (3, 1)
#> ┌────────────────┐
#> │ uint32_default │
#> │ ---            │
#> │ u32            │
#> ╞════════════════╡
#> │ 0              │
#> │ 0              │
#> │ 0              │
#> └────────────────┘

# Customize the number of default values in a list with `num_list_values`
l <- pl$List(pl$Float64)$to_dtype_expr()
pl$select(
  list_default = l$default_value(),
  list_default_bis = l$default_value(num_list_values = 3),
)

#> shape: (1, 2)
#> ┌──────────────┬──────────────────┐
#> │ list_default ┆ list_default_bis │
#> │ ---          ┆ ---              │
#> │ list[f64]    ┆ list[f64]        │
#> ╞══════════════╪══════════════════╡
#> │ []           ┆ [0.0, 0.0, 0.0]  │
#> └──────────────┴──────────────────┘