polars-df 0.2.0-arm64-darwin

Sign up to get free protection for your applications and to get access to all the features.
Files changed (46) hide show
  1. checksums.yaml +7 -0
  2. data/.yardopts +3 -0
  3. data/CHANGELOG.md +33 -0
  4. data/Cargo.lock +2230 -0
  5. data/Cargo.toml +10 -0
  6. data/LICENSE-THIRD-PARTY.txt +38856 -0
  7. data/LICENSE.txt +20 -0
  8. data/README.md +91 -0
  9. data/lib/polars/3.0/polars.bundle +0 -0
  10. data/lib/polars/3.1/polars.bundle +0 -0
  11. data/lib/polars/3.2/polars.bundle +0 -0
  12. data/lib/polars/batched_csv_reader.rb +96 -0
  13. data/lib/polars/cat_expr.rb +52 -0
  14. data/lib/polars/cat_name_space.rb +54 -0
  15. data/lib/polars/convert.rb +100 -0
  16. data/lib/polars/data_frame.rb +4833 -0
  17. data/lib/polars/data_types.rb +122 -0
  18. data/lib/polars/date_time_expr.rb +1418 -0
  19. data/lib/polars/date_time_name_space.rb +1484 -0
  20. data/lib/polars/dynamic_group_by.rb +52 -0
  21. data/lib/polars/exceptions.rb +20 -0
  22. data/lib/polars/expr.rb +5307 -0
  23. data/lib/polars/expr_dispatch.rb +22 -0
  24. data/lib/polars/functions.rb +453 -0
  25. data/lib/polars/group_by.rb +558 -0
  26. data/lib/polars/io.rb +814 -0
  27. data/lib/polars/lazy_frame.rb +2442 -0
  28. data/lib/polars/lazy_functions.rb +1195 -0
  29. data/lib/polars/lazy_group_by.rb +93 -0
  30. data/lib/polars/list_expr.rb +610 -0
  31. data/lib/polars/list_name_space.rb +346 -0
  32. data/lib/polars/meta_expr.rb +54 -0
  33. data/lib/polars/rolling_group_by.rb +35 -0
  34. data/lib/polars/series.rb +3730 -0
  35. data/lib/polars/slice.rb +104 -0
  36. data/lib/polars/string_expr.rb +972 -0
  37. data/lib/polars/string_name_space.rb +690 -0
  38. data/lib/polars/struct_expr.rb +100 -0
  39. data/lib/polars/struct_name_space.rb +64 -0
  40. data/lib/polars/utils.rb +192 -0
  41. data/lib/polars/version.rb +4 -0
  42. data/lib/polars/when.rb +16 -0
  43. data/lib/polars/when_then.rb +19 -0
  44. data/lib/polars-df.rb +1 -0
  45. data/lib/polars.rb +50 -0
  46. metadata +89 -0
@@ -0,0 +1,1418 @@
1
+ module Polars
2
+ # Namespace for datetime related expressions.
3
+ class DateTimeExpr
4
+ # @private
5
+ attr_accessor :_rbexpr
6
+
7
+ # @private
8
+ def initialize(expr)
9
+ self._rbexpr = expr._rbexpr
10
+ end
11
+
12
+ # Divide the date/datetime range into buckets.
13
+ #
14
+ # Each date/datetime is mapped to the start of its bucket.
15
+ #
16
+ # @param every [String]
17
+ # Every interval start and period length
18
+ # @param offset [String]
19
+ # Offset the window
20
+ #
21
+ # @return [Expr]
22
+ #
23
+ # @note
24
+ # The `every` and `offset` argument are created with the
25
+ # the following small string formatting language:
26
+ #
27
+ # 1ns # 1 nanosecond
28
+ # 1us # 1 microsecond
29
+ # 1ms # 1 millisecond
30
+ # 1s # 1 second
31
+ # 1m # 1 minute
32
+ # 1h # 1 hour
33
+ # 1d # 1 day
34
+ # 1w # 1 week
35
+ # 1mo # 1 calendar month
36
+ # 1y # 1 calendar year
37
+ #
38
+ # eg: 3d12h4m25s # 3 days, 12 hours, 4 minutes, and 25 seconds
39
+ #
40
+ # @example
41
+ # start = DateTime.new(2001, 1, 1)
42
+ # stop = DateTime.new(2001, 1, 2)
43
+ # df = Polars.date_range(
44
+ # start, stop, "225m", name: "dates"
45
+ # ).to_frame
46
+ # # =>
47
+ # # shape: (7, 1)
48
+ # # ┌─────────────────────┐
49
+ # # │ dates │
50
+ # # │ --- │
51
+ # # │ datetime[μs] │
52
+ # # ╞═════════════════════╡
53
+ # # │ 2001-01-01 00:00:00 │
54
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
55
+ # # │ 2001-01-01 03:45:00 │
56
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
57
+ # # │ 2001-01-01 07:30:00 │
58
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
59
+ # # │ 2001-01-01 11:15:00 │
60
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
61
+ # # │ 2001-01-01 15:00:00 │
62
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
63
+ # # │ 2001-01-01 18:45:00 │
64
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
65
+ # # │ 2001-01-01 22:30:00 │
66
+ # # └─────────────────────┘
67
+ #
68
+ # @example
69
+ # df.select(Polars.col("dates").dt.truncate("1h"))
70
+ # # =>
71
+ # # shape: (7, 1)
72
+ # # ┌─────────────────────┐
73
+ # # │ dates │
74
+ # # │ --- │
75
+ # # │ datetime[μs] │
76
+ # # ╞═════════════════════╡
77
+ # # │ 2001-01-01 00:00:00 │
78
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
79
+ # # │ 2001-01-01 03:00:00 │
80
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
81
+ # # │ 2001-01-01 07:00:00 │
82
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
83
+ # # │ 2001-01-01 11:00:00 │
84
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
85
+ # # │ 2001-01-01 15:00:00 │
86
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
87
+ # # │ 2001-01-01 18:00:00 │
88
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
89
+ # # │ 2001-01-01 22:00:00 │
90
+ # # └─────────────────────┘
91
+ #
92
+ # @example
93
+ # start = DateTime.new(2001, 1, 1)
94
+ # stop = DateTime.new(2001, 1, 1, 1)
95
+ # df = Polars.date_range(start, stop, "10m", name: "dates").to_frame
96
+ # df.select(["dates", Polars.col("dates").dt.truncate("30m").alias("truncate")])
97
+ # # =>
98
+ # # shape: (7, 2)
99
+ # # ┌─────────────────────┬─────────────────────┐
100
+ # # │ dates ┆ truncate │
101
+ # # │ --- ┆ --- │
102
+ # # │ datetime[μs] ┆ datetime[μs] │
103
+ # # ╞═════════════════════╪═════════════════════╡
104
+ # # │ 2001-01-01 00:00:00 ┆ 2001-01-01 00:00:00 │
105
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
106
+ # # │ 2001-01-01 00:10:00 ┆ 2001-01-01 00:00:00 │
107
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
108
+ # # │ 2001-01-01 00:20:00 ┆ 2001-01-01 00:00:00 │
109
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
110
+ # # │ 2001-01-01 00:30:00 ┆ 2001-01-01 00:30:00 │
111
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
112
+ # # │ 2001-01-01 00:40:00 ┆ 2001-01-01 00:30:00 │
113
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
114
+ # # │ 2001-01-01 00:50:00 ┆ 2001-01-01 00:30:00 │
115
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
116
+ # # │ 2001-01-01 01:00:00 ┆ 2001-01-01 01:00:00 │
117
+ # # └─────────────────────┴─────────────────────┘
118
+ def truncate(every, offset: nil)
119
+ if offset.nil?
120
+ offset = "0ns"
121
+ end
122
+
123
+ Utils.wrap_expr(
124
+ _rbexpr.dt_truncate(
125
+ Utils._timedelta_to_pl_duration(every),
126
+ Utils._timedelta_to_pl_duration(offset)
127
+ )
128
+ )
129
+ end
130
+
131
+ # Divide the date/datetime range into buckets.
132
+ #
133
+ # Each date/datetime in the first half of the interval
134
+ # is mapped to the start of its bucket.
135
+ # Each date/datetime in the seconod half of the interval
136
+ # is mapped to the end of its bucket.
137
+ #
138
+ # @param every [String]
139
+ # Every interval start and period length
140
+ # @param offset [String]
141
+ # Offset the window
142
+ #
143
+ # @return [Expr]
144
+ #
145
+ # @note
146
+ # The `every` and `offset` argument are created with the
147
+ # the following small string formatting language:
148
+ #
149
+ # 1ns # 1 nanosecond
150
+ # 1us # 1 microsecond
151
+ # 1ms # 1 millisecond
152
+ # 1s # 1 second
153
+ # 1m # 1 minute
154
+ # 1h # 1 hour
155
+ # 1d # 1 day
156
+ # 1w # 1 week
157
+ # 1mo # 1 calendar month
158
+ # 1y # 1 calendar year
159
+ #
160
+ # eg: 3d12h4m25s # 3 days, 12 hours, 4 minutes, and 25 seconds
161
+ #
162
+ # @note
163
+ # This functionality is currently experimental and may
164
+ # change without it being considered a breaking change.
165
+ #
166
+ # @example
167
+ # start = DateTime.new(2001, 1, 1)
168
+ # stop = DateTime.new(2001, 1, 2)
169
+ # df = Polars.date_range(
170
+ # start, stop, "225m", name: "dates"
171
+ # ).to_frame
172
+ # # =>
173
+ # # shape: (7, 1)
174
+ # # ┌─────────────────────┐
175
+ # # │ dates │
176
+ # # │ --- │
177
+ # # │ datetime[μs] │
178
+ # # ╞═════════════════════╡
179
+ # # │ 2001-01-01 00:00:00 │
180
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
181
+ # # │ 2001-01-01 03:45:00 │
182
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
183
+ # # │ 2001-01-01 07:30:00 │
184
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
185
+ # # │ 2001-01-01 11:15:00 │
186
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
187
+ # # │ 2001-01-01 15:00:00 │
188
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
189
+ # # │ 2001-01-01 18:45:00 │
190
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
191
+ # # │ 2001-01-01 22:30:00 │
192
+ # # └─────────────────────┘
193
+ #
194
+ # @example
195
+ # df.select(Polars.col("dates").dt.round("1h"))
196
+ # # =>
197
+ # # shape: (7, 1)
198
+ # # ┌─────────────────────┐
199
+ # # │ dates │
200
+ # # │ --- │
201
+ # # │ datetime[μs] │
202
+ # # ╞═════════════════════╡
203
+ # # │ 2001-01-01 00:00:00 │
204
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
205
+ # # │ 2001-01-01 04:00:00 │
206
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
207
+ # # │ 2001-01-01 08:00:00 │
208
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
209
+ # # │ 2001-01-01 11:00:00 │
210
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
211
+ # # │ 2001-01-01 15:00:00 │
212
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
213
+ # # │ 2001-01-01 19:00:00 │
214
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
215
+ # # │ 2001-01-01 23:00:00 │
216
+ # # └─────────────────────┘
217
+ #
218
+ # @example
219
+ # start = DateTime.new(2001, 1, 1)
220
+ # stop = DateTime.new(2001, 1, 1, 1)
221
+ # df = Polars.date_range(start, stop, "10m", name: "dates").to_frame
222
+ # df.select(["dates", Polars.col("dates").dt.round("30m").alias("round")])
223
+ # # =>
224
+ # # shape: (7, 2)
225
+ # # ┌─────────────────────┬─────────────────────┐
226
+ # # │ dates ┆ round │
227
+ # # │ --- ┆ --- │
228
+ # # │ datetime[μs] ┆ datetime[μs] │
229
+ # # ╞═════════════════════╪═════════════════════╡
230
+ # # │ 2001-01-01 00:00:00 ┆ 2001-01-01 00:00:00 │
231
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
232
+ # # │ 2001-01-01 00:10:00 ┆ 2001-01-01 00:00:00 │
233
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
234
+ # # │ 2001-01-01 00:20:00 ┆ 2001-01-01 00:30:00 │
235
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
236
+ # # │ 2001-01-01 00:30:00 ┆ 2001-01-01 00:30:00 │
237
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
238
+ # # │ 2001-01-01 00:40:00 ┆ 2001-01-01 00:30:00 │
239
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
240
+ # # │ 2001-01-01 00:50:00 ┆ 2001-01-01 01:00:00 │
241
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
242
+ # # │ 2001-01-01 01:00:00 ┆ 2001-01-01 01:00:00 │
243
+ # # └─────────────────────┴─────────────────────┘
244
+ def round(every, offset: nil)
245
+ if offset.nil?
246
+ offset = "0ns"
247
+ end
248
+
249
+ Utils.wrap_expr(
250
+ _rbexpr.dt_round(
251
+ Utils._timedelta_to_pl_duration(every),
252
+ Utils._timedelta_to_pl_duration(offset)
253
+ )
254
+ )
255
+ end
256
+
257
+ # Format Date/datetime with a formatting rule.
258
+ #
259
+ # See [chrono strftime/strptime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html).
260
+ #
261
+ # @return [Expr]
262
+ def strftime(fmt)
263
+ Utils.wrap_expr(_rbexpr.strftime(fmt))
264
+ end
265
+
266
+ # Extract year from underlying Date representation.
267
+ #
268
+ # Applies to Date and Datetime columns.
269
+ #
270
+ # Returns the year number in the calendar date.
271
+ #
272
+ # @return [Expr]
273
+ #
274
+ # @example
275
+ # start = DateTime.new(2001, 1, 1)
276
+ # stop = DateTime.new(2002, 7, 1)
277
+ # df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "180d")})
278
+ # # =>
279
+ # # shape: (4, 1)
280
+ # # ┌─────────────────────┐
281
+ # # │ date │
282
+ # # │ --- │
283
+ # # │ datetime[μs] │
284
+ # # ╞═════════════════════╡
285
+ # # │ 2001-01-01 00:00:00 │
286
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
287
+ # # │ 2001-06-30 00:00:00 │
288
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
289
+ # # │ 2001-12-27 00:00:00 │
290
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
291
+ # # │ 2002-06-25 00:00:00 │
292
+ # # └─────────────────────┘
293
+ #
294
+ # @example
295
+ # df.select(Polars.col("date").dt.year)
296
+ # # =>
297
+ # # shape: (4, 1)
298
+ # # ┌──────┐
299
+ # # │ date │
300
+ # # │ --- │
301
+ # # │ i32 │
302
+ # # ╞══════╡
303
+ # # │ 2001 │
304
+ # # ├╌╌╌╌╌╌┤
305
+ # # │ 2001 │
306
+ # # ├╌╌╌╌╌╌┤
307
+ # # │ 2001 │
308
+ # # ├╌╌╌╌╌╌┤
309
+ # # │ 2002 │
310
+ # # └──────┘
311
+ def year
312
+ Utils.wrap_expr(_rbexpr.year)
313
+ end
314
+
315
+ # Extract ISO year from underlying Date representation.
316
+ #
317
+ # Applies to Date and Datetime columns.
318
+ #
319
+ # Returns the year number in the ISO standard.
320
+ # This may not correspond with the calendar year.
321
+ #
322
+ # @return [Expr]
323
+ def iso_year
324
+ Utils.wrap_expr(_rbexpr.iso_year)
325
+ end
326
+
327
+ # Extract quarter from underlying Date representation.
328
+ #
329
+ # Applies to Date and Datetime columns.
330
+ #
331
+ # Returns the quarter ranging from 1 to 4.
332
+ #
333
+ # @return [Expr]
334
+ #
335
+ # @example
336
+ # start = DateTime.new(2001, 1, 1)
337
+ # stop = DateTime.new(2002, 6, 1)
338
+ # df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "180d")})
339
+ # # =>
340
+ # # shape: (3, 1)
341
+ # # ┌─────────────────────┐
342
+ # # │ date │
343
+ # # │ --- │
344
+ # # │ datetime[μs] │
345
+ # # ╞═════════════════════╡
346
+ # # │ 2001-01-01 00:00:00 │
347
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
348
+ # # │ 2001-06-30 00:00:00 │
349
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
350
+ # # │ 2001-12-27 00:00:00 │
351
+ # # └─────────────────────┘
352
+ #
353
+ # @example
354
+ # df.select(Polars.col("date").dt.quarter)
355
+ # # =>
356
+ # # shape: (3, 1)
357
+ # # ┌──────┐
358
+ # # │ date │
359
+ # # │ --- │
360
+ # # │ u32 │
361
+ # # ╞══════╡
362
+ # # │ 1 │
363
+ # # ├╌╌╌╌╌╌┤
364
+ # # │ 2 │
365
+ # # ├╌╌╌╌╌╌┤
366
+ # # │ 4 │
367
+ # # └──────┘
368
+ def quarter
369
+ Utils.wrap_expr(_rbexpr.quarter)
370
+ end
371
+
372
+ # Extract month from underlying Date representation.
373
+ #
374
+ # Applies to Date and Datetime columns.
375
+ #
376
+ # Returns the month number starting from 1.
377
+ # The return value ranges from 1 to 12.
378
+ #
379
+ # @return [Expr]
380
+ #
381
+ # @example
382
+ # start = DateTime.new(2001, 1, 1)
383
+ # stop = DateTime.new(2001, 4, 1)
384
+ # df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "31d")})
385
+ # # =>
386
+ # # shape: (3, 1)
387
+ # # ┌─────────────────────┐
388
+ # # │ date │
389
+ # # │ --- │
390
+ # # │ datetime[μs] │
391
+ # # ╞═════════════════════╡
392
+ # # │ 2001-01-01 00:00:00 │
393
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
394
+ # # │ 2001-02-01 00:00:00 │
395
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
396
+ # # │ 2001-03-04 00:00:00 │
397
+ # # └─────────────────────┘
398
+ #
399
+ # @example
400
+ # df.select(Polars.col("date").dt.month)
401
+ # # =>
402
+ # # shape: (3, 1)
403
+ # # ┌──────┐
404
+ # # │ date │
405
+ # # │ --- │
406
+ # # │ u32 │
407
+ # # ╞══════╡
408
+ # # │ 1 │
409
+ # # ├╌╌╌╌╌╌┤
410
+ # # │ 2 │
411
+ # # ├╌╌╌╌╌╌┤
412
+ # # │ 3 │
413
+ # # └──────┘
414
+ def month
415
+ Utils.wrap_expr(_rbexpr.month)
416
+ end
417
+
418
+ # Extract the week from the underlying Date representation.
419
+ #
420
+ # Applies to Date and Datetime columns.
421
+ #
422
+ # Returns the ISO week number starting from 1.
423
+ # The return value ranges from 1 to 53. (The last week of year differs by years.)
424
+ #
425
+ # @return [Expr]
426
+ #
427
+ # @example
428
+ # start = DateTime.new(2001, 1, 1)
429
+ # stop = DateTime.new(2001, 4, 1)
430
+ # df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "31d")})
431
+ # # =>
432
+ # # shape: (3, 1)
433
+ # # ┌─────────────────────┐
434
+ # # │ date │
435
+ # # │ --- │
436
+ # # │ datetime[μs] │
437
+ # # ╞═════════════════════╡
438
+ # # │ 2001-01-01 00:00:00 │
439
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
440
+ # # │ 2001-02-01 00:00:00 │
441
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
442
+ # # │ 2001-03-04 00:00:00 │
443
+ # # └─────────────────────┘
444
+ #
445
+ # @example
446
+ # df.select(Polars.col("date").dt.week)
447
+ # # =>
448
+ # # shape: (3, 1)
449
+ # # ┌──────┐
450
+ # # │ date │
451
+ # # │ --- │
452
+ # # │ u32 │
453
+ # # ╞══════╡
454
+ # # │ 1 │
455
+ # # ├╌╌╌╌╌╌┤
456
+ # # │ 5 │
457
+ # # ├╌╌╌╌╌╌┤
458
+ # # │ 9 │
459
+ # # └──────┘
460
+ def week
461
+ Utils.wrap_expr(_rbexpr.week)
462
+ end
463
+
464
+ # Extract the week day from the underlying Date representation.
465
+ #
466
+ # Applies to Date and Datetime columns.
467
+ #
468
+ # Returns the ISO weekday number where monday = 1 and sunday = 7
469
+ #
470
+ # @return [Expr]
471
+ #
472
+ # @example
473
+ # start = DateTime.new(2001, 1, 1)
474
+ # stop = DateTime.new(2001, 1, 9)
475
+ # df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "3d")})
476
+ # # =>
477
+ # # shape: (3, 1)
478
+ # # ┌─────────────────────┐
479
+ # # │ date │
480
+ # # │ --- │
481
+ # # │ datetime[μs] │
482
+ # # ╞═════════════════════╡
483
+ # # │ 2001-01-01 00:00:00 │
484
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
485
+ # # │ 2001-01-04 00:00:00 │
486
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
487
+ # # │ 2001-01-07 00:00:00 │
488
+ # # └─────────────────────┘
489
+ #
490
+ # @example
491
+ # df.select(
492
+ # [
493
+ # Polars.col("date").dt.weekday.alias("weekday"),
494
+ # Polars.col("date").dt.day.alias("day_of_month"),
495
+ # Polars.col("date").dt.ordinal_day.alias("day_of_year")
496
+ # ]
497
+ # )
498
+ # # =>
499
+ # # shape: (3, 3)
500
+ # # ┌─────────┬──────────────┬─────────────┐
501
+ # # │ weekday ┆ day_of_month ┆ day_of_year │
502
+ # # │ --- ┆ --- ┆ --- │
503
+ # # │ u32 ┆ u32 ┆ u32 │
504
+ # # ╞═════════╪══════════════╪═════════════╡
505
+ # # │ 1 ┆ 1 ┆ 1 │
506
+ # # ├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┤
507
+ # # │ 4 ┆ 4 ┆ 4 │
508
+ # # ├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┤
509
+ # # │ 7 ┆ 7 ┆ 7 │
510
+ # # └─────────┴──────────────┴─────────────┘
511
+ def weekday
512
+ Utils.wrap_expr(_rbexpr.weekday)
513
+ end
514
+
515
+ # Extract day from underlying Date representation.
516
+ #
517
+ # Applies to Date and Datetime columns.
518
+ #
519
+ # Returns the day of month starting from 1.
520
+ # The return value ranges from 1 to 31. (The last day of month differs by months.)
521
+ #
522
+ # @return [Expr]
523
+ #
524
+ # @example
525
+ # start = DateTime.new(2001, 1, 1)
526
+ # stop = DateTime.new(2001, 1, 9)
527
+ # df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "3d")})
528
+ # # =>
529
+ # # shape: (3, 1)
530
+ # # ┌─────────────────────┐
531
+ # # │ date │
532
+ # # │ --- │
533
+ # # │ datetime[μs] │
534
+ # # ╞═════════════════════╡
535
+ # # │ 2001-01-01 00:00:00 │
536
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
537
+ # # │ 2001-01-04 00:00:00 │
538
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
539
+ # # │ 2001-01-07 00:00:00 │
540
+ # # └─────────────────────┘
541
+ #
542
+ # @example
543
+ # df.select(
544
+ # [
545
+ # Polars.col("date").dt.weekday.alias("weekday"),
546
+ # Polars.col("date").dt.day.alias("day_of_month"),
547
+ # Polars.col("date").dt.ordinal_day.alias("day_of_year")
548
+ # ]
549
+ # )
550
+ # # =>
551
+ # # shape: (3, 3)
552
+ # # ┌─────────┬──────────────┬─────────────┐
553
+ # # │ weekday ┆ day_of_month ┆ day_of_year │
554
+ # # │ --- ┆ --- ┆ --- │
555
+ # # │ u32 ┆ u32 ┆ u32 │
556
+ # # ╞═════════╪══════════════╪═════════════╡
557
+ # # │ 1 ┆ 1 ┆ 1 │
558
+ # # ├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┤
559
+ # # │ 4 ┆ 4 ┆ 4 │
560
+ # # ├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┤
561
+ # # │ 7 ┆ 7 ┆ 7 │
562
+ # # └─────────┴──────────────┴─────────────┘
563
+ def day
564
+ Utils.wrap_expr(_rbexpr.day)
565
+ end
566
+
567
+ # Extract ordinal day from underlying Date representation.
568
+ #
569
+ # Applies to Date and Datetime columns.
570
+ #
571
+ # Returns the day of month starting from 1.
572
+ # The return value ranges from 1 to 31. (The last day of month differs by months.)
573
+ #
574
+ # @return [Expr]
575
+ #
576
+ # @example
577
+ # start = DateTime.new(2001, 1, 1)
578
+ # stop = DateTime.new(2001, 1, 9)
579
+ # df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "3d")})
580
+ # # =>
581
+ # # shape: (3, 1)
582
+ # # ┌─────────────────────┐
583
+ # # │ date │
584
+ # # │ --- │
585
+ # # │ datetime[μs] │
586
+ # # ╞═════════════════════╡
587
+ # # │ 2001-01-01 00:00:00 │
588
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
589
+ # # │ 2001-01-04 00:00:00 │
590
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
591
+ # # │ 2001-01-07 00:00:00 │
592
+ # # └─────────────────────┘
593
+ #
594
+ # @example
595
+ # df.select(
596
+ # [
597
+ # Polars.col("date").dt.weekday.alias("weekday"),
598
+ # Polars.col("date").dt.day.alias("day_of_month"),
599
+ # Polars.col("date").dt.ordinal_day.alias("day_of_year")
600
+ # ]
601
+ # )
602
+ # # =>
603
+ # # shape: (3, 3)
604
+ # # ┌─────────┬──────────────┬─────────────┐
605
+ # # │ weekday ┆ day_of_month ┆ day_of_year │
606
+ # # │ --- ┆ --- ┆ --- │
607
+ # # │ u32 ┆ u32 ┆ u32 │
608
+ # # ╞═════════╪══════════════╪═════════════╡
609
+ # # │ 1 ┆ 1 ┆ 1 │
610
+ # # ├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┤
611
+ # # │ 4 ┆ 4 ┆ 4 │
612
+ # # ├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┤
613
+ # # │ 7 ┆ 7 ┆ 7 │
614
+ # # └─────────┴──────────────┴─────────────┘
615
+ def ordinal_day
616
+ Utils.wrap_expr(_rbexpr.ordinal_day)
617
+ end
618
+
619
+ # Extract hour from underlying DateTime representation.
620
+ #
621
+ # Applies to Datetime columns.
622
+ #
623
+ # Returns the hour number from 0 to 23.
624
+ #
625
+ # @return [Expr]
626
+ #
627
+ # @example
628
+ # start = DateTime.new(2001, 1, 1)
629
+ # stop = DateTime.new(2001, 1, 2)
630
+ # df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "12h")})
631
+ # # =>
632
+ # # shape: (3, 1)
633
+ # # ┌─────────────────────┐
634
+ # # │ date │
635
+ # # │ --- │
636
+ # # │ datetime[μs] │
637
+ # # ╞═════════════════════╡
638
+ # # │ 2001-01-01 00:00:00 │
639
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
640
+ # # │ 2001-01-01 12:00:00 │
641
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
642
+ # # │ 2001-01-02 00:00:00 │
643
+ # # └─────────────────────┘
644
+ #
645
+ # @example
646
+ # df.select(Polars.col("date").dt.hour)
647
+ # # =>
648
+ # # shape: (3, 1)
649
+ # # ┌──────┐
650
+ # # │ date │
651
+ # # │ --- │
652
+ # # │ u32 │
653
+ # # ╞══════╡
654
+ # # │ 0 │
655
+ # # ├╌╌╌╌╌╌┤
656
+ # # │ 12 │
657
+ # # ├╌╌╌╌╌╌┤
658
+ # # │ 0 │
659
+ # # └──────┘
660
+ def hour
661
+ Utils.wrap_expr(_rbexpr.hour)
662
+ end
663
+
664
+ # Extract minutes from underlying DateTime representation.
665
+ #
666
+ # Applies to Datetime columns.
667
+ #
668
+ # Returns the minute number from 0 to 59.
669
+ #
670
+ # @return [Expr]
671
+ #
672
+ # @example
673
+ # start = DateTime.new(2001, 1, 1)
674
+ # stop = DateTime.new(2001, 1, 1, 0, 4, 0)
675
+ # df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "2m")})
676
+ # # =>
677
+ # # shape: (3, 1)
678
+ # # ┌─────────────────────┐
679
+ # # │ date │
680
+ # # │ --- │
681
+ # # │ datetime[μs] │
682
+ # # ╞═════════════════════╡
683
+ # # │ 2001-01-01 00:00:00 │
684
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
685
+ # # │ 2001-01-01 00:02:00 │
686
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
687
+ # # │ 2001-01-01 00:04:00 │
688
+ # # └─────────────────────┘
689
+ #
690
+ # @example
691
+ # df.select(Polars.col("date").dt.minute)
692
+ # # =>
693
+ # # shape: (3, 1)
694
+ # # ┌──────┐
695
+ # # │ date │
696
+ # # │ --- │
697
+ # # │ u32 │
698
+ # # ╞══════╡
699
+ # # │ 0 │
700
+ # # ├╌╌╌╌╌╌┤
701
+ # # │ 2 │
702
+ # # ├╌╌╌╌╌╌┤
703
+ # # │ 4 │
704
+ # # └──────┘
705
+ def minute
706
+ Utils.wrap_expr(_rbexpr.minute)
707
+ end
708
+
709
+ # Extract seconds from underlying DateTime representation.
710
+ #
711
+ # Applies to Datetime columns.
712
+ #
713
+ # Returns the integer second number from 0 to 59, or a floating
714
+ # point number from 0 < 60 if `fractional: true` that includes
715
+ # any milli/micro/nanosecond component.
716
+ #
717
+ # @return [Expr]
718
+ #
719
+ # @example
720
+ # df = Polars::DataFrame.new(
721
+ # {
722
+ # "date" => Polars.date_range(
723
+ # DateTime.new(2001, 1, 1, 0, 0, 0.456789),
724
+ # DateTime.new(2001, 1, 1, 0, 0, 6),
725
+ # "2s654321us"
726
+ # )
727
+ # }
728
+ # )
729
+ # # =>
730
+ # # shape: (3, 1)
731
+ # # ┌────────────────────────────┐
732
+ # # │ date │
733
+ # # │ --- │
734
+ # # │ datetime[μs] │
735
+ # # ╞════════════════════════════╡
736
+ # # │ 2001-01-01 00:00:00.456789 │
737
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
738
+ # # │ 2001-01-01 00:00:03.111110 │
739
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
740
+ # # │ 2001-01-01 00:00:05.765431 │
741
+ # # └────────────────────────────┘
742
+ #
743
+ # @example
744
+ # df.select(Polars.col("date").dt.second.alias("secs"))
745
+ # # =>
746
+ # # shape: (3, 1)
747
+ # # ┌──────┐
748
+ # # │ secs │
749
+ # # │ --- │
750
+ # # │ u32 │
751
+ # # ╞══════╡
752
+ # # │ 0 │
753
+ # # ├╌╌╌╌╌╌┤
754
+ # # │ 3 │
755
+ # # ├╌╌╌╌╌╌┤
756
+ # # │ 5 │
757
+ # # └──────┘
758
+ #
759
+ # df.select(Polars.col("date").dt.second(fractional: true).alias("secs"))
760
+ # # =>
761
+ # # shape: (3, 1)
762
+ # # ┌──────────┐
763
+ # # │ secs │
764
+ # # │ --- │
765
+ # # │ f64 │
766
+ # # ╞══════════╡
767
+ # # │ 0.456789 │
768
+ # # ├╌╌╌╌╌╌╌╌╌╌┤
769
+ # # │ 3.11111 │
770
+ # # ├╌╌╌╌╌╌╌╌╌╌┤
771
+ # # │ 5.765431 │
772
+ # # └──────────┘
773
+ #
774
+ # @example
775
+ # start = DateTime.new(2001, 1, 1)
776
+ # stop = DateTime.new(2001, 1, 1, 0, 0, 4)
777
+ # df = Polars::DataFrame.new(
778
+ # {"date" => Polars.date_range(start, stop, "2s")}
779
+ # )
780
+ # # =>
781
+ # # shape: (3, 1)
782
+ # # ┌─────────────────────┐
783
+ # # │ date │
784
+ # # │ --- │
785
+ # # │ datetime[μs] │
786
+ # # ╞═════════════════════╡
787
+ # # │ 2001-01-01 00:00:00 │
788
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
789
+ # # │ 2001-01-01 00:00:02 │
790
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
791
+ # # │ 2001-01-01 00:00:04 │
792
+ # # └─────────────────────┘
793
+ #
794
+ # @example
795
+ # df.select(Polars.col("date").dt.second)
796
+ # # =>
797
+ # # shape: (3, 1)
798
+ # # ┌──────┐
799
+ # # │ date │
800
+ # # │ --- │
801
+ # # │ u32 │
802
+ # # ╞══════╡
803
+ # # │ 0 │
804
+ # # ├╌╌╌╌╌╌┤
805
+ # # │ 2 │
806
+ # # ├╌╌╌╌╌╌┤
807
+ # # │ 4 │
808
+ # # └──────┘
809
+ def second(fractional: false)
810
+ sec = Utils.wrap_expr(_rbexpr.second)
811
+ if fractional
812
+ sec + (Utils.wrap_expr(_rbexpr.nanosecond) / Utils.lit(1_000_000_000.0))
813
+ else
814
+ sec
815
+ end
816
+ end
817
+
818
+ # Extract milliseconds from underlying DateTime representation.
819
+ #
820
+ # Applies to Datetime columns.
821
+ #
822
+ # @return [Expr]
823
+ def millisecond
824
+ Utils.wrap_expr(_rbexpr.millisecond)
825
+ end
826
+
827
+ # Extract microseconds from underlying DateTime representation.
828
+ #
829
+ # Applies to Datetime columns.
830
+ #
831
+ # @return [Expr]
832
+ def microsecond
833
+ Utils.wrap_expr(_rbexpr.microsecond)
834
+ end
835
+
836
+ # Extract nanoseconds from underlying DateTime representation.
837
+ #
838
+ # Applies to Datetime columns.
839
+ #
840
+ # @return [Expr]
841
+ def nanosecond
842
+ Utils.wrap_expr(_rbexpr.nanosecond)
843
+ end
844
+
845
+ # Get the time passed since the Unix EPOCH in the give time unit.
846
+ #
847
+ # @param tu ["us", "ns", "ms", "s", "d"]
848
+ # Time unit.
849
+ #
850
+ # @return [Expr]
851
+ #
852
+ # @example
853
+ # start = DateTime.new(2001, 1, 1)
854
+ # stop = DateTime.new(2001, 1, 3)
855
+ # df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "1d")})
856
+ # df.select(
857
+ # [
858
+ # Polars.col("date"),
859
+ # Polars.col("date").dt.epoch.alias("epoch_ns"),
860
+ # Polars.col("date").dt.epoch("s").alias("epoch_s")
861
+ # ]
862
+ # )
863
+ # # =>
864
+ # # shape: (3, 3)
865
+ # # ┌─────────────────────┬─────────────────┬───────────┐
866
+ # # │ date ┆ epoch_ns ┆ epoch_s │
867
+ # # │ --- ┆ --- ┆ --- │
868
+ # # │ datetime[μs] ┆ i64 ┆ i64 │
869
+ # # ╞═════════════════════╪═════════════════╪═══════════╡
870
+ # # │ 2001-01-01 00:00:00 ┆ 978307200000000 ┆ 978307200 │
871
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┤
872
+ # # │ 2001-01-02 00:00:00 ┆ 978393600000000 ┆ 978393600 │
873
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┤
874
+ # # │ 2001-01-03 00:00:00 ┆ 978480000000000 ┆ 978480000 │
875
+ # # └─────────────────────┴─────────────────┴───────────┘
876
+ def epoch(tu = "us")
877
+ if Utils::DTYPE_TEMPORAL_UNITS.include?(tu)
878
+ timestamp(tu)
879
+ elsif tu == "s"
880
+ Utils.wrap_expr(_rbexpr.dt_epoch_seconds)
881
+ elsif tu == "d"
882
+ Utils.wrap_expr(_rbexpr).cast(:date).cast(:i32)
883
+ else
884
+ raise ArgumentError, "tu must be one of {{'ns', 'us', 'ms', 's', 'd'}}, got #{tu}"
885
+ end
886
+ end
887
+
888
+ # Return a timestamp in the given time unit.
889
+ #
890
+ # @param tu ["us", "ns", "ms"]
891
+ # Time unit.
892
+ #
893
+ # @return [Expr]
894
+ #
895
+ # @example
896
+ # start = DateTime.new(2001, 1, 1)
897
+ # stop = DateTime.new(2001, 1, 3)
898
+ # df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "1d")})
899
+ # df.select(
900
+ # [
901
+ # Polars.col("date"),
902
+ # Polars.col("date").dt.timestamp.alias("timestamp_ns"),
903
+ # Polars.col("date").dt.timestamp("ms").alias("timestamp_ms")
904
+ # ]
905
+ # )
906
+ # # =>
907
+ # # shape: (3, 3)
908
+ # # ┌─────────────────────┬─────────────────┬──────────────┐
909
+ # # │ date ┆ timestamp_ns ┆ timestamp_ms │
910
+ # # │ --- ┆ --- ┆ --- │
911
+ # # │ datetime[μs] ┆ i64 ┆ i64 │
912
+ # # ╞═════════════════════╪═════════════════╪══════════════╡
913
+ # # │ 2001-01-01 00:00:00 ┆ 978307200000000 ┆ 978307200000 │
914
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
915
+ # # │ 2001-01-02 00:00:00 ┆ 978393600000000 ┆ 978393600000 │
916
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
917
+ # # │ 2001-01-03 00:00:00 ┆ 978480000000000 ┆ 978480000000 │
918
+ # # └─────────────────────┴─────────────────┴──────────────┘
919
+ def timestamp(tu = "us")
920
+ Utils.wrap_expr(_rbexpr.timestamp(tu))
921
+ end
922
+
923
+ # Set time unit of a Series of dtype Datetime or Duration.
924
+ #
925
+ # This does not modify underlying data, and should be used to fix an incorrect
926
+ # time unit.
927
+ #
928
+ # @param tu ["ns", "us", "ms"]
929
+ # Time unit for the `Datetime` Series.
930
+ #
931
+ # @return [Expr]
932
+ #
933
+ # @example
934
+ # df = Polars::DataFrame.new(
935
+ # {
936
+ # "date" => Polars.date_range(
937
+ # DateTime.new(2001, 1, 1), DateTime.new(2001, 1, 3), "1d", time_unit: "ns"
938
+ # )
939
+ # }
940
+ # )
941
+ # df.select(
942
+ # [
943
+ # Polars.col("date"),
944
+ # Polars.col("date").dt.with_time_unit("us").alias("tu_us")
945
+ # ]
946
+ # )
947
+ # # =>
948
+ # # shape: (3, 2)
949
+ # # ┌─────────────────────┬───────────────────────┐
950
+ # # │ date ┆ tu_us │
951
+ # # │ --- ┆ --- │
952
+ # # │ datetime[ns] ┆ datetime[μs] │
953
+ # # ╞═════════════════════╪═══════════════════════╡
954
+ # # │ 2001-01-01 00:00:00 ┆ +32971-04-28 00:00:00 │
955
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
956
+ # # │ 2001-01-02 00:00:00 ┆ +32974-01-22 00:00:00 │
957
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
958
+ # # │ 2001-01-03 00:00:00 ┆ +32976-10-18 00:00:00 │
959
+ # # └─────────────────────┴───────────────────────┘
960
+ def with_time_unit(tu)
961
+ Utils.wrap_expr(_rbexpr.dt_with_time_unit(tu))
962
+ end
963
+
964
+ # Cast the underlying data to another time unit. This may lose precision.
965
+ #
966
+ # @param tu ["ns", "us", "ms"]
967
+ # Time unit for the `Datetime` Series.
968
+ #
969
+ # @return [Expr]
970
+ #
971
+ # @example
972
+ # df = Polars::DataFrame.new(
973
+ # {
974
+ # "date" => Polars.date_range(
975
+ # DateTime.new(2001, 1, 1), DateTime.new(2001, 1, 3), "1d"
976
+ # )
977
+ # }
978
+ # )
979
+ # df.select(
980
+ # [
981
+ # Polars.col("date"),
982
+ # Polars.col("date").dt.cast_time_unit("ms").alias("tu_ms"),
983
+ # Polars.col("date").dt.cast_time_unit("ns").alias("tu_ns")
984
+ # ]
985
+ # )
986
+ # # =>
987
+ # # shape: (3, 3)
988
+ # # ┌─────────────────────┬─────────────────────┬─────────────────────┐
989
+ # # │ date ┆ tu_ms ┆ tu_ns │
990
+ # # │ --- ┆ --- ┆ --- │
991
+ # # │ datetime[μs] ┆ datetime[ms] ┆ datetime[ns] │
992
+ # # ╞═════════════════════╪═════════════════════╪═════════════════════╡
993
+ # # │ 2001-01-01 00:00:00 ┆ 2001-01-01 00:00:00 ┆ 2001-01-01 00:00:00 │
994
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
995
+ # # │ 2001-01-02 00:00:00 ┆ 2001-01-02 00:00:00 ┆ 2001-01-02 00:00:00 │
996
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
997
+ # # │ 2001-01-03 00:00:00 ┆ 2001-01-03 00:00:00 ┆ 2001-01-03 00:00:00 │
998
+ # # └─────────────────────┴─────────────────────┴─────────────────────┘
999
+ def cast_time_unit(tu)
1000
+ Utils.wrap_expr(_rbexpr.dt_cast_time_unit(tu))
1001
+ end
1002
+
1003
+ # Set time zone for a Series of type Datetime.
1004
+ #
1005
+ # @param tz [String]
1006
+ # Time zone for the `Datetime` Series.
1007
+ #
1008
+ # @return [Expr]
1009
+ #
1010
+ # @example
1011
+ # df = Polars::DataFrame.new(
1012
+ # {
1013
+ # "date" => Polars.date_range(
1014
+ # DateTime.new(2020, 3, 1), DateTime.new(2020, 5, 1), "1mo"
1015
+ # )
1016
+ # }
1017
+ # )
1018
+ # df.select(
1019
+ # [
1020
+ # Polars.col("date"),
1021
+ # Polars.col("date")
1022
+ # .dt.with_time_zone("Europe/London")
1023
+ # .alias("London")
1024
+ # ]
1025
+ # )
1026
+ # # =>
1027
+ # # shape: (3, 2)
1028
+ # # ┌─────────────────────┬─────────────────────────────┐
1029
+ # # │ date ┆ London │
1030
+ # # │ --- ┆ --- │
1031
+ # # │ datetime[μs] ┆ datetime[μs, Europe/London] │
1032
+ # # ╞═════════════════════╪═════════════════════════════╡
1033
+ # # │ 2020-03-01 00:00:00 ┆ 2020-03-01 00:00:00 GMT │
1034
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1035
+ # # │ 2020-04-01 00:00:00 ┆ 2020-04-01 01:00:00 BST │
1036
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1037
+ # # │ 2020-05-01 00:00:00 ┆ 2020-05-01 01:00:00 BST │
1038
+ # # └─────────────────────┴─────────────────────────────┘
1039
+ def with_time_zone(tz)
1040
+ Utils.wrap_expr(_rbexpr.dt_with_time_zone(tz))
1041
+ end
1042
+
1043
+ # Cast time zone for a Series of type Datetime.
1044
+ #
1045
+ # Different from `with_time_zone`, this will also modify
1046
+ # the underlying timestamp,
1047
+ #
1048
+ # @param tz [String]
1049
+ # Time zone for the `Datetime` Series.
1050
+ #
1051
+ # @return [Expr]
1052
+ def cast_time_zone(tz)
1053
+ Utils.wrap_expr(_rbexpr.dt_cast_time_zone(tz))
1054
+ end
1055
+
1056
+ # Localize tz-naive Datetime Series to tz-aware Datetime Series.
1057
+ #
1058
+ # This method takes a naive Datetime Series and makes this time zone aware.
1059
+ # It does not move the time to another time zone.
1060
+ #
1061
+ # @param tz [String]
1062
+ # Time zone for the `Datetime` Series.
1063
+ #
1064
+ # @return [Expr]
1065
+ def tz_localize(tz)
1066
+ Utils.wrap_expr(_rbexpr.dt_tz_localize(tz))
1067
+ end
1068
+
1069
+ # Extract the days from a Duration type.
1070
+ #
1071
+ # @return [Expr]
1072
+ #
1073
+ # @example
1074
+ # df = Polars::DataFrame.new(
1075
+ # {
1076
+ # "date" => Polars.date_range(
1077
+ # DateTime.new(2020, 3, 1), DateTime.new(2020, 5, 1), "1mo"
1078
+ # )
1079
+ # }
1080
+ # )
1081
+ # df.select(
1082
+ # [
1083
+ # Polars.col("date"),
1084
+ # Polars.col("date").diff.dt.days.alias("days_diff")
1085
+ # ]
1086
+ # )
1087
+ # # =>
1088
+ # # shape: (3, 2)
1089
+ # # ┌─────────────────────┬───────────┐
1090
+ # # │ date ┆ days_diff │
1091
+ # # │ --- ┆ --- │
1092
+ # # │ datetime[μs] ┆ i64 │
1093
+ # # ╞═════════════════════╪═══════════╡
1094
+ # # │ 2020-03-01 00:00:00 ┆ null │
1095
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┤
1096
+ # # │ 2020-04-01 00:00:00 ┆ 31 │
1097
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┤
1098
+ # # │ 2020-05-01 00:00:00 ┆ 30 │
1099
+ # # └─────────────────────┴───────────┘
1100
+ def days
1101
+ Utils.wrap_expr(_rbexpr.duration_days)
1102
+ end
1103
+
1104
+ # Extract the hours from a Duration type.
1105
+ #
1106
+ # @return [Expr]
1107
+ #
1108
+ # @example
1109
+ # df = Polars::DataFrame.new(
1110
+ # {
1111
+ # "date" => Polars.date_range(
1112
+ # DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 4), "1d"
1113
+ # )
1114
+ # }
1115
+ # )
1116
+ # df.select(
1117
+ # [
1118
+ # Polars.col("date"),
1119
+ # Polars.col("date").diff.dt.hours.alias("hours_diff")
1120
+ # ]
1121
+ # )
1122
+ # # =>
1123
+ # # shape: (4, 2)
1124
+ # # ┌─────────────────────┬────────────┐
1125
+ # # │ date ┆ hours_diff │
1126
+ # # │ --- ┆ --- │
1127
+ # # │ datetime[μs] ┆ i64 │
1128
+ # # ╞═════════════════════╪════════════╡
1129
+ # # │ 2020-01-01 00:00:00 ┆ null │
1130
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌┤
1131
+ # # │ 2020-01-02 00:00:00 ┆ 24 │
1132
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌┤
1133
+ # # │ 2020-01-03 00:00:00 ┆ 24 │
1134
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌┤
1135
+ # # │ 2020-01-04 00:00:00 ┆ 24 │
1136
+ # # └─────────────────────┴────────────┘
1137
+ def hours
1138
+ Utils.wrap_expr(_rbexpr.duration_hours)
1139
+ end
1140
+
1141
+ # Extract the minutes from a Duration type.
1142
+ #
1143
+ # @return [Expr]
1144
+ #
1145
+ # @example
1146
+ # df = Polars::DataFrame.new(
1147
+ # {
1148
+ # "date" => Polars.date_range(
1149
+ # DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 4), "1d"
1150
+ # )
1151
+ # }
1152
+ # )
1153
+ # df.select(
1154
+ # [
1155
+ # Polars.col("date"),
1156
+ # Polars.col("date").diff.dt.minutes.alias("minutes_diff")
1157
+ # ]
1158
+ # )
1159
+ # # =>
1160
+ # # shape: (4, 2)
1161
+ # # ┌─────────────────────┬──────────────┐
1162
+ # # │ date ┆ minutes_diff │
1163
+ # # │ --- ┆ --- │
1164
+ # # │ datetime[μs] ┆ i64 │
1165
+ # # ╞═════════════════════╪══════════════╡
1166
+ # # │ 2020-01-01 00:00:00 ┆ null │
1167
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1168
+ # # │ 2020-01-02 00:00:00 ┆ 1440 │
1169
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1170
+ # # │ 2020-01-03 00:00:00 ┆ 1440 │
1171
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1172
+ # # │ 2020-01-04 00:00:00 ┆ 1440 │
1173
+ # # └─────────────────────┴──────────────┘
1174
+ def minutes
1175
+ Utils.wrap_expr(_rbexpr.duration_minutes)
1176
+ end
1177
+
1178
+ # Extract the seconds from a Duration type.
1179
+ #
1180
+ # @return [Expr]
1181
+ #
1182
+ # @example
1183
+ # df = Polars::DataFrame.new(
1184
+ # {
1185
+ # "date" => Polars.date_range(
1186
+ # DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 4, 0), "1m"
1187
+ # )
1188
+ # }
1189
+ # )
1190
+ # df.select(
1191
+ # [
1192
+ # Polars.col("date"),
1193
+ # Polars.col("date").diff.dt.seconds.alias("seconds_diff")
1194
+ # ]
1195
+ # )
1196
+ # # =>
1197
+ # # shape: (5, 2)
1198
+ # # ┌─────────────────────┬──────────────┐
1199
+ # # │ date ┆ seconds_diff │
1200
+ # # │ --- ┆ --- │
1201
+ # # │ datetime[μs] ┆ i64 │
1202
+ # # ╞═════════════════════╪══════════════╡
1203
+ # # │ 2020-01-01 00:00:00 ┆ null │
1204
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1205
+ # # │ 2020-01-01 00:01:00 ┆ 60 │
1206
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1207
+ # # │ 2020-01-01 00:02:00 ┆ 60 │
1208
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1209
+ # # │ 2020-01-01 00:03:00 ┆ 60 │
1210
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1211
+ # # │ 2020-01-01 00:04:00 ┆ 60 │
1212
+ # # └─────────────────────┴──────────────┘
1213
+ def seconds
1214
+ Utils.wrap_expr(_rbexpr.duration_seconds)
1215
+ end
1216
+
1217
+ # Extract the milliseconds from a Duration type.
1218
+ #
1219
+ # @return [Expr]
1220
+ #
1221
+ # @example
1222
+ # df = Polars::DataFrame.new(
1223
+ # {
1224
+ # "date" => Polars.date_range(
1225
+ # DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 0, 1), "1ms"
1226
+ # )
1227
+ # }
1228
+ # )
1229
+ # df.select(
1230
+ # [
1231
+ # Polars.col("date"),
1232
+ # Polars.col("date").diff.dt.milliseconds.alias("milliseconds_diff")
1233
+ # ]
1234
+ # )
1235
+ # # =>
1236
+ # # shape: (1001, 2)
1237
+ # # ┌─────────────────────────┬───────────────────┐
1238
+ # # │ date ┆ milliseconds_diff │
1239
+ # # │ --- ┆ --- │
1240
+ # # │ datetime[μs] ┆ i64 │
1241
+ # # ╞═════════════════════════╪═══════════════════╡
1242
+ # # │ 2020-01-01 00:00:00 ┆ null │
1243
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1244
+ # # │ 2020-01-01 00:00:00.001 ┆ 1 │
1245
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1246
+ # # │ 2020-01-01 00:00:00.002 ┆ 1 │
1247
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1248
+ # # │ 2020-01-01 00:00:00.003 ┆ 1 │
1249
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1250
+ # # │ ... ┆ ... │
1251
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1252
+ # # │ 2020-01-01 00:00:00.997 ┆ 1 │
1253
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1254
+ # # │ 2020-01-01 00:00:00.998 ┆ 1 │
1255
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1256
+ # # │ 2020-01-01 00:00:00.999 ┆ 1 │
1257
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1258
+ # # │ 2020-01-01 00:00:01 ┆ 1 │
1259
+ # # └─────────────────────────┴───────────────────┘
1260
+ def milliseconds
1261
+ Utils.wrap_expr(_rbexpr.duration_milliseconds)
1262
+ end
1263
+
1264
+ # Extract the microseconds from a Duration type.
1265
+ #
1266
+ # @return [Expr]
1267
+ #
1268
+ # @example
1269
+ # df = Polars::DataFrame.new(
1270
+ # {
1271
+ # "date" => Polars.date_range(
1272
+ # DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 0, 1), "1ms"
1273
+ # )
1274
+ # }
1275
+ # )
1276
+ # df.select(
1277
+ # [
1278
+ # Polars.col("date"),
1279
+ # Polars.col("date").diff.dt.microseconds.alias("microseconds_diff")
1280
+ # ]
1281
+ # )
1282
+ # # =>
1283
+ # # shape: (1001, 2)
1284
+ # # ┌─────────────────────────┬───────────────────┐
1285
+ # # │ date ┆ microseconds_diff │
1286
+ # # │ --- ┆ --- │
1287
+ # # │ datetime[μs] ┆ i64 │
1288
+ # # ╞═════════════════════════╪═══════════════════╡
1289
+ # # │ 2020-01-01 00:00:00 ┆ null │
1290
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1291
+ # # │ 2020-01-01 00:00:00.001 ┆ 1000 │
1292
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1293
+ # # │ 2020-01-01 00:00:00.002 ┆ 1000 │
1294
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1295
+ # # │ 2020-01-01 00:00:00.003 ┆ 1000 │
1296
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1297
+ # # │ ... ┆ ... │
1298
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1299
+ # # │ 2020-01-01 00:00:00.997 ┆ 1000 │
1300
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1301
+ # # │ 2020-01-01 00:00:00.998 ┆ 1000 │
1302
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1303
+ # # │ 2020-01-01 00:00:00.999 ┆ 1000 │
1304
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1305
+ # # │ 2020-01-01 00:00:01 ┆ 1000 │
1306
+ # # └─────────────────────────┴───────────────────┘
1307
+ def microseconds
1308
+ Utils.wrap_expr(_rbexpr.duration_microseconds)
1309
+ end
1310
+
1311
+ # Extract the nanoseconds from a Duration type.
1312
+ #
1313
+ # @return [Expr]
1314
+ #
1315
+ # @example
1316
+ # df = Polars::DataFrame.new(
1317
+ # {
1318
+ # "date" => Polars.date_range(
1319
+ # DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 0, 1), "1ms"
1320
+ # )
1321
+ # }
1322
+ # )
1323
+ # df.select(
1324
+ # [
1325
+ # Polars.col("date"),
1326
+ # Polars.col("date").diff.dt.nanoseconds.alias("nanoseconds_diff")
1327
+ # ]
1328
+ # )
1329
+ # # =>
1330
+ # # shape: (1001, 2)
1331
+ # # ┌─────────────────────────┬──────────────────┐
1332
+ # # │ date ┆ nanoseconds_diff │
1333
+ # # │ --- ┆ --- │
1334
+ # # │ datetime[μs] ┆ i64 │
1335
+ # # ╞═════════════════════════╪══════════════════╡
1336
+ # # │ 2020-01-01 00:00:00 ┆ null │
1337
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1338
+ # # │ 2020-01-01 00:00:00.001 ┆ 1000000 │
1339
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1340
+ # # │ 2020-01-01 00:00:00.002 ┆ 1000000 │
1341
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1342
+ # # │ 2020-01-01 00:00:00.003 ┆ 1000000 │
1343
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1344
+ # # │ ... ┆ ... │
1345
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1346
+ # # │ 2020-01-01 00:00:00.997 ┆ 1000000 │
1347
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1348
+ # # │ 2020-01-01 00:00:00.998 ┆ 1000000 │
1349
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1350
+ # # │ 2020-01-01 00:00:00.999 ┆ 1000000 │
1351
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1352
+ # # │ 2020-01-01 00:00:01 ┆ 1000000 │
1353
+ # # └─────────────────────────┴──────────────────┘
1354
+ def nanoseconds
1355
+ Utils.wrap_expr(_rbexpr.duration_nanoseconds)
1356
+ end
1357
+
1358
+ # Offset this date by a relative time offset.
1359
+ #
1360
+ # This differs from `Polars.col("foo") + timedelta` in that it can
1361
+ # take months and leap years into account. Note that only a single minus
1362
+ # sign is allowed in the `by` string, as the first character.
1363
+ #
1364
+ # @param by [String]
1365
+ # The offset is dictated by the following string language:
1366
+ #
1367
+ # - 1ns (1 nanosecond)
1368
+ # - 1us (1 microsecond)
1369
+ # - 1ms (1 millisecond)
1370
+ # - 1s (1 second)
1371
+ # - 1m (1 minute)
1372
+ # - 1h (1 hour)
1373
+ # - 1d (1 day)
1374
+ # - 1w (1 week)
1375
+ # - 1mo (1 calendar month)
1376
+ # - 1y (1 calendar year)
1377
+ # - 1i (1 index count)
1378
+ #
1379
+ # @return [Expr]
1380
+ #
1381
+ # @example
1382
+ # df = Polars::DataFrame.new(
1383
+ # {
1384
+ # "dates" => Polars.date_range(
1385
+ # DateTime.new(2000, 1, 1), DateTime.new(2005, 1, 1), "1y"
1386
+ # )
1387
+ # }
1388
+ # )
1389
+ # df.select(
1390
+ # [
1391
+ # Polars.col("dates").dt.offset_by("1y").alias("date_plus_1y"),
1392
+ # Polars.col("dates").dt.offset_by("-1y2mo").alias("date_min")
1393
+ # ]
1394
+ # )
1395
+ # # =>
1396
+ # # shape: (6, 2)
1397
+ # # ┌─────────────────────┬─────────────────────┐
1398
+ # # │ date_plus_1y ┆ date_min │
1399
+ # # │ --- ┆ --- │
1400
+ # # │ datetime[μs] ┆ datetime[μs] │
1401
+ # # ╞═════════════════════╪═════════════════════╡
1402
+ # # │ 2001-01-01 00:00:00 ┆ 1998-11-01 00:00:00 │
1403
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1404
+ # # │ 2002-01-01 00:00:00 ┆ 1999-11-01 00:00:00 │
1405
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1406
+ # # │ 2003-01-01 00:00:00 ┆ 2000-11-01 00:00:00 │
1407
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1408
+ # # │ 2004-01-01 00:00:00 ┆ 2001-11-01 00:00:00 │
1409
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1410
+ # # │ 2005-01-01 00:00:00 ┆ 2002-11-01 00:00:00 │
1411
+ # # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
1412
+ # # │ 2006-01-01 00:00:00 ┆ 2003-11-01 00:00:00 │
1413
+ # # └─────────────────────┴─────────────────────┘
1414
+ def offset_by(by)
1415
+ Utils.wrap_expr(_rbexpr.dt_offset_by(by))
1416
+ end
1417
+ end
1418
+ end