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::chunked_array::ops::compare_inner::NonNull;
8use crate::chunked_array::ops::sort::arg_sort_multiple::arg_sort_multiple_impl;
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: usize,
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        if len >= (IdxSize::MAX as usize) && chunkops::CHECK_LENGTH.get() {
30            panic!("{}", LENGTH_LIMIT_MSG);
31        }
32
33        Self {
34            name,
35            length: len,
36            chunks: vec![Box::new(polars_arrow::array::NullArray::new(
37                ArrowDataType::Null,
38                len,
39            ))],
40        }
41    }
42
43    pub fn len(&self) -> usize {
44        self.length
45    }
46
47    pub fn is_empty(&self) -> bool {
48        self.length == 0
49    }
50}
51impl PrivateSeriesNumeric for NullChunked {
52    fn bit_repr(&self) -> Option<BitRepr> {
53        Some(BitRepr::U32(UInt32Chunked::full_null(
54            self.name.clone(),
55            self.len(),
56        )))
57    }
58}
59
60impl PrivateSeries for NullChunked {
61    fn compute_len(&mut self) {
62        fn inner(chunks: &[ArrayRef]) -> usize {
63            match chunks.len() {
64                // fast path
65                1 => chunks[0].len(),
66                _ => chunks.iter().fold(0, |acc, arr| acc + arr.len()),
67            }
68        }
69        let len = inner(&self.chunks);
70        if len >= (IdxSize::MAX as usize) && chunkops::CHECK_LENGTH.get() {
71            panic!("{}", LENGTH_LIMIT_MSG);
72        }
73        self.length = len;
74    }
75    fn _field(&self) -> Cow<'_, Field> {
76        Cow::Owned(Field::new(self.name().clone(), DataType::Null))
77    }
78
79    #[allow(unused)]
80    fn _set_flags(&mut self, flags: StatisticsFlags) {}
81
82    fn _dtype(&self) -> &DataType {
83        &DataType::Null
84    }
85
86    #[cfg(feature = "zip_with")]
87    fn zip_with_same_type(&self, mask: &BooleanChunked, other: &Series) -> PolarsResult<Series> {
88        let len = match (self.len(), mask.len(), other.len()) {
89            (a, b, c) if a == b && b == c => a,
90            (1, a, b) | (a, 1, b) | (a, b, 1) if a == b => a,
91            (a, 1, 1) | (1, a, 1) | (1, 1, a) => a,
92            (_, 0, _) => 0,
93            _ => {
94                polars_bail!(ShapeMismatch: "shapes of `self`, `mask` and `other` are not suitable for `zip_with` operation")
95            },
96        };
97
98        Ok(Self::new(self.name().clone(), len).into_series())
99    }
100
101    fn into_total_ord_inner<'a>(&'a self) -> Box<dyn TotalOrdInner + 'a> {
102        IntoTotalOrdInner::into_total_ord_inner(self)
103    }
104
105    fn subtract(&self, _rhs: &Series) -> PolarsResult<Series> {
106        null_arithmetic(self, _rhs, "subtract")
107    }
108
109    fn add_to(&self, _rhs: &Series) -> PolarsResult<Series> {
110        null_arithmetic(self, _rhs, "add_to")
111    }
112    fn multiply(&self, _rhs: &Series) -> PolarsResult<Series> {
113        null_arithmetic(self, _rhs, "multiply")
114    }
115    fn divide(&self, _rhs: &Series) -> PolarsResult<Series> {
116        null_arithmetic(self, _rhs, "divide")
117    }
118    fn remainder(&self, _rhs: &Series) -> PolarsResult<Series> {
119        null_arithmetic(self, _rhs, "remainder")
120    }
121
122    #[cfg(feature = "algorithm_group_by")]
123    fn group_tuples(&self, _multithreaded: bool, _sorted: bool) -> PolarsResult<GroupsType> {
124        Ok(if self.is_empty() {
125            GroupsType::default()
126        } else {
127            GroupsType::new_slice(vec![[0, self.length as IdxSize]], false, true)
128        })
129    }
130
131    #[cfg(feature = "algorithm_group_by")]
132    unsafe fn agg_list(&self, groups: &GroupsType) -> Series {
133        AggList::agg_list(self, groups)
134    }
135
136    fn _get_flags(&self) -> StatisticsFlags {
137        StatisticsFlags::empty()
138    }
139
140    fn vec_hash(
141        &self,
142        random_state: PlSeedableRandomStateQuality,
143        buf: &mut Vec<u64>,
144    ) -> PolarsResult<()> {
145        VecHash::vec_hash(self, random_state, buf)?;
146        Ok(())
147    }
148
149    fn vec_hash_combine(
150        &self,
151        build_hasher: PlSeedableRandomStateQuality,
152        hashes: &mut [u64],
153    ) -> PolarsResult<()> {
154        VecHash::vec_hash_combine(self, build_hasher, hashes)?;
155        Ok(())
156    }
157
158    fn arg_sort_multiple(
159        &self,
160        by: &[Column],
161        options: &SortMultipleOptions,
162    ) -> PolarsResult<IdxCa> {
163        let vals = (0..self.len())
164            .map(|i| (i as IdxSize, NonNull(())))
165            .collect();
166        arg_sort_multiple_impl(vals, by, options)
167    }
168}
169
170fn null_arithmetic(lhs: &NullChunked, rhs: &Series, op: &str) -> PolarsResult<Series> {
171    let output_len = match (lhs.len(), rhs.len()) {
172        (1, len_r) => len_r,
173        (len_l, 1) => len_l,
174        (len_l, len_r) if len_l == len_r => len_l,
175        _ => polars_bail!(ComputeError: "Cannot {:?} two series of different lengths.", op),
176    };
177    Ok(NullChunked::new(lhs.name().clone(), output_len).into_series())
178}
179
180impl SeriesTrait for NullChunked {
181    fn name(&self) -> &PlSmallStr {
182        &self.name
183    }
184
185    fn rename(&mut self, name: PlSmallStr) {
186        self.name = name
187    }
188
189    fn chunks(&self) -> &Vec<ArrayRef> {
190        &self.chunks
191    }
192    unsafe fn chunks_mut(&mut self) -> &mut Vec<ArrayRef> {
193        &mut self.chunks
194    }
195
196    fn chunk_lengths(&self) -> ChunkLenIter<'_> {
197        self.chunks.iter().map(|chunk| chunk.len())
198    }
199
200    fn take(&self, indices: &IdxCa) -> PolarsResult<Series> {
201        Ok(NullChunked::new(self.name.clone(), indices.len()).into_series())
202    }
203
204    unsafe fn take_unchecked(&self, indices: &IdxCa) -> Series {
205        NullChunked::new(self.name.clone(), indices.len()).into_series()
206    }
207
208    fn take_slice(&self, indices: &[IdxSize]) -> PolarsResult<Series> {
209        Ok(NullChunked::new(self.name.clone(), indices.len()).into_series())
210    }
211
212    unsafe fn take_slice_unchecked(&self, indices: &[IdxSize]) -> Series {
213        NullChunked::new(self.name.clone(), indices.len()).into_series()
214    }
215
216    fn deposit(&self, validity: &Bitmap) -> Series {
217        assert_eq!(validity.set_bits(), 0);
218        self.clone().into_series()
219    }
220
221    fn len(&self) -> usize {
222        self.length
223    }
224
225    fn has_nulls(&self) -> bool {
226        !self.is_empty()
227    }
228
229    fn rechunk(&self) -> Series {
230        NullChunked::new(self.name.clone(), self.len()).into_series()
231    }
232
233    fn with_validity(&self, _validity: Option<Bitmap>) -> Series {
234        self.clone().into_series()
235    }
236
237    fn drop_nulls(&self) -> Series {
238        NullChunked::new(self.name.clone(), 0).into_series()
239    }
240
241    fn cast(&self, dtype: &DataType, _cast_options: CastOptions) -> PolarsResult<Series> {
242        Ok(Series::full_null(self.name.clone(), self.len(), dtype))
243    }
244
245    fn null_count(&self) -> usize {
246        self.len()
247    }
248
249    #[cfg(feature = "algorithm_group_by")]
250    fn unique(&self) -> PolarsResult<Series> {
251        let ca = NullChunked::new(self.name.clone(), self.n_unique().unwrap());
252        Ok(ca.into_series())
253    }
254
255    #[cfg(feature = "algorithm_group_by")]
256    fn n_unique(&self) -> PolarsResult<usize> {
257        let n = if self.is_empty() { 0 } else { 1 };
258        Ok(n)
259    }
260
261    #[cfg(feature = "algorithm_group_by")]
262    fn arg_unique(&self) -> PolarsResult<IdxCa> {
263        let idxs: Vec<IdxSize> = (0..self.n_unique().unwrap() as IdxSize).collect();
264        Ok(IdxCa::new(self.name().clone(), idxs))
265    }
266
267    #[cfg(feature = "algorithm_group_by")]
268    fn unique_id(&self) -> PolarsResult<(IdxSize, Vec<IdxSize>)> {
269        if self.is_empty() {
270            Ok((0, Vec::new()))
271        } else {
272            Ok((1, vec![0; self.len()]))
273        }
274    }
275
276    fn new_from_index(&self, _index: usize, length: usize) -> Series {
277        NullChunked::new(self.name.clone(), length).into_series()
278    }
279
280    unsafe fn get_unchecked(&self, _index: usize) -> AnyValue<'_> {
281        AnyValue::Null
282    }
283
284    fn slice(&self, offset: i64, length: usize) -> Series {
285        let (chunks, len) = chunkops::slice(&self.chunks, offset, length, self.len());
286        NullChunked {
287            name: self.name.clone(),
288            length: len,
289            chunks,
290        }
291        .into_series()
292    }
293
294    fn split_at(&self, offset: i64) -> (Series, Series) {
295        let (l, r) = chunkops::split_at(self.chunks(), offset, self.len());
296        (
297            NullChunked {
298                name: self.name.clone(),
299                length: l.iter().map(|arr| arr.len()).sum(),
300                chunks: l,
301            }
302            .into_series(),
303            NullChunked {
304                name: self.name.clone(),
305                length: r.iter().map(|arr| arr.len()).sum(),
306                chunks: r,
307            }
308            .into_series(),
309        )
310    }
311
312    fn sort_with(&self, _options: SortOptions) -> PolarsResult<Series> {
313        Ok(self.clone().into_series())
314    }
315
316    fn arg_sort(&self, _options: SortOptions) -> IdxCa {
317        IdxCa::from_vec(self.name().clone(), (0..self.len() as IdxSize).collect())
318    }
319
320    fn is_null(&self) -> BooleanChunked {
321        BooleanChunked::full(self.name().clone(), true, self.len())
322    }
323
324    fn is_not_null(&self) -> BooleanChunked {
325        BooleanChunked::full(self.name().clone(), false, self.len())
326    }
327
328    fn reverse(&self) -> Series {
329        self.clone().into_series()
330    }
331
332    fn filter(&self, filter: &BooleanChunked) -> PolarsResult<Series> {
333        let len = if self.is_empty() {
334            // We still allow a length of `1` because it could be `lit(true)`.
335            polars_ensure!(filter.len() <= 1, ShapeMismatch: "filter's length: {} differs from that of the series: 0", filter.len());
336            0
337        } else if filter.len() == 1 {
338            return match filter.get(0) {
339                Some(true) => Ok(self.clone().into_series()),
340                None | Some(false) => Ok(NullChunked::new(self.name.clone(), 0).into_series()),
341            };
342        } else {
343            polars_ensure!(filter.len() == self.len(), ShapeMismatch: "filter's length: {} differs from that of the series: {}", filter.len(), self.len());
344            filter.sum().unwrap_or(0) as usize
345        };
346        Ok(NullChunked::new(self.name.clone(), len).into_series())
347    }
348
349    fn shift(&self, _periods: i64) -> Series {
350        self.clone().into_series()
351    }
352
353    fn sum_reduce(&self) -> PolarsResult<Scalar> {
354        Ok(Scalar::null(DataType::Null))
355    }
356
357    fn min_reduce(&self) -> PolarsResult<Scalar> {
358        Ok(Scalar::null(DataType::Null))
359    }
360
361    fn max_reduce(&self) -> PolarsResult<Scalar> {
362        Ok(Scalar::null(DataType::Null))
363    }
364
365    fn mean_reduce(&self) -> PolarsResult<Scalar> {
366        Ok(Scalar::null(DataType::Null))
367    }
368
369    fn median_reduce(&self) -> PolarsResult<Scalar> {
370        Ok(Scalar::null(DataType::Null))
371    }
372
373    fn std_reduce(&self, _ddof: u8) -> PolarsResult<Scalar> {
374        Ok(Scalar::null(DataType::Null))
375    }
376
377    fn var_reduce(&self, _ddof: u8) -> PolarsResult<Scalar> {
378        Ok(Scalar::null(DataType::Null))
379    }
380
381    fn append(&mut self, other: &Series) -> PolarsResult<()> {
382        polars_ensure!(other.dtype() == &DataType::Null, ComputeError: "expected null dtype");
383        // we don't create a new null array to keep probability of aligned chunks higher
384        self.length += other.len();
385        self.chunks.extend(other.chunks().iter().cloned());
386        Ok(())
387    }
388    fn append_owned(&mut self, mut other: Series) -> PolarsResult<()> {
389        polars_ensure!(other.dtype() == &DataType::Null, ComputeError: "expected null dtype");
390        // we don't create a new null array to keep probability of aligned chunks higher
391        let other: &mut NullChunked = other._get_inner_mut().as_any_mut().downcast_mut().unwrap();
392        self.length += other.len();
393        self.chunks.extend(std::mem::take(&mut other.chunks));
394        Ok(())
395    }
396
397    fn extend(&mut self, other: &Series) -> PolarsResult<()> {
398        *self = NullChunked::new(self.name.clone(), self.len() + other.len());
399        Ok(())
400    }
401
402    #[cfg(feature = "approx_unique")]
403    fn approx_n_unique(&self) -> PolarsResult<IdxSize> {
404        Ok(if self.is_empty() { 0 } else { 1 })
405    }
406
407    fn clone_inner(&self) -> Arc<dyn SeriesTrait> {
408        Arc::new(self.clone())
409    }
410
411    fn find_validity_mismatch(&self, other: &Series, idxs: &mut Vec<IdxSize>) {
412        ChunkNestingUtils::find_validity_mismatch(self, other, idxs)
413    }
414
415    fn as_any(&self) -> &dyn Any {
416        self
417    }
418
419    fn as_any_mut(&mut self) -> &mut dyn Any {
420        self
421    }
422
423    fn as_phys_any(&self) -> &dyn Any {
424        self
425    }
426
427    fn as_arc_any(self: Arc<Self>) -> Arc<dyn Any + Send + Sync> {
428        self as _
429    }
430}
431
432unsafe impl IntoSeries for NullChunked {
433    fn into_series(self) -> Series
434    where
435        Self: Sized,
436    {
437        Series(Arc::new(self))
438    }
439}
polars_core/series/implementations/null.rs

polars_core/series/implementations/
null.rs
