1use std::any::Any;
2use std::borrow::Cow;
3
4use arrow::bitmap::{Bitmap, BitmapBuilder};
5use polars_compute::rolling::QuantileMethod;
6
7use crate::chunked_array::cast::CastOptions;
8#[cfg(feature = "object")]
9use crate::chunked_array::object::PolarsObjectSafe;
10use crate::prelude::*;
11use crate::utils::{first_non_null, last_non_null};
12
13#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
14pub enum IsSorted {
15 Ascending,
16 Descending,
17 Not,
18}
19
20impl IsSorted {
21 pub fn reverse(self) -> Self {
22 use IsSorted::*;
23 match self {
24 Ascending => Descending,
25 Descending => Ascending,
26 Not => Not,
27 }
28 }
29}
30
31pub enum BitRepr {
32 U8(UInt8Chunked),
33 U16(UInt16Chunked),
34 U32(UInt32Chunked),
35 U64(UInt64Chunked),
36 #[cfg(feature = "dtype-u128")]
37 U128(UInt128Chunked),
38}
39
40pub(crate) mod private {
41 use polars_utils::aliases::PlSeedableRandomStateQuality;
42
43 use super::*;
44 use crate::chunked_array::flags::StatisticsFlags;
45 use crate::chunked_array::ops::compare_inner::{TotalEqInner, TotalOrdInner};
46
47 pub trait PrivateSeriesNumeric {
48 fn bit_repr(&self) -> Option<BitRepr>;
52 }
53
54 pub trait PrivateSeries {
55 #[cfg(feature = "object")]
56 fn get_list_builder(
57 &self,
58 _name: PlSmallStr,
59 _values_capacity: usize,
60 _list_capacity: usize,
61 ) -> Box<dyn ListBuilderTrait> {
62 invalid_operation_panic!(get_list_builder, self)
63 }
64
65 fn _field(&self) -> Cow<'_, Field>;
67
68 fn _dtype(&self) -> &DataType;
69
70 fn compute_len(&mut self);
71
72 fn _get_flags(&self) -> StatisticsFlags;
73
74 fn _set_flags(&mut self, flags: StatisticsFlags);
75
76 unsafe fn equal_element(
77 &self,
78 _idx_self: usize,
79 _idx_other: usize,
80 _other: &Series,
81 ) -> bool {
82 invalid_operation_panic!(equal_element, self)
83 }
84 #[expect(clippy::wrong_self_convention)]
85 fn into_total_eq_inner<'a>(&'a self) -> Box<dyn TotalEqInner + 'a>;
86 #[expect(clippy::wrong_self_convention)]
87 fn into_total_ord_inner<'a>(&'a self) -> Box<dyn TotalOrdInner + 'a>;
88
89 fn vec_hash(
90 &self,
91 _build_hasher: PlSeedableRandomStateQuality,
92 _buf: &mut Vec<u64>,
93 ) -> PolarsResult<()>;
94 fn vec_hash_combine(
95 &self,
96 _build_hasher: PlSeedableRandomStateQuality,
97 _hashes: &mut [u64],
98 ) -> PolarsResult<()>;
99
100 #[cfg(feature = "algorithm_group_by")]
104 unsafe fn agg_min(&self, groups: &GroupsType) -> Series {
105 Series::full_null(self._field().name().clone(), groups.len(), self._dtype())
106 }
107 #[cfg(feature = "algorithm_group_by")]
111 unsafe fn agg_max(&self, groups: &GroupsType) -> Series {
112 Series::full_null(self._field().name().clone(), groups.len(), self._dtype())
113 }
114 #[cfg(feature = "algorithm_group_by")]
118 unsafe fn agg_arg_min(&self, groups: &GroupsType) -> Series {
119 Series::full_null(self._field().name().clone(), groups.len(), &IDX_DTYPE)
120 }
121
122 #[cfg(feature = "algorithm_group_by")]
126 unsafe fn agg_arg_max(&self, groups: &GroupsType) -> Series {
127 Series::full_null(self._field().name().clone(), groups.len(), &IDX_DTYPE)
128 }
129
130 #[cfg(feature = "algorithm_group_by")]
133 unsafe fn agg_sum(&self, groups: &GroupsType) -> Series {
134 Series::full_null(self._field().name().clone(), groups.len(), self._dtype())
135 }
136 #[cfg(feature = "algorithm_group_by")]
140 unsafe fn agg_std(&self, groups: &GroupsType, _ddof: u8) -> Series {
141 Series::full_null(self._field().name().clone(), groups.len(), self._dtype())
142 }
143 #[cfg(feature = "algorithm_group_by")]
147 unsafe fn agg_var(&self, groups: &GroupsType, _ddof: u8) -> Series {
148 Series::full_null(self._field().name().clone(), groups.len(), self._dtype())
149 }
150 #[cfg(feature = "algorithm_group_by")]
154 unsafe fn agg_list(&self, groups: &GroupsType) -> Series {
155 Series::full_null(self._field().name().clone(), groups.len(), self._dtype())
156 }
157
158 #[cfg(feature = "bitwise")]
162 unsafe fn agg_and(&self, groups: &GroupsType) -> Series {
163 Series::full_null(self._field().name().clone(), groups.len(), self._dtype())
164 }
165
166 #[cfg(feature = "bitwise")]
170 unsafe fn agg_or(&self, groups: &GroupsType) -> Series {
171 Series::full_null(self._field().name().clone(), groups.len(), self._dtype())
172 }
173
174 #[cfg(feature = "bitwise")]
178 unsafe fn agg_xor(&self, groups: &GroupsType) -> Series {
179 Series::full_null(self._field().name().clone(), groups.len(), self._dtype())
180 }
181
182 fn subtract(&self, _rhs: &Series) -> PolarsResult<Series> {
183 polars_bail!(opq = subtract, self._dtype());
184 }
185 fn add_to(&self, _rhs: &Series) -> PolarsResult<Series> {
186 polars_bail!(opq = add, self._dtype());
187 }
188 fn multiply(&self, _rhs: &Series) -> PolarsResult<Series> {
189 polars_bail!(opq = multiply, self._dtype());
190 }
191 fn divide(&self, _rhs: &Series) -> PolarsResult<Series> {
192 polars_bail!(opq = divide, self._dtype());
193 }
194 fn remainder(&self, _rhs: &Series) -> PolarsResult<Series> {
195 polars_bail!(opq = remainder, self._dtype());
196 }
197 #[cfg(feature = "algorithm_group_by")]
198 fn group_tuples(&self, _multithreaded: bool, _sorted: bool) -> PolarsResult<GroupsType> {
199 polars_bail!(opq = group_tuples, self._dtype());
200 }
201 #[cfg(feature = "zip_with")]
202 fn zip_with_same_type(
203 &self,
204 _mask: &BooleanChunked,
205 _other: &Series,
206 ) -> PolarsResult<Series> {
207 polars_bail!(opq = zip_with_same_type, self._dtype());
208 }
209
210 #[allow(unused_variables)]
211 fn arg_sort_multiple(
212 &self,
213 by: &[Column],
214 _options: &SortMultipleOptions,
215 ) -> PolarsResult<IdxCa> {
216 polars_bail!(opq = arg_sort_multiple, self._dtype());
217 }
218 }
219}
220
221pub trait SeriesTrait:
222 Send + Sync + private::PrivateSeries + private::PrivateSeriesNumeric
223{
224 fn rename(&mut self, name: PlSmallStr);
226
227 fn chunk_lengths(&self) -> ChunkLenIter<'_>;
229
230 fn name(&self) -> &PlSmallStr;
232
233 fn field(&self) -> Cow<'_, Field> {
235 self._field()
236 }
237
238 fn dtype(&self) -> &DataType {
240 self._dtype()
241 }
242
243 fn chunks(&self) -> &Vec<ArrayRef>;
245
246 unsafe fn chunks_mut(&mut self) -> &mut Vec<ArrayRef>;
251
252 fn n_chunks(&self) -> usize {
254 self.chunks().len()
255 }
256
257 fn shrink_to_fit(&mut self) {
259 }
261
262 fn limit(&self, num_elements: usize) -> Series {
264 self.slice(0, num_elements)
265 }
266
267 fn slice(&self, _offset: i64, _length: usize) -> Series;
272
273 fn split_at(&self, _offset: i64) -> (Series, Series);
278
279 fn append(&mut self, other: &Series) -> PolarsResult<()>;
280 fn append_owned(&mut self, other: Series) -> PolarsResult<()>;
281
282 #[doc(hidden)]
283 fn extend(&mut self, _other: &Series) -> PolarsResult<()>;
284
285 fn filter(&self, _filter: &BooleanChunked) -> PolarsResult<Series>;
287
288 fn take(&self, _indices: &IdxCa) -> PolarsResult<Series>;
294
295 unsafe fn take_unchecked(&self, _idx: &IdxCa) -> Series;
302
303 fn take_slice(&self, _indices: &[IdxSize]) -> PolarsResult<Series>;
307
308 unsafe fn take_slice_unchecked(&self, _idx: &[IdxSize]) -> Series;
313
314 fn len(&self) -> usize;
316
317 fn is_empty(&self) -> bool {
319 self.len() == 0
320 }
321
322 fn is_full_null(&self) -> bool {
324 self.len() == self.null_count()
325 }
326
327 fn rechunk(&self) -> Series;
329
330 fn rechunk_validity(&self) -> Option<Bitmap> {
332 if self.chunks().len() == 1 {
333 return self.chunks()[0].validity().cloned();
334 }
335
336 if !self.has_nulls() || self.is_empty() {
337 return None;
338 }
339
340 let mut bm = BitmapBuilder::with_capacity(self.len());
341 for arr in self.chunks() {
342 if let Some(v) = arr.validity() {
343 bm.extend_from_bitmap(v);
344 } else {
345 bm.extend_constant(arr.len(), true);
346 }
347 }
348 bm.into_opt_validity()
349 }
350
351 fn with_validity(&self, validity: Option<Bitmap>) -> Series;
353
354 fn drop_nulls(&self) -> Series {
356 if self.null_count() == 0 {
357 Series(self.clone_inner())
358 } else {
359 self.filter(&self.is_not_null()).unwrap()
360 }
361 }
362
363 fn _sum_as_f64(&self) -> f64 {
365 invalid_operation_panic!(_sum_as_f64, self)
366 }
367
368 fn mean(&self) -> Option<f64> {
371 None
372 }
373
374 fn std(&self, _ddof: u8) -> Option<f64> {
377 None
378 }
379
380 fn var(&self, _ddof: u8) -> Option<f64> {
383 None
384 }
385
386 fn median(&self) -> Option<f64> {
389 None
390 }
391
392 fn new_from_index(&self, _index: usize, _length: usize) -> Series;
403
404 fn trim_lists_to_normalized_offsets(&self) -> Option<Series> {
409 None
410 }
411
412 fn propagate_nulls(&self) -> Option<Series> {
417 None
418 }
419
420 fn deposit(&self, validity: &Bitmap) -> Series;
421
422 fn find_validity_mismatch(&self, other: &Series, idxs: &mut Vec<IdxSize>);
424
425 fn cast(&self, _dtype: &DataType, options: CastOptions) -> PolarsResult<Series>;
426
427 fn get(&self, index: usize) -> PolarsResult<AnyValue<'_>> {
430 polars_ensure!(index < self.len(), oob = index, self.len());
431 let value = unsafe { self.get_unchecked(index) };
433 Ok(value)
434 }
435
436 unsafe fn get_unchecked(&self, _index: usize) -> AnyValue<'_>;
444
445 fn sort_with(&self, _options: SortOptions) -> PolarsResult<Series> {
446 polars_bail!(opq = sort_with, self._dtype());
447 }
448
449 #[allow(unused)]
451 fn arg_sort(&self, options: SortOptions) -> IdxCa {
452 invalid_operation_panic!(arg_sort, self)
453 }
454
455 fn null_count(&self) -> usize;
457
458 fn has_nulls(&self) -> bool;
460
461 fn unique(&self) -> PolarsResult<Series> {
463 polars_bail!(opq = unique, self._dtype());
464 }
465
466 fn n_unique(&self) -> PolarsResult<usize> {
470 polars_bail!(opq = n_unique, self._dtype());
471 }
472
473 fn arg_unique(&self) -> PolarsResult<IdxCa> {
475 polars_bail!(opq = arg_unique, self._dtype());
476 }
477
478 fn unique_id(&self) -> PolarsResult<(IdxSize, Vec<IdxSize>)>;
482
483 fn is_null(&self) -> BooleanChunked;
485
486 fn is_not_null(&self) -> BooleanChunked;
488
489 fn reverse(&self) -> Series;
491
492 fn as_single_ptr(&mut self) -> PolarsResult<usize> {
495 polars_bail!(opq = as_single_ptr, self._dtype());
496 }
497
498 fn shift(&self, _periods: i64) -> Series;
525
526 fn sum_reduce(&self) -> PolarsResult<Scalar> {
531 polars_bail!(opq = sum, self._dtype());
532 }
533 fn max_reduce(&self) -> PolarsResult<Scalar> {
535 polars_bail!(opq = max, self._dtype());
536 }
537 fn min_reduce(&self) -> PolarsResult<Scalar> {
539 polars_bail!(opq = min, self._dtype());
540 }
541 fn median_reduce(&self) -> PolarsResult<Scalar> {
543 polars_bail!(opq = median, self._dtype());
544 }
545 fn mean_reduce(&self) -> PolarsResult<Scalar> {
547 polars_bail!(opq = mean, self._dtype());
548 }
549 fn var_reduce(&self, _ddof: u8) -> PolarsResult<Scalar> {
551 polars_bail!(opq = var, self._dtype());
552 }
553 fn std_reduce(&self, _ddof: u8) -> PolarsResult<Scalar> {
555 polars_bail!(opq = std, self._dtype());
556 }
557 fn quantile_reduce(&self, _quantile: f64, _method: QuantileMethod) -> PolarsResult<Scalar> {
559 polars_bail!(opq = quantile, self._dtype());
560 }
561 fn quantiles_reduce(
563 &self,
564 _quantiles: &[f64],
565 _method: QuantileMethod,
566 ) -> PolarsResult<Scalar> {
567 polars_bail!(opq = quantiles, self._dtype());
568 }
569 fn and_reduce(&self) -> PolarsResult<Scalar> {
571 polars_bail!(opq = and_reduce, self._dtype());
572 }
573 fn or_reduce(&self) -> PolarsResult<Scalar> {
575 polars_bail!(opq = or_reduce, self._dtype());
576 }
577 fn xor_reduce(&self) -> PolarsResult<Scalar> {
579 polars_bail!(opq = xor_reduce, self._dtype());
580 }
581
582 fn first(&self) -> Scalar {
586 let dt = self.dtype();
587 let av = self.get(0).map_or(AnyValue::Null, AnyValue::into_static);
588
589 Scalar::new(dt.clone(), av)
590 }
591
592 fn first_non_null(&self) -> Scalar {
596 let av = if self.len() == 0 {
597 AnyValue::Null
598 } else {
599 let idx = if self.has_nulls() {
600 first_non_null(self.chunks().iter().map(|c| c.as_ref())).unwrap_or(0)
601 } else {
602 0
603 };
604 self.get(idx).map_or(AnyValue::Null, AnyValue::into_static)
605 };
606 Scalar::new(self.dtype().clone(), av)
607 }
608
609 fn last(&self) -> Scalar {
613 let dt = self.dtype();
614 let av = if self.len() == 0 {
615 AnyValue::Null
616 } else {
617 unsafe { self.get_unchecked(self.len() - 1) }.into_static()
619 };
620
621 Scalar::new(dt.clone(), av)
622 }
623
624 fn last_non_null(&self) -> Scalar {
628 let n = self.len();
629 let av = if n == 0 {
630 AnyValue::Null
631 } else {
632 let idx = if self.has_nulls() {
633 last_non_null(self.chunks().iter().map(|c| c.as_ref()), n).unwrap_or(n - 1)
634 } else {
635 n - 1
636 };
637 unsafe { self.get_unchecked(idx) }.into_static()
639 };
640 Scalar::new(self.dtype().clone(), av)
641 }
642
643 #[cfg(feature = "approx_unique")]
644 fn approx_n_unique(&self) -> PolarsResult<IdxSize> {
645 polars_bail!(opq = approx_n_unique, self._dtype());
646 }
647
648 fn clone_inner(&self) -> Arc<dyn SeriesTrait>;
650
651 #[cfg(feature = "object")]
652 fn get_object(&self, _index: usize) -> Option<&dyn PolarsObjectSafe> {
654 invalid_operation_panic!(get_object, self)
655 }
656
657 #[cfg(feature = "object")]
658 unsafe fn get_object_chunked_unchecked(
663 &self,
664 _chunk: usize,
665 _index: usize,
666 ) -> Option<&dyn PolarsObjectSafe> {
667 invalid_operation_panic!(get_object_chunked_unchecked, self)
668 }
669
670 fn as_any(&self) -> &dyn Any;
673
674 fn as_any_mut(&mut self) -> &mut dyn Any;
677
678 fn as_phys_any(&self) -> &dyn Any;
681
682 fn as_arc_any(self: Arc<Self>) -> Arc<dyn Any + Send + Sync>;
683
684 #[cfg(feature = "checked_arithmetic")]
685 fn checked_div(&self, _rhs: &Series) -> PolarsResult<Series> {
686 polars_bail!(opq = checked_div, self._dtype());
687 }
688
689 #[cfg(feature = "rolling_window")]
690 fn rolling_map(
693 &self,
694 _f: &dyn Fn(&Series) -> PolarsResult<Series>,
695 _options: RollingOptionsFixedWindow,
696 ) -> PolarsResult<Series> {
697 polars_bail!(opq = rolling_map, self._dtype());
698 }
699}
700
701impl dyn SeriesTrait + '_ {
702 pub fn unpack<T: PolarsPhysicalType>(&self) -> PolarsResult<&ChunkedArray<T>> {
703 polars_ensure!(&T::get_static_dtype() == self.dtype(), unpack);
704 Ok(self.as_ref())
705 }
706}