Return the first n characters of each string

Description

Usage

<Expr>$str$head(n)

Arguments

`n`	Length of the slice (integer or expression). Strings are parsed as column names. Negative indexing is supported.

Details

The n input is defined in terms of the number of characters in the (UTF-8) string. A character is defined as a Unicode scalar value. A single character is represented by a single byte when working with ASCII text, and a maximum of 4 bytes otherwise.

When the n input is negative, head() returns characters up to the nth from the end of the string. For example, if n = -3, then all characters except the last three are returned.

If the length of the string has fewer than n characters, the full string is returned.

Value

Expr: Series of dtype String.

Examples

library("polars")

df = pl$DataFrame(
  s = c("pear", NA, "papaya", "dragonfruit"),
  n = c(3, 4, -2, -5)
)

df$with_columns(
  s_head_5 = pl$col("s")$str$head(5),
  s_head_n = pl$col("s")$str$head("n")
)

#> shape: (4, 4)
#> ┌─────────────┬──────┬──────────┬──────────┐
#> │ s           ┆ n    ┆ s_head_5 ┆ s_head_n │
#> │ ---         ┆ ---  ┆ ---      ┆ ---      │
#> │ str         ┆ f64  ┆ str      ┆ str      │
#> ╞═════════════╪══════╪══════════╪══════════╡
#> │ pear        ┆ 3.0  ┆ pear     ┆ pea      │
#> │ null        ┆ 4.0  ┆ null     ┆ null     │
#> │ papaya      ┆ -2.0 ┆ papay    ┆ papa     │
#> │ dragonfruit ┆ -5.0 ┆ drago    ┆ dragon   │
#> └─────────────┴──────┴──────────┴──────────┘