polars_core/frame/
horizontal.rs

1use polars_error::{PolarsResult, polars_err};
2
3use super::Column;
4use crate::datatypes::AnyValue;
5use crate::frame::DataFrame;
6use crate::frame::validation::validate_columns_slice;
7
8impl DataFrame {
9    /// Add columns horizontally.
10    ///
11    /// # Safety
12    /// The caller must ensure:
13    /// - the length of all [`Column`] is equal to the height of this [`DataFrame`]
14    /// - the columns names are unique
15    ///
16    /// Note: If `self` is empty, `self.height` will always be overridden by the height of the first
17    /// column in `columns`.
18    ///
19    /// Note that on a debug build this will panic on duplicates / height mismatch.
20    pub unsafe fn hstack_mut_unchecked(&mut self, columns: &[Column]) -> &mut Self {
21        if self.shape() == (0, 0)
22            && let Some(c) = columns.first()
23        {
24            unsafe { self.set_height(c.len()) };
25        }
26
27        unsafe { self.columns_mut() }.extend_from_slice(columns);
28
29        if cfg!(debug_assertions) {
30            if let err @ Err(_) = validate_columns_slice(self.height(), self.columns()) {
31                let initial_width = self.width() - columns.len();
32                unsafe { self.columns_mut() }.truncate(initial_width);
33                err.unwrap();
34            }
35        }
36
37        self
38    }
39
40    /// Add multiple [`Column`] to a [`DataFrame`].
41    /// Errors if the resulting DataFrame columns have duplicate names or unequal heights.
42    ///
43    /// Note: If `self` is empty, `self.height` will always be overridden by the height of the first
44    /// column in `columns`.
45    ///
46    /// # Example
47    ///
48    /// ```rust
49    /// # use polars_core::prelude::*;
50    /// fn stack(df: &mut DataFrame, columns: &[Column]) {
51    ///     df.hstack_mut(columns);
52    /// }
53    /// ```
54    pub fn hstack_mut(&mut self, columns: &[Column]) -> PolarsResult<&mut Self> {
55        if self.shape() == (0, 0)
56            && let Some(c) = columns.first()
57        {
58            unsafe { self.set_height(c.len()) };
59        }
60
61        unsafe { self.columns_mut() }.extend_from_slice(columns);
62
63        if let err @ Err(_) = validate_columns_slice(self.height(), self.columns()) {
64            let initial_width = self.width() - columns.len();
65            unsafe { self.columns_mut() }.truncate(initial_width);
66            err?;
67        }
68
69        Ok(self)
70    }
71}
72
73/// Concat [`DataFrame`]s horizontally.
74///
75/// If the lengths don't match and strict is false we pad with nulls, or return a `ShapeError` if strict is true.
76pub fn concat_df_horizontal(
77    dfs: &[DataFrame],
78    check_duplicates: bool,
79    strict: bool,
80) -> PolarsResult<DataFrame> {
81    let output_height = dfs
82        .iter()
83        .map(|df| df.height())
84        .max()
85        .ok_or_else(|| polars_err!(ComputeError: "cannot concat empty dataframes"))?;
86
87    let owned_df;
88
89    let mut out_width = 0;
90
91    let all_equal_height = dfs.iter().all(|df| {
92        out_width += df.width();
93        df.height() == output_height
94    });
95
96    // if not all equal length, extend the DataFrame with nulls
97    let dfs = if !all_equal_height {
98        if strict {
99            return Err(
100                polars_err!(ShapeMismatch: "cannot concat dataframes with different heights in 'strict' mode"),
101            );
102        }
103        out_width = 0;
104
105        owned_df = dfs
106            .iter()
107            .cloned()
108            .map(|mut df| {
109                out_width += df.width();
110
111                if df.height() != output_height {
112                    let diff = output_height - df.height();
113
114                    // SAFETY: We extend each column with nulls to the point of being of length
115                    // `output_height`. Then, we set the height of the resulting dataframe.
116                    unsafe { df.columns_mut() }.iter_mut().for_each(|c| {
117                        *c = c.extend_constant(AnyValue::Null, diff).unwrap();
118                    });
119
120                    unsafe {
121                        df.set_height(output_height);
122                    }
123                }
124
125                df
126            })
127            .collect::<Vec<_>>();
128        owned_df.as_slice()
129    } else {
130        dfs
131    };
132
133    let mut acc_cols = Vec::with_capacity(out_width);
134
135    for df in dfs {
136        acc_cols.extend(df.columns().iter().cloned());
137    }
138
139    let df = if check_duplicates {
140        DataFrame::new(output_height, acc_cols)?
141    } else {
142        unsafe { DataFrame::new_unchecked(output_height, acc_cols) }
143    };
144
145    Ok(df)
146}
147
148#[cfg(test)]
149mod tests {
150    use polars_error::PolarsError;
151
152    #[test]
153    fn test_hstack_mut_empty_frame_height_validation() {
154        use crate::frame::DataFrame;
155        use crate::prelude::{Column, DataType};
156        let mut df = DataFrame::empty();
157        let result = df.hstack_mut(&[
158            Column::full_null("a".into(), 1, &DataType::Null),
159            Column::full_null("b".into(), 3, &DataType::Null),
160        ]);
161
162        assert!(
163            matches!(result, Err(PolarsError::ShapeMismatch(_))),
164            "expected shape mismatch error"
165        );
166
167        // Ensure the DataFrame is not mutated in the error case.
168        assert_eq!(df.width(), 0);
169    }
170}
polars_core/frame/horizontal.rs

polars_core/frame/
horizontal.rs
