polars_core/series/implementations/
null.rs

1use std::any::Any;
2
3use polars_error::constants::LENGTH_LIMIT_MSG;
4
5use self::compare_inner::TotalOrdInner;
6use super::*;
7use crate::prelude::compare_inner::{IntoTotalEqInner, TotalEqInner};
8use crate::prelude::*;
9use crate::series::private::{PrivateSeries, PrivateSeriesNumeric};
10use crate::series::*;
11
12impl Series {
13    pub fn new_null(name: PlSmallStr, len: usize) -> Series {
14        NullChunked::new(name, len).into_series()
15    }
16}
17
18#[derive(Clone)]
19pub struct NullChunked {
20    pub(crate) name: PlSmallStr,
21    length: IdxSize,
22    // we still need chunks as many series consumers expect
23    // chunks to be there
24    chunks: Vec<ArrayRef>,
25}
26
27impl NullChunked {
28    pub(crate) fn new(name: PlSmallStr, len: usize) -> Self {
29        Self {
30            name,
31            length: len as IdxSize,
32            chunks: vec![Box::new(arrow::array::NullArray::new(
33                ArrowDataType::Null,
34                len,
35            ))],
36        }
37    }
38}
39impl PrivateSeriesNumeric for NullChunked {
40    fn bit_repr(&self) -> Option<BitRepr> {
41        Some(BitRepr::Small(UInt32Chunked::full_null(
42            self.name.clone(),
43            self.len(),
44        )))
45    }
46}
47
48impl PrivateSeries for NullChunked {
49    fn compute_len(&mut self) {
50        fn inner(chunks: &[ArrayRef]) -> usize {
51            match chunks.len() {
52                // fast path
53                1 => chunks[0].len(),
54                _ => chunks.iter().fold(0, |acc, arr| acc + arr.len()),
55            }
56        }
57        self.length = IdxSize::try_from(inner(&self.chunks)).expect(LENGTH_LIMIT_MSG);
58    }
59    fn _field(&self) -> Cow<Field> {
60        Cow::Owned(Field::new(self.name().clone(), DataType::Null))
61    }
62
63    #[allow(unused)]
64    fn _set_flags(&mut self, flags: StatisticsFlags) {}
65
66    fn _dtype(&self) -> &DataType {
67        &DataType::Null
68    }
69
70    #[cfg(feature = "zip_with")]
71    fn zip_with_same_type(&self, mask: &BooleanChunked, other: &Series) -> PolarsResult<Series> {
72        let len = match (self.len(), mask.len(), other.len()) {
73            (a, b, c) if a == b && b == c => a,
74            (1, a, b) | (a, 1, b) | (a, b, 1) if a == b => a,
75            (a, 1, 1) | (1, a, 1) | (1, 1, a) => a,
76            (_, 0, _) => 0,
77            _ => {
78                polars_bail!(ShapeMismatch: "shapes of `self`, `mask` and `other` are not suitable for `zip_with` operation")
79            },
80        };
81
82        Ok(Self::new(self.name().clone(), len).into_series())
83    }
84
85    fn into_total_eq_inner<'a>(&'a self) -> Box<dyn TotalEqInner + 'a> {
86        IntoTotalEqInner::into_total_eq_inner(self)
87    }
88    fn into_total_ord_inner<'a>(&'a self) -> Box<dyn TotalOrdInner + 'a> {
89        invalid_operation_panic!(into_total_ord_inner, self)
90    }
91
92    fn subtract(&self, _rhs: &Series) -> PolarsResult<Series> {
93        null_arithmetic(self, _rhs, "subtract")
94    }
95
96    fn add_to(&self, _rhs: &Series) -> PolarsResult<Series> {
97        null_arithmetic(self, _rhs, "add_to")
98    }
99    fn multiply(&self, _rhs: &Series) -> PolarsResult<Series> {
100        null_arithmetic(self, _rhs, "multiply")
101    }
102    fn divide(&self, _rhs: &Series) -> PolarsResult<Series> {
103        null_arithmetic(self, _rhs, "divide")
104    }
105    fn remainder(&self, _rhs: &Series) -> PolarsResult<Series> {
106        null_arithmetic(self, _rhs, "remainder")
107    }
108
109    #[cfg(feature = "algorithm_group_by")]
110    fn group_tuples(&self, _multithreaded: bool, _sorted: bool) -> PolarsResult<GroupsType> {
111        Ok(if self.is_empty() {
112            GroupsType::default()
113        } else {
114            GroupsType::Slice {
115                groups: vec![[0, self.length]],
116                rolling: false,
117            }
118        })
119    }
120
121    #[cfg(feature = "algorithm_group_by")]
122    unsafe fn agg_list(&self, groups: &GroupsType) -> Series {
123        AggList::agg_list(self, groups)
124    }
125
126    fn _get_flags(&self) -> StatisticsFlags {
127        StatisticsFlags::empty()
128    }
129
130    fn vec_hash(
131        &self,
132        random_state: PlSeedableRandomStateQuality,
133        buf: &mut Vec<u64>,
134    ) -> PolarsResult<()> {
135        VecHash::vec_hash(self, random_state, buf)?;
136        Ok(())
137    }
138
139    fn vec_hash_combine(
140        &self,
141        build_hasher: PlSeedableRandomStateQuality,
142        hashes: &mut [u64],
143    ) -> PolarsResult<()> {
144        VecHash::vec_hash_combine(self, build_hasher, hashes)?;
145        Ok(())
146    }
147}
148
149fn null_arithmetic(lhs: &NullChunked, rhs: &Series, op: &str) -> PolarsResult<Series> {
150    let output_len = match (lhs.len(), rhs.len()) {
151        (1, len_r) => len_r,
152        (len_l, 1) => len_l,
153        (len_l, len_r) if len_l == len_r => len_l,
154        _ => polars_bail!(ComputeError: "Cannot {:?} two series of different lengths.", op),
155    };
156    Ok(NullChunked::new(lhs.name().clone(), output_len).into_series())
157}
158
159impl SeriesTrait for NullChunked {
160    fn name(&self) -> &PlSmallStr {
161        &self.name
162    }
163
164    fn rename(&mut self, name: PlSmallStr) {
165        self.name = name
166    }
167
168    fn chunks(&self) -> &Vec<ArrayRef> {
169        &self.chunks
170    }
171    unsafe fn chunks_mut(&mut self) -> &mut Vec<ArrayRef> {
172        &mut self.chunks
173    }
174
175    fn chunk_lengths(&self) -> ChunkLenIter {
176        self.chunks.iter().map(|chunk| chunk.len())
177    }
178
179    fn take(&self, indices: &IdxCa) -> PolarsResult<Series> {
180        Ok(NullChunked::new(self.name.clone(), indices.len()).into_series())
181    }
182
183    unsafe fn take_unchecked(&self, indices: &IdxCa) -> Series {
184        NullChunked::new(self.name.clone(), indices.len()).into_series()
185    }
186
187    fn take_slice(&self, indices: &[IdxSize]) -> PolarsResult<Series> {
188        Ok(NullChunked::new(self.name.clone(), indices.len()).into_series())
189    }
190
191    unsafe fn take_slice_unchecked(&self, indices: &[IdxSize]) -> Series {
192        NullChunked::new(self.name.clone(), indices.len()).into_series()
193    }
194
195    fn len(&self) -> usize {
196        self.length as usize
197    }
198
199    fn has_nulls(&self) -> bool {
200        self.len() > 0
201    }
202
203    fn rechunk(&self) -> Series {
204        NullChunked::new(self.name.clone(), self.len()).into_series()
205    }
206
207    fn drop_nulls(&self) -> Series {
208        NullChunked::new(self.name.clone(), 0).into_series()
209    }
210
211    fn cast(&self, dtype: &DataType, _cast_options: CastOptions) -> PolarsResult<Series> {
212        Ok(Series::full_null(self.name.clone(), self.len(), dtype))
213    }
214
215    fn null_count(&self) -> usize {
216        self.len()
217    }
218
219    #[cfg(feature = "algorithm_group_by")]
220    fn unique(&self) -> PolarsResult<Series> {
221        let ca = NullChunked::new(self.name.clone(), self.n_unique().unwrap());
222        Ok(ca.into_series())
223    }
224
225    #[cfg(feature = "algorithm_group_by")]
226    fn n_unique(&self) -> PolarsResult<usize> {
227        let n = if self.is_empty() { 0 } else { 1 };
228        Ok(n)
229    }
230
231    #[cfg(feature = "algorithm_group_by")]
232    fn arg_unique(&self) -> PolarsResult<IdxCa> {
233        let idxs: Vec<IdxSize> = (0..self.n_unique().unwrap() as IdxSize).collect();
234        Ok(IdxCa::new(self.name().clone(), idxs))
235    }
236
237    fn new_from_index(&self, _index: usize, length: usize) -> Series {
238        NullChunked::new(self.name.clone(), length).into_series()
239    }
240
241    unsafe fn get_unchecked(&self, _index: usize) -> AnyValue {
242        AnyValue::Null
243    }
244
245    fn slice(&self, offset: i64, length: usize) -> Series {
246        let (chunks, len) = chunkops::slice(&self.chunks, offset, length, self.len());
247        NullChunked {
248            name: self.name.clone(),
249            length: len as IdxSize,
250            chunks,
251        }
252        .into_series()
253    }
254
255    fn split_at(&self, offset: i64) -> (Series, Series) {
256        let (l, r) = chunkops::split_at(self.chunks(), offset, self.len());
257        (
258            NullChunked {
259                name: self.name.clone(),
260                length: l.iter().map(|arr| arr.len() as IdxSize).sum(),
261                chunks: l,
262            }
263            .into_series(),
264            NullChunked {
265                name: self.name.clone(),
266                length: r.iter().map(|arr| arr.len() as IdxSize).sum(),
267                chunks: r,
268            }
269            .into_series(),
270        )
271    }
272
273    fn sort_with(&self, _options: SortOptions) -> PolarsResult<Series> {
274        Ok(self.clone().into_series())
275    }
276
277    fn arg_sort(&self, _options: SortOptions) -> IdxCa {
278        IdxCa::from_vec(self.name().clone(), (0..self.len() as IdxSize).collect())
279    }
280
281    fn is_null(&self) -> BooleanChunked {
282        BooleanChunked::full(self.name().clone(), true, self.len())
283    }
284
285    fn is_not_null(&self) -> BooleanChunked {
286        BooleanChunked::full(self.name().clone(), false, self.len())
287    }
288
289    fn reverse(&self) -> Series {
290        self.clone().into_series()
291    }
292
293    fn filter(&self, filter: &BooleanChunked) -> PolarsResult<Series> {
294        let len = if self.is_empty() {
295            // We still allow a length of `1` because it could be `lit(true)`.
296            polars_ensure!(filter.len() <= 1, ShapeMismatch: "filter's length: {} differs from that of the series: 0", filter.len());
297            0
298        } else if filter.len() == 1 {
299            return match filter.get(0) {
300                Some(true) => Ok(self.clone().into_series()),
301                None | Some(false) => Ok(NullChunked::new(self.name.clone(), 0).into_series()),
302            };
303        } else {
304            polars_ensure!(filter.len() == self.len(), ShapeMismatch: "filter's length: {} differs from that of the series: {}", filter.len(), self.len());
305            filter.sum().unwrap_or(0) as usize
306        };
307        Ok(NullChunked::new(self.name.clone(), len).into_series())
308    }
309
310    fn shift(&self, _periods: i64) -> Series {
311        self.clone().into_series()
312    }
313
314    fn append(&mut self, other: &Series) -> PolarsResult<()> {
315        polars_ensure!(other.dtype() == &DataType::Null, ComputeError: "expected null dtype");
316        // we don't create a new null array to keep probability of aligned chunks higher
317        self.length += other.len() as IdxSize;
318        self.chunks.extend(other.chunks().iter().cloned());
319        Ok(())
320    }
321    fn append_owned(&mut self, mut other: Series) -> PolarsResult<()> {
322        polars_ensure!(other.dtype() == &DataType::Null, ComputeError: "expected null dtype");
323        // we don't create a new null array to keep probability of aligned chunks higher
324        let other: &mut NullChunked = other._get_inner_mut().as_any_mut().downcast_mut().unwrap();
325        self.length += other.len() as IdxSize;
326        self.chunks.extend(std::mem::take(&mut other.chunks));
327        Ok(())
328    }
329
330    fn extend(&mut self, other: &Series) -> PolarsResult<()> {
331        *self = NullChunked::new(self.name.clone(), self.len() + other.len());
332        Ok(())
333    }
334
335    fn clone_inner(&self) -> Arc<dyn SeriesTrait> {
336        Arc::new(self.clone())
337    }
338
339    fn as_any(&self) -> &dyn Any {
340        self
341    }
342
343    fn as_any_mut(&mut self) -> &mut dyn Any {
344        self
345    }
346
347    fn as_phys_any(&self) -> &dyn Any {
348        self
349    }
350
351    fn as_arc_any(self: Arc<Self>) -> Arc<dyn Any + Send + Sync> {
352        self as _
353    }
354}
355
356unsafe impl IntoSeries for NullChunked {
357    fn into_series(self) -> Series
358    where
359        Self: Sized,
360    {
361        Series(Arc::new(self))
362    }
363}
polars_core/series/implementations/null.rs

polars_core/series/implementations/
null.rs
