Class: Polars::DateTimeExpr

Inherits:

Object

Object
Polars::DateTimeExpr

show all

Defined in:: lib/polars/date_time_expr.rb

Overview

Namespace for datetime related expressions.

Instance Method Summary collapse

#cast_time_unit(tu) ⇒ Expr
Cast the underlying data to another time unit.
#combine(time, time_unit: "us") ⇒ Expr
Create a naive Datetime from an existing Date/Datetime expression and a Time.
#convert_time_zone(tz) ⇒ Expr
Set time zone for a Series of type Datetime.
#date ⇒ Expr
Date.
#datetime ⇒ Expr
Datetime.
#day ⇒ Expr
Extract day from underlying Date representation.
#epoch(tu = "us") ⇒ Expr
Get the time passed since the Unix EPOCH in the give time unit.
#hour ⇒ Expr
Extract hour from underlying DateTime representation.
#is_leap_year ⇒ Expr
Determine whether the year of the underlying date is a leap year.
#iso_year ⇒ Expr
Extract ISO year from underlying Date representation.
#microsecond ⇒ Expr
Extract microseconds from underlying DateTime representation.
#millisecond ⇒ Expr
Extract milliseconds from underlying DateTime representation.
#minute ⇒ Expr
Extract minutes from underlying DateTime representation.
#month ⇒ Expr
Extract month from underlying Date representation.
#month_end ⇒ Expr
Roll forward to the last day of the month.
#month_start ⇒ Expr
Roll backward to the first day of the month.
#nanosecond ⇒ Expr
Extract nanoseconds from underlying DateTime representation.
#offset_by(by) ⇒ Expr
Offset this date by a relative time offset.
#ordinal_day ⇒ Expr
Extract ordinal day from underlying Date representation.
#quarter ⇒ Expr
Extract quarter from underlying Date representation.
#replace_time_zone(time_zone, use_earliest: nil, ambiguous: "raise", non_existent: "raise") ⇒ Expr
Cast time zone for a Series of type Datetime.
#round(every, offset: nil) ⇒ Expr
Divide the date/datetime range into buckets.
#second(fractional: false) ⇒ Expr
Extract seconds from underlying DateTime representation.
#strftime(fmt) ⇒ Expr
Format Date/datetime with a formatting rule.
#time ⇒ Expr
Time.
#timestamp(tu = "us") ⇒ Expr
Return a timestamp in the given time unit.
#total_days ⇒ Expr (also: #days)
Extract the days from a Duration type.
#total_hours ⇒ Expr (also: #hours)
Extract the hours from a Duration type.
#total_microseconds ⇒ Expr (also: #microseconds)
Extract the microseconds from a Duration type.
#total_milliseconds ⇒ Expr (also: #milliseconds)
Extract the milliseconds from a Duration type.
#total_minutes ⇒ Expr (also: #minutes)
Extract the minutes from a Duration type.
#total_nanoseconds ⇒ Expr (also: #nanoseconds)
Extract the nanoseconds from a Duration type.
#total_seconds ⇒ Expr (also: #seconds)
Extract the seconds from a Duration type.
#truncate(every, offset: nil, use_earliest: nil) ⇒ Expr
Divide the date/datetime range into buckets.
#week ⇒ Expr
Extract the week from the underlying Date representation.
#weekday ⇒ Expr
Extract the week day from the underlying Date representation.
#with_time_unit(tu) ⇒ Expr
Set time unit of a Series of dtype Datetime or Duration.
#year ⇒ Expr
Extract year from underlying Date representation.

Instance Method Details

#cast_time_unit(tu) ⇒ `Expr`

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

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.date_range(
      DateTime.new(2001, 1, 1), DateTime.new(2001, 1, 3), "1d"
    )
  }
)
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[μs]        ┆ 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:

tu ("ns", "us", "ms") —
Time unit for the Datetime Series.

Returns:

(Expr)



980
981
982

# File 'lib/polars/date_time_expr.rb', line 980

def cast_time_unit(tu)
  Utils.wrap_expr(_rbexpr.dt_cast_time_unit(tu))
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:

(Expr)

# File 'lib/polars/date_time_expr.rb', line 237

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.expr_to_lit_or_expr(time)
  Utils.wrap_expr(_rbexpr.dt_combine(time._rbexpr, time_unit))
end

#convert_time_zone(tz) ⇒ `Expr`

Set time zone for a Series of type Datetime.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.date_range(
      DateTime.new(2020, 3, 1),
      DateTime.new(2020, 5, 1),
      "1mo",
      time_zone: "UTC"
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date")
      .dt.convert_time_zone("Europe/London")
      .alias("London")
  ]
)
# =>
# shape: (3, 2)
# ┌─────────────────────────┬─────────────────────────────┐
# │ date                    ┆ London                      │
# │ ---                     ┆ ---                         │
# │ datetime[μs, UTC]       ┆ datetime[μs, 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:

tz (String) —
Time zone for the Datetime Series.

Returns:

(Expr)



1021
1022
1023

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

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

#date ⇒ `Expr`

Date

Returns:

(Expr)



615
616
617

# File 'lib/polars/date_time_expr.rb', line 615

def date
  Utils.wrap_expr(_rbexpr.dt_date)
end

#datetime ⇒ `Expr`

Datetime

Returns:

(Expr)



622
623
624

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

def datetime
  Utils.wrap_expr(_rbexpr.dt_datetime)
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:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 9)
df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "3d")})
# =>
# shape: (3, 1)
# ┌─────────────────────┐
# │ date                │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 2001-01-01 00:00:00 │
# │ 2001-01-04 00:00:00 │
# │ 2001-01-07 00:00:00 │
# └─────────────────────┘

df.select(
  [
    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: (3, 3)
# ┌─────────┬──────────────┬─────────────┐
# │ weekday ┆ day_of_month ┆ day_of_year │
# │ ---     ┆ ---          ┆ ---         │
# │ i8      ┆ i8           ┆ i16         │
# ╞═════════╪══════════════╪═════════════╡
# │ 1       ┆ 1            ┆ 1           │
# │ 4       ┆ 4            ┆ 4           │
# │ 7       ┆ 7            ┆ 7           │
# └─────────┴──────────────┴─────────────┘

Returns:

(Expr)



553
554
555

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

def day
  Utils.wrap_expr(_rbexpr.day)
end

#epoch(tu = "us") ⇒ `Expr`

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

Examples:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 3)
df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "1d")})
df.select(
  [
    Polars.col("date"),
    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   │
# │ ---                 ┆ ---             ┆ ---       │
# │ datetime[μs]        ┆ i64             ┆ i64       │
# ╞═════════════════════╪═════════════════╪═══════════╡
# │ 2001-01-01 00:00:00 ┆ 978307200000000 ┆ 978307200 │
# │ 2001-01-02 00:00:00 ┆ 978393600000000 ┆ 978393600 │
# │ 2001-01-03 00:00:00 ┆ 978480000000000 ┆ 978480000 │
# └─────────────────────┴─────────────────┴───────────┘

Parameters:

tu ("us", "ns", "ms", "s", "d") (defaults to: "us") —
Time unit.

Returns:

(Expr)

# File 'lib/polars/date_time_expr.rb', line 863

def epoch(tu = "us")
  if Utils::DTYPE_TEMPORAL_UNITS.include?(tu)
    timestamp(tu)
  elsif tu == "s"
    Utils.wrap_expr(_rbexpr.dt_epoch_seconds)
  elsif tu == "d"
    Utils.wrap_expr(_rbexpr).cast(:date).cast(:i32)
  else
    raise ArgumentError, "tu must be one of {{'ns', 'us', 'ms', 's', 'd'}}, got #{tu}"
  end
end

#hour ⇒ `Expr`

Extract hour from underlying DateTime representation.

Applies to Datetime columns.

Returns the hour number from 0 to 23.

Examples:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 2)
df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "12h")})
# =>
# shape: (3, 1)
# ┌─────────────────────┐
# │ date                │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 2001-01-01 00:00:00 │
# │ 2001-01-01 12:00:00 │
# │ 2001-01-02 00:00:00 │
# └─────────────────────┘

df.select(Polars.col("date").dt.hour)
# =>
# shape: (3, 1)
# ┌──────┐
# │ date │
# │ ---  │
# │ i8   │
# ╞══════╡
# │ 0    │
# │ 12   │
# │ 0    │
# └──────┘

Returns:

(Expr)



663
664
665

# File 'lib/polars/date_time_expr.rb', line 663

def hour
  Utils.wrap_expr(_rbexpr.hour)
end

#is_leap_year ⇒ `Expr`

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

Applies to Date and Datetime columns.

Examples:

start = DateTime.new(2000, 1, 1)
stop = DateTime.new(2002, 1, 1)
df = Polars::DataFrame.new(
  {"date" => Polars.date_range(start, stop, "1y")}
)
df.select(Polars.col("date").dt.is_leap_year)
# =>
# shape: (3, 1)
# ┌───────┐
# │ date  │
# │ ---   │
# │ bool  │
# ╞═══════╡
# │ true  │
# │ false │
# │ false │
# └───────┘

Returns:

(Expr)



321
322
323

# File 'lib/polars/date_time_expr.rb', line 321

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.

Returns:

(Expr)



333
334
335

# File 'lib/polars/date_time_expr.rb', line 333

def iso_year
  Utils.wrap_expr(_rbexpr.iso_year)
end

#microsecond ⇒ `Expr`

Extract microseconds from underlying DateTime representation.

Applies to Datetime columns.

Returns:

(Expr)



821
822
823

# File 'lib/polars/date_time_expr.rb', line 821

def microsecond
  Utils.wrap_expr(_rbexpr.microsecond)
end

#millisecond ⇒ `Expr`

Extract milliseconds from underlying DateTime representation.

Applies to Datetime columns.

Returns:

(Expr)



812
813
814

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

def millisecond
  Utils.wrap_expr(_rbexpr.millisecond)
end

#minute ⇒ `Expr`

Extract minutes from underlying DateTime representation.

Applies to Datetime columns.

Returns the minute number from 0 to 59.

Examples:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 1, 0, 4, 0)
df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "2m")})
# =>
# shape: (3, 1)
# ┌─────────────────────┐
# │ date                │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 2001-01-01 00:00:00 │
# │ 2001-01-01 00:02:00 │
# │ 2001-01-01 00:04:00 │
# └─────────────────────┘

df.select(Polars.col("date").dt.minute)
# =>
# shape: (3, 1)
# ┌──────┐
# │ date │
# │ ---  │
# │ i8   │
# ╞══════╡
# │ 0    │
# │ 2    │
# │ 4    │
# └──────┘

Returns:

(Expr)



704
705
706

# File 'lib/polars/date_time_expr.rb', line 704

def minute
  Utils.wrap_expr(_rbexpr.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:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 4, 1)
df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "31d")})
# =>
# shape: (3, 1)
# ┌─────────────────────┐
# │ date                │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 2001-01-01 00:00:00 │
# │ 2001-02-01 00:00:00 │
# │ 2001-03-04 00:00:00 │
# └─────────────────────┘

df.select(Polars.col("date").dt.month)
# =>
# shape: (3, 1)
# ┌──────┐
# │ date │
# │ ---  │
# │ i8   │
# ╞══════╡
# │ 1    │
# │ 2    │
# │ 3    │
# └──────┘

Returns:

(Expr)



416
417
418

# File 'lib/polars/date_time_expr.rb', line 416

def month
  Utils.wrap_expr(_rbexpr.month)
end

#month_end ⇒ `Expr`

Roll forward to the last day of the month.

Examples:

df = Polars::DataFrame.new(
  {
    "dates" => Polars.date_range(
      DateTime.new(2000, 1, 15, 2),
      DateTime.new(2000, 12, 15, 2),
      "1mo"
    )
  }
)
df.select(Polars.col("dates").dt.month_end)
# =>
# shape: (12, 1)
# ┌─────────────────────┐
# │ dates               │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 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:

(Expr)



1440
1441
1442

# File 'lib/polars/date_time_expr.rb', line 1440

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.date_range(
      DateTime.new(2000, 1, 15, 2),
      DateTime.new(2000, 12, 15, 2),
      "1mo"
    )
  }
)
df.select(Polars.col("dates").dt.month_start)
# =>
# shape: (12, 1)
# ┌─────────────────────┐
# │ dates               │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 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:

(Expr)



1402
1403
1404

# File 'lib/polars/date_time_expr.rb', line 1402

def month_start
  Utils.wrap_expr(_rbexpr.dt_month_start)
end

#nanosecond ⇒ `Expr`

Extract nanoseconds from underlying DateTime representation.

Applies to Datetime columns.

Returns:

(Expr)



830
831
832

# File 'lib/polars/date_time_expr.rb', line 830

def nanosecond
  Utils.wrap_expr(_rbexpr.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.date_range(
      DateTime.new(2000, 1, 1), DateTime.new(2005, 1, 1), "1y"
    )
  }
)
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[μs]        ┆ datetime[μs]        │
# ╞═════════════════════╪═════════════════════╡
# │ 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:

(Expr)

# File 'lib/polars/date_time_expr.rb', line 1363

def offset_by(by)
  by = Utils.parse_as_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:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 9)
df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "3d")})
# =>
# shape: (3, 1)
# ┌─────────────────────┐
# │ date                │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 2001-01-01 00:00:00 │
# │ 2001-01-04 00:00:00 │
# │ 2001-01-07 00:00:00 │
# └─────────────────────┘

df.select(
  [
    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: (3, 3)
# ┌─────────┬──────────────┬─────────────┐
# │ weekday ┆ day_of_month ┆ day_of_year │
# │ ---     ┆ ---          ┆ ---         │
# │ i8      ┆ i8           ┆ i16         │
# ╞═════════╪══════════════╪═════════════╡
# │ 1       ┆ 1            ┆ 1           │
# │ 4       ┆ 4            ┆ 4           │
# │ 7       ┆ 7            ┆ 7           │
# └─────────┴──────────────┴─────────────┘

Returns:

(Expr)



601
602
603

# File 'lib/polars/date_time_expr.rb', line 601

def ordinal_day
  Utils.wrap_expr(_rbexpr.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:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2002, 6, 1)
df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "180d")})
# =>
# shape: (3, 1)
# ┌─────────────────────┐
# │ date                │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 2001-01-01 00:00:00 │
# │ 2001-06-30 00:00:00 │
# │ 2001-12-27 00:00:00 │
# └─────────────────────┘

df.select(Polars.col("date").dt.quarter)
# =>
# shape: (3, 1)
# ┌──────┐
# │ date │
# │ ---  │
# │ i8   │
# ╞══════╡
# │ 1    │
# │ 2    │
# │ 4    │
# └──────┘

Returns:

(Expr)



374
375
376

# File 'lib/polars/date_time_expr.rb', line 374

def quarter
  Utils.wrap_expr(_rbexpr.quarter)
end

#replace_time_zone(time_zone, use_earliest: nil, 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,

Parameters:

time_zone (String) —
Time zone for the Datetime Series. Pass nil to unset time zone.
use_earliest (Boolean) (defaults to: nil) —
Determine how to deal with ambiguous datetimes.
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:

(Expr)

# File 'lib/polars/date_time_expr.rb', line 1040

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

#round(every, offset: nil) ⇒ `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:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 2)
df = Polars.date_range(
  start, stop, "225m", name: "dates"
).to_frame
# =>
# shape: (7, 1)
# ┌─────────────────────┐
# │ dates               │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 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("dates").dt.round("1h"))
# =>
# shape: (7, 1)
# ┌─────────────────────┐
# │ dates               │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 2001-01-01 00:00:00 │
# │ 2001-01-01 04:00:00 │
# │ 2001-01-01 08:00:00 │
# │ 2001-01-01 11:00:00 │
# │ 2001-01-01 15:00:00 │
# │ 2001-01-01 19:00:00 │
# │ 2001-01-01 23:00:00 │
# └─────────────────────┘

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 1, 1)
df = Polars.date_range(start, stop, "10m", name: "dates").to_frame
df.select(["dates", Polars.col("dates").dt.round("30m").alias("round")])
# =>
# shape: (7, 2)
# ┌─────────────────────┬─────────────────────┐
# │ dates               ┆ round               │
# │ ---                 ┆ ---                 │
# │ datetime[μs]        ┆ datetime[μs]        │
# ╞═════════════════════╪═════════════════════╡
# │ 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
offset (String) (defaults to: nil) —
Offset the window

Returns:

(Expr)

# File 'lib/polars/date_time_expr.rb', line 213

def round(every, offset: nil)
  if offset.nil?
    offset = "0ns"
  end

  Utils.wrap_expr(
    _rbexpr.dt_round(
      Utils._timedelta_to_pl_duration(every),
      Utils._timedelta_to_pl_duration(offset)
    )
  )
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(
  {
    "date" => Polars.date_range(
      DateTime.new(2001, 1, 1, 0, 0, 0.456789),
      DateTime.new(2001, 1, 1, 0, 0, 6),
      "2s654321us"
    )
  }
)
# =>
# shape: (3, 1)
# ┌────────────────────────────┐
# │ date                       │
# │ ---                        │
# │ datetime[μs]               │
# ╞════════════════════════════╡
# │ 2001-01-01 00:00:00.456789 │
# │ 2001-01-01 00:00:03.111110 │
# │ 2001-01-01 00:00:05.765431 │
# └────────────────────────────┘

df.select(Polars.col("date").dt.second.alias("secs"))
# =>
# shape: (3, 1)
# ┌──────┐
# │ secs │
# │ ---  │
# │ i8   │
# ╞══════╡
# │ 0    │
# │ 3    │
# │ 5    │
# └──────┘

df.select(Polars.col("date").dt.second(fractional: true).alias("secs"))
# =>
# shape: (3, 1)
# ┌──────────┐
# │ secs     │
# │ ---      │
# │ f64      │
# ╞══════════╡
# │ 0.456789 │
# │ 3.11111  │
# │ 5.765431 │
# └──────────┘

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 1, 0, 0, 4)
df = Polars::DataFrame.new(
  {"date" => Polars.date_range(start, stop, "2s")}
)
# =>
# shape: (3, 1)
# ┌─────────────────────┐
# │ date                │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 2001-01-01 00:00:00 │
# │ 2001-01-01 00:00:02 │
# │ 2001-01-01 00:00:04 │
# └─────────────────────┘

df.select(Polars.col("date").dt.second)
# =>
# shape: (3, 1)
# ┌──────┐
# │ date │
# │ ---  │
# │ i8   │
# ╞══════╡
# │ 0    │
# │ 2    │
# │ 4    │
# └──────┘

Returns:

(Expr)

# File 'lib/polars/date_time_expr.rb', line 798

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

#strftime(fmt) ⇒ `Expr`

Format Date/datetime with a formatting rule.

See chrono strftime/strptime.

Returns:

(Expr)



250
251
252

# File 'lib/polars/date_time_expr.rb', line 250

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

#time ⇒ `Expr`

Time

Returns:

(Expr)



608
609
610

# File 'lib/polars/date_time_expr.rb', line 608

def time
  Utils.wrap_expr(_rbexpr.dt_time)
end

#timestamp(tu = "us") ⇒ `Expr`

Return a timestamp in the given time unit.

Examples:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 3)
df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "1d")})
df.select(
  [
    Polars.col("date"),
    Polars.col("date").dt.timestamp.alias("timestamp_ns"),
    Polars.col("date").dt.timestamp("ms").alias("timestamp_ms")
  ]
)
# =>
# shape: (3, 3)
# ┌─────────────────────┬─────────────────┬──────────────┐
# │ date                ┆ timestamp_ns    ┆ timestamp_ms │
# │ ---                 ┆ ---             ┆ ---          │
# │ datetime[μs]        ┆ i64             ┆ i64          │
# ╞═════════════════════╪═════════════════╪══════════════╡
# │ 2001-01-01 00:00:00 ┆ 978307200000000 ┆ 978307200000 │
# │ 2001-01-02 00:00:00 ┆ 978393600000000 ┆ 978393600000 │
# │ 2001-01-03 00:00:00 ┆ 978480000000000 ┆ 978480000000 │
# └─────────────────────┴─────────────────┴──────────────┘

Parameters:

tu ("us", "ns", "ms") (defaults to: "us") —
Time unit.

Returns:

(Expr)



904
905
906

# File 'lib/polars/date_time_expr.rb', line 904

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

#total_days ⇒ `Expr` Also known as: days

Extract the days from a Duration type.

Examples:

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

Returns:

(Expr)



1075
1076
1077

# File 'lib/polars/date_time_expr.rb', line 1075

def total_days
  Utils.wrap_expr(_rbexpr.dt_total_days)
end

#total_hours ⇒ `Expr` Also known as: hours

Extract the hours from a Duration type.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.date_range(
      DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 4), "1d"
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date").diff.dt.hours.alias("hours_diff")
  ]
)
# =>
# shape: (4, 2)
# ┌─────────────────────┬────────────┐
# │ date                ┆ hours_diff │
# │ ---                 ┆ ---        │
# │ datetime[μs]        ┆ 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         │
# └─────────────────────┴────────────┘

Returns:

(Expr)



1110
1111
1112

# File 'lib/polars/date_time_expr.rb', line 1110

def total_hours
  Utils.wrap_expr(_rbexpr.dt_total_hours)
end

#total_microseconds ⇒ `Expr` Also known as: microseconds

Extract the microseconds from a Duration type.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.date_range(
      DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 0, 1), "1ms"
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date").diff.dt.microseconds.alias("microseconds_diff")
  ]
)
# =>
# shape: (1_001, 2)
# ┌─────────────────────────┬───────────────────┐
# │ date                    ┆ microseconds_diff │
# │ ---                     ┆ ---               │
# │ datetime[μs]            ┆ 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              │
# └─────────────────────────┴───────────────────┘

Returns:

(Expr)



1265
1266
1267

# File 'lib/polars/date_time_expr.rb', line 1265

def total_microseconds
  Utils.wrap_expr(_rbexpr.dt_total_microseconds)
end

#total_milliseconds ⇒ `Expr` Also known as: milliseconds

Extract the milliseconds from a Duration type.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.date_range(
      DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 0, 1), "1ms"
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date").diff.dt.milliseconds.alias("milliseconds_diff")
  ]
)
# =>
# shape: (1_001, 2)
# ┌─────────────────────────┬───────────────────┐
# │ date                    ┆ milliseconds_diff │
# │ ---                     ┆ ---               │
# │ datetime[μs]            ┆ 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                 │
# └─────────────────────────┴───────────────────┘

Returns:

(Expr)



1223
1224
1225

# File 'lib/polars/date_time_expr.rb', line 1223

def total_milliseconds
  Utils.wrap_expr(_rbexpr.dt_total_milliseconds)
end

#total_minutes ⇒ `Expr` Also known as: minutes

Extract the minutes from a Duration type.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.date_range(
      DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 4), "1d"
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date").diff.dt.minutes.alias("minutes_diff")
  ]
)
# =>
# shape: (4, 2)
# ┌─────────────────────┬──────────────┐
# │ date                ┆ minutes_diff │
# │ ---                 ┆ ---          │
# │ datetime[μs]        ┆ 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         │
# └─────────────────────┴──────────────┘

Returns:

(Expr)



1145
1146
1147

# File 'lib/polars/date_time_expr.rb', line 1145

def total_minutes
  Utils.wrap_expr(_rbexpr.dt_total_minutes)
end

#total_nanoseconds ⇒ `Expr` Also known as: nanoseconds

Extract the nanoseconds from a Duration type.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.date_range(
      DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 0, 1), "1ms"
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date").diff.dt.nanoseconds.alias("nanoseconds_diff")
  ]
)
# =>
# shape: (1_001, 2)
# ┌─────────────────────────┬──────────────────┐
# │ date                    ┆ nanoseconds_diff │
# │ ---                     ┆ ---              │
# │ datetime[μs]            ┆ 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          │
# └─────────────────────────┴──────────────────┘

Returns:

(Expr)



1307
1308
1309

# File 'lib/polars/date_time_expr.rb', line 1307

def total_nanoseconds
  Utils.wrap_expr(_rbexpr.dt_total_nanoseconds)
end

#total_seconds ⇒ `Expr` Also known as: seconds

Extract the seconds from a Duration type.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.date_range(
      DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 4, 0), "1m"
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date").diff.dt.seconds.alias("seconds_diff")
  ]
)
# =>
# shape: (5, 2)
# ┌─────────────────────┬──────────────┐
# │ date                ┆ seconds_diff │
# │ ---                 ┆ ---          │
# │ datetime[μs]        ┆ 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           │
# └─────────────────────┴──────────────┘

Returns:

(Expr)



1181
1182
1183

# File 'lib/polars/date_time_expr.rb', line 1181

def total_seconds
  Utils.wrap_expr(_rbexpr.dt_total_seconds)
end

#truncate(every, offset: nil, use_earliest: nil) ⇒ `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

Divide the date/datetime range into buckets.

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

Examples:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 2)
df = Polars.date_range(
  start, stop, "225m", name: "dates"
).to_frame
# =>
# shape: (7, 1)
# ┌─────────────────────┐
# │ dates               │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 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("dates").dt.truncate("1h"))
# =>
# shape: (7, 1)
# ┌─────────────────────┐
# │ dates               │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 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 │
# └─────────────────────┘

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 1, 1)
df = Polars.date_range(start, stop, "10m", name: "dates").to_frame
df.select(["dates", Polars.col("dates").dt.truncate("30m").alias("truncate")])
# =>
# shape: (7, 2)
# ┌─────────────────────┬─────────────────────┐
# │ dates               ┆ truncate            │
# │ ---                 ┆ ---                 │
# │ datetime[μs]        ┆ datetime[μs]        │
# ╞═════════════════════╪═════════════════════╡
# │ 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
offset (String) (defaults to: nil) —
Offset the window

Returns:

(Expr)

# File 'lib/polars/date_time_expr.rb', line 100

def truncate(every, offset: nil, use_earliest: nil)
  if offset.nil?
    offset = "0ns"
  end

  if !every.is_a?(Expr)
    every = Utils._timedelta_to_pl_duration(every)
  end
  every = Utils.parse_as_expression(every, str_as_lit: true)

  Utils.wrap_expr(
    _rbexpr.dt_truncate(
      every,
      Utils._timedelta_to_pl_duration(offset),
    )
  )
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:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 4, 1)
df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "31d")})
# =>
# shape: (3, 1)
# ┌─────────────────────┐
# │ date                │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 2001-01-01 00:00:00 │
# │ 2001-02-01 00:00:00 │
# │ 2001-03-04 00:00:00 │
# └─────────────────────┘

df.select(Polars.col("date").dt.week)
# =>
# shape: (3, 1)
# ┌──────┐
# │ date │
# │ ---  │
# │ i8   │
# ╞══════╡
# │ 1    │
# │ 5    │
# │ 9    │
# └──────┘

Returns:

(Expr)



458
459
460

# File 'lib/polars/date_time_expr.rb', line 458

def week
  Utils.wrap_expr(_rbexpr.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:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 9)
df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "3d")})
# =>
# shape: (3, 1)
# ┌─────────────────────┐
# │ date                │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 2001-01-01 00:00:00 │
# │ 2001-01-04 00:00:00 │
# │ 2001-01-07 00:00:00 │
# └─────────────────────┘

df.select(
  [
    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: (3, 3)
# ┌─────────┬──────────────┬─────────────┐
# │ weekday ┆ day_of_month ┆ day_of_year │
# │ ---     ┆ ---          ┆ ---         │
# │ i8      ┆ i8           ┆ i16         │
# ╞═════════╪══════════════╪═════════════╡
# │ 1       ┆ 1            ┆ 1           │
# │ 4       ┆ 4            ┆ 4           │
# │ 7       ┆ 7            ┆ 7           │
# └─────────┴──────────────┴─────────────┘

Returns:

(Expr)



505
506
507

# File 'lib/polars/date_time_expr.rb', line 505

def weekday
  Utils.wrap_expr(_rbexpr.weekday)
end

#with_time_unit(tu) ⇒ `Expr`

Set time unit of a Series of dtype Datetime or Duration.

This does not modify underlying data, and should be used to fix an incorrect time unit.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.date_range(
      DateTime.new(2001, 1, 1), DateTime.new(2001, 1, 3), "1d", time_unit: "ns"
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date").dt.with_time_unit("us").alias("tu_us")
  ]
)
# =>
# shape: (3, 2)
# ┌─────────────────────┬───────────────────────┐
# │ date                ┆ tu_us                 │
# │ ---                 ┆ ---                   │
# │ datetime[ns]        ┆ datetime[μs]          │
# ╞═════════════════════╪═══════════════════════╡
# │ 2001-01-01 00:00:00 ┆ +32971-04-28 00:00:00 │
# │ 2001-01-02 00:00:00 ┆ +32974-01-22 00:00:00 │
# │ 2001-01-03 00:00:00 ┆ +32976-10-18 00:00:00 │
# └─────────────────────┴───────────────────────┘

Parameters:

tu ("ns", "us", "ms") —
Time unit for the Datetime Series.

Returns:

(Expr)



943
944
945

# File 'lib/polars/date_time_expr.rb', line 943

def with_time_unit(tu)
  Utils.wrap_expr(_rbexpr.dt_with_time_unit(tu))
end

#year ⇒ `Expr`

Extract year from underlying Date representation.

Applies to Date and Datetime columns.

Returns the year number in the calendar date.

Examples:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2002, 7, 1)
df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "180d")})
# =>
# shape: (4, 1)
# ┌─────────────────────┐
# │ date                │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 2001-01-01 00:00:00 │
# │ 2001-06-30 00:00:00 │
# │ 2001-12-27 00:00:00 │
# │ 2002-06-25 00:00:00 │
# └─────────────────────┘

df.select(Polars.col("date").dt.year)
# =>
# shape: (4, 1)
# ┌──────┐
# │ date │
# │ ---  │
# │ i32  │
# ╞══════╡
# │ 2001 │
# │ 2001 │
# │ 2001 │
# │ 2002 │
# └──────┘

Returns:

(Expr)



293
294
295

# File 'lib/polars/date_time_expr.rb', line 293

def year
  Utils.wrap_expr(_rbexpr.year)
end

Class: Polars::DateTimeExpr

Overview

Instance Method Summary collapse

Instance Method Details

#cast_time_unit(tu) ⇒ Expr

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

#convert_time_zone(tz) ⇒ Expr

#date ⇒ Expr

#datetime ⇒ Expr

#day ⇒ Expr

#epoch(tu = "us") ⇒ Expr

#hour ⇒ Expr

#is_leap_year ⇒ Expr

#iso_year ⇒ Expr

#microsecond ⇒ Expr

#millisecond ⇒ Expr

#minute ⇒ Expr

#month ⇒ Expr

#month_end ⇒ Expr

#month_start ⇒ Expr

#nanosecond ⇒ Expr

#offset_by(by) ⇒ Expr

#ordinal_day ⇒ Expr

#quarter ⇒ Expr

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

#round(every, offset: nil) ⇒ Expr

#second(fractional: false) ⇒ Expr

#strftime(fmt) ⇒ Expr

#time ⇒ Expr

#timestamp(tu = "us") ⇒ Expr

#total_days ⇒ Expr Also known as: days

#total_hours ⇒ Expr Also known as: hours

#total_microseconds ⇒ Expr Also known as: microseconds

#total_milliseconds ⇒ Expr Also known as: milliseconds

#total_minutes ⇒ Expr Also known as: minutes

#total_nanoseconds ⇒ Expr Also known as: nanoseconds

#total_seconds ⇒ Expr Also known as: seconds

#truncate(every, offset: nil, use_earliest: nil) ⇒ Expr

#week ⇒ Expr

#weekday ⇒ Expr

#with_time_unit(tu) ⇒ Expr

#year ⇒ Expr

#cast_time_unit(tu) ⇒ `Expr`

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

#convert_time_zone(tz) ⇒ `Expr`

#date ⇒ `Expr`

#datetime ⇒ `Expr`

#day ⇒ `Expr`

#epoch(tu = "us") ⇒ `Expr`

#hour ⇒ `Expr`

#is_leap_year ⇒ `Expr`

#iso_year ⇒ `Expr`

#microsecond ⇒ `Expr`

#millisecond ⇒ `Expr`

#minute ⇒ `Expr`

#month ⇒ `Expr`

#month_end ⇒ `Expr`

#month_start ⇒ `Expr`

#nanosecond ⇒ `Expr`

#offset_by(by) ⇒ `Expr`

#ordinal_day ⇒ `Expr`

#quarter ⇒ `Expr`

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

#round(every, offset: nil) ⇒ `Expr`

#second(fractional: false) ⇒ `Expr`

#strftime(fmt) ⇒ `Expr`

#time ⇒ `Expr`

#timestamp(tu = "us") ⇒ `Expr`

#total_days ⇒ `Expr` Also known as: days

#total_hours ⇒ `Expr` Also known as: hours

#total_microseconds ⇒ `Expr` Also known as: microseconds

#total_milliseconds ⇒ `Expr` Also known as: milliseconds

#total_minutes ⇒ `Expr` Also known as: minutes

#total_nanoseconds ⇒ `Expr` Also known as: nanoseconds

#total_seconds ⇒ `Expr` Also known as: seconds

#truncate(every, offset: nil, use_earliest: nil) ⇒ `Expr`

#week ⇒ `Expr`

#weekday ⇒ `Expr`

#with_time_unit(tu) ⇒ `Expr`

#year ⇒ `Expr`