Skip to content

Check if string contains a substring that matches a pattern

Source code

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.
… Ignored.
literal Logical. If TRUE (default), 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

Expr of Boolean data type

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    │
#> └─────────────┴───────┴─────────┘