Skip to main content

polars_ops/series/ops/
strings.rs

1use std::borrow::Cow;
2
3use polars_arrow::array::builder::StaticArrayBuilder;
4use polars_arrow::array::{Array, Utf8ViewArrayBuilder};
5use polars_arrow::datatypes::ArrowDataType;
6use polars_core::prelude::{Column, DataType, IntoColumn, StringChunked};
7use polars_core::scalar::Scalar;
8use polars_error::{PolarsContext, PolarsResult};
9use polars_utils::broadcast::broadcast_len;
10use polars_utils::pl_str::PlSmallStr;
11
12use super::format_spec::format_value;
13
14#[inline(always)]
15fn opt_str_to_string(s: Option<&str>) -> &str {
16    s.unwrap_or("null")
17}
18
19/// Fills the `insertions` of `format` with the values of `cs`, each formatted with its Python
20/// format specification in `specs`, if any.
21pub fn str_format(
22    cs: &mut [Column],
23    format: &str,
24    insertions: &[usize],
25    specs: &[Option<PlSmallStr>],
26) -> PolarsResult<Column> {
27    assert_eq!(cs.len(), insertions.len());
28    assert!(!cs.is_empty()); // Checked at IR construction
29
30    let output_name = cs[0].name().clone();
31    let output_length = broadcast_len(cs.iter()).context("str.format")?;
32
33    let mut validity = None;
34    let mut num_scalar_inputs = 0;
35    for c in cs.iter_mut() {
36        if let Some(c_validity) = c.rechunk_validity() {
37            // Column with only nulls means output is only nulls.
38            if c.null_count() == c.len() {
39                return Ok(Column::full_null(
40                    output_name,
41                    output_length,
42                    &DataType::String,
43                ));
44            }
45
46            match &mut validity {
47                v @ None => *v = Some(c_validity),
48                Some(v) => *v = polars_arrow::bitmap::and(v, &c_validity),
49            }
50        }
51    }
52
53    // Values in rows with a null are not converted, as the conversion can fail.
54    let null_count = validity.as_ref().map_or(0, |v| v.unset_bits());
55    if null_count == output_length {
56        return Ok(Column::full_null(
57            output_name,
58            output_length,
59            &DataType::String,
60        ));
61    }
62    for (i, c) in cs.iter_mut().enumerate() {
63        if let Some(validity) = &validity
64            && c.len() != 1
65            && c.null_count() < null_count
66        {
67            *c = c.mask(validity);
68        }
69        *c = match specs.get(i).and_then(Option::as_ref) {
70            Some(spec) => format_value(c, spec)?,
71            None => c.cast(&DataType::String)?,
72        };
73        num_scalar_inputs += usize::from(c.len() == 1);
74    }
75
76    let mut format = Cow::Borrowed(format);
77    let mut insertions = Cow::Borrowed(insertions);
78
79    // Fill in any constants into the format string.
80    if num_scalar_inputs > 0 {
81        let mut filled_format = String::new();
82        filled_format.push_str(&format[..*insertions.first().unwrap()]);
83        insertions = Cow::Owned(
84            cs.iter()
85                .enumerate()
86                .filter_map(|(i, c)| {
87                    let v = if c.len() == 1 {
88                        filled_format.push_str(opt_str_to_string(c.str().unwrap().get(0)));
89                        None
90                    } else {
91                        Some(filled_format.len())
92                    };
93
94                    let s = if i == cs.len() - 1 {
95                        &format[insertions[i]..]
96                    } else {
97                        &format[insertions[i]..insertions[i + 1]]
98                    };
99                    filled_format.push_str(s);
100
101                    v
102                })
103                .collect(),
104        );
105        format = filled_format.into();
106    }
107
108    let format = format.as_ref();
109    let insertions = insertions.as_ref();
110
111    // If the format string is constant.
112    if num_scalar_inputs == cs.len() {
113        let sc = Scalar::from(PlSmallStr::from_str(format));
114        return Ok(Column::new_scalar(output_name, sc, output_length));
115    }
116
117    let mut builder = Utf8ViewArrayBuilder::new(ArrowDataType::Utf8View);
118    builder.reserve(output_length);
119
120    let mut arrays = cs
121        .iter()
122        .filter(|c| c.len() != 1)
123        .map(|c| {
124            let ca = c.str().unwrap();
125            let mut iter = ca.downcast_iter();
126            let arr = iter.next().unwrap();
127            (iter, arr, 0)
128        })
129        .collect::<Vec<_>>();
130
131    // @Performance. There is some smarter stuff that can be done with views and stuff. Don't think
132    // it is worth the complexity.
133
134    // Amortize the format string allocation.
135    let mut s = String::new();
136    for i in 0..output_length {
137        if validity
138            .as_ref()
139            .is_some_and(|v| !unsafe { v.get_bit_unchecked(i) })
140        {
141            unsafe { builder.push_inline_view_ignore_validity(Default::default()) };
142
143            for (iter, arr, elem_idx) in arrays.iter_mut() {
144                while *elem_idx == arr.len() {
145                    *arr = iter.next().unwrap();
146                    *elem_idx = 0;
147                }
148                *elem_idx += 1;
149            }
150
151            continue;
152        }
153
154        s.clear();
155        s.push_str(&format[..insertions[0]]);
156
157        for (j, (iter, arr, elem_idx)) in arrays.iter_mut().enumerate() {
158            while *elem_idx == arr.len() {
159                *arr = iter.next().unwrap();
160                *elem_idx = 0;
161            }
162            s.push_str(opt_str_to_string(arr.get(*elem_idx)));
163            *elem_idx += 1;
164
165            let start = insertions[j];
166            let end = insertions.get(j + 1).copied().unwrap_or(format.len());
167            s.push_str(&format[start..end]);
168        }
169
170        builder.push_value_ignore_validity(&s);
171    }
172
173    let array = builder.freeze().with_validity(validity).to_boxed();
174    Ok(unsafe { StringChunked::from_chunks(output_name, vec![array]) }.into_column())
175}