Strings  字符串

The following section discusses operations performed on string data, which is a frequently used data type when working with dataframes. String processing functions are available in the namespace str.
以下部分讨论对字符串数据执行的操作，这是在处理数据框时常用的数据类型。字符串处理函数可在命名空间 str 中使用。

Working with strings in other dataframe libraries can be highly inefficient due to the fact that strings have unpredictable lengths. Polars mitigates these inefficiencies by following the Arrow Columnar Format specification, so you can write performant data queries on string data too.
在其他数据框库中处理字符串可能效率极低，因为字符串长度不可预测。Polars 通过遵循 Arrow 列式格式规范来缓解这些低效问题，因此您也能对字符串数据编写高性能查询。

The string namespace  字符串命名空间

When working with string data you will likely need to access the namespace str, which aggregates 40+ functions that let you work with strings. As an example of how to access functions from within that namespace, the snippet below shows how to compute the length of the strings in a column in terms of the number of bytes and the number of characters:
在处理字符串数据时，您很可能需要访问命名空间 str ，它集成了 40 多个用于操作字符串的函数。以下代码片段展示了如何从该命名空间中调用函数来计算列中字符串的字节长度和字符长度，作为使用示例：

Python Rust

str.len_bytes · str.len_chars

import polars as pl

df = pl.DataFrame(
    {
        "language": ["English", "Dutch", "Portuguese", "Finish"],
        "fruit": ["pear", "peer", "pêra", "päärynä"],
    }
)

result = df.with_columns(
    pl.col("fruit").str.len_bytes().alias("byte_count"),
    pl.col("fruit").str.len_chars().alias("letter_count"),
)
print(result)

str.len_bytes · str.len_chars

use polars::prelude::*;

let df = df! (
    "language" => ["English", "Dutch", "Portuguese", "Finish"],
    "fruit" => ["pear", "peer", "pêra", "päärynä"],
)?;

let result = df
    .clone()
    .lazy()
    .with_columns([
        col("fruit").str().len_bytes().alias("byte_count"),
        col("fruit").str().len_chars().alias("letter_count"),
    ])
    .collect()?;

println!("{}", result);

shape: (4, 4)
┌────────────┬─────────┬────────────┬──────────────┐
│ language   ┆ fruit   ┆ byte_count ┆ letter_count │
│ ---        ┆ ---     ┆ ---        ┆ ---          │
│ str        ┆ str     ┆ u32        ┆ u32          │
╞════════════╪═════════╪════════════╪══════════════╡
│ English    ┆ pear    ┆ 4          ┆ 4            │
│ Dutch      ┆ peer    ┆ 4          ┆ 4            │
│ Portuguese ┆ pêra    ┆ 5          ┆ 4            │
│ Finish     ┆ päärynä ┆ 10         ┆ 7            │
└────────────┴─────────┴────────────┴──────────────┘

Note  注意

If you are working exclusively with ASCII text, then the results of the two computations will be the same and using len_bytes is recommended since it is faster.
若您仅处理 ASCII 文本，两种计算方式的结果将相同，此时推荐使用 len_bytes ，因其速度更快。

Parsing strings  解析字符串

Polars offers multiple methods for checking and parsing elements of a string column, namely checking for the existence of given substrings or patterns, and counting, extracting, or replacing, them. We will demonstrate some of these operations in the upcoming examples.
Polars 提供了多种方法来检查和解析字符串列的元素，包括检查是否存在给定的子字符串或模式，以及计数、提取或替换它们。我们将在接下来的示例中演示其中一些操作。

Check for the existence of a pattern
检查模式是否存在

We can use the function contains to check for the presence of a pattern within a string. By default, the argument to the function contains is interpreted as a regular expression. If you want to specify a literal substring, set the parameter literal to True.
我们可以使用函数 contains 来检查字符串中是否存在某个模式。默认情况下，函数 contains 的参数会被解释为正则表达式。如果你想指定一个字面子字符串，请将参数 literal 设置为 True 。

For the special cases where you want to check if the strings start or end with a fixed substring, you can use the functions starts_with or ends_with, respectively.
对于需要检查字符串是否以固定子字符串开头或结尾的特殊情况，可以分别使用函数 starts_with 或 ends_with 。

Python Rust

str.contains · str.starts_with · str.ends_with

result = df.select(
    pl.col("fruit"),
    pl.col("fruit").str.starts_with("p").alias("starts_with_p"),
    pl.col("fruit").str.contains("p..r").alias("p..r"),
    pl.col("fruit").str.contains("e+").alias("e+"),
    pl.col("fruit").str.ends_with("r").alias("ends_with_r"),
)
print(result)

str.contains · str.starts_with · str.ends_with · Available on feature regex

let result = df
    .clone()
    .lazy()
    .select([
        col("fruit"),
        col("fruit")
            .str()
            .starts_with(lit("p"))
            .alias("starts_with_p"),
        col("fruit").str().contains(lit("p..r"), true).alias("p..r"),
        col("fruit").str().contains(lit("e+"), true).alias("e+"),
        col("fruit").str().ends_with(lit("r")).alias("ends_with_r"),
    ])
    .collect()?;

println!("{}", result);

shape: (4, 5)
┌─────────┬───────────────┬───────┬───────┬─────────────┐
│ fruit   ┆ starts_with_p ┆ p..r  ┆ e+    ┆ ends_with_r │
│ ---     ┆ ---           ┆ ---   ┆ ---   ┆ ---         │
│ str     ┆ bool          ┆ bool  ┆ bool  ┆ bool        │
╞═════════╪═══════════════╪═══════╪═══════╪═════════════╡
│ pear    ┆ true          ┆ true  ┆ true  ┆ true        │
│ peer    ┆ true          ┆ true  ┆ true  ┆ true        │
│ pêra    ┆ true          ┆ false ┆ false ┆ false       │
│ päärynä ┆ true          ┆ true  ┆ false ┆ false       │
└─────────┴───────────────┴───────┴───────┴─────────────┘

Regex specification  正则表达式规范

Polars relies on the Rust crate regex to work with regular expressions, so you may need to refer to the syntax documentation to see what features and flags are supported. In particular, note that the flavor of regex supported by Polars is different from Python's module re.
Polars 依赖 Rust 的 regex 库来处理正则表达式，因此您可能需要参考其语法文档以了解支持的功能和标志。特别需要注意的是，Polars 支持的正则表达式风格与 Python 的 re 模块有所不同。

Extract a pattern  提取模式

The function extract allows us to extract patterns from the string values in a column. The function extract accepts a regex pattern with one or more capture groups and extracts the capture group specified as the second argument.
函数 extract 允许我们从列中的字符串值提取模式。函数 extract 接受包含一个或多个捕获组的正则表达式模式，并提取作为第二个参数指定的捕获组。

Python Rust

str.extract

df = pl.DataFrame(
    {
        "urls": [
            "http://vote.com/ballon_dor?candidate=messi&ref=polars",
            "http://vote.com/ballon_dor?candidat=jorginho&ref=polars",
            "http://vote.com/ballon_dor?candidate=ronaldo&ref=polars",
        ]
    }
)
result = df.select(
    pl.col("urls").str.extract(r"candidate=(\w+)", group_index=1),
)
print(result)

str.extract

let df = df! (
    "urls" => [
        "http://vote.com/ballon_dor?candidate=messi&ref=polars",
        "http://vote.com/ballon_dor?candidat=jorginho&ref=polars",
        "http://vote.com/ballon_dor?candidate=ronaldo&ref=polars",
    ]
)?;

let result = df
    .clone()
    .lazy()
    .select([col("urls").str().extract(lit(r"candidate=(\w+)"), 1)])
    .collect()?;

println!("{}", result);

shape: (3, 1)
┌─────────┐
│ urls    │
│ ---     │
│ str     │
╞═════════╡
│ messi   │
│ null    │
│ ronaldo │
└─────────┘

To extract all occurrences of a pattern within a string, we can use the function extract_all. In the example below, we extract all numbers from a string using the regex pattern (\d+), which matches one or more digits. The resulting output of the function extract_all is a list containing all instances of the matched pattern within the string.
要提取字符串中所有匹配某个模式的内容，我们可以使用函数 extract_all 。在下面的示例中，我们使用正则表达式模式 (\d+) （匹配一个或多个数字）从字符串中提取所有数字。函数 extract_all 的输出结果是一个列表，包含字符串中所有匹配该模式的实例。

Python Rust

str.extract_all

df = pl.DataFrame({"text": ["123 bla 45 asd", "xyz 678 910t"]})
result = df.select(
    pl.col("text").str.extract_all(r"(\d+)").alias("extracted_nrs"),
)
print(result)

str.extract_all

let df = df! (
    "text" => ["123 bla 45 asd", "xyz 678 910t"]
)?;

let result = df
    .clone()
    .lazy()
    .select([col("text")
        .str()
        .extract_all(lit(r"(\d+)"))
        .alias("extracted_nrs")])
    .collect()?;

println!("{}", result);

shape: (2, 1)
┌────────────────┐
│ extracted_nrs  │
│ ---            │
│ list[str]      │
╞════════════════╡
│ ["123", "45"]  │
│ ["678", "910"] │
└────────────────┘

Replace a pattern  替换一个模式

Akin to the functions extract and extract_all, Polars provides the functions replace and replace_all. These accept a regex pattern or a literal substring (if the parameter literal is set to True) and perform the replacements specified. The function replace will make at most one replacement whereas the function replace_all will make all the non-overlapping replacements it finds.
类似于函数 extract 和 extract_all ，Polars 提供了函数 replace 和 replace_all 。这些函数接受一个正则表达式模式或字面子字符串（如果参数 literal 设置为 True ），并执行指定的替换操作。函数 replace 最多进行一次替换，而函数 replace_all 则会进行所有找到的非重叠替换。

Python Rust

str.replace · str.replace_all

df = pl.DataFrame({"text": ["123abc", "abc456"]})
result = df.with_columns(
    pl.col("text").str.replace(r"\d", "-"),
    pl.col("text").str.replace_all(r"\d", "-").alias("text_replace_all"),
)
print(result)

str.replace · str.replace_all · Available on feature regex

let df = df! (
    "text" => ["123abc", "abc456"]
)?;

let result = df
    .clone()
    .lazy()
    .with_columns([
        col("text").str().replace(lit(r"\d"), lit("-"), false),
        col("text")
            .str()
            .replace_all(lit(r"\d"), lit("-"), false)
            .alias("text_replace_all"),
    ])
    .collect()?;

println!("{}", result);

shape: (2, 2)
┌────────┬──────────────────┐
│ text   ┆ text_replace_all │
│ ---    ┆ ---              │
│ str    ┆ str              │
╞════════╪══════════════════╡
│ -23abc ┆ ---abc           │
│ abc-56 ┆ abc---           │
└────────┴──────────────────┘

Modifying strings  修改字符串

Case conversion  大小写转换

Converting the casing of a string is a common operation and Polars supports it out of the box with the functions to_lowercase, to_titlecase, and to_uppercase:
转换字符串的大小写是一种常见操作，Polars 通过函数 to_lowercase 、 to_titlecase 和 to_uppercase 原生支持这一功能：

Python Rust

str.to_lowercase · str.to_titlecase · str.to_uppercase

addresses = pl.DataFrame(
    {
        "addresses": [
            "128 PERF st",
            "Rust blVD, 158",
            "PoLaRs Av, 12",
            "1042 Query sq",
        ]
    }
)

addresses = addresses.select(
    pl.col("addresses").alias("originals"),
    pl.col("addresses").str.to_titlecase(),
    pl.col("addresses").str.to_lowercase().alias("lower"),
    pl.col("addresses").str.to_uppercase().alias("upper"),
)
print(addresses)

str.to_lowercase · str.to_titlecase · str.to_uppercase · Available on feature nightly

let addresses = df! (
    "addresses" => [
        "128 PERF st",
        "Rust blVD, 158",
        "PoLaRs Av, 12",
        "1042 Query sq",
    ]
)?;

let addresses = addresses
    .clone()
    .lazy()
    .select([
        col("addresses").alias("originals"),
        col("addresses").str().to_titlecase(),
        col("addresses").str().to_lowercase().alias("lower"),
        col("addresses").str().to_uppercase().alias("upper"),
    ])
    .collect()?;

println!("{}", addresses);

shape: (4, 4)
┌────────────────┬────────────────┬────────────────┬────────────────┐
│ originals      ┆ addresses      ┆ lower          ┆ upper          │
│ ---            ┆ ---            ┆ ---            ┆ ---            │
│ str            ┆ str            ┆ str            ┆ str            │
╞════════════════╪════════════════╪════════════════╪════════════════╡
│ 128 PERF st    ┆ 128 Perf St    ┆ 128 perf st    ┆ 128 PERF ST    │
│ Rust blVD, 158 ┆ Rust Blvd, 158 ┆ rust blvd, 158 ┆ RUST BLVD, 158 │
│ PoLaRs Av, 12  ┆ Polars Av, 12  ┆ polars av, 12  ┆ POLARS AV, 12  │
│ 1042 Query sq  ┆ 1042 Query Sq  ┆ 1042 query sq  ┆ 1042 QUERY SQ  │
└────────────────┴────────────────┴────────────────┴────────────────┘

Stripping characters from the ends
去除两端字符

Polars provides five functions in the namespace str that let you strip characters from the ends of the string:
Polars 在 str 命名空间中提供了五个函数，可用于去除字符串两端的字符：

Function  函数	Behaviour  行为
strip_chars	Removes leading and trailing occurrences of the characters specified. 移除指定字符在开头和结尾的出现。
strip_chars_end	Removes trailing occurrences of the characters specified. 移除指定字符的尾部出现项。
strip_chars_start	Removes leading occurrences of the characters specified. 移除指定字符的头部出现项。
strip_prefix	Removes an exact substring prefix if present. 如果存在，移除精确的子字符串前缀。
strip_suffix	Removes an exact substring suffix if present. 如果存在，移除精确的子字符串后缀。

Similarity to Python string methods
与 Python 字符串方法的相似性

strip_chars is similar to Python's string method strip and strip_prefix/strip_suffix are similar to Python's string methods removeprefix and removesuffix, respectively.

It is important to understand that the first three functions interpret their string argument as a set of characters whereas the functions strip_prefix and strip_suffix do interpret their string argument as a literal string.
重要的是要理解前三个函数将其字符串参数解释为一组字符，而函数 strip_prefix 和 strip_suffix 则将其字符串参数解释为字面字符串。

Python Rust

str.strip_chars · str.strip_chars_end · str.strip_chars_start · str.strip_prefix · str.strip_suffix

addr = pl.col("addresses")
chars = ", 0123456789"
result = addresses.select(
    addr.str.strip_chars(chars).alias("strip"),
    addr.str.strip_chars_end(chars).alias("end"),
    addr.str.strip_chars_start(chars).alias("start"),
    addr.str.strip_prefix("128 ").alias("prefix"),
    addr.str.strip_suffix(", 158").alias("suffix"),
)
print(result)

str.strip_chars · str.strip_chars_end · str.strip_chars_start · str.strip_prefix · str.strip_suffix

let addr = col("addresses");
let chars = lit(", 0123456789");
let result = addresses
    .clone()
    .lazy()
    .select([
        addr.clone().str().strip_chars(chars.clone()).alias("strip"),
        addr.clone()
            .str()
            .strip_chars_end(chars.clone())
            .alias("end"),
        addr.clone()
            .str()
            .strip_chars_start(chars.clone())
            .alias("start"),
        addr.clone().str().strip_prefix(lit("128 ")).alias("prefix"),
        addr.clone()
            .str()
            .strip_suffix(lit(", 158"))
            .alias("suffix"),
    ])
    .collect()?;

println!("{}", result);

shape: (4, 5)
┌───────────┬───────────────┬────────────────┬────────────────┬───────────────┐
│ strip     ┆ end           ┆ start          ┆ prefix         ┆ suffix        │
│ ---       ┆ ---           ┆ ---            ┆ ---            ┆ ---           │
│ str       ┆ str           ┆ str            ┆ str            ┆ str           │
╞═══════════╪═══════════════╪════════════════╪════════════════╪═══════════════╡
│ Perf St   ┆ 128 Perf St   ┆ Perf St        ┆ Perf St        ┆ 128 Perf St   │
│ Rust Blvd ┆ Rust Blvd     ┆ Rust Blvd, 158 ┆ Rust Blvd, 158 ┆ Rust Blvd     │
│ Polars Av ┆ Polars Av     ┆ Polars Av, 12  ┆ Polars Av, 12  ┆ Polars Av, 12 │
│ Query Sq  ┆ 1042 Query Sq ┆ Query Sq       ┆ 1042 Query Sq  ┆ 1042 Query Sq │
└───────────┴───────────────┴────────────────┴────────────────┴───────────────┘

If no argument is provided, the three functions strip_chars, strip_chars_end, and strip_chars_start, remove whitespace by default.
如果未提供参数，三个函数 strip_chars 、 strip_chars_end 和 strip_chars_start 默认会移除空白字符。

Slicing  切片

Besides extracting substrings as specified by patterns, you can also slice strings at specified offsets to produce substrings. The general-purpose function for slicing is slice and it takes the starting offset and the optional length of the slice. If the length of the slice is not specified or if it's past the end of the string, Polars slices the string all the way to the end.
除了按照模式提取子字符串外，您还可以在指定偏移量处对字符串进行切片以生成子字符串。通用的切片函数是 slice ，它接受起始偏移量和可选的切片长度。如果未指定切片长度或长度超出字符串末尾，Polars 会将字符串一直切片到末尾。

The functions head and tail are specialised versions used for slicing the beginning and end of a string, respectively.
函数 head 和 tail 是专门用于分别切片字符串开头和结尾的专用版本。

Python Rust

str.slice · str.head · str.tail

df = pl.DataFrame(
    {
        "fruits": ["pear", "mango", "dragonfruit", "passionfruit"],
        "n": [1, -1, 4, -4],
    }
)

result = df.with_columns(
    pl.col("fruits").str.slice(pl.col("n")).alias("slice"),
    pl.col("fruits").str.head(pl.col("n")).alias("head"),
    pl.col("fruits").str.tail(pl.col("n")).alias("tail"),
)
print(result)

str.str_slice · str.str_head · str.str_tail

let df = df! (
    "fruits" => ["pear", "mango", "dragonfruit", "passionfruit"],
    "n" => [1, -1, 4, -4],
)?;

let result = df
    .clone()
    .lazy()
    .with_columns([
        col("fruits")
            .str()
            .slice(col("n"), lit(NULL))
            .alias("slice"),
        col("fruits").str().head(col("n")).alias("head"),
        col("fruits").str().tail(col("n")).alias("tail"),
    ])
    .collect()?;

println!("{}", result);

shape: (4, 5)
┌──────────────┬─────┬─────────┬──────────┬──────────┐
│ fruits       ┆ n   ┆ slice   ┆ head     ┆ tail     │
│ ---          ┆ --- ┆ ---     ┆ ---      ┆ ---      │
│ str          ┆ i64 ┆ str     ┆ str      ┆ str      │
╞══════════════╪═════╪═════════╪══════════╪══════════╡
│ pear         ┆ 1   ┆ ear     ┆ p        ┆ r        │
│ mango        ┆ -1  ┆ o       ┆ mang     ┆ ango     │
│ dragonfruit  ┆ 4   ┆ onfruit ┆ drag     ┆ ruit     │
│ passionfruit ┆ -4  ┆ ruit    ┆ passionf ┆ ionfruit │
└──────────────┴─────┴─────────┴──────────┴──────────┘

API documentation  API 文档

In addition to the examples covered above, Polars offers various other string manipulation functions. To explore these additional methods, you can go to the API documentation of your chosen programming language for Polars.
除了上述示例外，Polars 还提供了多种其他字符串操作函数。要探索这些额外方法，您可以前往所选编程语言的 Polars API 文档进行查阅。