ExprStringNameSpace

class

class ExprStringNameSpace

Categories: string

String methods, accessed via Expr.str.

Examples

tf.with_columns(col("name").str.to_uppercase().alias("upper"))

Methods

method

to_date

def to_date(
    format: str | None = None,
    *,
    strict: bool = True,
    exact: bool = True,
    cache: bool = True,
) -> Expr

Parse each string into a date.

Parameters:

parameter

formatstr | None

chrono-style date format (e.g. %Y-%m-%d); inferred when omitted.

parameter

strictbool

If True, raise on an unparseable string; if False, set it to null.

parameter

exactbool

If True, the whole string must match; if False, match a date found anywhere in it.

parameter

cachebool

Cache parsing of repeated strings.

Example:

tf.select(col("day").str.to_date("%Y-%m-%d").alias("date"))

Omit the format to have it inferred, and pass strict=False to null out the strings that do not parse:

tf.select(col("day").str.to_date(strict=False).alias("date"))

method

to_datetime

def to_datetime(
    format: str | None = None,
    *,
    time_unit: TimeUnit | None = None,
    time_zone: str | None = None,
    strict: bool = True,
    exact: bool = True,
    cache: bool = True,
    ambiguous: Ambiguous | Expr = 'raise',
) -> Expr

Parse each string into a datetime.

Parameters:

parameter

formatstr | None

chrono-style datetime format; inferred when omitted.

parameter

time_unitTimeUnit | None (Literal['ns', 'us', 'ms'] | None)

Resolution of the result: ns, us or ms.

parameter

time_zonestr | None

Time zone to attach to the result.

parameter

strictbool

If True, raise on an unparseable string; if False, set it to null.

parameter

exactbool

If True, the whole string must match; if False, match a datetime found anywhere in it.

parameter

cachebool

Cache parsing of repeated strings.

parameter

ambiguousAmbiguous | Expr (Literal['earliest', 'latest', 'raise', 'null'] | Expr)

Policy for ambiguous local times: earliest, latest, raise or null.

Example:

tf.select(col("when").str.to_datetime("%Y-%m-%d %H:%M:%S"))

method

to_time

def to_time(
    format: str | None = None,
    *,
    strict: bool = True,
    cache: bool = True,
) -> Expr

Parse each string into a time.

Parameters:

parameter

formatstr | None

chrono-style time format (e.g. %H:%M:%S); inferred when omitted.

parameter

strictbool

If True, raise on an unparseable string; if False, set it to null.

parameter

cachebool

Cache parsing of repeated strings.

Example:

tf.select(col("clock").str.to_time("%H:%M:%S").alias("time"))

method

len_bytes

def len_bytes() -> Expr

Number of bytes in each string (not characters).

Example:

tf.select(col("name").str.len_bytes().alias("bytes"))

method

len_chars

def len_chars() -> Expr

Number of characters in each string (not bytes).

Example:

tf.select(col("name").str.len_chars().alias("chars"))

method

to_uppercase

def to_uppercase() -> Expr

Convert each string to uppercase.

Example:

tf.with_columns(col("name").str.to_uppercase().alias("upper"))

method

to_lowercase

def to_lowercase() -> Expr

Convert each string to lowercase.

Example:

tf.with_columns(col("name").str.to_lowercase().alias("lower"))

method

to_titlecase

def to_titlecase() -> Expr

Title-case each string, capitalizing the first letter of a word.

Example:

tf.with_columns(col("name").str.to_titlecase().alias("title"))

method

strip_chars

def strip_chars(characters: IntoExpr = None) -> Expr

Trim the given characters from both ends of each string.

Parameters:

parameter

charactersIntoExpr (int | float | Decimal | date | time | datetime | timedelta | str | bool | bytes | list[Any] | Expr | str | None)

Set of characters to remove, in any order; whitespace when omitted.

Example:

tf.with_columns(col("name").str.strip_chars().alias("trimmed"))

Pass the characters to remove to strip something other than whitespace:

tf.select(col("email").str.strip_chars(".moc").alias("stripped"))

method

strip_chars_start

def strip_chars_start(characters: IntoExpr = None) -> Expr

Trim the given characters from the start of each string.

Parameters:

parameter

charactersIntoExpr (int | float | Decimal | date | time | datetime | timedelta | str | bool | bytes | list[Any] | Expr | str | None)

Set of characters to remove, in any order; whitespace when omitted.

Example:

tf.select(col("name").str.strip_chars_start().alias("lstripped"))

method

strip_chars_end

def strip_chars_end(characters: IntoExpr = None) -> Expr

Trim the given characters from the end of each string.

Parameters:

parameter

charactersIntoExpr (int | float | Decimal | date | time | datetime | timedelta | str | bool | bytes | list[Any] | Expr | str | None)

Set of characters to remove, in any order; whitespace when omitted.

Example:

tf.select(col("name").str.strip_chars_end().alias("rstripped"))

method

strip_prefix

def strip_prefix(prefix: IntoExpr) -> Expr

Remove prefix from the start of each string if present.

Parameters:

parameter

prefixIntoExpr (int | float | Decimal | date | time | datetime | timedelta | str | bool | bytes | list[Any] | Expr | str | None)

Exact prefix to remove.

Example:

tf.select(col("email").str.strip_prefix("ada").alias("rest"))

method

strip_suffix

def strip_suffix(suffix: IntoExpr) -> Expr

Remove suffix from the end of each string if present.

Parameters:

parameter

suffixIntoExpr (int | float | Decimal | date | time | datetime | timedelta | str | bool | bytes | list[Any] | Expr | str | None)

Exact suffix to remove.

Example:

tf.select(col("email").str.strip_suffix(".com").alias("rest"))

method

pad_start

def pad_start(length: int | IntoExprColumn, fill_char: str = ' ') -> Expr

Left-pad each string to length with a fill character.

Strings already at or over length are unchanged.

Parameters:

parameter

lengthint | IntoExprColumn (int | Expr | str)

Target length.

parameter

fill_charstr

Single character used for padding.

Example:

tf.select(col("qty").str.pad_start(6, "-").alias("padded"))

method

pad_end

def pad_end(length: int | IntoExprColumn, fill_char: str = ' ') -> Expr

Right-pad each string to length with a fill character.

Strings already at or over length are unchanged.

Parameters:

parameter

lengthint | IntoExprColumn (int | Expr | str)

Target length.

parameter

fill_charstr

Single character used for padding.

Example:

tf.select(col("qty").str.pad_end(6, "-").alias("padded"))

method

zfill

def zfill(length: int | IntoExprColumn) -> Expr

Left-pad each numeric string with zeros to length.

A leading sign is preserved before the zeros. Strings already at or over length are unchanged.

Parameters:

parameter

lengthint | IntoExprColumn (int | Expr | str)

Target length.

Example:

tf.select(col("qty").str.zfill(5).alias("padded"))  # "42" -> "00042"

method

contains

def contains(pattern: str | Expr, *, literal: bool = False, strict: bool = True) -> Expr

Return whether each string contains pattern.

Parameters:

parameter

patternstr | Expr

Regular expression, or a literal when literal is True.

parameter

literalbool

Treat pattern as a literal string, not a regex.

parameter

strictbool

If True, raise on an invalid regex.

Example:

tf.filter(col("email").str.contains("@example"))

The pattern is a regular expression unless literal is set:

tf.filter(col("email").str.contains(".com", literal=True))

method

find

def find(pattern: str | Expr, *, literal: bool = False, strict: bool = True) -> Expr

Return the index of the first match of pattern, or null.

Parameters:

parameter

patternstr | Expr

Regular expression, or a literal when literal is True.

parameter

literalbool

Treat pattern as a literal string, not a regex.

parameter

strictbool

If True, raise on an invalid regex.

Example:

tf.select(col("email").str.find("@").alias("at"))

method

ends_with

def ends_with(suffix: str | Expr) -> Expr

Return whether each string ends with suffix.

Parameters:

parameter

suffixstr | Expr

Literal suffix to test for.

Example:

tf.filter(col("email").str.ends_with(".com"))

method

starts_with

def starts_with(prefix: str | Expr) -> Expr

Return whether each string starts with prefix.

Parameters:

parameter

prefixstr | Expr

Literal prefix to test for.

Example:

tf.filter(col("email").str.starts_with("ada"))

method

extract

def extract(pattern: IntoExprColumn, group_index: int = 1) -> Expr

Extract a regex capture group from each string.

Returns null where the pattern does not match.

Parameters:

parameter

patternIntoExprColumn (Expr | str)

Regular expression with one or more capture groups.

parameter

group_indexint

1-based group to return; 0 returns the whole match.

Example:

col("email").str.extract(r"(.+)@(.+)", 2)  # the domain

method

count_matches

def count_matches(pattern: str | Expr, *, literal: bool = False) -> Expr

Count non-overlapping matches of pattern in each string.

Parameters:

parameter

patternstr | Expr

Regular expression, or a literal when literal is True.

parameter

literalbool

Treat pattern as a literal string, not a regex.

Example:

tf.select(
    col("email").str.count_matches(".", literal=True).alias("dots"),
)

method

replace

def replace(
    pattern: str | Expr,
    value: str | Expr,
    *,
    literal: bool = False,
    n: int = 1,
) -> Expr

Replace matches of pattern with value in each string.

Parameters:

parameter

patternstr | Expr

Regular expression, or a literal when literal is True.

parameter

valuestr | Expr

Replacement string; may reference capture groups.

parameter

literalbool

Treat pattern as a literal string, not a regex.

parameter

nint

Number of matches to replace, counted from the left.

Example:

tf.with_columns(col("email").str.replace("example", "acme"))

Only the first match is replaced; use replace_all for every match:

tf.select(col("email").str.replace(r"[aeiou]", "*").alias("masked"))

method

replace_all

def replace_all(
    pattern: str | Expr,
    value: str | Expr,
    *,
    literal: bool = False,
) -> Expr

Replace all matches of pattern with value in each string.

Parameters:

parameter

patternstr | Expr

Regular expression, or a literal when literal is True.

parameter

valuestr | Expr

Replacement string; may reference capture groups.

parameter

literalbool

Treat pattern as a literal string, not a regex.

Example:

tf.select(col("email").str.replace_all(r"[aeiou]", "*"))

method

reverse

def reverse() -> Expr

Reverse the characters of each string.

Example:

tf.select(col("name").str.reverse().alias("reversed"))

method

slice

def slice(
    offset: int | IntoExprColumn,
    length: int | IntoExprColumn | None = None,
) -> Expr

Extract a substring at an offset for a given length.

Parameters:

parameter

offsetint | IntoExprColumn (int | Expr | str)

Start index; a negative value counts from the end.

parameter

lengthint | IntoExprColumn | None (int | Expr | str | None)

Number of characters; to the end of the string when omitted.

Example:

tf.select(col("email").str.slice(0, 3).alias("prefix"))

A negative offset counts from the end of the string:

tf.select(col("email").str.slice(-3).alias("tld"))

method

head

def head(n: int | IntoExprColumn) -> Expr

Return the first n characters of each string.

Parameters:

parameter

nint | IntoExprColumn (int | Expr | str)

Number of leading characters; a negative value drops that many from the end.

Example:

tf.select(col("email").str.head(3).alias("first_three"))

method

tail

def tail(n: int | IntoExprColumn) -> Expr

Return the last n characters of each string.

Parameters:

parameter

nint | IntoExprColumn (int | Expr | str)

Number of trailing characters; a negative value drops that many from the start.

Example:

tf.select(col("email").str.tail(3).alias("last_three"))

method

to_integer

def to_integer(
    *,
    base: int | IntoExprColumn = 10,
    dtype: PolarsIntegerType = Int64,
    strict: bool = True,
) -> Expr

Parse each string into an integer.

#MANUAL CHANGE POST GEN: default dtype is the Tabsdata alias Int64 from tabsdatak.tableframe.datatypes (import added); the generated stub referenced a bare, unimported Int64.

Parameters:

parameter

baseint | IntoExprColumn (int | Expr | str)

Numeric base for parsing (e.g. 10, 2, 16).

parameter

dtypePolarsIntegerType (type[Any])

Target integer type -- a Tabsdata datatype (e.g. Int64, Int32, UInt16), not a raw polars one.

parameter

strictbool

If True, raise on an unparseable string; if False, set it to null.

Example:

tf.select(col("qty").str.to_integer().alias("count"))

Parse in another base, or widen the result type:

tf.select(col("qty").str.to_integer(base=16, dtype=Int32))

method

contains_any

def contains_any(patterns: IntoExpr, *, ascii_case_insensitive: bool = False) -> Expr

Return whether each string contains any of the patterns.

Parameters:

parameter

patternsIntoExpr (int | float | Decimal | date | time | datetime | timedelta | str | bool | bytes | list[Any] | Expr | str | None)

Collection of substrings to search for.

parameter

ascii_case_insensitivebool

Match ASCII letters case-insensitively.

Example:

tf.filter(col("email").str.contains_any(["example", "navy"]))

method

replace_many

def replace_many(
    patterns: IntoExpr | Mapping[str, str],
    replace_with: IntoExpr = ...,
    *,
    ascii_case_insensitive: bool = False,
    leftmost: bool = False,
) -> Expr

Replace all occurrences of many substrings at once.

Parameters:

parameter

patternsIntoExpr | Mapping[str, str] (int | float | Decimal | date | time | datetime | timedelta | str | bool | bytes | list[Any] | Expr | str | None | Mapping[str, str])

Substrings to replace, or a {pattern: replacement} mapping.

parameter

replace_withIntoExpr (int | float | Decimal | date | time | datetime | timedelta | str | bool | bytes | list[Any] | Expr | str | None)

Replacement for each pattern, matched by position; omit when patterns is a mapping.

parameter

ascii_case_insensitivebool

Match ASCII letters case-insensitively.

parameter

leftmostbool

Match the leftmost pattern instead of the longest.

Example:

col("email").str.replace_many({"example": "acme", ".com": ".io"})