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 => $ca:ty) => {
13        match $series.dtype() {
14            $expected => {
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::Boolean`]
102    pub fn try_bool(&self) -> Option<&BooleanChunked> {
103        try_unpack_chunked!(self, DataType::Boolean => BooleanChunked)
104    }
105
106    /// Unpack to [`ChunkedArray`] of dtype [`DataType::String`]
107    pub fn try_str(&self) -> Option<&StringChunked> {
108        try_unpack_chunked!(self, DataType::String => StringChunked)
109    }
110
111    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Binary`]
112    pub fn try_binary(&self) -> Option<&BinaryChunked> {
113        try_unpack_chunked!(self, DataType::Binary => BinaryChunked)
114    }
115
116    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Binary`]
117    pub fn try_binary_offset(&self) -> Option<&BinaryOffsetChunked> {
118        try_unpack_chunked!(self, DataType::BinaryOffset => BinaryOffsetChunked)
119    }
120
121    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Time`]
122    #[cfg(feature = "dtype-time")]
123    pub fn try_time(&self) -> Option<&TimeChunked> {
124        try_unpack_chunked!(self, DataType::Time => TimeChunked)
125    }
126
127    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Date`]
128    #[cfg(feature = "dtype-date")]
129    pub fn try_date(&self) -> Option<&DateChunked> {
130        try_unpack_chunked!(self, DataType::Date => DateChunked)
131    }
132
133    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Datetime`]
134    #[cfg(feature = "dtype-datetime")]
135    pub fn try_datetime(&self) -> Option<&DatetimeChunked> {
136        try_unpack_chunked!(self, DataType::Datetime(_, _) => DatetimeChunked)
137    }
138
139    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Duration`]
140    #[cfg(feature = "dtype-duration")]
141    pub fn try_duration(&self) -> Option<&DurationChunked> {
142        try_unpack_chunked!(self, DataType::Duration(_) => DurationChunked)
143    }
144
145    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Decimal`]
146    #[cfg(feature = "dtype-decimal")]
147    pub fn try_decimal(&self) -> Option<&DecimalChunked> {
148        try_unpack_chunked!(self, DataType::Decimal(_, _) => DecimalChunked)
149    }
150
151    /// Unpack to [`ChunkedArray`] of dtype list
152    pub fn try_list(&self) -> Option<&ListChunked> {
153        try_unpack_chunked!(self, DataType::List(_) => ListChunked)
154    }
155
156    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Array`]
157    #[cfg(feature = "dtype-array")]
158    pub fn try_array(&self) -> Option<&ArrayChunked> {
159        try_unpack_chunked!(self, DataType::Array(_, _) => ArrayChunked)
160    }
161
162    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Categorical`]
163    #[cfg(feature = "dtype-categorical")]
164    pub fn try_categorical(&self) -> Option<&CategoricalChunked> {
165        try_unpack_chunked!(self, DataType::Categorical(_, _) | DataType::Enum(_, _) => CategoricalChunked)
166    }
167
168    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Struct`]
169    #[cfg(feature = "dtype-struct")]
170    pub fn try_struct(&self) -> Option<&StructChunked> {
171        #[cfg(debug_assertions)]
172        {
173            if let DataType::Struct(_) = self.dtype() {
174                let any = self.as_any();
175                assert!(any.is::<StructChunked>());
176            }
177        }
178        try_unpack_chunked!(self, DataType::Struct(_) => StructChunked)
179    }
180
181    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Null`]
182    pub fn try_null(&self) -> Option<&NullChunked> {
183        try_unpack_chunked!(self, DataType::Null => NullChunked)
184    }
185    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Int8`]
186    pub fn i8(&self) -> PolarsResult<&Int8Chunked> {
187        self.try_i8()
188            .ok_or_else(|| unpack_chunked_err!(self => "Int8"))
189    }
190
191    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Int16`]
192    pub fn i16(&self) -> PolarsResult<&Int16Chunked> {
193        self.try_i16()
194            .ok_or_else(|| unpack_chunked_err!(self => "Int16"))
195    }
196
197    /// Unpack to [`ChunkedArray`]
198    /// ```
199    /// # use polars_core::prelude::*;
200    /// let s = Series::new("foo".into(), [1i32 ,2, 3]);
201    /// let s_squared: Series = s.i32()
202    ///     .unwrap()
203    ///     .into_iter()
204    ///     .map(|opt_v| {
205    ///         match opt_v {
206    ///             Some(v) => Some(v * v),
207    ///             None => None, // null value
208    ///         }
209    /// }).collect();
210    /// ```
211    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Int32`]
212    pub fn i32(&self) -> PolarsResult<&Int32Chunked> {
213        self.try_i32()
214            .ok_or_else(|| unpack_chunked_err!(self => "Int32"))
215    }
216
217    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Int64`]
218    pub fn i64(&self) -> PolarsResult<&Int64Chunked> {
219        self.try_i64()
220            .ok_or_else(|| unpack_chunked_err!(self => "Int64"))
221    }
222
223    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Int128`]
224    #[cfg(feature = "dtype-i128")]
225    pub fn i128(&self) -> PolarsResult<&Int128Chunked> {
226        self.try_i128()
227            .ok_or_else(|| unpack_chunked_err!(self => "Int128"))
228    }
229
230    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Float32`]
231    pub fn f32(&self) -> PolarsResult<&Float32Chunked> {
232        self.try_f32()
233            .ok_or_else(|| unpack_chunked_err!(self => "Float32"))
234    }
235
236    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Float64`]
237    pub fn f64(&self) -> PolarsResult<&Float64Chunked> {
238        self.try_f64()
239            .ok_or_else(|| unpack_chunked_err!(self => "Float64"))
240    }
241
242    /// Unpack to [`ChunkedArray`] of dtype [`DataType::UInt8`]
243    pub fn u8(&self) -> PolarsResult<&UInt8Chunked> {
244        self.try_u8()
245            .ok_or_else(|| unpack_chunked_err!(self => "UInt8"))
246    }
247
248    /// Unpack to [`ChunkedArray`] of dtype [`DataType::UInt16`]
249    pub fn u16(&self) -> PolarsResult<&UInt16Chunked> {
250        self.try_u16()
251            .ok_or_else(|| unpack_chunked_err!(self => "UInt16"))
252    }
253
254    /// Unpack to [`ChunkedArray`] of dtype [`DataType::UInt32`]
255    pub fn u32(&self) -> PolarsResult<&UInt32Chunked> {
256        self.try_u32()
257            .ok_or_else(|| unpack_chunked_err!(self => "UInt32"))
258    }
259
260    /// Unpack to [`ChunkedArray`] of dtype [`DataType::UInt64`]
261    pub fn u64(&self) -> PolarsResult<&UInt64Chunked> {
262        self.try_u64()
263            .ok_or_else(|| unpack_chunked_err!(self => "UInt64"))
264    }
265
266    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Boolean`]
267    pub fn bool(&self) -> PolarsResult<&BooleanChunked> {
268        self.try_bool()
269            .ok_or_else(|| unpack_chunked_err!(self => "Boolean"))
270    }
271
272    /// Unpack to [`ChunkedArray`] of dtype [`DataType::String`]
273    pub fn str(&self) -> PolarsResult<&StringChunked> {
274        self.try_str()
275            .ok_or_else(|| unpack_chunked_err!(self => "String"))
276    }
277
278    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Binary`]
279    pub fn binary(&self) -> PolarsResult<&BinaryChunked> {
280        self.try_binary()
281            .ok_or_else(|| unpack_chunked_err!(self => "Binary"))
282    }
283
284    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Binary`]
285    pub fn binary_offset(&self) -> PolarsResult<&BinaryOffsetChunked> {
286        self.try_binary_offset()
287            .ok_or_else(|| unpack_chunked_err!(self => "BinaryOffset"))
288    }
289
290    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Time`]
291    #[cfg(feature = "dtype-time")]
292    pub fn time(&self) -> PolarsResult<&TimeChunked> {
293        self.try_time()
294            .ok_or_else(|| unpack_chunked_err!(self => "Time"))
295    }
296
297    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Date`]
298    #[cfg(feature = "dtype-date")]
299    pub fn date(&self) -> PolarsResult<&DateChunked> {
300        self.try_date()
301            .ok_or_else(|| unpack_chunked_err!(self => "Date"))
302    }
303
304    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Datetime`]
305    #[cfg(feature = "dtype-datetime")]
306    pub fn datetime(&self) -> PolarsResult<&DatetimeChunked> {
307        self.try_datetime()
308            .ok_or_else(|| unpack_chunked_err!(self => "Datetime"))
309    }
310
311    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Duration`]
312    #[cfg(feature = "dtype-duration")]
313    pub fn duration(&self) -> PolarsResult<&DurationChunked> {
314        self.try_duration()
315            .ok_or_else(|| unpack_chunked_err!(self => "Duration"))
316    }
317
318    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Decimal`]
319    #[cfg(feature = "dtype-decimal")]
320    pub fn decimal(&self) -> PolarsResult<&DecimalChunked> {
321        self.try_decimal()
322            .ok_or_else(|| unpack_chunked_err!(self => "Decimal"))
323    }
324
325    /// Unpack to [`ChunkedArray`] of dtype list
326    pub fn list(&self) -> PolarsResult<&ListChunked> {
327        self.try_list()
328            .ok_or_else(|| unpack_chunked_err!(self => "List"))
329    }
330
331    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Array`]
332    #[cfg(feature = "dtype-array")]
333    pub fn array(&self) -> PolarsResult<&ArrayChunked> {
334        self.try_array()
335            .ok_or_else(|| unpack_chunked_err!(self => "FixedSizeList"))
336    }
337
338    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Categorical`]
339    #[cfg(feature = "dtype-categorical")]
340    pub fn categorical(&self) -> PolarsResult<&CategoricalChunked> {
341        self.try_categorical()
342            .ok_or_else(|| unpack_chunked_err!(self => "Enum | Categorical"))
343    }
344
345    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Struct`]
346    #[cfg(feature = "dtype-struct")]
347    pub fn struct_(&self) -> PolarsResult<&StructChunked> {
348        #[cfg(debug_assertions)]
349        {
350            if let DataType::Struct(_) = self.dtype() {
351                let any = self.as_any();
352                assert!(any.is::<StructChunked>());
353            }
354        }
355
356        self.try_struct()
357            .ok_or_else(|| unpack_chunked_err!(self => "Struct"))
358    }
359
360    /// Unpack to [`ChunkedArray`] of dtype [`DataType::Null`]
361    pub fn null(&self) -> PolarsResult<&NullChunked> {
362        self.try_null()
363            .ok_or_else(|| unpack_chunked_err!(self => "Null"))
364    }
365}