polars-df 0.11.0-x86_64-linux → 0.12.0-x86_64-linux

Sign up to get free protection for your applications and to get access to all the features.
Files changed (53) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +16 -0
  3. data/Cargo.lock +360 -361
  4. data/LICENSE-THIRD-PARTY.txt +1065 -878
  5. data/lib/polars/3.1/polars.so +0 -0
  6. data/lib/polars/3.2/polars.so +0 -0
  7. data/lib/polars/3.3/polars.so +0 -0
  8. data/lib/polars/array_expr.rb +4 -4
  9. data/lib/polars/batched_csv_reader.rb +2 -2
  10. data/lib/polars/cat_expr.rb +0 -36
  11. data/lib/polars/cat_name_space.rb +0 -37
  12. data/lib/polars/data_frame.rb +93 -101
  13. data/lib/polars/data_types.rb +1 -1
  14. data/lib/polars/date_time_expr.rb +525 -573
  15. data/lib/polars/date_time_name_space.rb +263 -464
  16. data/lib/polars/dynamic_group_by.rb +3 -3
  17. data/lib/polars/exceptions.rb +3 -0
  18. data/lib/polars/expr.rb +367 -330
  19. data/lib/polars/expr_dispatch.rb +1 -1
  20. data/lib/polars/functions/aggregation/horizontal.rb +8 -8
  21. data/lib/polars/functions/as_datatype.rb +63 -40
  22. data/lib/polars/functions/lazy.rb +63 -14
  23. data/lib/polars/functions/lit.rb +1 -1
  24. data/lib/polars/functions/range/date_range.rb +18 -77
  25. data/lib/polars/functions/range/datetime_range.rb +4 -4
  26. data/lib/polars/functions/range/int_range.rb +2 -2
  27. data/lib/polars/functions/range/time_range.rb +4 -4
  28. data/lib/polars/functions/repeat.rb +1 -1
  29. data/lib/polars/functions/whenthen.rb +1 -1
  30. data/lib/polars/io/csv.rb +8 -8
  31. data/lib/polars/io/ipc.rb +3 -3
  32. data/lib/polars/io/json.rb +13 -2
  33. data/lib/polars/io/ndjson.rb +15 -4
  34. data/lib/polars/io/parquet.rb +5 -4
  35. data/lib/polars/lazy_frame.rb +120 -106
  36. data/lib/polars/lazy_group_by.rb +1 -1
  37. data/lib/polars/list_expr.rb +11 -11
  38. data/lib/polars/list_name_space.rb +5 -1
  39. data/lib/polars/rolling_group_by.rb +5 -7
  40. data/lib/polars/series.rb +105 -189
  41. data/lib/polars/string_expr.rb +42 -67
  42. data/lib/polars/string_name_space.rb +5 -4
  43. data/lib/polars/testing.rb +2 -2
  44. data/lib/polars/utils/constants.rb +9 -0
  45. data/lib/polars/utils/convert.rb +97 -0
  46. data/lib/polars/utils/parse.rb +89 -0
  47. data/lib/polars/utils/various.rb +76 -0
  48. data/lib/polars/utils/wrap.rb +19 -0
  49. data/lib/polars/utils.rb +4 -330
  50. data/lib/polars/version.rb +1 -1
  51. data/lib/polars/whenthen.rb +6 -6
  52. data/lib/polars.rb +11 -0
  53. metadata +7 -2
@@ -15,13 +15,11 @@ module Polars
15
15
  #
16
16
  # @param every [String]
17
17
  # Every interval start and period length
18
- # @param offset [String]
19
- # Offset the window
20
18
  #
21
19
  # @return [Expr]
22
20
  #
23
21
  # @note
24
- # The `every` and `offset` argument are created with the
22
+ # The `every` argument is created with the
25
23
  # the following small string formatting language:
26
24
  #
27
25
  # 1ns # 1 nanosecond
@@ -38,17 +36,22 @@ module Polars
38
36
  # eg: 3d12h4m25s # 3 days, 12 hours, 4 minutes, and 25 seconds
39
37
  #
40
38
  # @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
39
+ # df = (
40
+ # Polars.datetime_range(
41
+ # DateTime.new(2001, 1, 1),
42
+ # DateTime.new(2001, 1, 2),
43
+ # "225m",
44
+ # eager: true
45
+ # )
46
+ # .alias("datetime")
47
+ # .to_frame
48
+ # )
46
49
  # # =>
47
50
  # # shape: (7, 1)
48
51
  # # ┌─────────────────────┐
49
- # # │ dates
52
+ # # │ datetime
50
53
  # # │ --- │
51
- # # │ datetime[μs] │
54
+ # # │ datetime[ns] │
52
55
  # # ╞═════════════════════╡
53
56
  # # │ 2001-01-01 00:00:00 │
54
57
  # # │ 2001-01-01 03:45:00 │
@@ -60,13 +63,13 @@ module Polars
60
63
  # # └─────────────────────┘
61
64
  #
62
65
  # @example
63
- # df.select(Polars.col("dates").dt.truncate("1h"))
66
+ # df.select(Polars.col("datetime").dt.truncate("1h"))
64
67
  # # =>
65
68
  # # shape: (7, 1)
66
69
  # # ┌─────────────────────┐
67
- # # │ dates
70
+ # # │ datetime
68
71
  # # │ --- │
69
- # # │ datetime[μs] │
72
+ # # │ datetime[ns] │
70
73
  # # ╞═════════════════════╡
71
74
  # # │ 2001-01-01 00:00:00 │
72
75
  # # │ 2001-01-01 03:00:00 │
@@ -78,16 +81,20 @@ module Polars
78
81
  # # └─────────────────────┘
79
82
  #
80
83
  # @example
81
- # start = DateTime.new(2001, 1, 1)
82
- # stop = DateTime.new(2001, 1, 1, 1)
83
- # df = Polars.date_range(start, stop, "10m", name: "dates").to_frame
84
- # df.select(["dates", Polars.col("dates").dt.truncate("30m").alias("truncate")])
84
+ # df = (
85
+ # Polars.datetime_range(
86
+ # DateTime.new(2001, 1, 1), DateTime.new(2001, 1, 1, 1), "10m", eager: true
87
+ # )
88
+ # .alias("datetime")
89
+ # .to_frame
90
+ # )
91
+ # df.select(["datetime", Polars.col("datetime").dt.truncate("30m").alias("truncate")])
85
92
  # # =>
86
93
  # # shape: (7, 2)
87
94
  # # ┌─────────────────────┬─────────────────────┐
88
- # # │ dates ┆ truncate │
95
+ # # │ datetime ┆ truncate │
89
96
  # # │ --- ┆ --- │
90
- # # │ datetime[μs] ┆ datetime[μs] │
97
+ # # │ datetime[ns] ┆ datetime[ns] │
91
98
  # # ╞═════════════════════╪═════════════════════╡
92
99
  # # │ 2001-01-01 00:00:00 ┆ 2001-01-01 00:00:00 │
93
100
  # # │ 2001-01-01 00:10:00 ┆ 2001-01-01 00:00:00 │
@@ -97,22 +104,13 @@ module Polars
97
104
  # # │ 2001-01-01 00:50:00 ┆ 2001-01-01 00:30:00 │
98
105
  # # │ 2001-01-01 01:00:00 ┆ 2001-01-01 01:00:00 │
99
106
  # # └─────────────────────┴─────────────────────┘
100
- def truncate(every, offset: nil, use_earliest: nil)
101
- if offset.nil?
102
- offset = "0ns"
103
- end
104
-
107
+ def truncate(every)
105
108
  if !every.is_a?(Expr)
106
- every = Utils._timedelta_to_pl_duration(every)
109
+ every = Utils.parse_as_duration_string(every)
107
110
  end
108
- every = Utils.parse_as_expression(every, str_as_lit: true)
109
111
 
110
- Utils.wrap_expr(
111
- _rbexpr.dt_truncate(
112
- every,
113
- Utils._timedelta_to_pl_duration(offset),
114
- )
115
- )
112
+ every = Utils.parse_into_expression(every, str_as_lit: true)
113
+ Utils.wrap_expr(_rbexpr.dt_truncate(every))
116
114
  end
117
115
 
118
116
  # Divide the date/datetime range into buckets.
@@ -124,8 +122,6 @@ module Polars
124
122
  #
125
123
  # @param every [String]
126
124
  # Every interval start and period length
127
- # @param offset [String]
128
- # Offset the window
129
125
  #
130
126
  # @return [Expr]
131
127
  #
@@ -151,56 +147,48 @@ module Polars
151
147
  # change without it being considered a breaking change.
152
148
  #
153
149
  # @example
154
- # start = DateTime.new(2001, 1, 1)
155
- # stop = DateTime.new(2001, 1, 2)
156
- # df = Polars.date_range(
157
- # start, stop, "225m", name: "dates"
158
- # ).to_frame
159
- # # =>
160
- # # shape: (7, 1)
161
- # # ┌─────────────────────┐
162
- # # │ dates │
163
- # # │ --- │
164
- # # │ datetime[μs] │
165
- # # ╞═════════════════════╡
166
- # # │ 2001-01-01 00:00:00 │
167
- # # │ 2001-01-01 03:45:00 │
168
- # # │ 2001-01-01 07:30:00 │
169
- # # │ 2001-01-01 11:15:00 │
170
- # # │ 2001-01-01 15:00:00 │
171
- # # │ 2001-01-01 18:45:00 │
172
- # # │ 2001-01-01 22:30:00 │
173
- # # └─────────────────────┘
174
- #
175
- # @example
176
- # df.select(Polars.col("dates").dt.round("1h"))
150
+ # df = (
151
+ # Polars.datetime_range(
152
+ # DateTime.new(2001, 1, 1),
153
+ # DateTime.new(2001, 1, 2),
154
+ # "225m",
155
+ # eager: true
156
+ # )
157
+ # .alias("datetime")
158
+ # .to_frame
159
+ # )
160
+ # df.with_columns(Polars.col("datetime").dt.round("1h").alias("round"))
177
161
  # # =>
178
- # # shape: (7, 1)
179
- # # ┌─────────────────────┐
180
- # # │ dates
181
- # # │ --- │
182
- # # │ datetime[μs] │
183
- # # ╞═════════════════════╡
184
- # # │ 2001-01-01 00:00:00 │
185
- # # │ 2001-01-01 04:00:00 │
186
- # # │ 2001-01-01 08:00:00 │
187
- # # │ 2001-01-01 11:00:00 │
188
- # # │ 2001-01-01 15:00:00 │
189
- # # │ 2001-01-01 19:00:00 │
190
- # # │ 2001-01-01 23:00:00 │
191
- # # └─────────────────────┘
162
+ # # shape: (7, 2)
163
+ # # ┌─────────────────────┬─────────────────────┐
164
+ # # │ datetime ┆ round
165
+ # # │ --- ┆ ---
166
+ # # │ datetime[ns] ┆ datetime[ns]
167
+ # # ╞═════════════════════╪═════════════════════╡
168
+ # # │ 2001-01-01 00:00:00 ┆ 2001-01-01 00:00:00
169
+ # # │ 2001-01-01 03:45:00 ┆ 2001-01-01 04:00:00 │
170
+ # # │ 2001-01-01 07:30:00 ┆ 2001-01-01 08:00:00 │
171
+ # # │ 2001-01-01 11:15:00 ┆ 2001-01-01 11:00:00
172
+ # # │ 2001-01-01 15:00:00 ┆ 2001-01-01 15:00:00
173
+ # # │ 2001-01-01 18:45:00 ┆ 2001-01-01 19:00:00 │
174
+ # # │ 2001-01-01 22:30:00 ┆ 2001-01-01 23:00:00 │
175
+ # # └─────────────────────┴─────────────────────┘
192
176
  #
193
177
  # @example
194
- # start = DateTime.new(2001, 1, 1)
195
- # stop = DateTime.new(2001, 1, 1, 1)
196
- # df = Polars.date_range(start, stop, "10m", name: "dates").to_frame
197
- # df.select(["dates", Polars.col("dates").dt.round("30m").alias("round")])
178
+ # df = (
179
+ # Polars.datetime_range(
180
+ # DateTime.new(2001, 1, 1), DateTime.new(2001, 1, 1, 1), "10m", eager: true
181
+ # )
182
+ # .alias("datetime")
183
+ # .to_frame
184
+ # )
185
+ # df.with_columns(Polars.col("datetime").dt.round("30m").alias("round"))
198
186
  # # =>
199
187
  # # shape: (7, 2)
200
188
  # # ┌─────────────────────┬─────────────────────┐
201
- # # │ dates ┆ round │
189
+ # # │ datetime ┆ round │
202
190
  # # │ --- ┆ --- │
203
- # # │ datetime[μs] ┆ datetime[μs] │
191
+ # # │ datetime[ns] ┆ datetime[ns] │
204
192
  # # ╞═════════════════════╪═════════════════════╡
205
193
  # # │ 2001-01-01 00:00:00 ┆ 2001-01-01 00:00:00 │
206
194
  # # │ 2001-01-01 00:10:00 ┆ 2001-01-01 00:00:00 │
@@ -210,18 +198,9 @@ module Polars
210
198
  # # │ 2001-01-01 00:50:00 ┆ 2001-01-01 01:00:00 │
211
199
  # # │ 2001-01-01 01:00:00 ┆ 2001-01-01 01:00:00 │
212
200
  # # └─────────────────────┴─────────────────────┘
213
- def round(every, offset: nil)
214
- if offset.nil?
215
- offset = "0ns"
216
- end
217
-
218
- every = Utils.parse_as_expression(every, str_as_lit: true)
219
- Utils.wrap_expr(
220
- _rbexpr.dt_round(
221
- Utils._timedelta_to_pl_duration(every),
222
- Utils._timedelta_to_pl_duration(offset)
223
- )
224
- )
201
+ def round(every)
202
+ every = Utils.parse_into_expression(every, str_as_lit: true)
203
+ Utils.wrap_expr(_rbexpr.dt_round(every))
225
204
  end
226
205
 
227
206
  # Create a naive Datetime from an existing Date/Datetime expression and a Time.
@@ -239,8 +218,50 @@ module Polars
239
218
  unless time.is_a?(Time) || time.is_a?(Expr)
240
219
  raise TypeError, "expected 'time' to be a Ruby time or Polars expression, found #{time}"
241
220
  end
242
- time = Utils.expr_to_lit_or_expr(time)
243
- Utils.wrap_expr(_rbexpr.dt_combine(time._rbexpr, time_unit))
221
+ time = Utils.parse_into_expression(time)
222
+ Utils.wrap_expr(_rbexpr.dt_combine(time, time_unit))
223
+ end
224
+
225
+ # Convert a Date/Time/Datetime column into a String column with the given format.
226
+ #
227
+ # Similar to `cast(Polars::String)`, but this method allows you to customize the
228
+ # formatting of the resulting string.
229
+ #
230
+ # @param format [String]
231
+ # Format to use, refer to the `chrono strftime documentation
232
+ # <https://docs.rs/chrono/latest/chrono/format/strftime/index.html>`_
233
+ # for specification. Example: `"%y-%m-%d"`.
234
+ #
235
+ # @return [Expr]
236
+ #
237
+ # @example
238
+ # df = Polars::DataFrame.new(
239
+ # {
240
+ # "datetime" => [
241
+ # DateTime.new(2020, 3, 1),
242
+ # DateTime.new(2020, 4, 1),
243
+ # DateTime.new(2020, 5, 1)
244
+ # ]
245
+ # }
246
+ # )
247
+ # df.with_columns(
248
+ # Polars.col("datetime")
249
+ # .dt.to_string("%Y/%m/%d %H:%M:%S")
250
+ # .alias("datetime_string")
251
+ # )
252
+ # # =>
253
+ # # shape: (3, 2)
254
+ # # ┌─────────────────────┬─────────────────────┐
255
+ # # │ datetime ┆ datetime_string │
256
+ # # │ --- ┆ --- │
257
+ # # │ datetime[ns] ┆ str │
258
+ # # ╞═════════════════════╪═════════════════════╡
259
+ # # │ 2020-03-01 00:00:00 ┆ 2020/03/01 00:00:00 │
260
+ # # │ 2020-04-01 00:00:00 ┆ 2020/04/01 00:00:00 │
261
+ # # │ 2020-05-01 00:00:00 ┆ 2020/05/01 00:00:00 │
262
+ # # └─────────────────────┴─────────────────────┘
263
+ def to_string(format)
264
+ Utils.wrap_expr(_rbexpr.dt_to_string(format))
244
265
  end
245
266
 
246
267
  # Format Date/datetime with a formatting rule.
@@ -261,38 +282,26 @@ module Polars
261
282
  # @return [Expr]
262
283
  #
263
284
  # @example
264
- # start = DateTime.new(2001, 1, 1)
265
- # stop = DateTime.new(2002, 7, 1)
266
- # df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "180d")})
267
- # # =>
268
- # # shape: (4, 1)
269
- # # ┌─────────────────────┐
270
- # # │ date │
271
- # # │ --- │
272
- # # │ datetime[μs] │
273
- # # ╞═════════════════════╡
274
- # # │ 2001-01-01 00:00:00 │
275
- # # │ 2001-06-30 00:00:00 │
276
- # # │ 2001-12-27 00:00:00 │
277
- # # │ 2002-06-25 00:00:00 │
278
- # # └─────────────────────┘
279
- #
280
- # @example
281
- # df.select(Polars.col("date").dt.year)
285
+ # df = Polars::DataFrame.new(
286
+ # {"date" => [Date.new(1977, 1, 1), Date.new(1978, 1, 1), Date.new(1979, 1, 1)]}
287
+ # )
288
+ # df.with_columns(
289
+ # calendar_year: Polars.col("date").dt.year,
290
+ # iso_year: Polars.col("date").dt.iso_year
291
+ # )
282
292
  # # =>
283
- # # shape: (4, 1)
284
- # # ┌──────┐
285
- # # │ date │
286
- # # │ ---
287
- # # │ i32
288
- # # ╞══════╡
289
- # # │ 2001
290
- # # │ 2001
291
- # # │ 2001
292
- # # │ 2002 │
293
- # # └──────┘
293
+ # # shape: (3, 3)
294
+ # # ┌────────────┬───────────────┬──────────┐
295
+ # # │ date calendar_year ┆ iso_year
296
+ # # │ --- ┆ --- ┆ ---
297
+ # # │ date ┆ i32 ┆ i32
298
+ # # ╞════════════╪═══════════════╪══════════╡
299
+ # # │ 1977-01-01 ┆ 1977 ┆ 1976
300
+ # # │ 1978-01-01 ┆ 1978 ┆ 1977
301
+ # # │ 1979-01-01 ┆ 1979 ┆ 1979
302
+ # # └────────────┴───────────────┴──────────┘
294
303
  def year
295
- Utils.wrap_expr(_rbexpr.year)
304
+ Utils.wrap_expr(_rbexpr.dt_year)
296
305
  end
297
306
 
298
307
  # Determine whether the year of the underlying date is a leap year.
@@ -302,23 +311,23 @@ module Polars
302
311
  # @return [Expr]
303
312
  #
304
313
  # @example
305
- # start = DateTime.new(2000, 1, 1)
306
- # stop = DateTime.new(2002, 1, 1)
307
314
  # df = Polars::DataFrame.new(
308
- # {"date" => Polars.date_range(start, stop, "1y")}
315
+ # {"date" => [Date.new(2000, 1, 1), Date.new(2001, 1, 1), Date.new(2002, 1, 1)]}
316
+ # )
317
+ # df.with_columns(
318
+ # leap_year: Polars.col("date").dt.is_leap_year
309
319
  # )
310
- # df.select(Polars.col("date").dt.is_leap_year)
311
320
  # # =>
312
- # # shape: (3, 1)
313
- # # ┌───────┐
314
- # # │ date
315
- # # │ ---
316
- # # │ bool
317
- # # ╞═══════╡
318
- # # │ true
319
- # # │ false
320
- # # │ false
321
- # # └───────┘
321
+ # # shape: (3, 2)
322
+ # # ┌────────────┬───────────┐
323
+ # # │ date ┆ leap_year
324
+ # # │ --- ┆ ---
325
+ # # │ date ┆ bool
326
+ # # ╞════════════╪═══════════╡
327
+ # # │ 2000-01-01 ┆ true
328
+ # # │ 2001-01-01 ┆ false
329
+ # # │ 2002-01-01 ┆ false
330
+ # # └────────────┴───────────┘
322
331
  def is_leap_year
323
332
  Utils.wrap_expr(_rbexpr.dt_is_leap_year)
324
333
  end
@@ -331,8 +340,29 @@ module Polars
331
340
  # This may not correspond with the calendar year.
332
341
  #
333
342
  # @return [Expr]
343
+ #
344
+ # @example
345
+ # df = Polars::DataFrame.new(
346
+ # {"date" => [Date.new(1977, 1, 1), Date.new(1978, 1, 1), Date.new(1979, 1, 1)]}
347
+ # )
348
+ # df.select(
349
+ # "date",
350
+ # Polars.col("date").dt.year.alias("calendar_year"),
351
+ # Polars.col("date").dt.iso_year.alias("iso_year")
352
+ # )
353
+ # # =>
354
+ # # shape: (3, 3)
355
+ # # ┌────────────┬───────────────┬──────────┐
356
+ # # │ date ┆ calendar_year ┆ iso_year │
357
+ # # │ --- ┆ --- ┆ --- │
358
+ # # │ date ┆ i32 ┆ i32 │
359
+ # # ╞════════════╪═══════════════╪══════════╡
360
+ # # │ 1977-01-01 ┆ 1977 ┆ 1976 │
361
+ # # │ 1978-01-01 ┆ 1978 ┆ 1977 │
362
+ # # │ 1979-01-01 ┆ 1979 ┆ 1979 │
363
+ # # └────────────┴───────────────┴──────────┘
334
364
  def iso_year
335
- Utils.wrap_expr(_rbexpr.iso_year)
365
+ Utils.wrap_expr(_rbexpr.dt_iso_year)
336
366
  end
337
367
 
338
368
  # Extract quarter from underlying Date representation.
@@ -344,36 +374,23 @@ module Polars
344
374
  # @return [Expr]
345
375
  #
346
376
  # @example
347
- # start = DateTime.new(2001, 1, 1)
348
- # stop = DateTime.new(2002, 6, 1)
349
- # df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "180d")})
350
- # # =>
351
- # # shape: (3, 1)
352
- # # ┌─────────────────────┐
353
- # # │ date │
354
- # # │ --- │
355
- # # │ datetime[μs] │
356
- # # ╞═════════════════════╡
357
- # # │ 2001-01-01 00:00:00 │
358
- # # │ 2001-06-30 00:00:00 │
359
- # # │ 2001-12-27 00:00:00 │
360
- # # └─────────────────────┘
361
- #
362
- # @example
363
- # df.select(Polars.col("date").dt.quarter)
377
+ # df = Polars::DataFrame.new(
378
+ # {"date" => [Date.new(2001, 1, 1), Date.new(2001, 6, 30), Date.new(2001, 12, 27)]}
379
+ # )
380
+ # df.with_columns(Polars.col("date").dt.quarter.alias("quarter"))
364
381
  # # =>
365
- # # shape: (3, 1)
366
- # # ┌──────┐
367
- # # │ date │
368
- # # │ ---
369
- # # │ i8
370
- # # ╞══════╡
371
- # # │ 1
372
- # # │ 2
373
- # # │ 4
374
- # # └──────┘
382
+ # # shape: (3, 2)
383
+ # # ┌────────────┬─────────┐
384
+ # # │ date quarter
385
+ # # │ --- ┆ ---
386
+ # # │ date ┆ i8
387
+ # # ╞════════════╪═════════╡
388
+ # # │ 2001-01-01 ┆ 1
389
+ # # │ 2001-06-30 ┆ 2
390
+ # # │ 2001-12-27 ┆ 4
391
+ # # └────────────┴─────────┘
375
392
  def quarter
376
- Utils.wrap_expr(_rbexpr.quarter)
393
+ Utils.wrap_expr(_rbexpr.dt_quarter)
377
394
  end
378
395
 
379
396
  # Extract month from underlying Date representation.
@@ -386,36 +403,23 @@ module Polars
386
403
  # @return [Expr]
387
404
  #
388
405
  # @example
389
- # start = DateTime.new(2001, 1, 1)
390
- # stop = DateTime.new(2001, 4, 1)
391
- # df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "31d")})
392
- # # =>
393
- # # shape: (3, 1)
394
- # # ┌─────────────────────┐
395
- # # │ date │
396
- # # │ --- │
397
- # # │ datetime[μs] │
398
- # # ╞═════════════════════╡
399
- # # │ 2001-01-01 00:00:00 │
400
- # # │ 2001-02-01 00:00:00 │
401
- # # │ 2001-03-04 00:00:00 │
402
- # # └─────────────────────┘
403
- #
404
- # @example
405
- # df.select(Polars.col("date").dt.month)
406
+ # df = Polars::DataFrame.new(
407
+ # {"date" => [Date.new(2001, 1, 1), Date.new(2001, 6, 30), Date.new(2001, 12, 27)]}
408
+ # )
409
+ # df.with_columns(Polars.col("date").dt.month.alias("month"))
406
410
  # # =>
407
- # # shape: (3, 1)
408
- # # ┌──────┐
409
- # # │ date │
410
- # # │ ---
411
- # # │ i8
412
- # # ╞══════╡
413
- # # │ 1
414
- # # │ 2
415
- # # │ 3
416
- # # └──────┘
411
+ # # shape: (3, 2)
412
+ # # ┌────────────┬───────┐
413
+ # # │ date month
414
+ # # │ --- ┆ ---
415
+ # # │ date ┆ i8
416
+ # # ╞════════════╪═══════╡
417
+ # # │ 2001-01-01 ┆ 1
418
+ # # │ 2001-06-30 ┆ 6
419
+ # # │ 2001-12-27 ┆ 12
420
+ # # └────────────┴───────┘
417
421
  def month
418
- Utils.wrap_expr(_rbexpr.month)
422
+ Utils.wrap_expr(_rbexpr.dt_month)
419
423
  end
420
424
 
421
425
  # Extract the week from the underlying Date representation.
@@ -428,36 +432,23 @@ module Polars
428
432
  # @return [Expr]
429
433
  #
430
434
  # @example
431
- # start = DateTime.new(2001, 1, 1)
432
- # stop = DateTime.new(2001, 4, 1)
433
- # df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "31d")})
434
- # # =>
435
- # # shape: (3, 1)
436
- # # ┌─────────────────────┐
437
- # # │ date │
438
- # # │ --- │
439
- # # │ datetime[μs] │
440
- # # ╞═════════════════════╡
441
- # # │ 2001-01-01 00:00:00 │
442
- # # │ 2001-02-01 00:00:00 │
443
- # # │ 2001-03-04 00:00:00 │
444
- # # └─────────────────────┘
445
- #
446
- # @example
447
- # df.select(Polars.col("date").dt.week)
435
+ # df = Polars::DataFrame.new(
436
+ # {"date" => [Date.new(2001, 1, 1), Date.new(2001, 6, 30), Date.new(2001, 12, 27)]}
437
+ # )
438
+ # df.with_columns(Polars.col("date").dt.week.alias("week"))
448
439
  # # =>
449
- # # shape: (3, 1)
450
- # # ┌──────┐
451
- # # │ date │
452
- # # │ --- │
453
- # # │ i8 │
454
- # # ╞══════╡
455
- # # │ 1 │
456
- # # │ 5
457
- # # │ 9
458
- # # └──────┘
440
+ # # shape: (3, 2)
441
+ # # ┌────────────┬──────┐
442
+ # # │ date week
443
+ # # │ --- ┆ ---
444
+ # # │ date ┆ i8 │
445
+ # # ╞════════════╪══════╡
446
+ # # │ 2001-01-01 ┆ 1 │
447
+ # # │ 2001-06-30 ┆ 26
448
+ # # │ 2001-12-27 ┆ 52
449
+ # # └────────────┴──────┘
459
450
  def week
460
- Utils.wrap_expr(_rbexpr.week)
451
+ Utils.wrap_expr(_rbexpr.dt_week)
461
452
  end
462
453
 
463
454
  # Extract the week day from the underlying Date representation.
@@ -469,42 +460,32 @@ module Polars
469
460
  # @return [Expr]
470
461
  #
471
462
  # @example
472
- # start = DateTime.new(2001, 1, 1)
473
- # stop = DateTime.new(2001, 1, 9)
474
- # df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "3d")})
475
- # # =>
476
- # # shape: (3, 1)
477
- # # ┌─────────────────────┐
478
- # # │ date │
479
- # # │ --- │
480
- # # │ datetime[μs] │
481
- # # ╞═════════════════════╡
482
- # # │ 2001-01-01 00:00:00 │
483
- # # │ 2001-01-04 00:00:00 │
484
- # # │ 2001-01-07 00:00:00 │
485
- # # └─────────────────────┘
486
- #
487
- # @example
488
- # df.select(
489
- # [
490
- # Polars.col("date").dt.weekday.alias("weekday"),
491
- # Polars.col("date").dt.day.alias("day_of_month"),
492
- # Polars.col("date").dt.ordinal_day.alias("day_of_year")
493
- # ]
463
+ # df = Polars::DataFrame.new(
464
+ # {
465
+ # "date" => Polars.date_range(
466
+ # Date.new(2001, 12, 22), Date.new(2001, 12, 25), eager: true
467
+ # )
468
+ # }
469
+ # )
470
+ # df.with_columns(
471
+ # Polars.col("date").dt.weekday.alias("weekday"),
472
+ # Polars.col("date").dt.day.alias("day_of_month"),
473
+ # Polars.col("date").dt.ordinal_day.alias("day_of_year")
494
474
  # )
495
475
  # # =>
496
- # # shape: (3, 3)
497
- # # ┌─────────┬──────────────┬─────────────┐
498
- # # │ weekday ┆ day_of_month ┆ day_of_year │
499
- # # │ --- ┆ --- ┆ --- │
500
- # # │ i8 ┆ i8 ┆ i16 │
501
- # # ╞═════════╪══════════════╪═════════════╡
502
- # # │ 11 1
503
- # # │ 44 4
504
- # # │ 77 7
505
- # # └─────────┴──────────────┴─────────────┘
476
+ # # shape: (4, 4)
477
+ # # ┌────────────┬─────────┬──────────────┬─────────────┐
478
+ # # │ date ┆ weekday ┆ day_of_month ┆ day_of_year │
479
+ # # │ --- ┆ --- ┆ --- ┆ --- │
480
+ # # │ date ┆ i8 ┆ i8 ┆ i16 │
481
+ # # ╞════════════╪═════════╪══════════════╪═════════════╡
482
+ # # │ 2001-12-22 ┆ 622 356
483
+ # # │ 2001-12-23 ┆ 723 357
484
+ # # │ 2001-12-24 ┆ 124 358
485
+ # # │ 2001-12-25 ┆ 2 ┆ 25 ┆ 359 │
486
+ # # └────────────┴─────────┴──────────────┴─────────────┘
506
487
  def weekday
507
- Utils.wrap_expr(_rbexpr.weekday)
488
+ Utils.wrap_expr(_rbexpr.dt_weekday)
508
489
  end
509
490
 
510
491
  # Extract day from underlying Date representation.
@@ -517,42 +498,32 @@ module Polars
517
498
  # @return [Expr]
518
499
  #
519
500
  # @example
520
- # start = DateTime.new(2001, 1, 1)
521
- # stop = DateTime.new(2001, 1, 9)
522
- # df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "3d")})
523
- # # =>
524
- # # shape: (3, 1)
525
- # # ┌─────────────────────┐
526
- # # │ date │
527
- # # │ --- │
528
- # # │ datetime[μs] │
529
- # # ╞═════════════════════╡
530
- # # │ 2001-01-01 00:00:00 │
531
- # # │ 2001-01-04 00:00:00 │
532
- # # │ 2001-01-07 00:00:00 │
533
- # # └─────────────────────┘
534
- #
535
- # @example
536
- # df.select(
537
- # [
538
- # Polars.col("date").dt.weekday.alias("weekday"),
539
- # Polars.col("date").dt.day.alias("day_of_month"),
540
- # Polars.col("date").dt.ordinal_day.alias("day_of_year")
541
- # ]
501
+ # df = Polars::DataFrame.new(
502
+ # {
503
+ # "date" => Polars.date_range(
504
+ # Date.new(2001, 12, 22), Date.new(2001, 12, 25), eager: true
505
+ # )
506
+ # }
507
+ # )
508
+ # df.with_columns(
509
+ # Polars.col("date").dt.weekday.alias("weekday"),
510
+ # Polars.col("date").dt.day.alias("day_of_month"),
511
+ # Polars.col("date").dt.ordinal_day.alias("day_of_year")
542
512
  # )
543
513
  # # =>
544
- # # shape: (3, 3)
545
- # # ┌─────────┬──────────────┬─────────────┐
546
- # # │ weekday ┆ day_of_month ┆ day_of_year │
547
- # # │ --- ┆ --- ┆ --- │
548
- # # │ i8 ┆ i8 ┆ i16 │
549
- # # ╞═════════╪══════════════╪═════════════╡
550
- # # │ 11 1
551
- # # │ 44 4
552
- # # │ 77 7
553
- # # └─────────┴──────────────┴─────────────┘
514
+ # # shape: (4, 4)
515
+ # # ┌────────────┬─────────┬──────────────┬─────────────┐
516
+ # # │ date ┆ weekday ┆ day_of_month ┆ day_of_year │
517
+ # # │ --- ┆ --- ┆ --- ┆ --- │
518
+ # # │ date ┆ i8 ┆ i8 ┆ i16 │
519
+ # # ╞════════════╪═════════╪══════════════╪═════════════╡
520
+ # # │ 2001-12-22 ┆ 622 356
521
+ # # │ 2001-12-23 ┆ 723 357
522
+ # # │ 2001-12-24 ┆ 124 358
523
+ # # │ 2001-12-25 ┆ 2 ┆ 25 ┆ 359 │
524
+ # # └────────────┴─────────┴──────────────┴─────────────┘
554
525
  def day
555
- Utils.wrap_expr(_rbexpr.day)
526
+ Utils.wrap_expr(_rbexpr.dt_day)
556
527
  end
557
528
 
558
529
  # Extract ordinal day from underlying Date representation.
@@ -565,42 +536,32 @@ module Polars
565
536
  # @return [Expr]
566
537
  #
567
538
  # @example
568
- # start = DateTime.new(2001, 1, 1)
569
- # stop = DateTime.new(2001, 1, 9)
570
- # df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "3d")})
571
- # # =>
572
- # # shape: (3, 1)
573
- # # ┌─────────────────────┐
574
- # # │ date │
575
- # # │ --- │
576
- # # │ datetime[μs] │
577
- # # ╞═════════════════════╡
578
- # # │ 2001-01-01 00:00:00 │
579
- # # │ 2001-01-04 00:00:00 │
580
- # # │ 2001-01-07 00:00:00 │
581
- # # └─────────────────────┘
582
- #
583
- # @example
584
- # df.select(
585
- # [
586
- # Polars.col("date").dt.weekday.alias("weekday"),
587
- # Polars.col("date").dt.day.alias("day_of_month"),
588
- # Polars.col("date").dt.ordinal_day.alias("day_of_year")
589
- # ]
539
+ # df = Polars::DataFrame.new(
540
+ # {
541
+ # "date" => Polars.date_range(
542
+ # Date.new(2001, 12, 22), Date.new(2001, 12, 25), eager: true
543
+ # )
544
+ # }
545
+ # )
546
+ # df.with_columns(
547
+ # Polars.col("date").dt.weekday.alias("weekday"),
548
+ # Polars.col("date").dt.day.alias("day_of_month"),
549
+ # Polars.col("date").dt.ordinal_day.alias("day_of_year")
590
550
  # )
591
551
  # # =>
592
- # # shape: (3, 3)
593
- # # ┌─────────┬──────────────┬─────────────┐
594
- # # │ weekday ┆ day_of_month ┆ day_of_year │
595
- # # │ --- ┆ --- ┆ --- │
596
- # # │ i8 ┆ i8 ┆ i16 │
597
- # # ╞═════════╪══════════════╪═════════════╡
598
- # # │ 11 1
599
- # # │ 44 4
600
- # # │ 77 7
601
- # # └─────────┴──────────────┴─────────────┘
552
+ # # shape: (4, 4)
553
+ # # ┌────────────┬─────────┬──────────────┬─────────────┐
554
+ # # │ date ┆ weekday ┆ day_of_month ┆ day_of_year │
555
+ # # │ --- ┆ --- ┆ --- ┆ --- │
556
+ # # │ date ┆ i8 ┆ i8 ┆ i16 │
557
+ # # ╞════════════╪═════════╪══════════════╪═════════════╡
558
+ # # │ 2001-12-22 ┆ 622 356
559
+ # # │ 2001-12-23 ┆ 723 357
560
+ # # │ 2001-12-24 ┆ 124 358
561
+ # # │ 2001-12-25 ┆ 2 ┆ 25 ┆ 359 │
562
+ # # └────────────┴─────────┴──────────────┴─────────────┘
602
563
  def ordinal_day
603
- Utils.wrap_expr(_rbexpr.ordinal_day)
564
+ Utils.wrap_expr(_rbexpr.dt_ordinal_day)
604
565
  end
605
566
 
606
567
  # Time
@@ -633,36 +594,34 @@ module Polars
633
594
  # @return [Expr]
634
595
  #
635
596
  # @example
636
- # start = DateTime.new(2001, 1, 1)
637
- # stop = DateTime.new(2001, 1, 2)
638
- # df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "12h")})
639
- # # =>
640
- # # shape: (3, 1)
641
- # # ┌─────────────────────┐
642
- # # │ date │
643
- # # │ --- │
644
- # # │ datetime[μs] │
645
- # # ╞═════════════════════╡
646
- # # │ 2001-01-01 00:00:00 │
647
- # # │ 2001-01-01 12:00:00 │
648
- # # │ 2001-01-02 00:00:00 │
649
- # # └─────────────────────┘
650
- #
651
- # @example
652
- # df.select(Polars.col("date").dt.hour)
597
+ # df = Polars::DataFrame.new(
598
+ # {
599
+ # "datetime" => [
600
+ # Time.utc(1978, 1, 1, 1, 1, 1, 0),
601
+ # Time.utc(2024, 10, 13, 5, 30, 14, 500_000),
602
+ # Time.utc(2065, 1, 1, 10, 20, 30, 60_000)
603
+ # ]
604
+ # }
605
+ # )
606
+ # df.with_columns(
607
+ # Polars.col("datetime").dt.hour.alias("hour"),
608
+ # Polars.col("datetime").dt.minute.alias("minute"),
609
+ # Polars.col("datetime").dt.second.alias("second"),
610
+ # Polars.col("datetime").dt.millisecond.alias("millisecond")
611
+ # )
653
612
  # # =>
654
- # # shape: (3, 1)
655
- # # ┌──────┐
656
- # # │ date
657
- # # │ --- │
658
- # # │ i8 │
659
- # # ╞══════╡
660
- # # │ 0
661
- # # │ 12
662
- # # │ 0
663
- # # └──────┘
613
+ # # shape: (3, 5)
614
+ # # ┌─────────────────────────┬──────┬────────┬────────┬─────────────┐
615
+ # # │ datetime ┆ hour ┆ minute ┆ second ┆ millisecond
616
+ # # │ --- ┆ --- ┆ --- ┆ --- ┆ ---
617
+ # # │ datetime[ns] ┆ i8 ┆ i8 ┆ i8 ┆ i32
618
+ # # ╞═════════════════════════╪══════╪════════╪════════╪═════════════╡
619
+ # # │ 1978-01-01 01:01:01 ┆ 1 ┆ 1 ┆ 1 ┆ 0
620
+ # # │ 2024-10-13 05:30:14.500 ┆ 5 ┆ 30 ┆ 14 ┆ 500
621
+ # # │ 2065-01-01 10:20:30.060 ┆ 10 ┆ 20 ┆ 30 ┆ 60
622
+ # # └─────────────────────────┴──────┴────────┴────────┴─────────────┘
664
623
  def hour
665
- Utils.wrap_expr(_rbexpr.hour)
624
+ Utils.wrap_expr(_rbexpr.dt_hour)
666
625
  end
667
626
 
668
627
  # Extract minutes from underlying DateTime representation.
@@ -674,36 +633,34 @@ module Polars
674
633
  # @return [Expr]
675
634
  #
676
635
  # @example
677
- # start = DateTime.new(2001, 1, 1)
678
- # stop = DateTime.new(2001, 1, 1, 0, 4, 0)
679
- # df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "2m")})
680
- # # =>
681
- # # shape: (3, 1)
682
- # # ┌─────────────────────┐
683
- # # │ date │
684
- # # │ --- │
685
- # # │ datetime[μs] │
686
- # # ╞═════════════════════╡
687
- # # │ 2001-01-01 00:00:00 │
688
- # # │ 2001-01-01 00:02:00 │
689
- # # │ 2001-01-01 00:04:00 │
690
- # # └─────────────────────┘
691
- #
692
- # @example
693
- # df.select(Polars.col("date").dt.minute)
636
+ # df = Polars::DataFrame.new(
637
+ # {
638
+ # "datetime" => [
639
+ # Time.utc(1978, 1, 1, 1, 1, 1, 0),
640
+ # Time.utc(2024, 10, 13, 5, 30, 14, 500_000),
641
+ # Time.utc(2065, 1, 1, 10, 20, 30, 60_000)
642
+ # ]
643
+ # }
644
+ # )
645
+ # df.with_columns(
646
+ # Polars.col("datetime").dt.hour.alias("hour"),
647
+ # Polars.col("datetime").dt.minute.alias("minute"),
648
+ # Polars.col("datetime").dt.second.alias("second"),
649
+ # Polars.col("datetime").dt.millisecond.alias("millisecond")
650
+ # )
694
651
  # # =>
695
- # # shape: (3, 1)
696
- # # ┌──────┐
697
- # # │ date
698
- # # │ --- │
699
- # # │ i8 │
700
- # # ╞══════╡
701
- # # │ 0
702
- # # │ 2
703
- # # │ 4
704
- # # └──────┘
652
+ # # shape: (3, 5)
653
+ # # ┌─────────────────────────┬──────┬────────┬────────┬─────────────┐
654
+ # # │ datetime ┆ hour ┆ minute ┆ second ┆ millisecond
655
+ # # │ --- ┆ --- ┆ --- ┆ --- ┆ ---
656
+ # # │ datetime[ns] ┆ i8 ┆ i8 ┆ i8 ┆ i32
657
+ # # ╞═════════════════════════╪══════╪════════╪════════╪═════════════╡
658
+ # # │ 1978-01-01 01:01:01 ┆ 1 ┆ 1 ┆ 1 ┆ 0
659
+ # # │ 2024-10-13 05:30:14.500 ┆ 5 ┆ 30 ┆ 14 ┆ 500
660
+ # # │ 2065-01-01 10:20:30.060 ┆ 10 ┆ 20 ┆ 30 ┆ 60
661
+ # # └─────────────────────────┴──────┴────────┴────────┴─────────────┘
705
662
  def minute
706
- Utils.wrap_expr(_rbexpr.minute)
663
+ Utils.wrap_expr(_rbexpr.dt_minute)
707
664
  end
708
665
 
709
666
  # Extract seconds from underlying DateTime representation.
@@ -719,87 +676,52 @@ module Polars
719
676
  # @example
720
677
  # df = Polars::DataFrame.new(
721
678
  # {
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
- # )
679
+ # "datetime" => [
680
+ # Time.utc(1978, 1, 1, 1, 1, 1, 0),
681
+ # Time.utc(2024, 10, 13, 5, 30, 14, 500_000),
682
+ # Time.utc(2065, 1, 1, 10, 20, 30, 60_000)
683
+ # ]
727
684
  # }
728
685
  # )
729
- # # =>
730
- # # shape: (3, 1)
731
- # # ┌────────────────────────────┐
732
- # # │ date │
733
- # # │ --- │
734
- # # │ datetime[μs] │
735
- # # ╞════════════════════════════╡
736
- # # │ 2001-01-01 00:00:00.456789 │
737
- # # │ 2001-01-01 00:00:03.111110 │
738
- # # │ 2001-01-01 00:00:05.765431 │
739
- # # └────────────────────────────┘
740
- #
741
- # @example
742
- # df.select(Polars.col("date").dt.second.alias("secs"))
743
- # # =>
744
- # # shape: (3, 1)
745
- # # ┌──────┐
746
- # # │ secs │
747
- # # │ --- │
748
- # # │ i8 │
749
- # # ╞══════╡
750
- # # │ 0 │
751
- # # │ 3 │
752
- # # │ 5 │
753
- # # └──────┘
754
- #
755
- # df.select(Polars.col("date").dt.second(fractional: true).alias("secs"))
756
- # # =>
757
- # # shape: (3, 1)
758
- # # ┌──────────┐
759
- # # │ secs │
760
- # # │ --- │
761
- # # │ f64 │
762
- # # ╞══════════╡
763
- # # │ 0.456789 │
764
- # # │ 3.11111 │
765
- # # │ 5.765431 │
766
- # # └──────────┘
767
- #
768
- # @example
769
- # start = DateTime.new(2001, 1, 1)
770
- # stop = DateTime.new(2001, 1, 1, 0, 0, 4)
771
- # df = Polars::DataFrame.new(
772
- # {"date" => Polars.date_range(start, stop, "2s")}
686
+ # df.with_columns(
687
+ # Polars.col("datetime").dt.hour.alias("hour"),
688
+ # Polars.col("datetime").dt.minute.alias("minute"),
689
+ # Polars.col("datetime").dt.second.alias("second"),
690
+ # Polars.col("datetime").dt.millisecond.alias("millisecond")
773
691
  # )
774
692
  # # =>
775
- # # shape: (3, 1)
776
- # # ┌─────────────────────┐
777
- # # │ date
778
- # # │ ---
779
- # # │ datetime[μs]
780
- # # ╞═════════════════════╡
781
- # # │ 2001-01-01 00:00:00
782
- # # │ 2001-01-01 00:00:02
783
- # # │ 2001-01-01 00:00:04
784
- # # └─────────────────────┘
693
+ # # shape: (3, 5)
694
+ # # ┌─────────────────────────┬──────┬────────┬────────┬─────────────┐
695
+ # # │ datetime ┆ hour ┆ minute ┆ second ┆ millisecond
696
+ # # │ --- ┆ --- ┆ --- ┆ --- ┆ ---
697
+ # # │ datetime[ns] ┆ i8 ┆ i8 ┆ i8 ┆ i32
698
+ # # ╞═════════════════════════╪══════╪════════╪════════╪═════════════╡
699
+ # # │ 1978-01-01 01:01:01 ┆ 1 ┆ 1 ┆ 1 ┆ 0
700
+ # # │ 2024-10-13 05:30:14.500 ┆ 5 ┆ 30 ┆ 14 ┆ 500
701
+ # # │ 2065-01-01 10:20:30.060 ┆ 10 ┆ 20 ┆ 30 ┆ 60
702
+ # # └─────────────────────────┴──────┴────────┴────────┴─────────────┘
785
703
  #
786
704
  # @example
787
- # df.select(Polars.col("date").dt.second)
705
+ # df.with_columns(
706
+ # Polars.col("datetime").dt.hour.alias("hour"),
707
+ # Polars.col("datetime").dt.minute.alias("minute"),
708
+ # Polars.col("datetime").dt.second(fractional: true).alias("second")
709
+ # )
788
710
  # # =>
789
- # # shape: (3, 1)
790
- # # ┌──────┐
791
- # # │ date
792
- # # │ --- │
793
- # # │ i8 │
794
- # # ╞══════╡
795
- # # │ 0 │
796
- # # │ 2
797
- # # │ 4
798
- # # └──────┘
711
+ # # shape: (3, 4)
712
+ # # ┌─────────────────────────┬──────┬────────┬────────┐
713
+ # # │ datetime ┆ hour ┆ minute ┆ second
714
+ # # │ --- ┆ --- ┆ --- ┆ ---
715
+ # # │ datetime[ns] ┆ i8 ┆ i8 ┆ f64
716
+ # # ╞═════════════════════════╪══════╪════════╪════════╡
717
+ # # │ 1978-01-01 01:01:01 ┆ 1 ┆ 1 ┆ 1.0 │
718
+ # # │ 2024-10-13 05:30:14.500 ┆ 5 ┆ 30 ┆ 14.5
719
+ # # │ 2065-01-01 10:20:30.060 ┆ 10 ┆ 20 ┆ 30.06
720
+ # # └─────────────────────────┴──────┴────────┴────────┘
799
721
  def second(fractional: false)
800
- sec = Utils.wrap_expr(_rbexpr.second)
722
+ sec = Utils.wrap_expr(_rbexpr.dt_second)
801
723
  if fractional
802
- sec + (Utils.wrap_expr(_rbexpr.nanosecond) / Utils.lit(1_000_000_000.0))
724
+ sec + (Utils.wrap_expr(_rbexpr.dt_nanosecond) / F.lit(1_000_000_000.0))
803
725
  else
804
726
  sec
805
727
  end
@@ -811,7 +733,7 @@ module Polars
811
733
  #
812
734
  # @return [Expr]
813
735
  def millisecond
814
- Utils.wrap_expr(_rbexpr.millisecond)
736
+ Utils.wrap_expr(_rbexpr.dt_millisecond)
815
737
  end
816
738
 
817
739
  # Extract microseconds from underlying DateTime representation.
@@ -820,7 +742,7 @@ module Polars
820
742
  #
821
743
  # @return [Expr]
822
744
  def microsecond
823
- Utils.wrap_expr(_rbexpr.microsecond)
745
+ Utils.wrap_expr(_rbexpr.dt_microsecond)
824
746
  end
825
747
 
826
748
  # Extract nanoseconds from underlying DateTime representation.
@@ -829,81 +751,79 @@ module Polars
829
751
  #
830
752
  # @return [Expr]
831
753
  def nanosecond
832
- Utils.wrap_expr(_rbexpr.nanosecond)
754
+ Utils.wrap_expr(_rbexpr.dt_nanosecond)
833
755
  end
834
756
 
835
757
  # Get the time passed since the Unix EPOCH in the give time unit.
836
758
  #
837
- # @param tu ["us", "ns", "ms", "s", "d"]
759
+ # @param time_unit ["us", "ns", "ms", "s", "d"]
838
760
  # Time unit.
839
761
  #
840
762
  # @return [Expr]
841
763
  #
842
764
  # @example
843
- # start = DateTime.new(2001, 1, 1)
844
- # stop = DateTime.new(2001, 1, 3)
845
- # df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "1d")})
846
- # df.select(
847
- # [
848
- # Polars.col("date"),
849
- # Polars.col("date").dt.epoch.alias("epoch_ns"),
850
- # Polars.col("date").dt.epoch("s").alias("epoch_s")
851
- # ]
765
+ # df = (
766
+ # Polars.date_range(Date.new(2001, 1, 1), Date.new(2001, 1, 3), eager: true)
767
+ # .alias("date")
768
+ # .to_frame
769
+ # )
770
+ # df.with_columns(
771
+ # Polars.col("date").dt.epoch.alias("epoch_ns"),
772
+ # Polars.col("date").dt.epoch("s").alias("epoch_s")
852
773
  # )
853
774
  # # =>
854
775
  # # shape: (3, 3)
855
- # # ┌─────────────────────┬─────────────────┬───────────┐
856
- # # │ date ┆ epoch_ns ┆ epoch_s │
857
- # # │ --- ┆ --- ┆ --- │
858
- # # │ datetime[μs] ┆ i64 ┆ i64 │
859
- # # ╞═════════════════════╪═════════════════╪═══════════╡
860
- # # │ 2001-01-01 00:00:00 ┆ 978307200000000 ┆ 978307200 │
861
- # # │ 2001-01-02 00:00:00 ┆ 978393600000000 ┆ 978393600 │
862
- # # │ 2001-01-03 00:00:00 ┆ 978480000000000 ┆ 978480000 │
863
- # # └─────────────────────┴─────────────────┴───────────┘
864
- def epoch(tu = "us")
865
- if Utils::DTYPE_TEMPORAL_UNITS.include?(tu)
866
- timestamp(tu)
867
- elsif tu == "s"
776
+ # # ┌────────────┬─────────────────┬───────────┐
777
+ # # │ date ┆ epoch_ns ┆ epoch_s │
778
+ # # │ --- ┆ --- ┆ --- │
779
+ # # │ date ┆ i64 ┆ i64 │
780
+ # # ╞════════════╪═════════════════╪═══════════╡
781
+ # # │ 2001-01-01 ┆ 978307200000000 ┆ 978307200 │
782
+ # # │ 2001-01-02 ┆ 978393600000000 ┆ 978393600 │
783
+ # # │ 2001-01-03 ┆ 978480000000000 ┆ 978480000 │
784
+ # # └────────────┴─────────────────┴───────────┘
785
+ def epoch(time_unit = "us")
786
+ if Utils::DTYPE_TEMPORAL_UNITS.include?(time_unit)
787
+ timestamp(time_unit)
788
+ elsif time_unit == "s"
868
789
  Utils.wrap_expr(_rbexpr.dt_epoch_seconds)
869
- elsif tu == "d"
790
+ elsif time_unit == "d"
870
791
  Utils.wrap_expr(_rbexpr).cast(:date).cast(:i32)
871
792
  else
872
- raise ArgumentError, "tu must be one of {{'ns', 'us', 'ms', 's', 'd'}}, got #{tu}"
793
+ raise ArgumentError, "time_unit must be one of {'ns', 'us', 'ms', 's', 'd'}, got #{time_unit.inspect}"
873
794
  end
874
795
  end
875
796
 
876
797
  # Return a timestamp in the given time unit.
877
798
  #
878
- # @param tu ["us", "ns", "ms"]
799
+ # @param time_unit ["us", "ns", "ms"]
879
800
  # Time unit.
880
801
  #
881
802
  # @return [Expr]
882
803
  #
883
804
  # @example
884
- # start = DateTime.new(2001, 1, 1)
885
- # stop = DateTime.new(2001, 1, 3)
886
- # df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "1d")})
887
- # df.select(
888
- # [
889
- # Polars.col("date"),
890
- # Polars.col("date").dt.timestamp.alias("timestamp_ns"),
891
- # Polars.col("date").dt.timestamp("ms").alias("timestamp_ms")
892
- # ]
805
+ # df = (
806
+ # Polars.date_range(Date.new(2001, 1, 1), Date.new(2001, 1, 3), eager: true)
807
+ # .alias("date")
808
+ # .to_frame
809
+ # )
810
+ # df.with_columns(
811
+ # Polars.col("date").dt.timestamp.alias("timestamp_us"),
812
+ # Polars.col("date").dt.timestamp("ms").alias("timestamp_ms")
893
813
  # )
894
814
  # # =>
895
815
  # # shape: (3, 3)
896
- # # ┌─────────────────────┬─────────────────┬──────────────┐
897
- # # │ date timestamp_ns ┆ timestamp_ms │
898
- # # │ --- ┆ --- ┆ --- │
899
- # # │ datetime[μs] ┆ i64 ┆ i64 │
900
- # # ╞═════════════════════╪═════════════════╪══════════════╡
901
- # # │ 2001-01-01 00:00:00 ┆ 978307200000000 ┆ 978307200000 │
902
- # # │ 2001-01-02 00:00:00 ┆ 978393600000000 ┆ 978393600000 │
903
- # # │ 2001-01-03 00:00:00 ┆ 978480000000000 ┆ 978480000000 │
904
- # # └─────────────────────┴─────────────────┴──────────────┘
905
- def timestamp(tu = "us")
906
- Utils.wrap_expr(_rbexpr.timestamp(tu))
816
+ # # ┌────────────┬─────────────────┬──────────────┐
817
+ # # │ date timestamp_us ┆ timestamp_ms │
818
+ # # │ --- ┆ --- ┆ --- │
819
+ # # │ date ┆ i64 ┆ i64 │
820
+ # # ╞════════════╪═════════════════╪══════════════╡
821
+ # # │ 2001-01-01 ┆ 978307200000000 ┆ 978307200000 │
822
+ # # │ 2001-01-02 ┆ 978393600000000 ┆ 978393600000 │
823
+ # # │ 2001-01-03 ┆ 978480000000000 ┆ 978480000000 │
824
+ # # └────────────┴─────────────────┴──────────────┘
825
+ def timestamp(time_unit = "us")
826
+ Utils.wrap_expr(_rbexpr.dt_timestamp(time_unit))
907
827
  end
908
828
 
909
829
  # Set time unit of a Series of dtype Datetime or Duration.
@@ -911,43 +831,17 @@ module Polars
911
831
  # This does not modify underlying data, and should be used to fix an incorrect
912
832
  # time unit.
913
833
  #
914
- # @param tu ["ns", "us", "ms"]
834
+ # @param time_unit ["ns", "us", "ms"]
915
835
  # Time unit for the `Datetime` Series.
916
836
  #
917
837
  # @return [Expr]
918
- #
919
- # @example
920
- # df = Polars::DataFrame.new(
921
- # {
922
- # "date" => Polars.date_range(
923
- # DateTime.new(2001, 1, 1), DateTime.new(2001, 1, 3), "1d", time_unit: "ns"
924
- # )
925
- # }
926
- # )
927
- # df.select(
928
- # [
929
- # Polars.col("date"),
930
- # Polars.col("date").dt.with_time_unit("us").alias("tu_us")
931
- # ]
932
- # )
933
- # # =>
934
- # # shape: (3, 2)
935
- # # ┌─────────────────────┬───────────────────────┐
936
- # # │ date ┆ tu_us │
937
- # # │ --- ┆ --- │
938
- # # │ datetime[ns] ┆ datetime[μs] │
939
- # # ╞═════════════════════╪═══════════════════════╡
940
- # # │ 2001-01-01 00:00:00 ┆ +32971-04-28 00:00:00 │
941
- # # │ 2001-01-02 00:00:00 ┆ +32974-01-22 00:00:00 │
942
- # # │ 2001-01-03 00:00:00 ┆ +32976-10-18 00:00:00 │
943
- # # └─────────────────────┴───────────────────────┘
944
- def with_time_unit(tu)
945
- Utils.wrap_expr(_rbexpr.dt_with_time_unit(tu))
838
+ def with_time_unit(time_unit)
839
+ Utils.wrap_expr(_rbexpr.dt_with_time_unit(time_unit))
946
840
  end
947
841
 
948
842
  # Cast the underlying data to another time unit. This may lose precision.
949
843
  #
950
- # @param tu ["ns", "us", "ms"]
844
+ # @param time_unit ["ns", "us", "ms"]
951
845
  # Time unit for the `Datetime` Series.
952
846
  #
953
847
  # @return [Expr]
@@ -955,8 +849,8 @@ module Polars
955
849
  # @example
956
850
  # df = Polars::DataFrame.new(
957
851
  # {
958
- # "date" => Polars.date_range(
959
- # DateTime.new(2001, 1, 1), DateTime.new(2001, 1, 3), "1d"
852
+ # "date" => Polars.datetime_range(
853
+ # DateTime.new(2001, 1, 1), DateTime.new(2001, 1, 3), "1d", eager: true
960
854
  # )
961
855
  # }
962
856
  # )
@@ -972,19 +866,19 @@ module Polars
972
866
  # # ┌─────────────────────┬─────────────────────┬─────────────────────┐
973
867
  # # │ date ┆ tu_ms ┆ tu_ns │
974
868
  # # │ --- ┆ --- ┆ --- │
975
- # # │ datetime[μs] ┆ datetime[ms] ┆ datetime[ns] │
869
+ # # │ datetime[ns] ┆ datetime[ms] ┆ datetime[ns] │
976
870
  # # ╞═════════════════════╪═════════════════════╪═════════════════════╡
977
871
  # # │ 2001-01-01 00:00:00 ┆ 2001-01-01 00:00:00 ┆ 2001-01-01 00:00:00 │
978
872
  # # │ 2001-01-02 00:00:00 ┆ 2001-01-02 00:00:00 ┆ 2001-01-02 00:00:00 │
979
873
  # # │ 2001-01-03 00:00:00 ┆ 2001-01-03 00:00:00 ┆ 2001-01-03 00:00:00 │
980
874
  # # └─────────────────────┴─────────────────────┴─────────────────────┘
981
- def cast_time_unit(tu)
982
- Utils.wrap_expr(_rbexpr.dt_cast_time_unit(tu))
875
+ def cast_time_unit(time_unit)
876
+ Utils.wrap_expr(_rbexpr.dt_cast_time_unit(time_unit))
983
877
  end
984
878
 
985
879
  # Set time zone for a Series of type Datetime.
986
880
  #
987
- # @param tz [String]
881
+ # @param time_zone [String]
988
882
  # Time zone for the `Datetime` Series.
989
883
  #
990
884
  # @return [Expr]
@@ -992,11 +886,12 @@ module Polars
992
886
  # @example
993
887
  # df = Polars::DataFrame.new(
994
888
  # {
995
- # "date" => Polars.date_range(
889
+ # "date" => Polars.datetime_range(
996
890
  # DateTime.new(2020, 3, 1),
997
891
  # DateTime.new(2020, 5, 1),
998
892
  # "1mo",
999
- # time_zone: "UTC"
893
+ # time_zone: "UTC",
894
+ # eager: true
1000
895
  # )
1001
896
  # }
1002
897
  # )
@@ -1013,14 +908,14 @@ module Polars
1013
908
  # # ┌─────────────────────────┬─────────────────────────────┐
1014
909
  # # │ date ┆ London │
1015
910
  # # │ --- ┆ --- │
1016
- # # │ datetime[μs, UTC] ┆ datetime[μs, Europe/London] │
911
+ # # │ datetime[ns, UTC] ┆ datetime[ns, Europe/London] │
1017
912
  # # ╞═════════════════════════╪═════════════════════════════╡
1018
913
  # # │ 2020-03-01 00:00:00 UTC ┆ 2020-03-01 00:00:00 GMT │
1019
914
  # # │ 2020-04-01 00:00:00 UTC ┆ 2020-04-01 01:00:00 BST │
1020
915
  # # │ 2020-05-01 00:00:00 UTC ┆ 2020-05-01 01:00:00 BST │
1021
916
  # # └─────────────────────────┴─────────────────────────────┘
1022
- def convert_time_zone(tz)
1023
- Utils.wrap_expr(_rbexpr.dt_convert_time_zone(tz))
917
+ def convert_time_zone(time_zone)
918
+ Utils.wrap_expr(_rbexpr.dt_convert_time_zone(time_zone))
1024
919
  end
1025
920
 
1026
921
  # Cast time zone for a Series of type Datetime.
@@ -1030,17 +925,16 @@ module Polars
1030
925
  #
1031
926
  # @param time_zone [String]
1032
927
  # Time zone for the `Datetime` Series. Pass `nil` to unset time zone.
1033
- # @param use_earliest [Boolean]
1034
- # Determine how to deal with ambiguous datetimes.
1035
928
  # @param ambiguous [String]
1036
929
  # Determine how to deal with ambiguous datetimes.
1037
930
  # @param non_existent [String]
1038
931
  # Determine how to deal with non-existent datetimes.
1039
932
  #
1040
933
  # @return [Expr]
1041
- def replace_time_zone(time_zone, use_earliest: nil, ambiguous: "raise", non_existent: "raise")
1042
- ambiguous = Utils.rename_use_earliest_to_ambiguous(use_earliest, ambiguous)
1043
- ambiguous = Polars.lit(ambiguous) unless ambiguous.is_a?(Expr)
934
+ def replace_time_zone(time_zone, ambiguous: "raise", non_existent: "raise")
935
+ unless ambiguous.is_a?(Expr)
936
+ ambiguous = Polars.lit(ambiguous)
937
+ end
1044
938
  Utils.wrap_expr(_rbexpr.dt_replace_time_zone(time_zone, ambiguous._rbexpr, non_existent))
1045
939
  end
1046
940
 
@@ -1051,8 +945,8 @@ module Polars
1051
945
  # @example
1052
946
  # df = Polars::DataFrame.new(
1053
947
  # {
1054
- # "date" => Polars.date_range(
1055
- # DateTime.new(2020, 3, 1), DateTime.new(2020, 5, 1), "1mo"
948
+ # "date" => Polars.datetime_range(
949
+ # DateTime.new(2020, 3, 1), DateTime.new(2020, 5, 1), "1mo", eager: true
1056
950
  # )
1057
951
  # }
1058
952
  # )
@@ -1067,7 +961,7 @@ module Polars
1067
961
  # # ┌─────────────────────┬───────────┐
1068
962
  # # │ date ┆ days_diff │
1069
963
  # # │ --- ┆ --- │
1070
- # # │ datetime[μs] ┆ i64 │
964
+ # # │ datetime[ns] ┆ i64 │
1071
965
  # # ╞═════════════════════╪═══════════╡
1072
966
  # # │ 2020-03-01 00:00:00 ┆ null │
1073
967
  # # │ 2020-04-01 00:00:00 ┆ 31 │
@@ -1085,8 +979,8 @@ module Polars
1085
979
  # @example
1086
980
  # df = Polars::DataFrame.new(
1087
981
  # {
1088
- # "date" => Polars.date_range(
1089
- # DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 4), "1d"
982
+ # "date" => Polars.datetime_range(
983
+ # DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 4), "1d", eager: true
1090
984
  # )
1091
985
  # }
1092
986
  # )
@@ -1101,7 +995,7 @@ module Polars
1101
995
  # # ┌─────────────────────┬────────────┐
1102
996
  # # │ date ┆ hours_diff │
1103
997
  # # │ --- ┆ --- │
1104
- # # │ datetime[μs] ┆ i64 │
998
+ # # │ datetime[ns] ┆ i64 │
1105
999
  # # ╞═════════════════════╪════════════╡
1106
1000
  # # │ 2020-01-01 00:00:00 ┆ null │
1107
1001
  # # │ 2020-01-02 00:00:00 ┆ 24 │
@@ -1120,8 +1014,8 @@ module Polars
1120
1014
  # @example
1121
1015
  # df = Polars::DataFrame.new(
1122
1016
  # {
1123
- # "date" => Polars.date_range(
1124
- # DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 4), "1d"
1017
+ # "date" => Polars.datetime_range(
1018
+ # DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 4), "1d", eager: true
1125
1019
  # )
1126
1020
  # }
1127
1021
  # )
@@ -1136,7 +1030,7 @@ module Polars
1136
1030
  # # ┌─────────────────────┬──────────────┐
1137
1031
  # # │ date ┆ minutes_diff │
1138
1032
  # # │ --- ┆ --- │
1139
- # # │ datetime[μs] ┆ i64 │
1033
+ # # │ datetime[ns] ┆ i64 │
1140
1034
  # # ╞═════════════════════╪══════════════╡
1141
1035
  # # │ 2020-01-01 00:00:00 ┆ null │
1142
1036
  # # │ 2020-01-02 00:00:00 ┆ 1440 │
@@ -1155,8 +1049,8 @@ module Polars
1155
1049
  # @example
1156
1050
  # df = Polars::DataFrame.new(
1157
1051
  # {
1158
- # "date" => Polars.date_range(
1159
- # DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 4, 0), "1m"
1052
+ # "date" => Polars.datetime_range(
1053
+ # DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 4, 0), "1m", eager: true
1160
1054
  # )
1161
1055
  # }
1162
1056
  # )
@@ -1171,7 +1065,7 @@ module Polars
1171
1065
  # # ┌─────────────────────┬──────────────┐
1172
1066
  # # │ date ┆ seconds_diff │
1173
1067
  # # │ --- ┆ --- │
1174
- # # │ datetime[μs] ┆ i64 │
1068
+ # # │ datetime[ns] ┆ i64 │
1175
1069
  # # ╞═════════════════════╪══════════════╡
1176
1070
  # # │ 2020-01-01 00:00:00 ┆ null │
1177
1071
  # # │ 2020-01-01 00:01:00 ┆ 60 │
@@ -1191,8 +1085,8 @@ module Polars
1191
1085
  # @example
1192
1086
  # df = Polars::DataFrame.new(
1193
1087
  # {
1194
- # "date" => Polars.date_range(
1195
- # DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 0, 1), "1ms"
1088
+ # "date" => Polars.datetime_range(
1089
+ # DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 0, 1), "1ms", eager: true
1196
1090
  # )
1197
1091
  # }
1198
1092
  # )
@@ -1207,7 +1101,7 @@ module Polars
1207
1101
  # # ┌─────────────────────────┬───────────────────┐
1208
1102
  # # │ date ┆ milliseconds_diff │
1209
1103
  # # │ --- ┆ --- │
1210
- # # │ datetime[μs] ┆ i64 │
1104
+ # # │ datetime[ns] ┆ i64 │
1211
1105
  # # ╞═════════════════════════╪═══════════════════╡
1212
1106
  # # │ 2020-01-01 00:00:00 ┆ null │
1213
1107
  # # │ 2020-01-01 00:00:00.001 ┆ 1 │
@@ -1233,8 +1127,8 @@ module Polars
1233
1127
  # @example
1234
1128
  # df = Polars::DataFrame.new(
1235
1129
  # {
1236
- # "date" => Polars.date_range(
1237
- # DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 0, 1), "1ms"
1130
+ # "date" => Polars.datetime_range(
1131
+ # DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 0, 1), "1ms", eager: true
1238
1132
  # )
1239
1133
  # }
1240
1134
  # )
@@ -1249,7 +1143,7 @@ module Polars
1249
1143
  # # ┌─────────────────────────┬───────────────────┐
1250
1144
  # # │ date ┆ microseconds_diff │
1251
1145
  # # │ --- ┆ --- │
1252
- # # │ datetime[μs] ┆ i64 │
1146
+ # # │ datetime[ns] ┆ i64 │
1253
1147
  # # ╞═════════════════════════╪═══════════════════╡
1254
1148
  # # │ 2020-01-01 00:00:00 ┆ null │
1255
1149
  # # │ 2020-01-01 00:00:00.001 ┆ 1000 │
@@ -1275,8 +1169,8 @@ module Polars
1275
1169
  # @example
1276
1170
  # df = Polars::DataFrame.new(
1277
1171
  # {
1278
- # "date" => Polars.date_range(
1279
- # DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 0, 1), "1ms"
1172
+ # "date" => Polars.datetime_range(
1173
+ # DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 0, 1), "1ms", eager: true
1280
1174
  # )
1281
1175
  # }
1282
1176
  # )
@@ -1291,7 +1185,7 @@ module Polars
1291
1185
  # # ┌─────────────────────────┬──────────────────┐
1292
1186
  # # │ date ┆ nanoseconds_diff │
1293
1187
  # # │ --- ┆ --- │
1294
- # # │ datetime[μs] ┆ i64 │
1188
+ # # │ datetime[ns] ┆ i64 │
1295
1189
  # # ╞═════════════════════════╪══════════════════╡
1296
1190
  # # │ 2020-01-01 00:00:00 ┆ null │
1297
1191
  # # │ 2020-01-01 00:00:00.001 ┆ 1000000 │
@@ -1336,8 +1230,8 @@ module Polars
1336
1230
  # @example
1337
1231
  # df = Polars::DataFrame.new(
1338
1232
  # {
1339
- # "dates" => Polars.date_range(
1340
- # DateTime.new(2000, 1, 1), DateTime.new(2005, 1, 1), "1y"
1233
+ # "dates" => Polars.datetime_range(
1234
+ # DateTime.new(2000, 1, 1), DateTime.new(2005, 1, 1), "1y", eager: true
1341
1235
  # )
1342
1236
  # }
1343
1237
  # )
@@ -1352,7 +1246,7 @@ module Polars
1352
1246
  # # ┌─────────────────────┬─────────────────────┐
1353
1247
  # # │ date_plus_1y ┆ date_min │
1354
1248
  # # │ --- ┆ --- │
1355
- # # │ datetime[μs] ┆ datetime[μs] │
1249
+ # # │ datetime[ns] ┆ datetime[ns] │
1356
1250
  # # ╞═════════════════════╪═════════════════════╡
1357
1251
  # # │ 2001-01-01 00:00:00 ┆ 1998-11-01 00:00:00 │
1358
1252
  # # │ 2002-01-01 00:00:00 ┆ 1999-11-01 00:00:00 │
@@ -1362,7 +1256,7 @@ module Polars
1362
1256
  # # │ 2006-01-01 00:00:00 ┆ 2003-11-01 00:00:00 │
1363
1257
  # # └─────────────────────┴─────────────────────┘
1364
1258
  def offset_by(by)
1365
- by = Utils.parse_as_expression(by, str_as_lit: true)
1259
+ by = Utils.parse_into_expression(by, str_as_lit: true)
1366
1260
  Utils.wrap_expr(_rbexpr.dt_offset_by(by))
1367
1261
  end
1368
1262
 
@@ -1373,10 +1267,11 @@ module Polars
1373
1267
  # @example
1374
1268
  # df = Polars::DataFrame.new(
1375
1269
  # {
1376
- # "dates" => Polars.date_range(
1270
+ # "dates" => Polars.datetime_range(
1377
1271
  # DateTime.new(2000, 1, 15, 2),
1378
1272
  # DateTime.new(2000, 12, 15, 2),
1379
- # "1mo"
1273
+ # "1mo",
1274
+ # eager: true
1380
1275
  # )
1381
1276
  # }
1382
1277
  # )
@@ -1386,7 +1281,7 @@ module Polars
1386
1281
  # # ┌─────────────────────┐
1387
1282
  # # │ dates │
1388
1283
  # # │ --- │
1389
- # # │ datetime[μs] │
1284
+ # # │ datetime[ns] │
1390
1285
  # # ╞═════════════════════╡
1391
1286
  # # │ 2000-01-01 02:00:00 │
1392
1287
  # # │ 2000-02-01 02:00:00 │
@@ -1411,10 +1306,11 @@ module Polars
1411
1306
  # @example
1412
1307
  # df = Polars::DataFrame.new(
1413
1308
  # {
1414
- # "dates" => Polars.date_range(
1309
+ # "dates" => Polars.datetime_range(
1415
1310
  # DateTime.new(2000, 1, 15, 2),
1416
1311
  # DateTime.new(2000, 12, 15, 2),
1417
- # "1mo"
1312
+ # "1mo",
1313
+ # eager: true
1418
1314
  # )
1419
1315
  # }
1420
1316
  # )
@@ -1424,7 +1320,7 @@ module Polars
1424
1320
  # # ┌─────────────────────┐
1425
1321
  # # │ dates │
1426
1322
  # # │ --- │
1427
- # # │ datetime[μs] │
1323
+ # # │ datetime[ns] │
1428
1324
  # # ╞═════════════════════╡
1429
1325
  # # │ 2000-01-31 02:00:00 │
1430
1326
  # # │ 2000-02-29 02:00:00 │
@@ -1441,5 +1337,61 @@ module Polars
1441
1337
  def month_end
1442
1338
  Utils.wrap_expr(_rbexpr.dt_month_end)
1443
1339
  end
1340
+
1341
+ # Base offset from UTC.
1342
+ #
1343
+ # This is usually constant for all datetimes in a given time zone, but
1344
+ # may vary in the rare case that a country switches time zone, like
1345
+ # Samoa (Apia) did at the end of 2011.
1346
+ #
1347
+ # @return [Expr]
1348
+ #
1349
+ # @example
1350
+ # df = Polars::DataFrame.new(
1351
+ # {
1352
+ # "ts" => [DateTime.new(2011, 12, 29), DateTime.new(2012, 1, 1)],
1353
+ # }
1354
+ # )
1355
+ # df = df.with_columns(Polars.col("ts").dt.replace_time_zone("Pacific/Apia"))
1356
+ # df.with_columns(Polars.col("ts").dt.base_utc_offset.alias("base_utc_offset"))
1357
+ # # =>
1358
+ # # shape: (2, 2)
1359
+ # # ┌────────────────────────────┬─────────────────┐
1360
+ # # │ ts ┆ base_utc_offset │
1361
+ # # │ --- ┆ --- │
1362
+ # # │ datetime[ns, Pacific/Apia] ┆ duration[ms] │
1363
+ # # ╞════════════════════════════╪═════════════════╡
1364
+ # # │ 2011-12-29 00:00:00 -10 ┆ -11h │
1365
+ # # │ 2012-01-01 00:00:00 +14 ┆ 13h │
1366
+ # # └────────────────────────────┴─────────────────┘
1367
+ def base_utc_offset
1368
+ Utils.wrap_expr(_rbexpr.dt_base_utc_offset)
1369
+ end
1370
+
1371
+ # Additional offset currently in effect (typically due to daylight saving time).
1372
+ #
1373
+ # @return [Expr]
1374
+ #
1375
+ # @example
1376
+ # df = Polars::DataFrame.new(
1377
+ # {
1378
+ # "ts" => [DateTime.new(2020, 10, 25), DateTime.new(2020, 10, 26)],
1379
+ # }
1380
+ # )
1381
+ # df = df.with_columns(Polars.col("ts").dt.replace_time_zone("Europe/London"))
1382
+ # df.with_columns(Polars.col("ts").dt.dst_offset.alias("dst_offset"))
1383
+ # # =>
1384
+ # # shape: (2, 2)
1385
+ # # ┌─────────────────────────────┬──────────────┐
1386
+ # # │ ts ┆ dst_offset │
1387
+ # # │ --- ┆ --- │
1388
+ # # │ datetime[ns, Europe/London] ┆ duration[ms] │
1389
+ # # ╞═════════════════════════════╪══════════════╡
1390
+ # # │ 2020-10-25 00:00:00 BST ┆ 1h │
1391
+ # # │ 2020-10-26 00:00:00 GMT ┆ 0ms │
1392
+ # # └─────────────────────────────┴──────────────┘
1393
+ def dst_offset
1394
+ Utils.wrap_expr(_rbexpr.dt_dst_offset)
1395
+ end
1444
1396
  end
1445
1397
  end