Skip to content

Check if string contains a substring that matches a pattern

Description

Check if string contains a substring that matches a pattern

Usage

<Expr>$str$contains(pattern, ..., literal = FALSE, strict = TRUE)

Arguments

pattern A character or something can be coerced to a string Expr of a valid regex pattern, compatible with the regex crate.
… These dots are for future extensions and must be empty.
literal Logical. If TRUE, treat pattern as a literal string, not as a regular expression.
strict Logical. If TRUE (default), raise an error if the underlying pattern is not a valid regex, otherwise mask out with a null value.

Details

To modify regular expression behaviour (such as case-sensitivity) with flags, use the inline (?iLmsuxU) syntax. See the regex crate’s section on grouping and flags for additional information about the use of inline expression modifiers.

Value

A polars expression

See Also

  • $str$start_with(): Check if string values start with a substring.
  • $str$ends_with(): Check if string values end with a substring.
  • $str$find(): Return the index position of the first substring matching a pattern.

Examples

library("polars")

# The inline `(?i)` syntax example
pl$DataFrame(s = c("AAA", "aAa", "aaa"))$with_columns(
  default_match = pl$col("s")$str$contains("AA"),
  insensitive_match = pl$col("s")$str$contains("(?i)AA")
)

#> shape: (3, 3)
#> ┌─────┬───────────────┬───────────────────┐
#> │ s   ┆ default_match ┆ insensitive_match │
#> │ --- ┆ ---           ┆ ---               │
#> │ str ┆ bool          ┆ bool              │
#> ╞═════╪═══════════════╪═══════════════════╡
#> │ AAA ┆ true          ┆ true              │
#> │ aAa ┆ false         ┆ true              │
#> │ aaa ┆ false         ┆ true              │
#> └─────┴───────────────┴───────────────────┘

df <- pl$DataFrame(txt = c("Crab", "cat and dog", "rab$bit", NA))
df$with_columns(
  regex = pl$col("txt")$str$contains("cat|bit"),
  literal = pl$col("txt")$str$contains("rab$", literal = TRUE)
)

#> shape: (4, 3)
#> ┌─────────────┬───────┬─────────┐
#> │ txt         ┆ regex ┆ literal │
#> │ ---         ┆ ---   ┆ ---     │
#> │ str         ┆ bool  ┆ bool    │
#> ╞═════════════╪═══════╪═════════╡
#> │ Crab        ┆ false ┆ false   │
#> │ cat and dog ┆ true  ┆ false   │
#> │ rab$bit     ┆ true  ┆ true    │
#> │ null        ┆ null  ┆ null    │
#> └─────────────┴───────┴─────────┘