polars-df 0.1.2 → 0.1.4

data/lib/polars/date_time_expr.rb

@@ -1,77 +1,878 @@
 module Polars
+  # Namespace for datetime related expressions.
   class DateTimeExpr
+    # @private
     attr_accessor :_rbexpr
 
+    # @private
     def initialize(expr)
       self._rbexpr = expr._rbexpr
     end
 
-    # def truncate
-    # end
+    # Divide the date/datetime range into buckets.
+    #
+    # Each date/datetime is mapped to the start of its bucket.
+    #
+    # @param every [String]
+    #   Every interval start and period length
+    # @param offset [String]
+    #   Offset the window
+    #
+    # @return [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
+    #
+    # @example
+    #   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 │
+    #   # └─────────────────────┘
+    #
+    # @example
+    #   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 │
+    #   # └─────────────────────┘
+    #
+    # @example
+    #   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 │
+    #   # └─────────────────────┴─────────────────────┘
+    def truncate(every, offset: nil)
+      if offset.nil?
+        offset = "0ns"
+      end
+
+      Utils.wrap_expr(
+        _rbexpr.dt_truncate(
+          Utils._timedelta_to_pl_duration(every),
+          Utils._timedelta_to_pl_duration(offset)
+        )
+      )
+    end
+
+    # 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.
+    #
+    # @param every [String]
+    #   Every interval start and period length
+    # @param offset [String]
+    #   Offset the window
+    #
+    # @return [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.
+    #
+    # @example
+    #   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 │
+    #   # └─────────────────────┘
+    #
+    # @example
+    #   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 │
+    #   # └─────────────────────┘
+    #
+    # @example
+    #   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 │
+    #   # └─────────────────────┴─────────────────────┘
+    def round(every, offset: nil)
+      if offset.nil?
+        offset = "0ns"
+      end
 
-    # def round
-    # end
+      Utils.wrap_expr(
+        _rbexpr.dt_round(
+          Utils._timedelta_to_pl_duration(every),
+          Utils._timedelta_to_pl_duration(offset)
+        )
+      )
+    end
 
+    # Format Date/datetime with a formatting rule.
+    #
+    # See [chrono strftime/strptime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html).
+    #
+    # @return [Expr]
     def strftime(fmt)
       Utils.wrap_expr(_rbexpr.strftime(fmt))
     end
 
+    # Extract year from underlying Date representation.
+    #
+    # Applies to Date and Datetime columns.
+    #
+    # Returns the year number in the calendar date.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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 │
+    #   # └─────────────────────┘
+    #
+    # @example
+    #   df.select(Polars.col("date").dt.year)
+    #   # =>
+    #   # shape: (4, 1)
+    #   # ┌──────┐
+    #   # │ date │
+    #   # │ ---  │
+    #   # │ i32  │
+    #   # ╞══════╡
+    #   # │ 2001 │
+    #   # ├╌╌╌╌╌╌┤
+    #   # │ 2001 │
+    #   # ├╌╌╌╌╌╌┤
+    #   # │ 2001 │
+    #   # ├╌╌╌╌╌╌┤
+    #   # │ 2002 │
+    #   # └──────┘
     def year
       Utils.wrap_expr(_rbexpr.year)
     end
 
+    # 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.
+    #
+    # @return [Expr]
     def iso_year
       Utils.wrap_expr(_rbexpr.iso_year)
     end
 
+    # Extract quarter from underlying Date representation.
+    #
+    # Applies to Date and Datetime columns.
+    #
+    # Returns the quarter ranging from 1 to 4.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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 │
+    #   # └─────────────────────┘
+    #
+    # @example
+    #   df.select(Polars.col("date").dt.quarter)
+    #   # =>
+    #   # shape: (3, 1)
+    #   # ┌──────┐
+    #   # │ date │
+    #   # │ ---  │
+    #   # │ u32  │
+    #   # ╞══════╡
+    #   # │ 1    │
+    #   # ├╌╌╌╌╌╌┤
+    #   # │ 2    │
+    #   # ├╌╌╌╌╌╌┤
+    #   # │ 4    │
+    #   # └──────┘
     def quarter
       Utils.wrap_expr(_rbexpr.quarter)
     end
 
+    # 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.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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 │
+    #   # └─────────────────────┘
+    #
+    # @example
+    #   df.select(Polars.col("date").dt.month)
+    #   # =>
+    #   # shape: (3, 1)
+    #   # ┌──────┐
+    #   # │ date │
+    #   # │ ---  │
+    #   # │ u32  │
+    #   # ╞══════╡
+    #   # │ 1    │
+    #   # ├╌╌╌╌╌╌┤
+    #   # │ 2    │
+    #   # ├╌╌╌╌╌╌┤
+    #   # │ 3    │
+    #   # └──────┘
     def month
       Utils.wrap_expr(_rbexpr.month)
     end
 
+    # 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.)
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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 │
+    #   # └─────────────────────┘
+    #
+    # @example
+    #   df.select(Polars.col("date").dt.week)
+    #   # =>
+    #   # shape: (3, 1)
+    #   # ┌──────┐
+    #   # │ date │
+    #   # │ ---  │
+    #   # │ u32  │
+    #   # ╞══════╡
+    #   # │ 1    │
+    #   # ├╌╌╌╌╌╌┤
+    #   # │ 5    │
+    #   # ├╌╌╌╌╌╌┤
+    #   # │ 9    │
+    #   # └──────┘
     def week
       Utils.wrap_expr(_rbexpr.week)
     end
 
+    # Extract the week day from the underlying Date representation.
+    #
+    # Applies to Date and Datetime columns.
+    #
+    # Returns the weekday number where monday = 0 and sunday = 6
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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 │
+    #   # └─────────────────────┘
+    #
+    # @example
+    #   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 │
+    #   # │ ---     ┆ ---          ┆ ---         │
+    #   # │ u32     ┆ u32          ┆ u32         │
+    #   # ╞═════════╪══════════════╪═════════════╡
+    #   # │ 0       ┆ 1            ┆ 1           │
+    #   # ├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┤
+    #   # │ 3       ┆ 4            ┆ 4           │
+    #   # ├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┤
+    #   # │ 6       ┆ 7            ┆ 7           │
+    #   # └─────────┴──────────────┴─────────────┘
     def weekday
       Utils.wrap_expr(_rbexpr.weekday)
     end
 
+    # 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.)
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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 │
+    #   # └─────────────────────┘
+    #
+    # @example
+    #   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 │
+    #   # │ ---     ┆ ---          ┆ ---         │
+    #   # │ u32     ┆ u32          ┆ u32         │
+    #   # ╞═════════╪══════════════╪═════════════╡
+    #   # │ 0       ┆ 1            ┆ 1           │
+    #   # ├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┤
+    #   # │ 3       ┆ 4            ┆ 4           │
+    #   # ├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┤
+    #   # │ 6       ┆ 7            ┆ 7           │
+    #   # └─────────┴──────────────┴─────────────┘
     def day
       Utils.wrap_expr(_rbexpr.day)
     end
 
+    # 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.)
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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 │
+    #   # └─────────────────────┘
+    #
+    # @example
+    #   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 │
+    #   # │ ---     ┆ ---          ┆ ---         │
+    #   # │ u32     ┆ u32          ┆ u32         │
+    #   # ╞═════════╪══════════════╪═════════════╡
+    #   # │ 0       ┆ 1            ┆ 1           │
+    #   # ├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┤
+    #   # │ 3       ┆ 4            ┆ 4           │
+    #   # ├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┤
+    #   # │ 6       ┆ 7            ┆ 7           │
+    #   # └─────────┴──────────────┴─────────────┘
     def ordinal_day
       Utils.wrap_expr(_rbexpr.ordinal_day)
     end
 
+    # Extract hour from underlying DateTime representation.
+    #
+    # Applies to Datetime columns.
+    #
+    # Returns the hour number from 0 to 23.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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 │
+    #   # └─────────────────────┘
+    #
+    # @example
+    #   df.select(Polars.col("date").dt.hour)
+    #   # =>
+    #   # shape: (3, 1)
+    #   # ┌──────┐
+    #   # │ date │
+    #   # │ ---  │
+    #   # │ u32  │
+    #   # ╞══════╡
+    #   # │ 0    │
+    #   # ├╌╌╌╌╌╌┤
+    #   # │ 12   │
+    #   # ├╌╌╌╌╌╌┤
+    #   # │ 0    │
+    #   # └──────┘
     def hour
       Utils.wrap_expr(_rbexpr.hour)
     end
 
+    # Extract minutes from underlying DateTime representation.
+    #
+    # Applies to Datetime columns.
+    #
+    # Returns the minute number from 0 to 59.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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 │
+    #   # └─────────────────────┘
+    #
+    # @example
+    #   df.select(Polars.col("date").dt.minute)
+    #   # =>
+    #   # shape: (3, 1)
+    #   # ┌──────┐
+    #   # │ date │
+    #   # │ ---  │
+    #   # │ u32  │
+    #   # ╞══════╡
+    #   # │ 0    │
+    #   # ├╌╌╌╌╌╌┤
+    #   # │ 2    │
+    #   # ├╌╌╌╌╌╌┤
+    #   # │ 4    │
+    #   # └──────┘
     def minute
       Utils.wrap_expr(_rbexpr.minute)
     end
 
-    def second
-      Utils.wrap_expr(_rbexpr.second)
+    # 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.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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 │
+    #   # └────────────────────────────┘
+    #
+    # @example
+    #   df.select(Polars.col("date").dt.second.alias("secs"))
+    #   # =>
+    #   # shape: (3, 1)
+    #   # ┌──────┐
+    #   # │ secs │
+    #   # │ ---  │
+    #   # │ u32  │
+    #   # ╞══════╡
+    #   # │ 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 │
+    #   # └──────────┘
+    #
+    # @example
+    #   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 │
+    #   # └─────────────────────┘
+    #
+    # @example
+    #   df.select(Polars.col("date").dt.second)
+    #   # =>
+    #   # shape: (3, 1)
+    #   # ┌──────┐
+    #   # │ date │
+    #   # │ ---  │
+    #   # │ u32  │
+    #   # ╞══════╡
+    #   # │ 0    │
+    #   # ├╌╌╌╌╌╌┤
+    #   # │ 2    │
+    #   # ├╌╌╌╌╌╌┤
+    #   # │ 4    │
+    #   # └──────┘
+    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
 
+    # Extract milliseconds from underlying DateTime representation.
+    #
+    # Applies to Datetime columns.
+    #
+    # @return [Expr]
     def millisecond
       Utils.wrap_expr(_rbexpr.millisecond)
     end
 
+    # Extract microseconds from underlying DateTime representation.
+    #
+    # Applies to Datetime columns.
+    #
+    # @return [Expr]
     def microsecond
       Utils.wrap_expr(_rbexpr.microsecond)
     end
 
+    # Extract nanoseconds from underlying DateTime representation.
+    #
+    # Applies to Datetime columns.
+    #
+    # @return [Expr]
     def nanosecond
       Utils.wrap_expr(_rbexpr.nanosecond)
     end
 
+    # Get the time passed since the Unix EPOCH in the give time unit.
+    #
+    # @param tu ["us", "ns", "ms", "s", "d"]
+    #   Time unit.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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 │
+    #   # └─────────────────────┴─────────────────┴───────────┘
     def epoch(tu = "us")
       if Utils::DTYPE_TEMPORAL_UNITS.include?(tu)
         timestamp(tu)
@@ -80,62 +881,536 @@ module Polars
       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}"
+        raise ArgumentError, "tu must be one of {{'ns', 'us', 'ms', 's', 'd'}}, got #{tu}"
       end
     end
 
+    # Return a timestamp in the given time unit.
+    #
+    # @param tu ["us", "ns", "ms"]
+    #   Time unit.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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 │
+    #   # └─────────────────────┴─────────────────┴──────────────┘
     def timestamp(tu = "us")
       Utils.wrap_expr(_rbexpr.timestamp(tu))
     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 tu ["ns", "us", "ms"]
+    #   Time unit for the `Datetime` Series.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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 │
+    #   # └─────────────────────┴───────────────────────┘
     def with_time_unit(tu)
       Utils.wrap_expr(_rbexpr.dt_with_time_unit(tu))
     end
 
+    # Cast the underlying data to another time unit. This may lose precision.
+    #
+    # @param tu ["ns", "us", "ms"]
+    #   Time unit for the `Datetime` Series.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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 │
+    #   # └─────────────────────┴─────────────────────┴─────────────────────┘
     def cast_time_unit(tu)
       Utils.wrap_expr(_rbexpr.dt_cast_time_unit(tu))
     end
 
+    # Set time zone for a Series of type Datetime.
+    #
+    # @param tz [String]
+    #   Time zone for the `Datetime` Series.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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")
+    #         .dt.with_time_zone("Europe/London")
+    #         .alias("London")
+    #     ]
+    #   )
+    #   # =>
+    #   # shape: (3, 2)
+    #   # ┌─────────────────────┬─────────────────────────────┐
+    #   # │ date                ┆ London                      │
+    #   # │ ---                 ┆ ---                         │
+    #   # │ datetime[μs]        ┆ datetime[μs, Europe/London] │
+    #   # ╞═════════════════════╪═════════════════════════════╡
+    #   # │ 2020-03-01 00:00:00 ┆ 2020-03-01 00:00:00 GMT     │
+    #   # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
+    #   # │ 2020-04-01 00:00:00 ┆ 2020-04-01 01:00:00 BST     │
+    #   # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
+    #   # │ 2020-05-01 00:00:00 ┆ 2020-05-01 01:00:00 BST     │
+    #   # └─────────────────────┴─────────────────────────────┘
     def with_time_zone(tz)
       Utils.wrap_expr(_rbexpr.dt_with_time_zone(tz))
     end
 
+    # Cast time zone for a Series of type Datetime.
+    #
+    # Different from `with_time_zone`, this will also modify
+    # the underlying timestamp,
+    #
+    # @param tz [String]
+    #   Time zone for the `Datetime` Series.
+    #
+    # @return [Expr]
     def cast_time_zone(tz)
       Utils.wrap_expr(_rbexpr.dt_cast_time_zone(tz))
     end
 
+    # Localize tz-naive Datetime Series to tz-aware Datetime Series.
+    #
+    # This method takes a naive Datetime Series and makes this time zone aware.
+    # It does not move the time to another time zone.
+    #
+    # @param tz [String]
+    #   Time zone for the `Datetime` Series.
+    #
+    # @return [Expr]
     def tz_localize(tz)
       Utils.wrap_expr(_rbexpr.dt_tz_localize(tz))
     end
 
+    # Extract the days from a Duration type.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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        │
+    #   # └─────────────────────┴───────────┘
     def days
       Utils.wrap_expr(_rbexpr.duration_days)
     end
 
+    # Extract the hours from a Duration type.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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         │
+    #   # └─────────────────────┴────────────┘
     def hours
       Utils.wrap_expr(_rbexpr.duration_hours)
     end
 
+    # Extract the minutes from a Duration type.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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         │
+    #   # └─────────────────────┴──────────────┘
     def minutes
       Utils.wrap_expr(_rbexpr.duration_minutes)
     end
 
+    # Extract the seconds from a Duration type.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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           │
+    #   # └─────────────────────┴──────────────┘
     def seconds
       Utils.wrap_expr(_rbexpr.duration_seconds)
     end
 
+    # Extract the milliseconds from a Duration type.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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: (1001, 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.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                 │
+    #   # └─────────────────────────┴───────────────────┘
     def milliseconds
       Utils.wrap_expr(_rbexpr.duration_milliseconds)
     end
 
+    # Extract the microseconds from a Duration type.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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: (1001, 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.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              │
+    #   # └─────────────────────────┴───────────────────┘
     def microseconds
       Utils.wrap_expr(_rbexpr.duration_microseconds)
     end
 
+    # Extract the nanoseconds from a Duration type.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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: (1001, 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.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          │
+    #   # └─────────────────────────┴──────────────────┘
     def nanoseconds
       Utils.wrap_expr(_rbexpr.duration_nanoseconds)
     end
 
+    # 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.
+    #
+    # @param 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)
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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 │
+    #   # └─────────────────────┴─────────────────────┘
     def offset_by(by)
       Utils.wrap_expr(_rbexpr.dt_offset_by(by))
     end