depr(python, rust!): Rename ljust/rjust to pad_end/pad_start

crates/polars-lazy/Cargo.toml

@@ -114,7 +114,7 @@ chunked_ids = ["polars-plan/chunked_ids", "polars-core/chunked_ids", "polars-ops
 list_to_struct = ["polars-plan/list_to_struct"]
 python = ["pyo3", "polars-plan/python", "polars-core/python", "polars-io/python"]
 row_hash = ["polars-plan/row_hash"]
-string_justify = ["polars-plan/string_justify"]
+string_pad = ["polars-plan/string_pad"]
 string_from_radix = ["polars-plan/string_from_radix"]
 arg_where = ["polars-plan/arg_where"]
 search_sorted = ["polars-plan/search_sorted"]
@@ -175,7 +175,7 @@ test_all = [
   "regex",
   "ipc",
   "row_hash",
-  "string_justify",
+  "string_pad",
   "string_from_radix",
   "search_sorted",
   "top_k",

crates/polars-ops/Cargo.toml

@@ -86,7 +86,7 @@ list_count = []
 diff = []
 pct_change = ["diff"]
 strings = ["polars-core/strings"]
-string_justify = ["polars-core/strings"]
+string_pad = ["polars-core/strings"]
 string_from_radix = ["polars-core/strings"]
 extract_jsonpath = ["serde_json", "jsonpath_lib", "polars-json"]
 log = []

crates/polars-ops/src/chunked_array/strings/mod.rs

@@ -6,10 +6,10 @@ mod concat;
 mod extract;
 #[cfg(feature = "extract_jsonpath")]
 mod json_path;
-#[cfg(feature = "string_justify")]
-mod justify;
 #[cfg(feature = "strings")]
 mod namespace;
+#[cfg(feature = "string_pad")]
+mod pad;
 #[cfg(feature = "strings")]
 mod replace;
 #[cfg(feature = "strings")]

crates/polars-ops/src/chunked_array/strings/namespace.rs

@@ -156,32 +156,38 @@ pub trait Utf8NameSpaceImpl: AsUtf8 {
         ca.apply_kernel_cast(&string_len_bytes)
     }
 
-    /// Return a copy of the string left filled with ASCII '0' digits to make a string of length width.
-    /// A leading sign prefix ('+'/'-') is handled by inserting the padding after the sign character
-    /// rather than before.
-    /// The original string is returned if width is less than or equal to `s.len()`.
-    #[cfg(feature = "string_justify")]
-    fn zfill(&self, alignment: usize) -> Utf8Chunked {
+    /// Pad the start of the string until it reaches the given length.
+    ///
+    /// Padding is done using the specified `fill_char`.
+    /// Strings with length equal to or greater than the given length are
+    /// returned as-is.
+    #[cfg(feature = "string_pad")]
+    fn pad_start(&self, length: usize, fill_char: char) -> Utf8Chunked {
         let ca = self.as_utf8();
-        justify::zfill(ca, alignment)
+        pad::pad_start(ca, length, fill_char)
     }
 
-    /// Return the string left justified in a string of length width.
-    /// Padding is done using the specified `fillchar`,
-    /// The original string is returned if width is less than or equal to `s.len()`.
-    #[cfg(feature = "string_justify")]
-    fn ljust(&self, width: usize, fillchar: char) -> Utf8Chunked {
+    /// Pad the end of the string until it reaches the given length.
+    ///
+    /// Padding is done using the specified `fill_char`.
+    /// Strings with length equal to or greater than the given length are
+    /// returned as-is.
+    #[cfg(feature = "string_pad")]
+    fn pad_end(&self, length: usize, fill_char: char) -> Utf8Chunked {
         let ca = self.as_utf8();
-        justify::ljust(ca, width, fillchar)
+        pad::pad_end(ca, length, fill_char)
     }
 
-    /// Return the string right justified in a string of length width.
-    /// Padding is done using the specified `fillchar`,
-    /// The original string is returned if width is less than or equal to `s.len()`.
-    #[cfg(feature = "string_justify")]
-    fn rjust(&self, width: usize, fillchar: char) -> Utf8Chunked {
-        let ca = self.as_utf8();
-        justify::rjust(ca, width, fillchar)
+    /// Pad the start of the string with zeros until it reaches the given length.
+    ///
+    /// A sign prefix (`-`) is handled by inserting the padding after the sign
+    /// character rather than before.
+    /// Strings with length equal to or greater than the given length are
+    /// returned as-is.
+    #[cfg(feature = "string_pad")]
+    fn zfill(&self, length: usize) -> Utf8Chunked {
+        let ca = self.as_utf8();
+        pad::zfill(ca, length)
     }
 
     /// Check if strings contain a regex pattern.

crates/polars-ops/src/chunked_array/strings/justify.rs → crates/polars-ops/src/chunked_array/strings/pad.rs

@@ -2,18 +2,18 @@ use std::fmt::Write;
 
 use polars_core::prelude::Utf8Chunked;
 
-pub(super) fn ljust<'a>(ca: &'a Utf8Chunked, width: usize, fillchar: char) -> Utf8Chunked {
+pub(super) fn pad_end<'a>(ca: &'a Utf8Chunked, length: usize, fill_char: char) -> Utf8Chunked {
     // amortize allocation
     let mut buf = String::new();
     let f = |s: &'a str| {
-        let padding = width.saturating_sub(s.len());
+        let padding = length.saturating_sub(s.len());
         if padding == 0 {
             s
         } else {
             buf.clear();
             buf.push_str(s);
             for _ in 0..padding {
-                buf.push(fillchar)
+                buf.push(fill_char)
             }
             // extend lifetime
             // lifetime is bound to 'a
@@ -24,17 +24,17 @@ pub(super) fn ljust<'a>(ca: &'a Utf8Chunked, width: usize, fillchar: char) -> Ut
     ca.apply_mut(f)
 }
 
-pub(super) fn rjust<'a>(ca: &'a Utf8Chunked, width: usize, fillchar: char) -> Utf8Chunked {
+pub(super) fn pad_start<'a>(ca: &'a Utf8Chunked, length: usize, fill_char: char) -> Utf8Chunked {
     // amortize allocation
     let mut buf = String::new();
     let f = |s: &'a str| {
-        let padding = width.saturating_sub(s.len());
+        let padding = length.saturating_sub(s.len());
         if padding == 0 {
             s
         } else {
             buf.clear();
             for _ in 0..padding {
-                buf.push(fillchar)
+                buf.push(fill_char)
             }
             buf.push_str(s);
             // extend lifetime
@@ -46,30 +46,30 @@ pub(super) fn rjust<'a>(ca: &'a Utf8Chunked, width: usize, fillchar: char) -> Ut
     ca.apply_mut(f)
 }
 
-pub(super) fn zfill<'a>(ca: &'a Utf8Chunked, alignment: usize) -> Utf8Chunked {
+pub(super) fn zfill<'a>(ca: &'a Utf8Chunked, length: usize) -> Utf8Chunked {
     // amortize allocation
     let mut buf = String::new();
     let f = |s: &'a str| {
-        let alignment = alignment.saturating_sub(s.len());
-        if alignment == 0 {
+        let length = length.saturating_sub(s.len());
+        if length == 0 {
             return s;
         }
         buf.clear();
         if let Some(stripped) = s.strip_prefix('-') {
             write!(
                 &mut buf,
-                "-{:0alignment$}{value}",
+                "-{:0length$}{value}",
                 0,
-                alignment = alignment,
+                length = length,
                 value = stripped
             )
             .unwrap();
         } else {
             write!(
                 &mut buf,
-                "{:0alignment$}{value}",
+                "{:0length$}{value}",
                 0,
-                alignment = alignment,
+                length = length,
                 value = s
             )
             .unwrap();

crates/polars-plan/Cargo.toml

@@ -121,7 +121,7 @@ log = ["polars-ops/log"]
 chunked_ids = ["polars-core/chunked_ids"]
 list_to_struct = ["polars-ops/list_to_struct"]
 row_hash = ["polars-core/row_hash", "polars-ops/hash"]
-string_justify = ["polars-ops/string_justify"]
+string_pad = ["polars-ops/string_pad"]
 string_from_radix = ["polars-ops/string_from_radix"]
 arg_where = []
 search_sorted = ["polars-ops/search_sorted"]

crates/polars-plan/src/dsl/function_expr/mod.rs

@@ -1041,17 +1041,17 @@ impl From<StringFunction> for SpecialEq<Arc<dyn SeriesUdf>> {
             },
             LenBytes => map!(strings::len_bytes),
             LenChars => map!(strings::len_chars),
-            #[cfg(feature = "string_justify")]
-            Zfill(alignment) => {
-                map!(strings::zfill, alignment)
+            #[cfg(feature = "string_pad")]
+            PadEnd { length, fill_char } => {
+                map!(strings::pad_end, length, fill_char)
             },
-            #[cfg(feature = "string_justify")]
-            LJust { width, fillchar } => {
-                map!(strings::ljust, width, fillchar)
+            #[cfg(feature = "string_pad")]
+            PadStart { length, fill_char } => {
+                map!(strings::pad_start, length, fill_char)
             },
-            #[cfg(feature = "string_justify")]
-            RJust { width, fillchar } => {
-                map!(strings::rjust, width, fillchar)
+            #[cfg(feature = "string_pad")]
+            ZFill(alignment) => {
+                map!(strings::zfill, alignment)
             },
             #[cfg(feature = "temporal")]
             Strptime(dtype, options) => {

crates/polars-plan/src/dsl/function_expr/strings.rs

@@ -46,11 +46,6 @@ pub enum StringFunction {
     FromRadix(u32, bool),
     LenBytes,
     LenChars,
-    #[cfg(feature = "string_justify")]
-    LJust {
-        width: usize,
-        fillchar: char,
-    },
     Lowercase,
     #[cfg(feature = "extract_jsonpath")]
     JsonExtract {
@@ -64,10 +59,15 @@ pub enum StringFunction {
         n: i64,
         literal: bool,
     },
-    #[cfg(feature = "string_justify")]
-    RJust {
-        width: usize,
-        fillchar: char,
+    #[cfg(feature = "string_pad")]
+    PadStart {
+        length: usize,
+        fill_char: char,
+    },
+    #[cfg(feature = "string_pad")]
+    PadEnd {
+        length: usize,
+        fill_char: char,
     },
     Slice(i64, Option<u64>),
     StartsWith,
@@ -91,8 +91,8 @@ pub enum StringFunction {
     #[cfg(feature = "nightly")]
     Titlecase,
     Uppercase,
-    #[cfg(feature = "string_justify")]
-    Zfill(usize),
+    #[cfg(feature = "string_pad")]
+    ZFill(usize),
 }
 
 impl StringFunction {
@@ -133,8 +133,8 @@ impl StringFunction {
             | StripPrefix
             | StripSuffix
             | Slice(_, _) => mapper.with_same_dtype(),
-            #[cfg(feature = "string_justify")]
-            Zfill { .. } | LJust { .. } | RJust { .. } => mapper.with_same_dtype(),
+            #[cfg(feature = "string_pad")]
+            PadStart { .. } | PadEnd { .. } | ZFill { .. } => mapper.with_same_dtype(),
             #[cfg(feature = "dtype-struct")]
             SplitExact { n, .. } => mapper.with_dtype(DataType::Struct(
                 (0..n + 1)
@@ -171,13 +171,13 @@ impl Display for StringFunction {
             StringFunction::FromRadix { .. } => "from_radix",
             #[cfg(feature = "extract_jsonpath")]
             StringFunction::JsonExtract { .. } => "json_extract",
-            #[cfg(feature = "string_justify")]
-            StringFunction::LJust { .. } => "ljust",
             StringFunction::LenBytes => "len_bytes",
             StringFunction::Lowercase => "lowercase",
             StringFunction::LenChars => "len_chars",
-            #[cfg(feature = "string_justify")]
-            StringFunction::RJust { .. } => "rjust",
+            #[cfg(feature = "string_pad")]
+            StringFunction::PadEnd { .. } => "pad_end",
+            #[cfg(feature = "string_pad")]
+            StringFunction::PadStart { .. } => "pad_start",
             #[cfg(feature = "regex")]
             StringFunction::Replace { .. } => "replace",
             StringFunction::Slice(_, _) => "slice",
@@ -211,8 +211,8 @@ impl Display for StringFunction {
             #[cfg(feature = "dtype-decimal")]
             StringFunction::ToDecimal(_) => "to_decimal",
             StringFunction::Uppercase => "uppercase",
-            #[cfg(feature = "string_justify")]
-            StringFunction::Zfill(_) => "zfill",
+            #[cfg(feature = "string_pad")]
+            StringFunction::ZFill(_) => "zfill",
         };
         write!(f, "str.{s}")
     }
@@ -281,21 +281,22 @@ pub(super) fn extract_groups(s: &Series, pat: &str, dtype: &DataType) -> PolarsR
     ca.extract_groups(pat, dtype)
 }
 
-#[cfg(feature = "string_justify")]
-pub(super) fn zfill(s: &Series, alignment: usize) -> PolarsResult<Series> {
+#[cfg(feature = "string_pad")]
+pub(super) fn pad_start(s: &Series, length: usize, fill_char: char) -> PolarsResult<Series> {
     let ca = s.utf8()?;
-    Ok(ca.zfill(alignment).into_series())
+    Ok(ca.pad_start(length, fill_char).into_series())
 }
 
-#[cfg(feature = "string_justify")]
-pub(super) fn ljust(s: &Series, width: usize, fillchar: char) -> PolarsResult<Series> {
+#[cfg(feature = "string_pad")]
+pub(super) fn pad_end(s: &Series, length: usize, fill_char: char) -> PolarsResult<Series> {
     let ca = s.utf8()?;
-    Ok(ca.ljust(width, fillchar).into_series())
+    Ok(ca.pad_end(length, fill_char).into_series())
 }
-#[cfg(feature = "string_justify")]
-pub(super) fn rjust(s: &Series, width: usize, fillchar: char) -> PolarsResult<Series> {
+
+#[cfg(feature = "string_pad")]
+pub(super) fn zfill(s: &Series, length: usize) -> PolarsResult<Series> {
     let ca = s.utf8()?;
-    Ok(ca.rjust(width, fillchar).into_series())
+    Ok(ca.zfill(length).into_series())
 }
 
 pub(super) fn strip_chars(s: &[Series]) -> PolarsResult<Series> {

crates/polars-plan/src/dsl/string.rs

@@ -93,31 +93,37 @@ impl StringNameSpace {
         ))
     }
 
-    /// Return a copy of the string left filled with ASCII '0' digits to make a string of length width.
-    /// A leading sign prefix ('+'/'-') is handled by inserting the padding after the sign character
-    /// rather than before.
-    /// The original string is returned if width is less than or equal to `s.len()`.
-    #[cfg(feature = "string_justify")]
-    pub fn zfill(self, alignment: usize) -> Expr {
-        self.0.map_private(StringFunction::Zfill(alignment).into())
-    }
-
-    /// Return the string left justified in a string of length width.
-    /// Padding is done using the specified `fillchar`,
-    /// The original string is returned if width is less than or equal to `s.len()`.
-    #[cfg(feature = "string_justify")]
-    pub fn ljust(self, width: usize, fillchar: char) -> Expr {
+    /// Pad the start of the string until it reaches the given length.
+    ///
+    /// Padding is done using the specified `fill_char`.
+    /// Strings with length equal to or greater than the given length are
+    /// returned as-is.
+    #[cfg(feature = "string_pad")]
+    pub fn pad_start(self, length: usize, fill_char: char) -> Expr {
         self.0
-            .map_private(StringFunction::LJust { width, fillchar }.into())
+            .map_private(StringFunction::PadStart { length, fill_char }.into())
     }
 
-    /// Return the string right justified in a string of length width.
-    /// Padding is done using the specified `fillchar`,
-    /// The original string is returned if width is less than or equal to `s.len()`.
-    #[cfg(feature = "string_justify")]
-    pub fn rjust(self, width: usize, fillchar: char) -> Expr {
+    /// Pad the end of the string until it reaches the given length.
+    ///
+    /// Padding is done using the specified `fill_char`.
+    /// Strings with length equal to or greater than the given length are
+    /// returned as-is.
+    #[cfg(feature = "string_pad")]
+    pub fn pad_end(self, length: usize, fill_char: char) -> Expr {
         self.0
-            .map_private(StringFunction::RJust { width, fillchar }.into())
+            .map_private(StringFunction::PadEnd { length, fill_char }.into())
+    }
+
+    /// Pad the start of the string with zeros until it reaches the given length.
+    ///
+    /// A sign prefix (`-`) is handled by inserting the padding after the sign
+    /// character rather than before.
+    /// Strings with length equal to or greater than the given length are
+    /// returned as-is.
+    #[cfg(feature = "string_pad")]
+    pub fn zfill(self, length: usize) -> Expr {
+        self.0.map_private(StringFunction::ZFill(length).into())
     }
 
     /// Extract each successive non-overlapping match in an individual string as an array

crates/polars/Cargo.toml

@@ -170,7 +170,7 @@ list_count = ["polars-ops/list_count", "polars-lazy?/list_count"]
 list_take = ["polars-ops/list_take", "polars-lazy?/list_take"]
 describe = ["polars-core/describe"]
 timezones = ["polars-core/timezones", "polars-lazy?/timezones", "polars-io/timezones"]
-string_justify = ["polars-lazy?/string_justify", "polars-ops/string_justify"]
+string_pad = ["polars-lazy?/string_pad", "polars-ops/string_pad"]
 string_from_radix = ["polars-lazy?/string_from_radix", "polars-ops/string_from_radix"]
 arg_where = ["polars-lazy?/arg_where"]
 search_sorted = ["polars-lazy?/search_sorted"]