polars_plan/dsl/
array.rs

1use polars_core::prelude::*;
2#[cfg(feature = "array_to_struct")]
3use polars_ops::chunked_array::array::{
4    arr_default_struct_name_gen, ArrToStructNameGenerator, ToStruct,
5};
6
7use crate::dsl::function_expr::ArrayFunction;
8use crate::prelude::*;
9
10/// Specialized expressions for [`Series`] of [`DataType::Array`].
11pub struct ArrayNameSpace(pub Expr);
12
13impl ArrayNameSpace {
14    /// Compute the maximum of the items in every subarray.
15    pub fn max(self) -> Expr {
16        self.0
17            .map_private(FunctionExpr::ArrayExpr(ArrayFunction::Max))
18    }
19
20    /// Compute the minimum of the items in every subarray.
21    pub fn min(self) -> Expr {
22        self.0
23            .map_private(FunctionExpr::ArrayExpr(ArrayFunction::Min))
24    }
25
26    /// Compute the sum of the items in every subarray.
27    pub fn sum(self) -> Expr {
28        self.0
29            .map_private(FunctionExpr::ArrayExpr(ArrayFunction::Sum))
30    }
31
32    /// Compute the std of the items in every subarray.
33    pub fn std(self, ddof: u8) -> Expr {
34        self.0
35            .map_private(FunctionExpr::ArrayExpr(ArrayFunction::Std(ddof)))
36    }
37
38    /// Compute the var of the items in every subarray.
39    pub fn var(self, ddof: u8) -> Expr {
40        self.0
41            .map_private(FunctionExpr::ArrayExpr(ArrayFunction::Var(ddof)))
42    }
43
44    /// Compute the median of the items in every subarray.
45    pub fn median(self) -> Expr {
46        self.0
47            .map_private(FunctionExpr::ArrayExpr(ArrayFunction::Median))
48    }
49
50    /// Keep only the unique values in every sub-array.
51    pub fn unique(self) -> Expr {
52        self.0
53            .map_private(FunctionExpr::ArrayExpr(ArrayFunction::Unique(false)))
54    }
55
56    /// Keep only the unique values in every sub-array.
57    pub fn unique_stable(self) -> Expr {
58        self.0
59            .map_private(FunctionExpr::ArrayExpr(ArrayFunction::Unique(true)))
60    }
61
62    pub fn n_unique(self) -> Expr {
63        self.0
64            .map_private(FunctionExpr::ArrayExpr(ArrayFunction::NUnique))
65    }
66
67    /// Cast the Array column to List column with the same inner data type.
68    pub fn to_list(self) -> Expr {
69        self.0
70            .map_private(FunctionExpr::ArrayExpr(ArrayFunction::ToList))
71    }
72
73    #[cfg(feature = "array_any_all")]
74    /// Evaluate whether all boolean values are true for every subarray.
75    pub fn all(self) -> Expr {
76        self.0
77            .map_private(FunctionExpr::ArrayExpr(ArrayFunction::All))
78    }
79
80    #[cfg(feature = "array_any_all")]
81    /// Evaluate whether any boolean value is true for every subarray
82    pub fn any(self) -> Expr {
83        self.0
84            .map_private(FunctionExpr::ArrayExpr(ArrayFunction::Any))
85    }
86
87    pub fn sort(self, options: SortOptions) -> Expr {
88        self.0
89            .map_private(FunctionExpr::ArrayExpr(ArrayFunction::Sort(options)))
90    }
91
92    pub fn reverse(self) -> Expr {
93        self.0
94            .map_private(FunctionExpr::ArrayExpr(ArrayFunction::Reverse))
95    }
96
97    pub fn arg_min(self) -> Expr {
98        self.0
99            .map_private(FunctionExpr::ArrayExpr(ArrayFunction::ArgMin))
100    }
101
102    pub fn arg_max(self) -> Expr {
103        self.0
104            .map_private(FunctionExpr::ArrayExpr(ArrayFunction::ArgMax))
105    }
106
107    /// Get items in every sub-array by index.
108    pub fn get(self, index: Expr, null_on_oob: bool) -> Expr {
109        self.0.map_many_private(
110            FunctionExpr::ArrayExpr(ArrayFunction::Get(null_on_oob)),
111            &[index],
112            false,
113            None,
114        )
115    }
116
117    /// Join all string items in a sub-array and place a separator between them.
118    /// # Error
119    /// Raise if inner type of array is not `DataType::String`.
120    pub fn join(self, separator: Expr, ignore_nulls: bool) -> Expr {
121        self.0.map_many_private(
122            FunctionExpr::ArrayExpr(ArrayFunction::Join(ignore_nulls)),
123            &[separator],
124            false,
125            None,
126        )
127    }
128
129    #[cfg(feature = "is_in")]
130    /// Check if the sub-array contains specific element
131    pub fn contains<E: Into<Expr>>(self, other: E) -> Expr {
132        let other = other.into();
133
134        self.0.map_many_private(
135            FunctionExpr::ArrayExpr(ArrayFunction::Contains),
136            &[other],
137            false,
138            None,
139        )
140    }
141
142    #[cfg(feature = "array_count")]
143    /// Count how often the value produced by ``element`` occurs.
144    pub fn count_matches<E: Into<Expr>>(self, element: E) -> Expr {
145        let other = element.into();
146
147        self.0.map_many_private(
148            FunctionExpr::ArrayExpr(ArrayFunction::CountMatches),
149            &[other],
150            false,
151            None,
152        )
153    }
154
155    #[cfg(feature = "array_to_struct")]
156    pub fn to_struct(self, name_generator: Option<ArrToStructNameGenerator>) -> PolarsResult<Expr> {
157        Ok(self
158            .0
159            .map(
160                move |s| {
161                    s.array()?
162                        .to_struct(name_generator.clone())
163                        .map(|s| Some(s.into_column()))
164                },
165                GetOutput::map_dtype(move |dt: &DataType| {
166                    let DataType::Array(inner, width) = dt else {
167                        polars_bail!(InvalidOperation: "expected Array type, got: {}", dt)
168                    };
169
170                    let fields = (0..*width)
171                        .map(|i| {
172                            let name = arr_default_struct_name_gen(i);
173                            Field::new(name, inner.as_ref().clone())
174                        })
175                        .collect();
176                    Ok(DataType::Struct(fields))
177                }),
178            )
179            .with_fmt("arr.to_struct"))
180    }
181
182    /// Shift every sub-array.
183    pub fn shift(self, n: Expr) -> Expr {
184        self.0.map_many_private(
185            FunctionExpr::ArrayExpr(ArrayFunction::Shift),
186            &[n],
187            false,
188            None,
189        )
190    }
191    /// Returns a column with a separate row for every array element.
192    pub fn explode(self) -> Expr {
193        self.0
194            .map_private(FunctionExpr::ArrayExpr(ArrayFunction::Explode))
195    }
196}
polars_plan/dsl/array.rs

polars_plan/dsl/
array.rs
