Skip to content

Convert a Date/Time/Datetime/Duration column into a String column with the given format

Description

Similar to $cast(pl$String), but this method allows you to customize the formatting of the resulting string; if no format is provided, the appropriate ISO format for the underlying data type is used.

Usage

<Expr>$dt$to_string(format = NULL)

Arguments

format Single string of format to use, or NULL (default). NULL will be treated as “iso”. Available formats depend on the column data type:
  • For Date/Time/Datetime, refer to the chrono strftime documentation for specification. Example: “%y-%m-%d”. Special case “iso” will use the ISO8601 format.
  • For Duration, “iso” or “polars” can be used. The “iso” format string results in ISO8601 duration string output, and “polars” results in the same form seen in the polars print representation.

Value

A polars expression

Examples

library("polars")


df <- pl$DataFrame(
  dt = as.Date(c("1990-03-01", "2020-05-03", "2077-07-05")),
  dtm = as.POSIXct(c("1980-08-10 00:10:20", "2010-10-20 08:25:35", "2040-12-30 16:40:50")),
  tm = hms::as_hms(c("01:02:03.456789", "23:59:09.101", "00:00:00.000100")),
  dur = clock::duration_days(c(-1, 14, 0)) + clock::duration_hours(c(0, -10, 0)) +
    clock::duration_seconds(c(-42, 0, 0)) + clock::duration_microseconds(c(0, 1001, 0)),
)

# Default format for temporal dtypes is ISO8601:
df$select((cs$date() | cs$datetime())$dt$to_string()$name$prefix("s_"))

#> shape: (3, 2)
#> ┌────────────┬─────────────────────────┐
#> │ s_dt       ┆ s_dtm                   │
#> │ ---        ┆ ---                     │
#> │ str        ┆ str                     │
#> ╞════════════╪═════════════════════════╡
#> │ 1990-03-01 ┆ 1980-08-10 00:10:20.000 │
#> │ 2020-05-03 ┆ 2010-10-20 08:25:35.000 │
#> │ 2077-07-05 ┆ 2040-12-30 16:40:50.000 │
#> └────────────┴─────────────────────────┘

df$select((cs$time() | cs$duration())$dt$to_string()$name$prefix("s_"))

#> shape: (3, 2)
#> ┌────────────────────┬───────────────────┐
#> │ s_tm               ┆ s_dur             │
#> │ ---                ┆ ---               │
#> │ str                ┆ str               │
#> ╞════════════════════╪═══════════════════╡
#> │ 01:02:03.456789016 ┆ -P1DT42S          │
#> │ 23:59:09.101000070 ┆ P13DT14H0.001001S │
#> │ 00:00:00.000099897 ┆ PT0S              │
#> └────────────────────┴───────────────────┘

# All temporal types (aside from Duration) support strftime formatting:
df$select(
  pl$col("dtm"),
  s_dtm = pl$col("dtm")$dt$to_string("%Y/%m/%d (%H.%M.%S)"),
)

#> shape: (3, 2)
#> ┌─────────────────────┬───────────────────────┐
#> │ dtm                 ┆ s_dtm                 │
#> │ ---                 ┆ ---                   │
#> │ datetime[ms]        ┆ str                   │
#> ╞═════════════════════╪═══════════════════════╡
#> │ 1980-08-10 00:10:20 ┆ 1980/08/10 (00.10.20) │
#> │ 2010-10-20 08:25:35 ┆ 2010/10/20 (08.25.35) │
#> │ 2040-12-30 16:40:50 ┆ 2040/12/30 (16.40.50) │
#> └─────────────────────┴───────────────────────┘

# The Polars Duration string format is also available:
df$select(pl$col("dur"), s_dur = pl$col("dur")$dt$to_string("polars"))

#> shape: (3, 2)
#> ┌────────────────┬────────────────┐
#> │ dur            ┆ s_dur          │
#> │ ---            ┆ ---            │
#> │ duration[μs]   ┆ str            │
#> ╞════════════════╪════════════════╡
#> │ -1d -42s       ┆ -1d -42s       │
#> │ 13d 14h 1001µs ┆ 13d 14h 1001µs │
#> │ 0µs            ┆ 0µs            │
#> └────────────────┴────────────────┘

# If you’re interested in extracting the day or month names,
# you can use the '%A' and '%B' strftime specifiers:
df$select(
  pl$col("dt"),
  day_name = pl$col("dtm")$dt$to_string("%A"),
  month_name = pl$col("dtm")$dt$to_string("%B"),
)

#> shape: (3, 3)
#> ┌────────────┬───────────┬────────────┐
#> │ dt         ┆ day_name  ┆ month_name │
#> │ ---        ┆ ---       ┆ ---        │
#> │ date       ┆ str       ┆ str        │
#> ╞════════════╪═══════════╪════════════╡
#> │ 1990-03-01 ┆ Sunday    ┆ August     │
#> │ 2020-05-03 ┆ Wednesday ┆ October    │
#> │ 2077-07-05 ┆ Sunday    ┆ December   │
#> └────────────┴───────────┴────────────┘