polars_core/series/ops/
downcast.rs

1#![allow(unsafe_op_in_unsafe_fn)]
2use crate::prelude::*;
3use crate::series::implementations::null::NullChunked;
4
5macro_rules! unpack_chunked_err {
6    ($series:expr => $name:expr) => {
7        polars_err!(SchemaMismatch: "invalid series dtype: expected `{}`, got `{}` for series with name `{}`", $name, $series.dtype(), $series.name())
8    };
9}
10
11macro_rules! try_unpack_chunked {
12    ($series:expr, $expected:pat $(if $guard: expr)? => $ca:ty) => {
13        match $series.dtype() {
14            $expected $(if $guard)? => {
15                // Check downcast in debug compiles
16                #[cfg(debug_assertions)]
17                {
18                    Some($series.as_ref().as_any().downcast_ref::<$ca>().unwrap())
19                }
20                #[cfg(not(debug_assertions))]
21                unsafe {
22                    Some(&*($series.as_ref() as *const dyn SeriesTrait as *const $ca))
23                }
24            },
25            _ => None,
26        }
27    };
28}
29
30impl Series {
31    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Int8`]
32    pub fn try_i8(&self) -> Option<&Int8Chunked> {
33        try_unpack_chunked!(self, DataType::Int8 => Int8Chunked)
34    }
35
36    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Int16`]
37    pub fn try_i16(&self) -> Option<&Int16Chunked> {
38        try_unpack_chunked!(self, DataType::Int16 => Int16Chunked)
39    }
40
41    /// Unpack to [`ChunkedArray`]
42    /// ```
43    /// # use polars_core::prelude::*;
44    /// let s = Series::new("foo".into(), [1i32 ,2, 3]);
45    /// let s_squared: Series = s.i32()
46    ///     .unwrap()
47    ///     .into_iter()
48    ///     .map(|opt_v| {
49    ///         match opt_v {
50    ///             Some(v) => Some(v * v),
51    ///             None => None, // null value
52    ///         }
53    /// }).collect();
54    /// ```
55    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Int32`]
56    pub fn try_i32(&self) -> Option<&Int32Chunked> {
57        try_unpack_chunked!(self, DataType::Int32 => Int32Chunked)
58    }
59
60    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Int64`]
61    pub fn try_i64(&self) -> Option<&Int64Chunked> {
62        try_unpack_chunked!(self, DataType::Int64 => Int64Chunked)
63    }
64
65    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Int128`]
66    #[cfg(feature = "dtype-i128")]
67    pub fn try_i128(&self) -> Option<&Int128Chunked> {
68        try_unpack_chunked!(self, DataType::Int128 => Int128Chunked)
69    }
70
71    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Float32`]
72    pub fn try_f32(&self) -> Option<&Float32Chunked> {
73        try_unpack_chunked!(self, DataType::Float32 => Float32Chunked)
74    }
75
76    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Float64`]
77    pub fn try_f64(&self) -> Option<&Float64Chunked> {
78        try_unpack_chunked!(self, DataType::Float64 => Float64Chunked)
79    }
80
81    /// Unpack to [`ChunkedArray`] of dtype [`DataType::UInt8`]
82    pub fn try_u8(&self) -> Option<&UInt8Chunked> {
83        try_unpack_chunked!(self, DataType::UInt8 => UInt8Chunked)
84    }
85
86    /// Unpack to [`ChunkedArray`] of dtype [`DataType::UInt16`]
87    pub fn try_u16(&self) -> Option<&UInt16Chunked> {
88        try_unpack_chunked!(self, DataType::UInt16 => UInt16Chunked)
89    }
90
91    /// Unpack to [`ChunkedArray`] of dtype [`DataType::UInt32`]
92    pub fn try_u32(&self) -> Option<&UInt32Chunked> {
93        try_unpack_chunked!(self, DataType::UInt32 => UInt32Chunked)
94    }
95
96    /// Unpack to [`ChunkedArray`] of dtype [`DataType::UInt64`]
97    pub fn try_u64(&self) -> Option<&UInt64Chunked> {
98        try_unpack_chunked!(self, DataType::UInt64 => UInt64Chunked)
99    }
100
101    /// Unpack to [`ChunkedArray`] of dtype [`DataType::UInt128`]
102    #[cfg(feature = "dtype-u128")]
103    pub fn try_u128(&self) -> Option<&UInt128Chunked> {
104        try_unpack_chunked!(self, DataType::UInt128 => UInt128Chunked)
105    }
106
107    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Boolean`]
108    pub fn try_bool(&self) -> Option<&BooleanChunked> {
109        try_unpack_chunked!(self, DataType::Boolean => BooleanChunked)
110    }
111
112    /// Unpack to [`ChunkedArray`] of dtype [`DataType::String`]
113    pub fn try_str(&self) -> Option<&StringChunked> {
114        try_unpack_chunked!(self, DataType::String => StringChunked)
115    }
116
117    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Binary`]
118    pub fn try_binary(&self) -> Option<&BinaryChunked> {
119        try_unpack_chunked!(self, DataType::Binary => BinaryChunked)
120    }
121
122    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Binary`]
123    pub fn try_binary_offset(&self) -> Option<&BinaryOffsetChunked> {
124        try_unpack_chunked!(self, DataType::BinaryOffset => BinaryOffsetChunked)
125    }
126
127    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Time`]
128    #[cfg(feature = "dtype-time")]
129    pub fn try_time(&self) -> Option<&TimeChunked> {
130        try_unpack_chunked!(self, DataType::Time => TimeChunked)
131    }
132
133    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Date`]
134    #[cfg(feature = "dtype-date")]
135    pub fn try_date(&self) -> Option<&DateChunked> {
136        try_unpack_chunked!(self, DataType::Date => DateChunked)
137    }
138
139    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Datetime`]
140    #[cfg(feature = "dtype-datetime")]
141    pub fn try_datetime(&self) -> Option<&DatetimeChunked> {
142        try_unpack_chunked!(self, DataType::Datetime(_, _) => DatetimeChunked)
143    }
144
145    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Duration`]
146    #[cfg(feature = "dtype-duration")]
147    pub fn try_duration(&self) -> Option<&DurationChunked> {
148        try_unpack_chunked!(self, DataType::Duration(_) => DurationChunked)
149    }
150
151    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Decimal`]
152    #[cfg(feature = "dtype-decimal")]
153    pub fn try_decimal(&self) -> Option<&DecimalChunked> {
154        try_unpack_chunked!(self, DataType::Decimal(_, _) => DecimalChunked)
155    }
156
157    /// Unpack to [`ChunkedArray`] of dtype list
158    pub fn try_list(&self) -> Option<&ListChunked> {
159        try_unpack_chunked!(self, DataType::List(_) => ListChunked)
160    }
161
162    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Array`]
163    #[cfg(feature = "dtype-array")]
164    pub fn try_array(&self) -> Option<&ArrayChunked> {
165        try_unpack_chunked!(self, DataType::Array(_, _) => ArrayChunked)
166    }
167
168    #[cfg(feature = "dtype-categorical")]
169    pub fn try_cat<T: PolarsCategoricalType>(&self) -> Option<&CategoricalChunked<T>> {
170        try_unpack_chunked!(self, dt @ DataType::Enum(_, _) | dt @ DataType::Categorical(_, _) if dt.cat_physical().unwrap() == T::physical() => CategoricalChunked<T>)
171    }
172
173    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Categorical`] or [`DataType::Enum`] with a physical type of UInt8.
174    #[cfg(feature = "dtype-categorical")]
175    pub fn try_cat8(&self) -> Option<&Categorical8Chunked> {
176        self.try_cat::<Categorical8Type>()
177    }
178
179    #[cfg(feature = "dtype-categorical")]
180    pub fn try_cat16(&self) -> Option<&Categorical16Chunked> {
181        self.try_cat::<Categorical16Type>()
182    }
183
184    #[cfg(feature = "dtype-categorical")]
185    pub fn try_cat32(&self) -> Option<&Categorical32Chunked> {
186        self.try_cat::<Categorical32Type>()
187    }
188
189    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Struct`]
190    #[cfg(feature = "dtype-struct")]
191    pub fn try_struct(&self) -> Option<&StructChunked> {
192        #[cfg(debug_assertions)]
193        {
194            if let DataType::Struct(_) = self.dtype() {
195                let any = self.as_any();
196                assert!(any.is::<StructChunked>());
197            }
198        }
199        try_unpack_chunked!(self, DataType::Struct(_) => StructChunked)
200    }
201
202    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Null`]
203    pub fn try_null(&self) -> Option<&NullChunked> {
204        try_unpack_chunked!(self, DataType::Null => NullChunked)
205    }
206    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Int8`]
207    pub fn i8(&self) -> PolarsResult<&Int8Chunked> {
208        self.try_i8()
209            .ok_or_else(|| unpack_chunked_err!(self => "Int8"))
210    }
211
212    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Int16`]
213    pub fn i16(&self) -> PolarsResult<&Int16Chunked> {
214        self.try_i16()
215            .ok_or_else(|| unpack_chunked_err!(self => "Int16"))
216    }
217
218    /// Unpack to [`ChunkedArray`]
219    /// ```
220    /// # use polars_core::prelude::*;
221    /// let s = Series::new("foo".into(), [1i32 ,2, 3]);
222    /// let s_squared: Series = s.i32()
223    ///     .unwrap()
224    ///     .into_iter()
225    ///     .map(|opt_v| {
226    ///         match opt_v {
227    ///             Some(v) => Some(v * v),
228    ///             None => None, // null value
229    ///         }
230    /// }).collect();
231    /// ```
232    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Int32`]
233    pub fn i32(&self) -> PolarsResult<&Int32Chunked> {
234        self.try_i32()
235            .ok_or_else(|| unpack_chunked_err!(self => "Int32"))
236    }
237
238    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Int64`]
239    pub fn i64(&self) -> PolarsResult<&Int64Chunked> {
240        self.try_i64()
241            .ok_or_else(|| unpack_chunked_err!(self => "Int64"))
242    }
243
244    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Int128`]
245    #[cfg(feature = "dtype-i128")]
246    pub fn i128(&self) -> PolarsResult<&Int128Chunked> {
247        self.try_i128()
248            .ok_or_else(|| unpack_chunked_err!(self => "Int128"))
249    }
250
251    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Float32`]
252    pub fn f32(&self) -> PolarsResult<&Float32Chunked> {
253        self.try_f32()
254            .ok_or_else(|| unpack_chunked_err!(self => "Float32"))
255    }
256
257    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Float64`]
258    pub fn f64(&self) -> PolarsResult<&Float64Chunked> {
259        self.try_f64()
260            .ok_or_else(|| unpack_chunked_err!(self => "Float64"))
261    }
262
263    /// Unpack to [`ChunkedArray`] of dtype [`DataType::UInt8`]
264    pub fn u8(&self) -> PolarsResult<&UInt8Chunked> {
265        self.try_u8()
266            .ok_or_else(|| unpack_chunked_err!(self => "UInt8"))
267    }
268
269    /// Unpack to [`ChunkedArray`] of dtype [`DataType::UInt16`]
270    pub fn u16(&self) -> PolarsResult<&UInt16Chunked> {
271        self.try_u16()
272            .ok_or_else(|| unpack_chunked_err!(self => "UInt16"))
273    }
274
275    /// Unpack to [`ChunkedArray`] of dtype [`DataType::UInt32`]
276    pub fn u32(&self) -> PolarsResult<&UInt32Chunked> {
277        self.try_u32()
278            .ok_or_else(|| unpack_chunked_err!(self => "UInt32"))
279    }
280
281    /// Unpack to [`ChunkedArray`] of dtype [`DataType::UInt64`]
282    pub fn u64(&self) -> PolarsResult<&UInt64Chunked> {
283        self.try_u64()
284            .ok_or_else(|| unpack_chunked_err!(self => "UInt64"))
285    }
286
287    /// Unpack to [`ChunkedArray`] of dtype [`DataType::UInt128`]
288    #[cfg(feature = "dtype-u128")]
289    pub fn u128(&self) -> PolarsResult<&UInt128Chunked> {
290        self.try_u128()
291            .ok_or_else(|| unpack_chunked_err!(self => "UInt128"))
292    }
293
294    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Boolean`]
295    pub fn bool(&self) -> PolarsResult<&BooleanChunked> {
296        self.try_bool()
297            .ok_or_else(|| unpack_chunked_err!(self => "Boolean"))
298    }
299
300    /// Unpack to [`ChunkedArray`] of dtype [`DataType::String`]
301    pub fn str(&self) -> PolarsResult<&StringChunked> {
302        self.try_str()
303            .ok_or_else(|| unpack_chunked_err!(self => "String"))
304    }
305
306    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Binary`]
307    pub fn binary(&self) -> PolarsResult<&BinaryChunked> {
308        self.try_binary()
309            .ok_or_else(|| unpack_chunked_err!(self => "Binary"))
310    }
311
312    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Binary`]
313    pub fn binary_offset(&self) -> PolarsResult<&BinaryOffsetChunked> {
314        self.try_binary_offset()
315            .ok_or_else(|| unpack_chunked_err!(self => "BinaryOffset"))
316    }
317
318    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Time`]
319    #[cfg(feature = "dtype-time")]
320    pub fn time(&self) -> PolarsResult<&TimeChunked> {
321        self.try_time()
322            .ok_or_else(|| unpack_chunked_err!(self => "Time"))
323    }
324
325    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Date`]
326    #[cfg(feature = "dtype-date")]
327    pub fn date(&self) -> PolarsResult<&DateChunked> {
328        self.try_date()
329            .ok_or_else(|| unpack_chunked_err!(self => "Date"))
330    }
331
332    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Datetime`]
333    #[cfg(feature = "dtype-datetime")]
334    pub fn datetime(&self) -> PolarsResult<&DatetimeChunked> {
335        self.try_datetime()
336            .ok_or_else(|| unpack_chunked_err!(self => "Datetime"))
337    }
338
339    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Duration`]
340    #[cfg(feature = "dtype-duration")]
341    pub fn duration(&self) -> PolarsResult<&DurationChunked> {
342        self.try_duration()
343            .ok_or_else(|| unpack_chunked_err!(self => "Duration"))
344    }
345
346    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Decimal`]
347    #[cfg(feature = "dtype-decimal")]
348    pub fn decimal(&self) -> PolarsResult<&DecimalChunked> {
349        self.try_decimal()
350            .ok_or_else(|| unpack_chunked_err!(self => "Decimal"))
351    }
352
353    /// Unpack to [`ChunkedArray`] of dtype list
354    pub fn list(&self) -> PolarsResult<&ListChunked> {
355        self.try_list()
356            .ok_or_else(|| unpack_chunked_err!(self => "List"))
357    }
358
359    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Array`]
360    #[cfg(feature = "dtype-array")]
361    pub fn array(&self) -> PolarsResult<&ArrayChunked> {
362        self.try_array()
363            .ok_or_else(|| unpack_chunked_err!(self => "Array"))
364    }
365
366    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Categorical`] or [`DataType::Enum`].
367    #[cfg(feature = "dtype-categorical")]
368    pub fn cat<T: PolarsCategoricalType>(&self) -> PolarsResult<&CategoricalChunked<T>> {
369        self.try_cat::<T>()
370            .ok_or_else(|| unpack_chunked_err!(self => "Enum | Categorical"))
371    }
372
373    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Categorical`] or [`DataType::Enum`] with a physical type of UInt8.
374    #[cfg(feature = "dtype-categorical")]
375    pub fn cat8(&self) -> PolarsResult<&CategoricalChunked<Categorical8Type>> {
376        self.try_cat8()
377            .ok_or_else(|| unpack_chunked_err!(self => "Enum8 | Categorical8"))
378    }
379
380    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Categorical`] or [`DataType::Enum`] with a physical type of UInt16.
381    #[cfg(feature = "dtype-categorical")]
382    pub fn cat16(&self) -> PolarsResult<&CategoricalChunked<Categorical16Type>> {
383        self.try_cat16()
384            .ok_or_else(|| unpack_chunked_err!(self => "Enum16 | Categorical16"))
385    }
386
387    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Categorical`] or [`DataType::Enum`] with a physical type of UInt32.
388    #[cfg(feature = "dtype-categorical")]
389    pub fn cat32(&self) -> PolarsResult<&CategoricalChunked<Categorical32Type>> {
390        self.try_cat32()
391            .ok_or_else(|| unpack_chunked_err!(self => "Enum32 | Categorical32"))
392    }
393
394    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Struct`]
395    #[cfg(feature = "dtype-struct")]
396    pub fn struct_(&self) -> PolarsResult<&StructChunked> {
397        #[cfg(debug_assertions)]
398        {
399            if let DataType::Struct(_) = self.dtype() {
400                let any = self.as_any();
401                assert!(any.is::<StructChunked>());
402            }
403        }
404
405        self.try_struct()
406            .ok_or_else(|| unpack_chunked_err!(self => "Struct"))
407    }
408
409    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Null`]
410    pub fn null(&self) -> PolarsResult<&NullChunked> {
411        self.try_null()
412            .ok_or_else(|| unpack_chunked_err!(self => "Null"))
413    }
414}
polars_core/series/ops/downcast.rs

polars_core/series/ops/
downcast.rs
