Skip to content

Create a Polars literal expression of type Datetime

Description

Create a Polars literal expression of type Datetime

Usage

pl$datetime(
  year,
  month,
  day,
  hour = NULL,
  minute = NULL,
  second = NULL,
  microsecond = NULL,
  ...,
  time_unit = c("us", "ns", "ms"),
  time_zone = NULL,
  ambiguous = c("raise", "earliest", "latest", "null")
)

Arguments

year An polars expression or something can be coerced to an polars expression by as_polars_expr(), which represents a column or literal number of year.
month An polars expression or something can be coerced to an polars expression by as_polars_expr(), which represents a column or literal number of month. Range: 1-12.
day An polars expression or something can be coerced to an polars expression by as_polars_expr(), which represents a column or literal number of day. Range: 1-31.
hour An polars expression or something can be coerced to an polars expression by as_polars_expr(), which represents a column or literal number of hour. Range: 0-23.
minute An polars expression or something can be coerced to an polars expression by as_polars_expr(), which represents a column or literal number of minute. Range: 0-59.
second An polars expression or something can be coerced to an polars expression by as_polars_expr(), which represents a column or literal number of second. Range: 0-59.
microsecond An polars expression or something can be coerced to an polars expression by as_polars_expr(), which represents a column or literal number of microsecond. Range: 0-999999.
… These dots are for future extensions and must be empty.
time_unit One of “us” (default, microseconds), “ns” (nanoseconds) or “ms”(milliseconds). Representing the unit of time.
time_zone A string or NULL (default). Representing the timezone.
ambiguous Determine how to deal with ambiguous datetimes. Character vector or expression containing the followings:
  • “raise” (default): Throw an error
  • “earliest”: Use the earliest datetime
  • “latest”: Use the latest datetime
  • “null”: Return a null value

Value

A polars expression

Examples

library("polars")

df <- pl$DataFrame(
  month = c(1, 2, 3),
  day = c(4, 5, 6),
  hour = c(12, 13, 14),
  minute = c(15, 30, 45)
)

df$with_columns(
  pl$datetime(
    2024,
    pl$col("month"),
    pl$col("day"),
    pl$col("hour"),
    pl$col("minute"),
    time_zone = "Australia/Sydney"
  )
)

#> shape: (3, 5)
#> ┌───────┬─────┬──────┬────────┬────────────────────────────────┐
#> │ month ┆ day ┆ hour ┆ minute ┆ datetime                       │
#> │ ---   ┆ --- ┆ ---  ┆ ---    ┆ ---                            │
#> │ f64   ┆ f64 ┆ f64  ┆ f64    ┆ datetime[μs, Australia/Sydney] │
#> ╞═══════╪═════╪══════╪════════╪════════════════════════════════╡
#> │ 1.0   ┆ 4.0 ┆ 12.0 ┆ 15.0   ┆ 2024-01-04 12:15:00 AEDT       │
#> │ 2.0   ┆ 5.0 ┆ 13.0 ┆ 30.0   ┆ 2024-02-05 13:30:00 AEDT       │
#> │ 3.0   ┆ 6.0 ┆ 14.0 ┆ 45.0   ┆ 2024-03-06 14:45:00 AEDT       │
#> └───────┴─────┴──────┴────────┴────────────────────────────────┘

# We can also use `pl$datetime()` for filtering:
df <- pl$select(
  start = ISOdatetime(2024, 1, 1, 0, 0, 0),
  end = c(
    ISOdatetime(2024, 5, 1, 20, 15, 10),
    ISOdatetime(2024, 7, 1, 21, 25, 20),
    ISOdatetime(2024, 9, 1, 22, 35, 30)
  )
)

df$filter(pl$col("end") > pl$datetime(2024, 6, 1))

#> shape: (2, 2)
#> ┌─────────────────────┬─────────────────────┐
#> │ start               ┆ end                 │
#> │ ---                 ┆ ---                 │
#> │ datetime[ms]        ┆ datetime[ms]        │
#> ╞═════════════════════╪═════════════════════╡
#> │ 2024-01-01 00:00:00 ┆ 2024-07-01 21:25:20 │
#> │ 2024-01-01 00:00:00 ┆ 2024-09-01 22:35:30 │
#> └─────────────────────┴─────────────────────┘