polars-df 0.15.0 → 0.26.0

data/lib/polars/date_time_expr.rb

@@ -9,6 +9,109 @@ module Polars
       self._rbexpr = expr._rbexpr
     end
 
+    # Offset by `n` business days.
+    #
+    # @note
+    #   This functionality is considered **unstable**. It may be changed
+    #   at any point without it being considered a breaking change.
+    #
+    # @param n
+    #   Number of business days to offset by. Can be a single number of an
+    #   expression.
+    # @param week_mask
+    #   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]`.
+    # @param holidays [Object]
+    #   Holidays to exclude from the count.
+    # @param roll
+    #   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
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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 │
+    #   # └────────────┴────────────┘
+    #
+    # @example 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 │
+    #   # └────────────┴────────────┘
+    #
+    # @example 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 │
+    #   # └────────────┴────────────┘
+    #
+    # @example 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      │
+    #   # └────────────┴─────────────────┘
+    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
+
     # Divide the date/datetime range into buckets.
     #
     # Each date/datetime is mapped to the start of its bucket.
@@ -203,6 +306,93 @@ module Polars
       Utils.wrap_expr(_rbexpr.dt_round(every))
     end
 
+    # Replace time unit.
+    #
+    # @param year [Object]
+    #   Column or literal.
+    # @param month [Object]
+    #   Column or literal, ranging from 1-12.
+    # @param day [Object]
+    #   Column or literal, ranging from 1-31.
+    # @param hour [Object]
+    #   Column or literal, ranging from 0-23.
+    # @param minute [Object]
+    #   Column or literal, ranging from 0-59.
+    # @param second [Object]
+    #   Column or literal, ranging from 0-59.
+    # @param microsecond [Object]
+    #   Column or literal, ranging from 0-999999.
+    # @param ambiguous [String]
+    #   Determine how to deal with ambiguous datetimes:
+    #
+    #   - `'raise'` (default): raise
+    #   - `'earliest'`: use the earliest datetime
+    #   - `'latest'`: use the latest datetime
+    #   - `'null'`: set to null
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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 │
+    #   # └────────────┴─────────┴────────────┘
+    #
+    # @example
+    #   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 │
+    #   # └────────────┴─────────┴────────────┘
+    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
+
     # 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,
@@ -215,7 +405,7 @@ module Polars
     #
     # @return [Expr]
     def combine(time, time_unit: "us")
-      unless time.is_a?(Time) || time.is_a?(Expr)
+      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)
@@ -260,13 +450,21 @@ module Polars
     #   # │ 2020-04-01 00:00:00 ┆ 2020/04/01 00:00:00 │
     #   # │ 2020-05-01 00:00:00 ┆ 2020/05/01 00:00:00 │
     #   # └─────────────────────┴─────────────────────┘
-    def to_string(format)
+    def to_string(format = nil)
+      if format.nil?
+        format = "iso"
+      end
       Utils.wrap_expr(_rbexpr.dt_to_string(format))
     end
 
-    # Format Date/datetime with a formatting rule.
+    # 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.
     #
-    # See [chrono strftime/strptime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html).
+    # @param format [String]
+    #   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"`.
     #
     # @return [Expr]
     #
@@ -313,8 +511,84 @@ module Polars
     #   # │ 2020-04-01 00:00:00 ┆ Wednesday ┆ April      │
     #   # │ 2020-05-01 00:00:00 ┆ Friday    ┆ May        │
     #   # └─────────────────────┴───────────┴────────────┘
-    def strftime(fmt)
-      Utils.wrap_expr(_rbexpr.strftime(fmt))
+    def strftime(format)
+      Utils.wrap_expr(_rbexpr.strftime(format))
+    end
+
+    # Extract the millennium from underlying representation.
+    #
+    # Applies to Date and Datetime columns.
+    #
+    # Returns the millennium number in the calendar date.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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    │
+    #   # └────────────┴──────┘
+    def millennium
+      Utils.wrap_expr(_rbexpr.dt_millennium)
+    end
+
+    # Extract the century from underlying representation.
+    #
+    # Applies to Date and Datetime columns.
+    #
+    # Returns the century number in the calendar date.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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   │
+    #   # └────────────┴──────┘
+    def century
+      Utils.wrap_expr(_rbexpr.dt_century)
     end
 
     # Extract year from underlying Date representation.
@@ -348,6 +622,79 @@ module Polars
       Utils.wrap_expr(_rbexpr.dt_year)
     end
 
+    # Determine whether each day lands on a business day.
+    #
+    # @note
+    #   This functionality is considered **unstable**. It may be changed
+    #   at any point without it being considered a breaking change.
+    #
+    # @param week_mask [Array]
+    #   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]`.
+    # @param holidays [Object]
+    #   Holidays to exclude from the count.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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           │
+    #   # └────────────┴─────────────────┘
+    #
+    # @example 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           │
+    #   # └────────────┴─────────────────┘
+    #
+    # @example 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           │
+    #   # └────────────┴─────────────────┘
+    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
+
     # Determine whether the year of the underlying date is a leap year.
     #
     # Applies to Date and Datetime columns.
@@ -466,6 +813,35 @@ module Polars
       Utils.wrap_expr(_rbexpr.dt_month)
     end
 
+    # 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.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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            │
+    #   # └────────────┴───────────────┘
+    def days_in_month
+      Utils.wrap_expr(_rbexpr.dt_days_in_month)
+    end
+
     # Extract the week from the underlying Date representation.
     #
     # Applies to Date and Datetime columns.
@@ -645,13 +1021,6 @@ module Polars
       Utils.wrap_expr(_rbexpr.dt_date)
     end
 
-    # Datetime
-    #
-    # @return [Expr]
-    def datetime
-      Utils.wrap_expr(_rbexpr.dt_datetime)
-    end
-
     # Extract hour from underlying DateTime representation.
     #
     # Applies to Datetime columns.
@@ -937,9 +1306,9 @@ module Polars
       if Utils::DTYPE_TEMPORAL_UNITS.include?(time_unit)
         timestamp(time_unit)
       elsif time_unit == "s"
-        Utils.wrap_expr(_rbexpr.dt_epoch_seconds)
+        timestamp("ms").floordiv(F.lit(1000, dtype: Int64))
       elsif time_unit == "d"
-        Utils.wrap_expr(_rbexpr).cast(:date).cast(:i32)
+        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
@@ -977,47 +1346,6 @@ module Polars
       Utils.wrap_expr(_rbexpr.dt_timestamp(time_unit))
     end
 
-    # 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.
-    #
-    # @param time_unit ["ns", "us", "ms"]
-    #   Time unit for the `Datetime` Series.
-    #
-    # @return [Expr]
-    #
-    # @example
-    #   df = Polars::DataFrame.new(
-    #     {
-    #       "date" => Polars.datetime_range(
-    #         Time.utc(2001, 1, 1),
-    #         Time.utc(2001, 1, 3),
-    #         "1d",
-    #         time_unit: "ns",
-    #         eager: true
-    #       )
-    #     }
-    #   )
-    #   df.select(
-    #     Polars.col("date"),
-    #     Polars.col("date").dt.with_time_unit("us").alias("time_unit_us")
-    #   )
-    #   # =>
-    #   # shape: (3, 2)
-    #   # ┌─────────────────────┬───────────────────────┐
-    #   # │ date                ┆ time_unit_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 │
-    #   # └─────────────────────┴───────────────────────┘
-    def with_time_unit(time_unit)
-      Utils.wrap_expr(_rbexpr.dt_with_time_unit(time_unit))
-    end
-
     # Cast the underlying data to another time unit. This may lose precision.
     #
     # @param time_unit ["ns", "us", "ms"]
@@ -1184,6 +1512,9 @@ module Polars
 
     # Extract the days from a Duration type.
     #
+    # @param fractional [Boolean]
+    #   Whether to include the fractional component of the second.
+    #
     # @return [Expr]
     #
     # @example
@@ -1197,7 +1528,7 @@ module Polars
     #   df.select(
     #     [
     #       Polars.col("date"),
-    #       Polars.col("date").diff.dt.days.alias("days_diff")
+    #       Polars.col("date").diff.dt.total_days.alias("days_diff")
     #     ]
     #   )
     #   # =>
@@ -1211,13 +1542,15 @@ module Polars
     #   # │ 2020-04-01 00:00:00 ┆ 31        │
     #   # │ 2020-05-01 00:00:00 ┆ 30        │
     #   # └─────────────────────┴───────────┘
-    def total_days
-      Utils.wrap_expr(_rbexpr.dt_total_days)
+    def total_days(fractional: false)
+      Utils.wrap_expr(_rbexpr.dt_total_days(fractional))
     end
-    alias_method :days, :total_days
 
     # Extract the hours from a Duration type.
     #
+    # @param fractional [Boolean]
+    #   Whether to include the fractional component of the second.
+    #
     # @return [Expr]
     #
     # @example
@@ -1231,7 +1564,7 @@ module Polars
     #   df.select(
     #     [
     #       Polars.col("date"),
-    #       Polars.col("date").diff.dt.hours.alias("hours_diff")
+    #       Polars.col("date").diff.dt.total_hours.alias("hours_diff")
     #     ]
     #   )
     #   # =>
@@ -1246,13 +1579,15 @@ module Polars
     #   # │ 2020-01-03 00:00:00 ┆ 24         │
     #   # │ 2020-01-04 00:00:00 ┆ 24         │
     #   # └─────────────────────┴────────────┘
-    def total_hours
-      Utils.wrap_expr(_rbexpr.dt_total_hours)
+    def total_hours(fractional: false)
+      Utils.wrap_expr(_rbexpr.dt_total_hours(fractional))
     end
-    alias_method :hours, :total_hours
 
     # Extract the minutes from a Duration type.
     #
+    # @param fractional [Boolean]
+    #   Whether to include the fractional component of the second.
+    #
     # @return [Expr]
     #
     # @example
@@ -1266,7 +1601,7 @@ module Polars
     #   df.select(
     #     [
     #       Polars.col("date"),
-    #       Polars.col("date").diff.dt.minutes.alias("minutes_diff")
+    #       Polars.col("date").diff.dt.total_minutes.alias("minutes_diff")
     #     ]
     #   )
     #   # =>
@@ -1281,13 +1616,15 @@ module Polars
     #   # │ 2020-01-03 00:00:00 ┆ 1440         │
     #   # │ 2020-01-04 00:00:00 ┆ 1440         │
     #   # └─────────────────────┴──────────────┘
-    def total_minutes
-      Utils.wrap_expr(_rbexpr.dt_total_minutes)
+    def total_minutes(fractional: false)
+      Utils.wrap_expr(_rbexpr.dt_total_minutes(fractional))
     end
-    alias_method :minutes, :total_minutes
 
     # Extract the seconds from a Duration type.
     #
+    # @param fractional [Boolean]
+    #   Whether to include the fractional component of the second.
+    #
     # @return [Expr]
     #
     # @example
@@ -1301,7 +1638,7 @@ module Polars
     #   df.select(
     #     [
     #       Polars.col("date"),
-    #       Polars.col("date").diff.dt.seconds.alias("seconds_diff")
+    #       Polars.col("date").diff.dt.total_seconds.alias("seconds_diff")
     #     ]
     #   )
     #   # =>
@@ -1317,13 +1654,15 @@ module Polars
     #   # │ 2020-01-01 00:03:00 ┆ 60           │
     #   # │ 2020-01-01 00:04:00 ┆ 60           │
     #   # └─────────────────────┴──────────────┘
-    def total_seconds
-      Utils.wrap_expr(_rbexpr.dt_total_seconds)
+    def total_seconds(fractional: false)
+      Utils.wrap_expr(_rbexpr.dt_total_seconds(fractional))
     end
-    alias_method :seconds, :total_seconds
 
     # Extract the milliseconds from a Duration type.
     #
+    # @param fractional [Boolean]
+    #   Whether to include the fractional component of the second.
+    #
     # @return [Expr]
     #
     # @example
@@ -1337,7 +1676,7 @@ module Polars
     #   df.select(
     #     [
     #       Polars.col("date"),
-    #       Polars.col("date").diff.dt.milliseconds.alias("milliseconds_diff")
+    #       Polars.col("date").diff.dt.total_milliseconds.alias("milliseconds_diff")
     #     ]
     #   )
     #   # =>
@@ -1359,13 +1698,15 @@ module Polars
     #   # │ 2020-01-01 00:00:00.999 ┆ 1                 │
     #   # │ 2020-01-01 00:00:01     ┆ 1                 │
     #   # └─────────────────────────┴───────────────────┘
-    def total_milliseconds
-      Utils.wrap_expr(_rbexpr.dt_total_milliseconds)
+    def total_milliseconds(fractional: false)
+      Utils.wrap_expr(_rbexpr.dt_total_milliseconds(fractional))
     end
-    alias_method :milliseconds, :total_milliseconds
 
     # Extract the microseconds from a Duration type.
     #
+    # @param fractional [Boolean]
+    #   Whether to include the fractional component of the second.
+    #
     # @return [Expr]
     #
     # @example
@@ -1379,7 +1720,7 @@ module Polars
     #   df.select(
     #     [
     #       Polars.col("date"),
-    #       Polars.col("date").diff.dt.microseconds.alias("microseconds_diff")
+    #       Polars.col("date").diff.dt.total_microseconds.alias("microseconds_diff")
     #     ]
     #   )
     #   # =>
@@ -1401,13 +1742,15 @@ module Polars
     #   # │ 2020-01-01 00:00:00.999 ┆ 1000              │
     #   # │ 2020-01-01 00:00:01     ┆ 1000              │
     #   # └─────────────────────────┴───────────────────┘
-    def total_microseconds
-      Utils.wrap_expr(_rbexpr.dt_total_microseconds)
+    def total_microseconds(fractional: false)
+      Utils.wrap_expr(_rbexpr.dt_total_microseconds(fractional))
     end
-    alias_method :microseconds, :total_microseconds
 
     # Extract the nanoseconds from a Duration type.
     #
+    # @param fractional [Boolean]
+    #   Whether to include the fractional component of the second.
+    #
     # @return [Expr]
     #
     # @example
@@ -1421,7 +1764,7 @@ module Polars
     #   df.select(
     #     [
     #       Polars.col("date"),
-    #       Polars.col("date").diff.dt.nanoseconds.alias("nanoseconds_diff")
+    #       Polars.col("date").diff.dt.total_nanoseconds.alias("nanoseconds_diff")
     #     ]
     #   )
     #   # =>
@@ -1443,10 +1786,9 @@ module Polars
     #   # │ 2020-01-01 00:00:00.999 ┆ 1000000          │
     #   # │ 2020-01-01 00:00:01     ┆ 1000000          │
     #   # └─────────────────────────┴──────────────────┘
-    def total_nanoseconds
-      Utils.wrap_expr(_rbexpr.dt_total_nanoseconds)
+    def total_nanoseconds(fractional: false)
+      Utils.wrap_expr(_rbexpr.dt_total_nanoseconds(fractional))
     end
-    alias_method :nanoseconds, :total_nanoseconds
 
     # Offset this date by a relative time offset.
     #