Class: Polars::DateTimeExpr

Inherits:
Object
  • Object
show all
Defined in:
lib/polars/date_time_expr.rb

Overview

Namespace for datetime related expressions.

Instance Method Summary collapse

Instance Method Details

#add_business_days(n, week_mask: [true, true, true, true, true, false, false], holidays: [], roll: "raise") ⇒ Expr

Note:

This functionality is considered unstable. It may be changed at any point without it being considered a breaking change.

Offset by n business days.

Examples:

df = Polars::DataFrame.new({"start" => [Date.new(2020, 1, 1), Date.new(2020, 1, 2)]})
df.with_columns(result: Polars.col("start").dt.add_business_days(5))
# =>
# shape: (2, 2)
# ┌────────────┬────────────┐
# │ start      ┆ result     │
# │ ---        ┆ ---        │
# │ date       ┆ date       │
# ╞════════════╪════════════╡
# │ 2020-01-01 ┆ 2020-01-08 │
# │ 2020-01-02 ┆ 2020-01-09 │
# └────────────┴────────────┘

You can pass a custom weekend - for example, if you only take Sunday off:

week_mask = [true, true, true, true, true, true, false]
df.with_columns(
  result: Polars.col("start").dt.add_business_days(5, week_mask: week_mask)
)
# =>
# shape: (2, 2)
# ┌────────────┬────────────┐
# │ start      ┆ result     │
# │ ---        ┆ ---        │
# │ date       ┆ date       │
# ╞════════════╪════════════╡
# │ 2020-01-01 ┆ 2020-01-07 │
# │ 2020-01-02 ┆ 2020-01-08 │
# └────────────┴────────────┘

You can also pass a list of holidays:

holidays = [Date.new(2020, 1, 3), Date.new(2020, 1, 6)]
df.with_columns(
  result: Polars.col("start").dt.add_business_days(5, holidays: holidays)
)
# =>
# shape: (2, 2)
# ┌────────────┬────────────┐
# │ start      ┆ result     │
# │ ---        ┆ ---        │
# │ date       ┆ date       │
# ╞════════════╪════════════╡
# │ 2020-01-01 ┆ 2020-01-10 │
# │ 2020-01-02 ┆ 2020-01-13 │
# └────────────┴────────────┘

Roll all dates forwards to the next business day:

df = Polars::DataFrame.new({"start" => [Date.new(2020, 1, 5), Date.new(2020, 1, 6)]})
df.with_columns(
  rolled_forwards: Polars.col("start").dt.add_business_days(0, roll: "forward")
)
# =>
# shape: (2, 2)
# ┌────────────┬─────────────────┐
# │ start      ┆ rolled_forwards │
# │ ---        ┆ ---             │
# │ date       ┆ date            │
# ╞════════════╪═════════════════╡
# │ 2020-01-05 ┆ 2020-01-06      │
# │ 2020-01-06 ┆ 2020-01-06      │
# └────────────┴─────────────────┘

Parameters:

  • n —

    Number of business days to offset by. Can be a single number of an expression.

  • week_mask (defaults to: [true, true, true, true, true, false, false]) —

    Which days of the week to count. The default is Monday to Friday. If you wanted to count only Monday to Thursday, you would pass [true, true, true, true, false, false, false].

  • holidays (Object) (defaults to: []) —

    Holidays to exclude from the count.

  • roll (defaults to: "raise") —

    What to do when the start date lands on a non-business day. Options are:

    • 'raise': raise an error
    • 'forward': move to the next business day
    • 'backward': move to the previous business day

Returns:



97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/polars/date_time_expr.rb', line 97

def add_business_days(
  n,
  week_mask: [true, true, true, true, true, false, false],
  holidays: [],
  roll: "raise"
)
  n_rbexpr = Utils.parse_into_expression(n)
  holidays_rbexpr = Utils._holidays_to_expr(holidays)
  Utils.wrap_expr(
    _rbexpr.dt_add_business_days(
      n_rbexpr,
      week_mask,
      holidays_rbexpr,
      roll
    )
  )
end

#base_utc_offset ⇒ Expr

Base offset from UTC.

This is usually constant for all datetimes in a given time zone, but may vary in the rare case that a country switches time zone, like Samoa (Apia) did at the end of 2011.

Examples:

df = Polars::DataFrame.new(
  {
    "ts" => [DateTime.new(2011, 12, 29), DateTime.new(2012, 1, 1)],
  }
)
df = df.with_columns(Polars.col("ts").dt.replace_time_zone("Pacific/Apia"))
df.with_columns(Polars.col("ts").dt.base_utc_offset.alias("base_utc_offset"))
# =>
# shape: (2, 2)
# ┌────────────────────────────┬─────────────────┐
# │ ts                         ┆ base_utc_offset │
# │ ---                        ┆ ---             │
# │ datetime[ns, Pacific/Apia] ┆ duration[ms]    │
# ╞════════════════════════════╪═════════════════╡
# │ 2011-12-29 00:00:00 -10    ┆ -11h            │
# │ 2012-01-01 00:00:00 +14    ┆ 13h             │
# └────────────────────────────┴─────────────────┘

Returns:



1953
1954
1955
 
# File 'lib/polars/date_time_expr.rb', line 1953

def base_utc_offset
  Utils.wrap_expr(_rbexpr.dt_base_utc_offset)
end

#cast_time_unit(time_unit) ⇒ Expr

Cast the underlying data to another time unit. This may lose precision.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.datetime_range(
      DateTime.new(2001, 1, 1), DateTime.new(2001, 1, 3), "1d", eager: true
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date").dt.cast_time_unit("ms").alias("tu_ms"),
    Polars.col("date").dt.cast_time_unit("ns").alias("tu_ns")
  ]
)
# =>
# shape: (3, 3)
# ┌─────────────────────┬─────────────────────┬─────────────────────┐
# │ date                ┆ tu_ms               ┆ tu_ns               │
# │ ---                 ┆ ---                 ┆ ---                 │
# │ datetime[ns]        ┆ datetime[ms]        ┆ datetime[ns]        │
# ╞═════════════════════╪═════════════════════╪═════════════════════╡
# │ 2001-01-01 00:00:00 ┆ 2001-01-01 00:00:00 ┆ 2001-01-01 00:00:00 │
# │ 2001-01-02 00:00:00 ┆ 2001-01-02 00:00:00 ┆ 2001-01-02 00:00:00 │
# │ 2001-01-03 00:00:00 ┆ 2001-01-03 00:00:00 ┆ 2001-01-03 00:00:00 │
# └─────────────────────┴─────────────────────┴─────────────────────┘

Parameters:

  • time_unit ("ns", "us", "ms") —

    Time unit for the Datetime Series.

Returns:



1382
1383
1384
 
# File 'lib/polars/date_time_expr.rb', line 1382

def cast_time_unit(time_unit)
  Utils.wrap_expr(_rbexpr.dt_cast_time_unit(time_unit))
end

#century ⇒ Expr

Extract the century from underlying representation.

Applies to Date and Datetime columns.

Returns the century number in the calendar date.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => [
      Date.new(999, 12, 31),
      Date.new(1897, 5, 7),
      Date.new(2000, 1, 1),
      Date.new(2001, 7, 5),
      Date.new(3002, 10, 20)
    ]
  }
)
df.with_columns(cent: Polars.col("date").dt.century)
# =>
# shape: (5, 2)
# ┌────────────┬──────┐
# │ date       ┆ cent │
# │ ---        ┆ ---  │
# │ date       ┆ i32  │
# ╞════════════╪══════╡
# │ 0999-12-31 ┆ 10   │
# │ 1897-05-07 ┆ 19   │
# │ 2000-01-01 ┆ 20   │
# │ 2001-07-05 ┆ 21   │
# │ 3002-10-20 ┆ 31   │
# └────────────┴──────┘

Returns:



590
591
592
 
# File 'lib/polars/date_time_expr.rb', line 590

def century
  Utils.wrap_expr(_rbexpr.dt_century)
end

#combine(time, time_unit: "us") ⇒ Expr

Create a naive Datetime from an existing Date/Datetime expression and a Time.

If the underlying expression is a Datetime then its time component is replaced, and if it is a Date then a new Datetime is created by combining the two values.

Parameters:

  • time (Object) —

    A Ruby time literal or Polars expression/column that resolves to a time.

  • time_unit ("ns", "us", "ms") (defaults to: "us") —

    Unit of time.

Returns:



407
408
409
410
411
412
413
 
# File 'lib/polars/date_time_expr.rb', line 407

def combine(time, time_unit: "us")
  unless time.is_a?(::Time) || time.is_a?(Expr)
    raise TypeError, "expected 'time' to be a Ruby time or Polars expression, found #{time}"
  end
  time = Utils.parse_into_expression(time)
  Utils.wrap_expr(_rbexpr.dt_combine(time, time_unit))
end

#convert_time_zone(time_zone) ⇒ Expr

Set time zone for a Series of type Datetime.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.datetime_range(
      DateTime.new(2020, 3, 1),
      DateTime.new(2020, 5, 1),
      "1mo",
      time_zone: "UTC",
      eager: true
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date")
      .dt.convert_time_zone("Europe/London")
      .alias("London")
  ]
)
# =>
# shape: (3, 2)
# ┌─────────────────────────┬─────────────────────────────┐
# │ date                    ┆ London                      │
# │ ---                     ┆ ---                         │
# │ datetime[ns, UTC]       ┆ datetime[ns, Europe/London] │
# ╞═════════════════════════╪═════════════════════════════╡
# │ 2020-03-01 00:00:00 UTC ┆ 2020-03-01 00:00:00 GMT     │
# │ 2020-04-01 00:00:00 UTC ┆ 2020-04-01 01:00:00 BST     │
# │ 2020-05-01 00:00:00 UTC ┆ 2020-05-01 01:00:00 BST     │
# └─────────────────────────┴─────────────────────────────┘

Parameters:

  • time_zone (String) —

    Time zone for the Datetime Series.

Returns:



1424
1425
1426
 
# File 'lib/polars/date_time_expr.rb', line 1424

def convert_time_zone(time_zone)
  Utils.wrap_expr(_rbexpr.dt_convert_time_zone(time_zone))
end

#date ⇒ Expr

Date

Examples:

df = Polars::DataFrame.new(
  {
    "datetime" => [
      Time.utc(1978, 1, 1, 1, 1, 1, 0),
      Time.utc(2024, 10, 13, 5, 30, 14, 500_000),
      Time.utc(2065, 1, 1, 10, 20, 30, 60_000)
    ]
  }
)
df.with_columns(Polars.col("datetime").dt.date.alias("date"))
# =>
# shape: (3, 2)
# ┌─────────────────────────┬────────────┐
# │ datetime                ┆ date       │
# │ ---                     ┆ ---        │
# │ datetime[ns]            ┆ date       │
# ╞═════════════════════════╪════════════╡
# │ 1978-01-01 01:01:01     ┆ 1978-01-01 │
# │ 2024-10-13 05:30:14.500 ┆ 2024-10-13 │
# │ 2065-01-01 10:20:30.060 ┆ 2065-01-01 │
# └─────────────────────────┴────────────┘

Returns:



1020
1021
1022
 
# File 'lib/polars/date_time_expr.rb', line 1020

def date
  Utils.wrap_expr(_rbexpr.dt_date)
end

#day ⇒ Expr

Extract day from underlying Date representation.

Applies to Date and Datetime columns.

Returns the day of month starting from 1. The return value ranges from 1 to 31. (The last day of month differs by months.)

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.date_range(
      Date.new(2001, 12, 22), Date.new(2001, 12, 25), eager: true
    )
  }
)
df.with_columns(
  Polars.col("date").dt.weekday.alias("weekday"),
  Polars.col("date").dt.day.alias("day_of_month"),
  Polars.col("date").dt.ordinal_day.alias("day_of_year")
)
# =>
# shape: (4, 4)
# ┌────────────┬─────────┬──────────────┬─────────────┐
# │ date       ┆ weekday ┆ day_of_month ┆ day_of_year │
# │ ---        ┆ ---     ┆ ---          ┆ ---         │
# │ date       ┆ i8      ┆ i8           ┆ i16         │
# ╞════════════╪═════════╪══════════════╪═════════════╡
# │ 2001-12-22 ┆ 6       ┆ 22           ┆ 356         │
# │ 2001-12-23 ┆ 7       ┆ 23           ┆ 357         │
# │ 2001-12-24 ┆ 1       ┆ 24           ┆ 358         │
# │ 2001-12-25 ┆ 2       ┆ 25           ┆ 359         │
# └────────────┴─────────┴──────────────┴─────────────┘

Returns:



945
946
947
 
# File 'lib/polars/date_time_expr.rb', line 945

def day
  Utils.wrap_expr(_rbexpr.dt_day)
end

#days_in_month ⇒ Expr

Extract the number of days in the month from the underlying Date representation.

Applies to Date and Datetime columns.

Returns the number of days in the month. The return value ranges from 28 to 31.

Examples:

df = Polars::DataFrame.new(
  {"date" => [Date.new(2001, 1, 1), Date.new(2001, 2, 1), Date.new(2000, 2, 1)]}
)
df.with_columns(Polars.col("date").dt.days_in_month.alias("days_in_month"))
# =>
# shape: (3, 2)
# ┌────────────┬───────────────┐
# │ date       ┆ days_in_month │
# │ ---        ┆ ---           │
# │ date       ┆ i8            │
# ╞════════════╪═══════════════╡
# │ 2001-01-01 ┆ 31            │
# │ 2001-02-01 ┆ 28            │
# │ 2000-02-01 ┆ 29            │
# └────────────┴───────────────┘

Returns:



841
842
843
 
# File 'lib/polars/date_time_expr.rb', line 841

def days_in_month
  Utils.wrap_expr(_rbexpr.dt_days_in_month)
end

#dst_offset ⇒ Expr

Additional offset currently in effect (typically due to daylight saving time).

Examples:

df = Polars::DataFrame.new(
  {
    "ts" => [DateTime.new(2020, 10, 25), DateTime.new(2020, 10, 26)],
  }
)
df = df.with_columns(Polars.col("ts").dt.replace_time_zone("Europe/London"))
df.with_columns(Polars.col("ts").dt.dst_offset.alias("dst_offset"))
# =>
# shape: (2, 2)
# ┌─────────────────────────────┬──────────────┐
# │ ts                          ┆ dst_offset   │
# │ ---                         ┆ ---          │
# │ datetime[ns, Europe/London] ┆ duration[ms] │
# ╞═════════════════════════════╪══════════════╡
# │ 2020-10-25 00:00:00 BST     ┆ 1h           │
# │ 2020-10-26 00:00:00 GMT     ┆ 0ms          │
# └─────────────────────────────┴──────────────┘

Returns:



1979
1980
1981
 
# File 'lib/polars/date_time_expr.rb', line 1979

def dst_offset
  Utils.wrap_expr(_rbexpr.dt_dst_offset)
end

#epoch(time_unit = "us") ⇒ Expr

Get the time passed since the Unix EPOCH in the give time unit.

Examples:

df = (
  Polars.date_range(Date.new(2001, 1, 1), Date.new(2001, 1, 3), eager: true)
  .alias("date")
  .to_frame
)
df.with_columns(
  Polars.col("date").dt.epoch.alias("epoch_ns"),
  Polars.col("date").dt.epoch("s").alias("epoch_s")
)
# =>
# shape: (3, 3)
# ┌────────────┬─────────────────┬───────────┐
# │ date       ┆ epoch_ns        ┆ epoch_s   │
# │ ---        ┆ ---             ┆ ---       │
# │ date       ┆ i64             ┆ i64       │
# ╞════════════╪═════════════════╪═══════════╡
# │ 2001-01-01 ┆ 978307200000000 ┆ 978307200 │
# │ 2001-01-02 ┆ 978393600000000 ┆ 978393600 │
# │ 2001-01-03 ┆ 978480000000000 ┆ 978480000 │
# └────────────┴─────────────────┴───────────┘

Parameters:

  • time_unit ("us", "ns", "ms", "s", "d") (defaults to: "us") —

    Time unit.

Returns:



1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
 
# File 'lib/polars/date_time_expr.rb', line 1305

def epoch(time_unit = "us")
  if Utils::DTYPE_TEMPORAL_UNITS.include?(time_unit)
    timestamp(time_unit)
  elsif time_unit == "s"
    timestamp("ms").floordiv(F.lit(1000, dtype: Int64))
  elsif time_unit == "d"
    Utils.wrap_expr(_rbexpr).cast(Date).cast(Int32)
  else
    raise ArgumentError, "time_unit must be one of {'ns', 'us', 'ms', 's', 'd'}, got #{time_unit.inspect}"
  end
end

#hour ⇒ Expr

Extract hour from underlying DateTime representation.

Applies to Datetime columns.

Returns the hour number from 0 to 23.

Examples:

df = Polars::DataFrame.new(
  {
    "datetime" => [
      Time.utc(1978, 1, 1, 1, 1, 1, 0),
      Time.utc(2024, 10, 13, 5, 30, 14, 500_000),
      Time.utc(2065, 1, 1, 10, 20, 30, 60_000)
    ]
  }
)
df.with_columns(
  Polars.col("datetime").dt.hour.alias("hour"),
  Polars.col("datetime").dt.minute.alias("minute"),
  Polars.col("datetime").dt.second.alias("second"),
  Polars.col("datetime").dt.millisecond.alias("millisecond")
)
# =>
# shape: (3, 5)
# ┌─────────────────────────┬──────┬────────┬────────┬─────────────┐
# │ datetime                ┆ hour ┆ minute ┆ second ┆ millisecond │
# │ ---                     ┆ ---  ┆ ---    ┆ ---    ┆ ---         │
# │ datetime[ns]            ┆ i8   ┆ i8     ┆ i8     ┆ i32         │
# ╞═════════════════════════╪══════╪════════╪════════╪═════════════╡
# │ 1978-01-01 01:01:01     ┆ 1    ┆ 1      ┆ 1      ┆ 0           │
# │ 2024-10-13 05:30:14.500 ┆ 5    ┆ 30     ┆ 14     ┆ 500         │
# │ 2065-01-01 10:20:30.060 ┆ 10   ┆ 20     ┆ 30     ┆ 60          │
# └─────────────────────────┴──────┴────────┴────────┴─────────────┘

Returns:



1059
1060
1061
 
# File 'lib/polars/date_time_expr.rb', line 1059

def hour
  Utils.wrap_expr(_rbexpr.dt_hour)
end

#is_business_day(week_mask: [true, true, true, true, true, false, false], holidays: []) ⇒ Expr

Note:

This functionality is considered unstable. It may be changed at any point without it being considered a breaking change.

Determine whether each day lands on a business day.

Examples:

df = Polars::DataFrame.new({"start" => [Date.new(2020, 1, 3), Date.new(2020, 1, 5)]})
df.with_columns(is_business_day: Polars.col("start").dt.is_business_day)
# =>
# shape: (2, 2)
# ┌────────────┬─────────────────┐
# │ start      ┆ is_business_day │
# │ ---        ┆ ---             │
# │ date       ┆ bool            │
# ╞════════════╪═════════════════╡
# │ 2020-01-03 ┆ true            │
# │ 2020-01-05 ┆ false           │
# └────────────┴─────────────────┘

You can pass a custom weekend - for example, if you only take Sunday off:

week_mask = [true, true, true, true, true, true, false]
df.with_columns(
  is_business_day: Polars.col("start").dt.is_business_day(week_mask: week_mask)
)
# =>
# shape: (2, 2)
# ┌────────────┬─────────────────┐
# │ start      ┆ is_business_day │
# │ ---        ┆ ---             │
# │ date       ┆ bool            │
# ╞════════════╪═════════════════╡
# │ 2020-01-03 ┆ true            │
# │ 2020-01-05 ┆ false           │
# └────────────┴─────────────────┘

You can also pass a list of holidays:

holidays = [Date.new(2020, 1, 3), Date.new(2020, 1, 6)]
df.with_columns(
  is_business_day: Polars.col("start").dt.is_business_day(holidays: holidays)
)
# =>
# shape: (2, 2)
# ┌────────────┬─────────────────┐
# │ start      ┆ is_business_day │
# │ ---        ┆ ---             │
# │ date       ┆ bool            │
# ╞════════════╪═════════════════╡
# │ 2020-01-03 ┆ false           │
# │ 2020-01-05 ┆ false           │
# └────────────┴─────────────────┘

Parameters:

  • week_mask (Array) (defaults to: [true, true, true, true, true, false, false]) —

    Which days of the week to count. The default is Monday to Friday. If you wanted to count only Monday to Thursday, you would pass [true, true, true, true, false, false, false].

  • holidays (Object) (defaults to: []) —

    Holidays to exclude from the count.

Returns:



685
686
687
688
689
690
691
692
693
694
695
696
 
# File 'lib/polars/date_time_expr.rb', line 685

def is_business_day(
  week_mask: [true, true, true, true, true, false, false],
  holidays: []
)
  holidays_rbexpr = Utils._holidays_to_expr(holidays)
  Utils.wrap_expr(
    _rbexpr.dt_is_business_day(
      week_mask,
      holidays_rbexpr
    )
  )
end

#is_leap_year ⇒ Expr

Determine whether the year of the underlying date is a leap year.

Applies to Date and Datetime columns.

Examples:

df = Polars::DataFrame.new(
  {"date" => [Date.new(2000, 1, 1), Date.new(2001, 1, 1), Date.new(2002, 1, 1)]}
)
df.with_columns(
  leap_year: Polars.col("date").dt.is_leap_year
)
# =>
# shape: (3, 2)
# ┌────────────┬───────────┐
# │ date       ┆ leap_year │
# │ ---        ┆ ---       │
# │ date       ┆ bool      │
# ╞════════════╪═══════════╡
# │ 2000-01-01 ┆ true      │
# │ 2001-01-01 ┆ false     │
# │ 2002-01-01 ┆ false     │
# └────────────┴───────────┘

Returns:



722
723
724
 
# File 'lib/polars/date_time_expr.rb', line 722

def is_leap_year
  Utils.wrap_expr(_rbexpr.dt_is_leap_year)
end

#iso_year ⇒ Expr

Extract ISO year from underlying Date representation.

Applies to Date and Datetime columns.

Returns the year number in the ISO standard. This may not correspond with the calendar year.

Examples:

df = Polars::DataFrame.new(
  {"date" => [Date.new(1977, 1, 1), Date.new(1978, 1, 1), Date.new(1979, 1, 1)]}
)
df.select(
  "date",
  Polars.col("date").dt.year.alias("calendar_year"),
  Polars.col("date").dt.iso_year.alias("iso_year")
)
# =>
# shape: (3, 3)
# ┌────────────┬───────────────┬──────────┐
# │ date       ┆ calendar_year ┆ iso_year │
# │ ---        ┆ ---           ┆ ---      │
# │ date       ┆ i32           ┆ i32      │
# ╞════════════╪═══════════════╪══════════╡
# │ 1977-01-01 ┆ 1977          ┆ 1976     │
# │ 1978-01-01 ┆ 1978          ┆ 1977     │
# │ 1979-01-01 ┆ 1979          ┆ 1979     │
# └────────────┴───────────────┴──────────┘

Returns:



755
756
757
 
# File 'lib/polars/date_time_expr.rb', line 755

def iso_year
  Utils.wrap_expr(_rbexpr.dt_iso_year)
end

#microsecond ⇒ Expr

Extract microseconds from underlying DateTime representation.

Applies to Datetime columns.

Examples:

df = Polars::DataFrame.new(
  {
    "datetime": [
      Time.utc(1978, 1, 1, 1, 1, 1, 0),
      Time.utc(2024, 10, 13, 5, 30, 14, 500_000),
      Time.utc(2065, 1, 1, 10, 20, 30, 60_000),
    ]
  }
)
df.with_columns(
  Polars.col("datetime").dt.hour.alias("hour"),
  Polars.col("datetime").dt.minute.alias("minute"),
  Polars.col("datetime").dt.second.alias("second"),
  Polars.col("datetime").dt.microsecond.alias("microsecond")
)
# =>
# shape: (3, 5)
# ┌─────────────────────────┬──────┬────────┬────────┬─────────────┐
# │ datetime                ┆ hour ┆ minute ┆ second ┆ microsecond │
# │ ---                     ┆ ---  ┆ ---    ┆ ---    ┆ ---         │
# │ datetime[ns]            ┆ i8   ┆ i8     ┆ i8     ┆ i32         │
# ╞═════════════════════════╪══════╪════════╪════════╪═════════════╡
# │ 1978-01-01 01:01:01     ┆ 1    ┆ 1      ┆ 1      ┆ 0           │
# │ 2024-10-13 05:30:14.500 ┆ 5    ┆ 30     ┆ 14     ┆ 500000      │
# │ 2065-01-01 10:20:30.060 ┆ 10   ┆ 20     ┆ 30     ┆ 60000       │
# └─────────────────────────┴──────┴────────┴────────┴─────────────┘

Returns:



1236
1237
1238
 
# File 'lib/polars/date_time_expr.rb', line 1236

def microsecond
  Utils.wrap_expr(_rbexpr.dt_microsecond)
end

#millennium ⇒ Expr

Extract the millennium from underlying representation.

Applies to Date and Datetime columns.

Returns the millennium number in the calendar date.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => [
      Date.new(999, 12, 31),
      Date.new(1897, 5, 7),
      Date.new(2000, 1, 1),
      Date.new(2001, 7, 5),
      Date.new(3002, 10, 20)
    ]
  }
)
df.with_columns(mlnm: Polars.col("date").dt.millennium)
# =>
# shape: (5, 2)
# ┌────────────┬──────┐
# │ date       ┆ mlnm │
# │ ---        ┆ ---  │
# │ date       ┆ i32  │
# ╞════════════╪══════╡
# │ 0999-12-31 ┆ 1    │
# │ 1897-05-07 ┆ 2    │
# │ 2000-01-01 ┆ 2    │
# │ 2001-07-05 ┆ 3    │
# │ 3002-10-20 ┆ 4    │
# └────────────┴──────┘

Returns:



552
553
554
 
# File 'lib/polars/date_time_expr.rb', line 552

def millennium
  Utils.wrap_expr(_rbexpr.dt_millennium)
end

#millisecond ⇒ Expr

Extract milliseconds from underlying DateTime representation.

Applies to Datetime columns.

Examples:

df = Polars::DataFrame.new(
  {
    "datetime": [
      Time.utc(1978, 1, 1, 1, 1, 1, 0),
      Time.utc(2024, 10, 13, 5, 30, 14, 500_000),
      Time.utc(2065, 1, 1, 10, 20, 30, 60_000),
    ]
  }
)
df.with_columns(
  Polars.col("datetime").dt.hour.alias("hour"),
  Polars.col("datetime").dt.minute.alias("minute"),
  Polars.col("datetime").dt.second.alias("second"),
  Polars.col("datetime").dt.millisecond.alias("millisecond")
)
# =>
# shape: (3, 5)
# ┌─────────────────────────┬──────┬────────┬────────┬─────────────┐
# │ datetime                ┆ hour ┆ minute ┆ second ┆ millisecond │
# │ ---                     ┆ ---  ┆ ---    ┆ ---    ┆ ---         │
# │ datetime[ns]            ┆ i8   ┆ i8     ┆ i8     ┆ i32         │
# ╞═════════════════════════╪══════╪════════╪════════╪═════════════╡
# │ 1978-01-01 01:01:01     ┆ 1    ┆ 1      ┆ 1      ┆ 0           │
# │ 2024-10-13 05:30:14.500 ┆ 5    ┆ 30     ┆ 14     ┆ 500         │
# │ 2065-01-01 10:20:30.060 ┆ 10   ┆ 20     ┆ 30     ┆ 60          │
# └─────────────────────────┴──────┴────────┴────────┴─────────────┘

Returns:



1199
1200
1201
 
# File 'lib/polars/date_time_expr.rb', line 1199

def millisecond
  Utils.wrap_expr(_rbexpr.dt_millisecond)
end

#minute ⇒ Expr

Extract minutes from underlying DateTime representation.

Applies to Datetime columns.

Returns the minute number from 0 to 59.

Examples:

df = Polars::DataFrame.new(
  {
    "datetime" => [
      Time.utc(1978, 1, 1, 1, 1, 1, 0),
      Time.utc(2024, 10, 13, 5, 30, 14, 500_000),
      Time.utc(2065, 1, 1, 10, 20, 30, 60_000)
    ]
  }
)
df.with_columns(
  Polars.col("datetime").dt.hour.alias("hour"),
  Polars.col("datetime").dt.minute.alias("minute"),
  Polars.col("datetime").dt.second.alias("second"),
  Polars.col("datetime").dt.millisecond.alias("millisecond")
)
# =>
# shape: (3, 5)
# ┌─────────────────────────┬──────┬────────┬────────┬─────────────┐
# │ datetime                ┆ hour ┆ minute ┆ second ┆ millisecond │
# │ ---                     ┆ ---  ┆ ---    ┆ ---    ┆ ---         │
# │ datetime[ns]            ┆ i8   ┆ i8     ┆ i8     ┆ i32         │
# ╞═════════════════════════╪══════╪════════╪════════╪═════════════╡
# │ 1978-01-01 01:01:01     ┆ 1    ┆ 1      ┆ 1      ┆ 0           │
# │ 2024-10-13 05:30:14.500 ┆ 5    ┆ 30     ┆ 14     ┆ 500         │
# │ 2065-01-01 10:20:30.060 ┆ 10   ┆ 20     ┆ 30     ┆ 60          │
# └─────────────────────────┴──────┴────────┴────────┴─────────────┘

Returns:



1098
1099
1100
 
# File 'lib/polars/date_time_expr.rb', line 1098

def minute
  Utils.wrap_expr(_rbexpr.dt_minute)
end

#month ⇒ Expr

Extract month from underlying Date representation.

Applies to Date and Datetime columns.

Returns the month number starting from 1. The return value ranges from 1 to 12.

Examples:

df = Polars::DataFrame.new(
  {"date" => [Date.new(2001, 1, 1), Date.new(2001, 6, 30), Date.new(2001, 12, 27)]}
)
df.with_columns(Polars.col("date").dt.month.alias("month"))
# =>
# shape: (3, 2)
# ┌────────────┬───────┐
# │ date       ┆ month │
# │ ---        ┆ ---   │
# │ date       ┆ i8    │
# ╞════════════╪═══════╡
# │ 2001-01-01 ┆ 1     │
# │ 2001-06-30 ┆ 6     │
# │ 2001-12-27 ┆ 12    │
# └────────────┴───────┘

Returns:



812
813
814
 
# File 'lib/polars/date_time_expr.rb', line 812

def month
  Utils.wrap_expr(_rbexpr.dt_month)
end

#month_end ⇒ Expr

Roll forward to the last day of the month.

Examples:

df = Polars::DataFrame.new(
  {
    "dates" => Polars.datetime_range(
      DateTime.new(2000, 1, 15, 2),
      DateTime.new(2000, 12, 15, 2),
      "1mo",
      eager: true
    )
  }
)
df.select(Polars.col("dates").dt.month_end)
# =>
# shape: (12, 1)
# ┌─────────────────────┐
# │ dates               │
# │ ---                 │
# │ datetime[ns]        │
# ╞═════════════════════╡
# │ 2000-01-31 02:00:00 │
# │ 2000-02-29 02:00:00 │
# │ 2000-03-31 02:00:00 │
# │ 2000-04-30 02:00:00 │
# │ 2000-05-31 02:00:00 │
# │ …                   │
# │ 2000-08-31 02:00:00 │
# │ 2000-09-30 02:00:00 │
# │ 2000-10-31 02:00:00 │
# │ 2000-11-30 02:00:00 │
# │ 2000-12-31 02:00:00 │
# └─────────────────────┘

Returns:



1923
1924
1925
 
# File 'lib/polars/date_time_expr.rb', line 1923

def month_end
  Utils.wrap_expr(_rbexpr.dt_month_end)
end

#month_start ⇒ Expr

Roll backward to the first day of the month.

Examples:

df = Polars::DataFrame.new(
  {
    "dates" => Polars.datetime_range(
      DateTime.new(2000, 1, 15, 2),
      DateTime.new(2000, 12, 15, 2),
      "1mo",
      eager: true
    )
  }
)
df.select(Polars.col("dates").dt.month_start)
# =>
# shape: (12, 1)
# ┌─────────────────────┐
# │ dates               │
# │ ---                 │
# │ datetime[ns]        │
# ╞═════════════════════╡
# │ 2000-01-01 02:00:00 │
# │ 2000-02-01 02:00:00 │
# │ 2000-03-01 02:00:00 │
# │ 2000-04-01 02:00:00 │
# │ 2000-05-01 02:00:00 │
# │ …                   │
# │ 2000-08-01 02:00:00 │
# │ 2000-09-01 02:00:00 │
# │ 2000-10-01 02:00:00 │
# │ 2000-11-01 02:00:00 │
# │ 2000-12-01 02:00:00 │
# └─────────────────────┘

Returns:



1884
1885
1886
 
# File 'lib/polars/date_time_expr.rb', line 1884

def month_start
  Utils.wrap_expr(_rbexpr.dt_month_start)
end

#nanosecond ⇒ Expr

Extract nanoseconds from underlying DateTime representation.

Applies to Datetime columns.

Examples:

df = Polars::DataFrame.new(
  {
    "datetime": [
      Time.utc(1978, 1, 1, 1, 1, 1, 0),
      Time.utc(2024, 10, 13, 5, 30, 14, 500_000),
      Time.utc(2065, 1, 1, 10, 20, 30, 60_000),
    ]
  }
)
df.with_columns(
  Polars.col("datetime").dt.hour.alias("hour"),
  Polars.col("datetime").dt.minute.alias("minute"),
  Polars.col("datetime").dt.second.alias("second"),
  Polars.col("datetime").dt.nanosecond.alias("nanosecond")
)
# =>
# shape: (3, 5)
# ┌─────────────────────────┬──────┬────────┬────────┬────────────┐
# │ datetime                ┆ hour ┆ minute ┆ second ┆ nanosecond │
# │ ---                     ┆ ---  ┆ ---    ┆ ---    ┆ ---        │
# │ datetime[ns]            ┆ i8   ┆ i8     ┆ i8     ┆ i32        │
# ╞═════════════════════════╪══════╪════════╪════════╪════════════╡
# │ 1978-01-01 01:01:01     ┆ 1    ┆ 1      ┆ 1      ┆ 0          │
# │ 2024-10-13 05:30:14.500 ┆ 5    ┆ 30     ┆ 14     ┆ 500000000  │
# │ 2065-01-01 10:20:30.060 ┆ 10   ┆ 20     ┆ 30     ┆ 60000000   │
# └─────────────────────────┴──────┴────────┴────────┴────────────┘

Returns:



1273
1274
1275
 
# File 'lib/polars/date_time_expr.rb', line 1273

def nanosecond
  Utils.wrap_expr(_rbexpr.dt_nanosecond)
end

#offset_by(by) ⇒ Expr

Offset this date by a relative time offset.

This differs from Polars.col("foo") + timedelta in that it can take months and leap years into account. Note that only a single minus sign is allowed in the by string, as the first character.

Examples:

df = Polars::DataFrame.new(
  {
    "dates" => Polars.datetime_range(
      DateTime.new(2000, 1, 1), DateTime.new(2005, 1, 1), "1y", eager: true
    )
  }
)
df.select(
  [
    Polars.col("dates").dt.offset_by("1y").alias("date_plus_1y"),
    Polars.col("dates").dt.offset_by("-1y2mo").alias("date_min")
  ]
)
# =>
# shape: (6, 2)
# ┌─────────────────────┬─────────────────────┐
# │ date_plus_1y        ┆ date_min            │
# │ ---                 ┆ ---                 │
# │ datetime[ns]        ┆ datetime[ns]        │
# ╞═════════════════════╪═════════════════════╡
# │ 2001-01-01 00:00:00 ┆ 1998-11-01 00:00:00 │
# │ 2002-01-01 00:00:00 ┆ 1999-11-01 00:00:00 │
# │ 2003-01-01 00:00:00 ┆ 2000-11-01 00:00:00 │
# │ 2004-01-01 00:00:00 ┆ 2001-11-01 00:00:00 │
# │ 2005-01-01 00:00:00 ┆ 2002-11-01 00:00:00 │
# │ 2006-01-01 00:00:00 ┆ 2003-11-01 00:00:00 │
# └─────────────────────┴─────────────────────┘

Parameters:

  • by (String) —

    The offset is dictated by the following string language:

    • 1ns (1 nanosecond)
    • 1us (1 microsecond)
    • 1ms (1 millisecond)
    • 1s (1 second)
    • 1m (1 minute)
    • 1h (1 hour)
    • 1d (1 day)
    • 1w (1 week)
    • 1mo (1 calendar month)
    • 1y (1 calendar year)
    • 1i (1 index count)

Returns:



1844
1845
1846
1847
 
# File 'lib/polars/date_time_expr.rb', line 1844

def offset_by(by)
  by = Utils.parse_into_expression(by, str_as_lit: true)
  Utils.wrap_expr(_rbexpr.dt_offset_by(by))
end

#ordinal_day ⇒ Expr

Extract ordinal day from underlying Date representation.

Applies to Date and Datetime columns.

Returns the day of month starting from 1. The return value ranges from 1 to 31. (The last day of month differs by months.)

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.date_range(
      Date.new(2001, 12, 22), Date.new(2001, 12, 25), eager: true
    )
  }
)
df.with_columns(
  Polars.col("date").dt.weekday.alias("weekday"),
  Polars.col("date").dt.day.alias("day_of_month"),
  Polars.col("date").dt.ordinal_day.alias("day_of_year")
)
# =>
# shape: (4, 4)
# ┌────────────┬─────────┬──────────────┬─────────────┐
# │ date       ┆ weekday ┆ day_of_month ┆ day_of_year │
# │ ---        ┆ ---     ┆ ---          ┆ ---         │
# │ date       ┆ i8      ┆ i8           ┆ i16         │
# ╞════════════╪═════════╪══════════════╪═════════════╡
# │ 2001-12-22 ┆ 6       ┆ 22           ┆ 356         │
# │ 2001-12-23 ┆ 7       ┆ 23           ┆ 357         │
# │ 2001-12-24 ┆ 1       ┆ 24           ┆ 358         │
# │ 2001-12-25 ┆ 2       ┆ 25           ┆ 359         │
# └────────────┴─────────┴──────────────┴─────────────┘

Returns:



983
984
985
 
# File 'lib/polars/date_time_expr.rb', line 983

def ordinal_day
  Utils.wrap_expr(_rbexpr.dt_ordinal_day)
end

#quarter ⇒ Expr

Extract quarter from underlying Date representation.

Applies to Date and Datetime columns.

Returns the quarter ranging from 1 to 4.

Examples:

df = Polars::DataFrame.new(
  {"date" => [Date.new(2001, 1, 1), Date.new(2001, 6, 30), Date.new(2001, 12, 27)]}
)
df.with_columns(Polars.col("date").dt.quarter.alias("quarter"))
# =>
# shape: (3, 2)
# ┌────────────┬─────────┐
# │ date       ┆ quarter │
# │ ---        ┆ ---     │
# │ date       ┆ i8      │
# ╞════════════╪═════════╡
# │ 2001-01-01 ┆ 1       │
# │ 2001-06-30 ┆ 2       │
# │ 2001-12-27 ┆ 4       │
# └────────────┴─────────┘

Returns:



783
784
785
 
# File 'lib/polars/date_time_expr.rb', line 783

def quarter
  Utils.wrap_expr(_rbexpr.dt_quarter)
end

#replace(year: nil, month: nil, day: nil, hour: nil, minute: nil, second: nil, microsecond: nil, ambiguous: "raise") ⇒ Expr

Replace time unit.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => [Date.new(2024, 4, 1), Date.new(2025, 3, 16)],
    "new_day" => [10, 15]
  }
)
df.with_columns(Polars.col("date").dt.replace(day: "new_day").alias("replaced"))
# =>
# shape: (2, 3)
# ┌────────────┬─────────┬────────────┐
# │ date       ┆ new_day ┆ replaced   │
# │ ---        ┆ ---     ┆ ---        │
# │ date       ┆ i64     ┆ date       │
# ╞════════════╪═════════╪════════════╡
# │ 2024-04-01 ┆ 10      ┆ 2024-04-10 │
# │ 2025-03-16 ┆ 15      ┆ 2025-03-15 │
# └────────────┴─────────┴────────────┘
df.with_columns(Polars.col("date").dt.replace(year: 1800).alias("replaced"))
# =>
# shape: (2, 3)
# ┌────────────┬─────────┬────────────┐
# │ date       ┆ new_day ┆ replaced   │
# │ ---        ┆ ---     ┆ ---        │
# │ date       ┆ i64     ┆ date       │
# ╞════════════╪═════════╪════════════╡
# │ 2024-04-01 ┆ 10      ┆ 1800-04-01 │
# │ 2025-03-16 ┆ 15      ┆ 1800-03-16 │
# └────────────┴─────────┴────────────┘

Parameters:

  • year (Object) (defaults to: nil) —

    Column or literal.

  • month (Object) (defaults to: nil) —

    Column or literal, ranging from 1-12.

  • day (Object) (defaults to: nil) —

    Column or literal, ranging from 1-31.

  • hour (Object) (defaults to: nil) —

    Column or literal, ranging from 0-23.

  • minute (Object) (defaults to: nil) —

    Column or literal, ranging from 0-59.

  • second (Object) (defaults to: nil) —

    Column or literal, ranging from 0-59.

  • microsecond (Object) (defaults to: nil) —

    Column or literal, ranging from 0-999999.

  • ambiguous (String) (defaults to: "raise") —

    Determine how to deal with ambiguous datetimes:

    • 'raise' (default): raise
    • 'earliest': use the earliest datetime
    • 'latest': use the latest datetime
    • 'null': set to null

Returns:



366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
 
# File 'lib/polars/date_time_expr.rb', line 366

def replace(
  year: nil,
  month: nil,
  day: nil,
  hour: nil,
  minute: nil,
  second: nil,
  microsecond: nil,
  ambiguous: "raise"
)
  day, month, year, hour, minute, second, microsecond = (
    Utils.parse_into_list_of_expressions(
      day, month, year, hour, minute, second, microsecond
    )
  )
  ambiguous_expr = Utils.parse_into_expression(ambiguous, str_as_lit: true)
  Utils.wrap_expr(
    _rbexpr.dt_replace(
      year,
      month,
      day,
      hour,
      minute,
      second,
      microsecond,
      ambiguous_expr
    )
  )
end

#replace_time_zone(time_zone, ambiguous: "raise", non_existent: "raise") ⇒ Expr

Cast time zone for a Series of type Datetime.

Different from convert_time_zone, this will also modify the underlying timestamp,

Examples:

df = Polars::DataFrame.new(
  {
    "london_timezone": Polars.datetime_range(
      Time.utc(2020, 3, 1),
      Time.utc(2020, 7, 1),
      "1mo",
      time_zone: "UTC",
      eager: true,
    ).dt.convert_time_zone("Europe/London")
  }
)
df.select(
  [
    Polars.col("london_timezone"),
    Polars.col("london_timezone")
    .dt.replace_time_zone("Europe/Amsterdam")
    .alias("London_to_Amsterdam")
  ]
)
# =>
# shape: (5, 2)
# ┌─────────────────────────────┬────────────────────────────────┐
# │ london_timezone             ┆ London_to_Amsterdam            │
# │ ---                         ┆ ---                            │
# │ datetime[ns, Europe/London] ┆ datetime[ns, Europe/Amsterdam] │
# ╞═════════════════════════════╪════════════════════════════════╡
# │ 2020-03-01 00:00:00 GMT     ┆ 2020-03-01 00:00:00 CET        │
# │ 2020-04-01 01:00:00 BST     ┆ 2020-04-01 01:00:00 CEST       │
# │ 2020-05-01 01:00:00 BST     ┆ 2020-05-01 01:00:00 CEST       │
# │ 2020-06-01 01:00:00 BST     ┆ 2020-06-01 01:00:00 CEST       │
# │ 2020-07-01 01:00:00 BST     ┆ 2020-07-01 01:00:00 CEST       │
# └─────────────────────────────┴────────────────────────────────┘

You can use ambiguous to deal with ambiguous datetimes:

dates = [
  "2018-10-28 01:30",
  "2018-10-28 02:00",
  "2018-10-28 02:30",
  "2018-10-28 02:00"
]
df = Polars::DataFrame.new(
  {
    "ts" => Polars::Series.new(dates).str.strptime(Polars::Datetime),
    "ambiguous" => ["earliest", "earliest", "latest", "latest"]
  }
)
df.with_columns(
  ts_localized: Polars.col("ts").dt.replace_time_zone(
    "Europe/Brussels", ambiguous: Polars.col("ambiguous")
  )
)
# =>
# shape: (4, 3)
# ┌─────────────────────┬───────────┬───────────────────────────────┐
# │ ts                  ┆ ambiguous ┆ ts_localized                  │
# │ ---                 ┆ ---       ┆ ---                           │
# │ datetime[μs]        ┆ str       ┆ datetime[μs, Europe/Brussels] │
# ╞═════════════════════╪═══════════╪═══════════════════════════════╡
# │ 2018-10-28 01:30:00 ┆ earliest  ┆ 2018-10-28 01:30:00 CEST      │
# │ 2018-10-28 02:00:00 ┆ earliest  ┆ 2018-10-28 02:00:00 CEST      │
# │ 2018-10-28 02:30:00 ┆ latest    ┆ 2018-10-28 02:30:00 CET       │
# │ 2018-10-28 02:00:00 ┆ latest    ┆ 2018-10-28 02:00:00 CET       │
# └─────────────────────┴───────────┴───────────────────────────────┘

Parameters:

  • time_zone (String) —

    Time zone for the Datetime Series. Pass nil to unset time zone.

  • ambiguous (String) (defaults to: "raise") —

    Determine how to deal with ambiguous datetimes.

  • non_existent (String) (defaults to: "raise") —

    Determine how to deal with non-existent datetimes.

Returns:



1506
1507
1508
1509
1510
1511
 
# File 'lib/polars/date_time_expr.rb', line 1506

def replace_time_zone(time_zone, ambiguous: "raise", non_existent: "raise")
  unless ambiguous.is_a?(Expr)
    ambiguous = Polars.lit(ambiguous)
  end
  Utils.wrap_expr(_rbexpr.dt_replace_time_zone(time_zone, ambiguous._rbexpr, non_existent))
end

#round(every) ⇒ Expr

Note:

The every and offset argument are created with the the following small string formatting language:

1ns # 1 nanosecond 1us # 1 microsecond 1ms # 1 millisecond 1s # 1 second 1m # 1 minute 1h # 1 hour 1d # 1 day 1w # 1 week 1mo # 1 calendar month 1y # 1 calendar year

eg: 3d12h4m25s # 3 days, 12 hours, 4 minutes, and 25 seconds

Note:

This functionality is currently experimental and may change without it being considered a breaking change.

Divide the date/datetime range into buckets.

Each date/datetime in the first half of the interval is mapped to the start of its bucket. Each date/datetime in the seconod half of the interval is mapped to the end of its bucket.

Examples:

df = (
  Polars.datetime_range(
    DateTime.new(2001, 1, 1),
    DateTime.new(2001, 1, 2),
    "225m",
    eager: true
  )
  .alias("datetime")
  .to_frame
)
df.with_columns(Polars.col("datetime").dt.round("1h").alias("round"))
# =>
# shape: (7, 2)
# ┌─────────────────────┬─────────────────────┐
# │ datetime            ┆ round               │
# │ ---                 ┆ ---                 │
# │ datetime[ns]        ┆ datetime[ns]        │
# ╞═════════════════════╪═════════════════════╡
# │ 2001-01-01 00:00:00 ┆ 2001-01-01 00:00:00 │
# │ 2001-01-01 03:45:00 ┆ 2001-01-01 04:00:00 │
# │ 2001-01-01 07:30:00 ┆ 2001-01-01 08:00:00 │
# │ 2001-01-01 11:15:00 ┆ 2001-01-01 11:00:00 │
# │ 2001-01-01 15:00:00 ┆ 2001-01-01 15:00:00 │
# │ 2001-01-01 18:45:00 ┆ 2001-01-01 19:00:00 │
# │ 2001-01-01 22:30:00 ┆ 2001-01-01 23:00:00 │
# └─────────────────────┴─────────────────────┘
df = (
  Polars.datetime_range(
    DateTime.new(2001, 1, 1), DateTime.new(2001, 1, 1, 1), "10m", eager: true
  )
  .alias("datetime")
  .to_frame
)
df.with_columns(Polars.col("datetime").dt.round("30m").alias("round"))
# =>
# shape: (7, 2)
# ┌─────────────────────┬─────────────────────┐
# │ datetime            ┆ round               │
# │ ---                 ┆ ---                 │
# │ datetime[ns]        ┆ datetime[ns]        │
# ╞═════════════════════╪═════════════════════╡
# │ 2001-01-01 00:00:00 ┆ 2001-01-01 00:00:00 │
# │ 2001-01-01 00:10:00 ┆ 2001-01-01 00:00:00 │
# │ 2001-01-01 00:20:00 ┆ 2001-01-01 00:30:00 │
# │ 2001-01-01 00:30:00 ┆ 2001-01-01 00:30:00 │
# │ 2001-01-01 00:40:00 ┆ 2001-01-01 00:30:00 │
# │ 2001-01-01 00:50:00 ┆ 2001-01-01 01:00:00 │
# │ 2001-01-01 01:00:00 ┆ 2001-01-01 01:00:00 │
# └─────────────────────┴─────────────────────┘

Parameters:

  • every (String) —

    Every interval start and period length

Returns:



304
305
306
307
 
# File 'lib/polars/date_time_expr.rb', line 304

def round(every)
  every = Utils.parse_into_expression(every, str_as_lit: true)
  Utils.wrap_expr(_rbexpr.dt_round(every))
end

#second(fractional: false) ⇒ Expr

Extract seconds from underlying DateTime representation.

Applies to Datetime columns.

Returns the integer second number from 0 to 59, or a floating point number from 0 < 60 if fractional: true that includes any milli/micro/nanosecond component.

Examples:

df = Polars::DataFrame.new(
  {
    "datetime" => [
      Time.utc(1978, 1, 1, 1, 1, 1, 0),
      Time.utc(2024, 10, 13, 5, 30, 14, 500_000),
      Time.utc(2065, 1, 1, 10, 20, 30, 60_000)
    ]
  }
)
df.with_columns(
  Polars.col("datetime").dt.hour.alias("hour"),
  Polars.col("datetime").dt.minute.alias("minute"),
  Polars.col("datetime").dt.second.alias("second"),
  Polars.col("datetime").dt.millisecond.alias("millisecond")
)
# =>
# shape: (3, 5)
# ┌─────────────────────────┬──────┬────────┬────────┬─────────────┐
# │ datetime                ┆ hour ┆ minute ┆ second ┆ millisecond │
# │ ---                     ┆ ---  ┆ ---    ┆ ---    ┆ ---         │
# │ datetime[ns]            ┆ i8   ┆ i8     ┆ i8     ┆ i32         │
# ╞═════════════════════════╪══════╪════════╪════════╪═════════════╡
# │ 1978-01-01 01:01:01     ┆ 1    ┆ 1      ┆ 1      ┆ 0           │
# │ 2024-10-13 05:30:14.500 ┆ 5    ┆ 30     ┆ 14     ┆ 500         │
# │ 2065-01-01 10:20:30.060 ┆ 10   ┆ 20     ┆ 30     ┆ 60          │
# └─────────────────────────┴──────┴────────┴────────┴─────────────┘
df.with_columns(
  Polars.col("datetime").dt.hour.alias("hour"),
  Polars.col("datetime").dt.minute.alias("minute"),
  Polars.col("datetime").dt.second(fractional: true).alias("second")
)
# =>
# shape: (3, 4)
# ┌─────────────────────────┬──────┬────────┬────────┐
# │ datetime                ┆ hour ┆ minute ┆ second │
# │ ---                     ┆ ---  ┆ ---    ┆ ---    │
# │ datetime[ns]            ┆ i8   ┆ i8     ┆ f64    │
# ╞═════════════════════════╪══════╪════════╪════════╡
# │ 1978-01-01 01:01:01     ┆ 1    ┆ 1      ┆ 1.0    │
# │ 2024-10-13 05:30:14.500 ┆ 5    ┆ 30     ┆ 14.5   │
# │ 2065-01-01 10:20:30.060 ┆ 10   ┆ 20     ┆ 30.06  │
# └─────────────────────────┴──────┴────────┴────────┘

Returns:



1157
1158
1159
1160
1161
1162
1163
1164
 
# File 'lib/polars/date_time_expr.rb', line 1157

def second(fractional: false)
  sec = Utils.wrap_expr(_rbexpr.dt_second)
  if fractional
    sec + (Utils.wrap_expr(_rbexpr.dt_nanosecond) / F.lit(1_000_000_000.0))
  else
    sec
  end
end

#strftime(format) ⇒ Expr

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

Similar to cast(Polars::String), but this method allows you to customize the formatting of the resulting string.

Examples:

df = Polars::DataFrame.new(
  {
    "datetime" => [
      Time.utc(2020, 3, 1),
      Time.utc(2020, 4, 1),
      Time.utc(2020, 5, 1)
    ]
  }
)
df.with_columns(
  Polars.col("datetime")
  .dt.strftime("%Y/%m/%d %H:%M:%S")
  .alias("datetime_string")
)
# =>
# shape: (3, 2)
# ┌─────────────────────┬─────────────────────┐
# │ datetime            ┆ datetime_string     │
# │ ---                 ┆ ---                 │
# │ datetime[ns]        ┆ str                 │
# ╞═════════════════════╪═════════════════════╡
# │ 2020-03-01 00:00:00 ┆ 2020/03/01 00:00:00 │
# │ 2020-04-01 00:00:00 ┆ 2020/04/01 00:00:00 │
# │ 2020-05-01 00:00:00 ┆ 2020/05/01 00:00:00 │
# └─────────────────────┴─────────────────────┘

If you're interested in the day name / month name, you can use '%A' / '%B':

df.with_columns(
  day_name: Polars.col("datetime").dt.strftime("%A"),
  month_name: Polars.col("datetime").dt.strftime("%B")
)
# =>
# shape: (3, 3)
# ┌─────────────────────┬───────────┬────────────┐
# │ datetime            ┆ day_name  ┆ month_name │
# │ ---                 ┆ ---       ┆ ---        │
# │ datetime[ns]        ┆ str       ┆ str        │
# ╞═════════════════════╪═══════════╪════════════╡
# │ 2020-03-01 00:00:00 ┆ Sunday    ┆ March      │
# │ 2020-04-01 00:00:00 ┆ Wednesday ┆ April      │
# │ 2020-05-01 00:00:00 ┆ Friday    ┆ May        │
# └─────────────────────┴───────────┴────────────┘

Parameters:

Returns:



514
515
516
 
# File 'lib/polars/date_time_expr.rb', line 514

def strftime(format)
  Utils.wrap_expr(_rbexpr.strftime(format))
end

#time ⇒ Expr

Time

Returns:



990
991
992
 
# File 'lib/polars/date_time_expr.rb', line 990

def time
  Utils.wrap_expr(_rbexpr.dt_time)
end

#timestamp(time_unit = "us") ⇒ Expr

Return a timestamp in the given time unit.

Examples:

df = (
  Polars.date_range(Date.new(2001, 1, 1), Date.new(2001, 1, 3), eager: true)
  .alias("date")
  .to_frame
)
df.with_columns(
  Polars.col("date").dt.timestamp.alias("timestamp_us"),
  Polars.col("date").dt.timestamp("ms").alias("timestamp_ms")
)
# =>
# shape: (3, 3)
# ┌────────────┬─────────────────┬──────────────┐
# │ date       ┆ timestamp_us    ┆ timestamp_ms │
# │ ---        ┆ ---             ┆ ---          │
# │ date       ┆ i64             ┆ i64          │
# ╞════════════╪═════════════════╪══════════════╡
# │ 2001-01-01 ┆ 978307200000000 ┆ 978307200000 │
# │ 2001-01-02 ┆ 978393600000000 ┆ 978393600000 │
# │ 2001-01-03 ┆ 978480000000000 ┆ 978480000000 │
# └────────────┴─────────────────┴──────────────┘

Parameters:

  • time_unit ("us", "ns", "ms") (defaults to: "us") —

    Time unit.

Returns:



1345
1346
1347
 
# File 'lib/polars/date_time_expr.rb', line 1345

def timestamp(time_unit = "us")
  Utils.wrap_expr(_rbexpr.dt_timestamp(time_unit))
end

#to_string(format = nil) ⇒ Expr

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

Similar to cast(Polars::String), but this method allows you to customize the formatting of the resulting string.

Examples:

df = Polars::DataFrame.new(
  {
    "datetime" => [
      DateTime.new(2020, 3, 1),
      DateTime.new(2020, 4, 1),
      DateTime.new(2020, 5, 1)
    ]
  }
)
df.with_columns(
  Polars.col("datetime")
  .dt.to_string("%Y/%m/%d %H:%M:%S")
  .alias("datetime_string")
)
# =>
# shape: (3, 2)
# ┌─────────────────────┬─────────────────────┐
# │ datetime            ┆ datetime_string     │
# │ ---                 ┆ ---                 │
# │ datetime[ns]        ┆ str                 │
# ╞═════════════════════╪═════════════════════╡
# │ 2020-03-01 00:00:00 ┆ 2020/03/01 00:00:00 │
# │ 2020-04-01 00:00:00 ┆ 2020/04/01 00:00:00 │
# │ 2020-05-01 00:00:00 ┆ 2020/05/01 00:00:00 │
# └─────────────────────┴─────────────────────┘

Parameters:

  • format (String) (defaults to: nil) —

    Format to use, refer to the chrono strftime documentation <https://docs.rs/chrono/latest/chrono/format/strftime/index.html>_ for specification. Example: "%y-%m-%d".

Returns:



453
454
455
456
457
458
 
# File 'lib/polars/date_time_expr.rb', line 453

def to_string(format = nil)
  if format.nil?
    format = "iso"
  end
  Utils.wrap_expr(_rbexpr.dt_to_string(format))
end

#total_days(fractional: false) ⇒ Expr

Extract the days from a Duration type.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.datetime_range(
      DateTime.new(2020, 3, 1), DateTime.new(2020, 5, 1), "1mo", eager: true
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date").diff.dt.total_days.alias("days_diff")
  ]
)
# =>
# shape: (3, 2)
# ┌─────────────────────┬───────────┐
# │ date                ┆ days_diff │
# │ ---                 ┆ ---       │
# │ datetime[ns]        ┆ i64       │
# ╞═════════════════════╪═══════════╡
# │ 2020-03-01 00:00:00 ┆ null      │
# │ 2020-04-01 00:00:00 ┆ 31        │
# │ 2020-05-01 00:00:00 ┆ 30        │
# └─────────────────────┴───────────┘

Parameters:

  • fractional (Boolean) (defaults to: false) —

    Whether to include the fractional component of the second.

Returns:



1545
1546
1547
 
# File 'lib/polars/date_time_expr.rb', line 1545

def total_days(fractional: false)
  Utils.wrap_expr(_rbexpr.dt_total_days(fractional))
end

#total_hours(fractional: false) ⇒ Expr

Extract the hours from a Duration type.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.datetime_range(
      DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 4), "1d", eager: true
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date").diff.dt.total_hours.alias("hours_diff")
  ]
)
# =>
# shape: (4, 2)
# ┌─────────────────────┬────────────┐
# │ date                ┆ hours_diff │
# │ ---                 ┆ ---        │
# │ datetime[ns]        ┆ i64        │
# ╞═════════════════════╪════════════╡
# │ 2020-01-01 00:00:00 ┆ null       │
# │ 2020-01-02 00:00:00 ┆ 24         │
# │ 2020-01-03 00:00:00 ┆ 24         │
# │ 2020-01-04 00:00:00 ┆ 24         │
# └─────────────────────┴────────────┘

Parameters:

  • fractional (Boolean) (defaults to: false) —

    Whether to include the fractional component of the second.

Returns:



1582
1583
1584
 
# File 'lib/polars/date_time_expr.rb', line 1582

def total_hours(fractional: false)
  Utils.wrap_expr(_rbexpr.dt_total_hours(fractional))
end

#total_microseconds(fractional: false) ⇒ Expr

Extract the microseconds from a Duration type.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.datetime_range(
      DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 0, 1), "1ms", eager: true
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date").diff.dt.total_microseconds.alias("microseconds_diff")
  ]
)
# =>
# shape: (1_001, 2)
# ┌─────────────────────────┬───────────────────┐
# │ date                    ┆ microseconds_diff │
# │ ---                     ┆ ---               │
# │ datetime[ns]            ┆ i64               │
# ╞═════════════════════════╪═══════════════════╡
# │ 2020-01-01 00:00:00     ┆ null              │
# │ 2020-01-01 00:00:00.001 ┆ 1000              │
# │ 2020-01-01 00:00:00.002 ┆ 1000              │
# │ 2020-01-01 00:00:00.003 ┆ 1000              │
# │ 2020-01-01 00:00:00.004 ┆ 1000              │
# │ …                       ┆ …                 │
# │ 2020-01-01 00:00:00.996 ┆ 1000              │
# │ 2020-01-01 00:00:00.997 ┆ 1000              │
# │ 2020-01-01 00:00:00.998 ┆ 1000              │
# │ 2020-01-01 00:00:00.999 ┆ 1000              │
# │ 2020-01-01 00:00:01     ┆ 1000              │
# └─────────────────────────┴───────────────────┘

Parameters:

  • fractional (Boolean) (defaults to: false) —

    Whether to include the fractional component of the second.

Returns:



1745
1746
1747
 
# File 'lib/polars/date_time_expr.rb', line 1745

def total_microseconds(fractional: false)
  Utils.wrap_expr(_rbexpr.dt_total_microseconds(fractional))
end

#total_milliseconds(fractional: false) ⇒ Expr

Extract the milliseconds from a Duration type.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.datetime_range(
      DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 0, 1), "1ms", eager: true
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date").diff.dt.total_milliseconds.alias("milliseconds_diff")
  ]
)
# =>
# shape: (1_001, 2)
# ┌─────────────────────────┬───────────────────┐
# │ date                    ┆ milliseconds_diff │
# │ ---                     ┆ ---               │
# │ datetime[ns]            ┆ i64               │
# ╞═════════════════════════╪═══════════════════╡
# │ 2020-01-01 00:00:00     ┆ null              │
# │ 2020-01-01 00:00:00.001 ┆ 1                 │
# │ 2020-01-01 00:00:00.002 ┆ 1                 │
# │ 2020-01-01 00:00:00.003 ┆ 1                 │
# │ 2020-01-01 00:00:00.004 ┆ 1                 │
# │ …                       ┆ …                 │
# │ 2020-01-01 00:00:00.996 ┆ 1                 │
# │ 2020-01-01 00:00:00.997 ┆ 1                 │
# │ 2020-01-01 00:00:00.998 ┆ 1                 │
# │ 2020-01-01 00:00:00.999 ┆ 1                 │
# │ 2020-01-01 00:00:01     ┆ 1                 │
# └─────────────────────────┴───────────────────┘

Parameters:

  • fractional (Boolean) (defaults to: false) —

    Whether to include the fractional component of the second.

Returns:



1701
1702
1703
 
# File 'lib/polars/date_time_expr.rb', line 1701

def total_milliseconds(fractional: false)
  Utils.wrap_expr(_rbexpr.dt_total_milliseconds(fractional))
end

#total_minutes(fractional: false) ⇒ Expr

Extract the minutes from a Duration type.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.datetime_range(
      DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 4), "1d", eager: true
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date").diff.dt.total_minutes.alias("minutes_diff")
  ]
)
# =>
# shape: (4, 2)
# ┌─────────────────────┬──────────────┐
# │ date                ┆ minutes_diff │
# │ ---                 ┆ ---          │
# │ datetime[ns]        ┆ i64          │
# ╞═════════════════════╪══════════════╡
# │ 2020-01-01 00:00:00 ┆ null         │
# │ 2020-01-02 00:00:00 ┆ 1440         │
# │ 2020-01-03 00:00:00 ┆ 1440         │
# │ 2020-01-04 00:00:00 ┆ 1440         │
# └─────────────────────┴──────────────┘

Parameters:

  • fractional (Boolean) (defaults to: false) —

    Whether to include the fractional component of the second.

Returns:



1619
1620
1621
 
# File 'lib/polars/date_time_expr.rb', line 1619

def total_minutes(fractional: false)
  Utils.wrap_expr(_rbexpr.dt_total_minutes(fractional))
end

#total_nanoseconds(fractional: false) ⇒ Expr

Extract the nanoseconds from a Duration type.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.datetime_range(
      DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 0, 1), "1ms", eager: true
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date").diff.dt.total_nanoseconds.alias("nanoseconds_diff")
  ]
)
# =>
# shape: (1_001, 2)
# ┌─────────────────────────┬──────────────────┐
# │ date                    ┆ nanoseconds_diff │
# │ ---                     ┆ ---              │
# │ datetime[ns]            ┆ i64              │
# ╞═════════════════════════╪══════════════════╡
# │ 2020-01-01 00:00:00     ┆ null             │
# │ 2020-01-01 00:00:00.001 ┆ 1000000          │
# │ 2020-01-01 00:00:00.002 ┆ 1000000          │
# │ 2020-01-01 00:00:00.003 ┆ 1000000          │
# │ 2020-01-01 00:00:00.004 ┆ 1000000          │
# │ …                       ┆ …                │
# │ 2020-01-01 00:00:00.996 ┆ 1000000          │
# │ 2020-01-01 00:00:00.997 ┆ 1000000          │
# │ 2020-01-01 00:00:00.998 ┆ 1000000          │
# │ 2020-01-01 00:00:00.999 ┆ 1000000          │
# │ 2020-01-01 00:00:01     ┆ 1000000          │
# └─────────────────────────┴──────────────────┘

Parameters:

  • fractional (Boolean) (defaults to: false) —

    Whether to include the fractional component of the second.

Returns:



1789
1790
1791
 
# File 'lib/polars/date_time_expr.rb', line 1789

def total_nanoseconds(fractional: false)
  Utils.wrap_expr(_rbexpr.dt_total_nanoseconds(fractional))
end

#total_seconds(fractional: false) ⇒ Expr

Extract the seconds from a Duration type.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.datetime_range(
      DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 4, 0), "1m", eager: true
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date").diff.dt.total_seconds.alias("seconds_diff")
  ]
)
# =>
# shape: (5, 2)
# ┌─────────────────────┬──────────────┐
# │ date                ┆ seconds_diff │
# │ ---                 ┆ ---          │
# │ datetime[ns]        ┆ i64          │
# ╞═════════════════════╪══════════════╡
# │ 2020-01-01 00:00:00 ┆ null         │
# │ 2020-01-01 00:01:00 ┆ 60           │
# │ 2020-01-01 00:02:00 ┆ 60           │
# │ 2020-01-01 00:03:00 ┆ 60           │
# │ 2020-01-01 00:04:00 ┆ 60           │
# └─────────────────────┴──────────────┘

Parameters:

  • fractional (Boolean) (defaults to: false) —

    Whether to include the fractional component of the second.

Returns:



1657
1658
1659
 
# File 'lib/polars/date_time_expr.rb', line 1657

def total_seconds(fractional: false)
  Utils.wrap_expr(_rbexpr.dt_total_seconds(fractional))
end

#truncate(every) ⇒ Expr

Note:

The every argument is created with the the following small string formatting language:

1ns # 1 nanosecond 1us # 1 microsecond 1ms # 1 millisecond 1s # 1 second 1m # 1 minute 1h # 1 hour 1d # 1 day 1w # 1 week 1mo # 1 calendar month 1y # 1 calendar year

eg: 3d12h4m25s # 3 days, 12 hours, 4 minutes, and 25 seconds

Divide the date/datetime range into buckets.

Each date/datetime is mapped to the start of its bucket.

Examples:

df = (
  Polars.datetime_range(
    DateTime.new(2001, 1, 1),
    DateTime.new(2001, 1, 2),
    "225m",
    eager: true
  )
  .alias("datetime")
  .to_frame
)
# =>
# shape: (7, 1)
# ┌─────────────────────┐
# │ datetime            │
# │ ---                 │
# │ datetime[ns]        │
# ╞═════════════════════╡
# │ 2001-01-01 00:00:00 │
# │ 2001-01-01 03:45:00 │
# │ 2001-01-01 07:30:00 │
# │ 2001-01-01 11:15:00 │
# │ 2001-01-01 15:00:00 │
# │ 2001-01-01 18:45:00 │
# │ 2001-01-01 22:30:00 │
# └─────────────────────┘
df.select(Polars.col("datetime").dt.truncate("1h"))
# =>
# shape: (7, 1)
# ┌─────────────────────┐
# │ datetime            │
# │ ---                 │
# │ datetime[ns]        │
# ╞═════════════════════╡
# │ 2001-01-01 00:00:00 │
# │ 2001-01-01 03:00:00 │
# │ 2001-01-01 07:00:00 │
# │ 2001-01-01 11:00:00 │
# │ 2001-01-01 15:00:00 │
# │ 2001-01-01 18:00:00 │
# │ 2001-01-01 22:00:00 │
# └─────────────────────┘
df = (
  Polars.datetime_range(
    DateTime.new(2001, 1, 1), DateTime.new(2001, 1, 1, 1), "10m", eager: true
  )
  .alias("datetime")
  .to_frame
)
df.select(["datetime", Polars.col("datetime").dt.truncate("30m").alias("truncate")])
# =>
# shape: (7, 2)
# ┌─────────────────────┬─────────────────────┐
# │ datetime            ┆ truncate            │
# │ ---                 ┆ ---                 │
# │ datetime[ns]        ┆ datetime[ns]        │
# ╞═════════════════════╪═════════════════════╡
# │ 2001-01-01 00:00:00 ┆ 2001-01-01 00:00:00 │
# │ 2001-01-01 00:10:00 ┆ 2001-01-01 00:00:00 │
# │ 2001-01-01 00:20:00 ┆ 2001-01-01 00:00:00 │
# │ 2001-01-01 00:30:00 ┆ 2001-01-01 00:30:00 │
# │ 2001-01-01 00:40:00 ┆ 2001-01-01 00:30:00 │
# │ 2001-01-01 00:50:00 ┆ 2001-01-01 00:30:00 │
# │ 2001-01-01 01:00:00 ┆ 2001-01-01 01:00:00 │
# └─────────────────────┴─────────────────────┘

Parameters:

  • every (String) —

    Every interval start and period length

Returns:



210
211
212
213
214
215
216
217
 
# File 'lib/polars/date_time_expr.rb', line 210

def truncate(every)
  if !every.is_a?(Expr)
    every = Utils.parse_as_duration_string(every)
  end

  every = Utils.parse_into_expression(every, str_as_lit: true)
  Utils.wrap_expr(_rbexpr.dt_truncate(every))
end

#week ⇒ Expr

Extract the week from the underlying Date representation.

Applies to Date and Datetime columns.

Returns the ISO week number starting from 1. The return value ranges from 1 to 53. (The last week of year differs by years.)

Examples:

df = Polars::DataFrame.new(
  {"date" => [Date.new(2001, 1, 1), Date.new(2001, 6, 30), Date.new(2001, 12, 27)]}
)
df.with_columns(Polars.col("date").dt.week.alias("week"))
# =>
# shape: (3, 2)
# ┌────────────┬──────┐
# │ date       ┆ week │
# │ ---        ┆ ---  │
# │ date       ┆ i8   │
# ╞════════════╪══════╡
# │ 2001-01-01 ┆ 1    │
# │ 2001-06-30 ┆ 26   │
# │ 2001-12-27 ┆ 52   │
# └────────────┴──────┘

Returns:



870
871
872
 
# File 'lib/polars/date_time_expr.rb', line 870

def week
  Utils.wrap_expr(_rbexpr.dt_week)
end

#weekday ⇒ Expr

Extract the week day from the underlying Date representation.

Applies to Date and Datetime columns.

Returns the ISO weekday number where monday = 1 and sunday = 7

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.date_range(
      Date.new(2001, 12, 22), Date.new(2001, 12, 25), eager: true
    )
  }
)
df.with_columns(
  Polars.col("date").dt.weekday.alias("weekday"),
  Polars.col("date").dt.day.alias("day_of_month"),
  Polars.col("date").dt.ordinal_day.alias("day_of_year")
)
# =>
# shape: (4, 4)
# ┌────────────┬─────────┬──────────────┬─────────────┐
# │ date       ┆ weekday ┆ day_of_month ┆ day_of_year │
# │ ---        ┆ ---     ┆ ---          ┆ ---         │
# │ date       ┆ i8      ┆ i8           ┆ i16         │
# ╞════════════╪═════════╪══════════════╪═════════════╡
# │ 2001-12-22 ┆ 6       ┆ 22           ┆ 356         │
# │ 2001-12-23 ┆ 7       ┆ 23           ┆ 357         │
# │ 2001-12-24 ┆ 1       ┆ 24           ┆ 358         │
# │ 2001-12-25 ┆ 2       ┆ 25           ┆ 359         │
# └────────────┴─────────┴──────────────┴─────────────┘

Returns:



907
908
909
 
# File 'lib/polars/date_time_expr.rb', line 907

def weekday
  Utils.wrap_expr(_rbexpr.dt_weekday)
end

#year ⇒ Expr

Extract year from underlying Date representation.

Applies to Date and Datetime columns.

Returns the year number in the calendar date.

Examples:

df = Polars::DataFrame.new(
  {"date" => [Date.new(1977, 1, 1), Date.new(1978, 1, 1), Date.new(1979, 1, 1)]}
)
df.with_columns(
  calendar_year: Polars.col("date").dt.year,
  iso_year: Polars.col("date").dt.iso_year
)
# =>
# shape: (3, 3)
# ┌────────────┬───────────────┬──────────┐
# │ date       ┆ calendar_year ┆ iso_year │
# │ ---        ┆ ---           ┆ ---      │
# │ date       ┆ i32           ┆ i32      │
# ╞════════════╪═══════════════╪══════════╡
# │ 1977-01-01 ┆ 1977          ┆ 1976     │
# │ 1978-01-01 ┆ 1978          ┆ 1977     │
# │ 1979-01-01 ┆ 1979          ┆ 1979     │
# └────────────┴───────────────┴──────────┘

Returns:



621
622
623
 
# File 'lib/polars/date_time_expr.rb', line 621

def year
  Utils.wrap_expr(_rbexpr.dt_year)
end