Expr.Str (StringOps)

Namespace: Polars.FSharp

Instance Methods

Contains

Check if the string contains a substring or regex pattern.

member Contains(pattern: string, ?literal: bool, ?strict: bool) : Expr

Parameters

Name	Type	Description
pattern	string	-
literal	bool (optional)	-
strict	bool (optional)	-

---

ContainsAny

Use the Aho-Corasick algorithm to find matches. Determines if any of the patterns are contained in the string.

member ContainsAny(pattern: string, ?asciiCaseInsensitive: bool) : Expr

Parameters

Name	Type	Description
pattern	string	-
asciiCaseInsensitive	bool (optional)	Enable ASCII-aware case-insensitive matching. When this option is enabled, searching will be performed without respect to case for ASCII letters (a-z and A-Z) only.

---

CountMatches

Count all successive non-overlapping regex matches.

member CountMatches(pattern: string, ?literal: bool) : Expr

Parameters

Name	Type	Description
pattern	string	A valid regular expression pattern, compatible with the regex crate.
literal	bool (optional)	Treat pattern as a literal string, not as a regular expression.

Returns: Expression of data type UInt32. Returns null if the original value is null.

---

Decode

Decode values using the provided encoding.

member Decode(encoding: TransferEncoding, ?strict: bool) : Expr

Parameters

Name	Type	Description
encoding	TransferEncoding	The encoding to use.
strict	bool (optional)	Raise an error if the underlying value cannot be decoded, otherwise mask out with a null value.

Returns: Expression of data type Binary.

---

Encode

Encode values using the provided encoding.

member Encode(encoding: TransferEncoding) : Expr

Parameters

Name	Type	Description
encoding	TransferEncoding	The encoding to use.

Returns: Expression of data type String.

---

EndsWith

Check if string ends with a specific suffix.

member EndsWith(suffix: string) : Expr

Parameters

Name	Type	Description
suffix	string	-

---

EscapeRegex

Returns string values with all regular expression meta characters escaped.

member EscapeRegex : unit -> Expr

---

Extract

Extract the first match of a regex pattern.

member Extract(pattern: string, ?groupIndex: int) : Expr

Parameters

Name	Type	Description
pattern	string	Regex pattern with capture groups.
groupIndex	int (optional)	The index of the capture group to extract (usually 1).

---

ExtractAll

Extract all matches for the given regex pattern. Extract each successive non-overlapping regex match in an individual string as a list. If the haystack string is null, null is returned.

member ExtractAll(pattern: string) : Expr

Parameters

Name	Type	Description
pattern	string	A valid regular expression pattern, compatible with the regex crate.

Returns: Expression of data type List(String).

---

ExtractGroups

Extract all capture groups for the given regex pattern.

member ExtractGroups(pattern: string) : Expr

Parameters

Name	Type	Description
pattern	string	A valid regular expression pattern containing at least one capture group, compatible with the regex crate.

Returns: Expression of data type Struct with fields of data type String.

---

ExtractMany

Use the Aho-Corasick algorithm to extract many matches.This method supports matching on string literals only, and does not support regular expression matching.

member ExtractMany(
    patterns: Expr,
    ?asciiCaseInsensitive: bool,
    ?overlapping: bool,
    ?leftmost: bool
) : Expr

Parameters

Name	Type	Description
patterns	Expr	String patterns to search.
asciiCaseInsensitive	bool (optional)	Enable ASCII-aware case-insensitive matching. When this option is enabled, searching will be performed without respect to case for ASCII letters (a-z and A-Z) only.
overlapping	bool (optional)	Whether matches may overlap.
leftmost	bool (optional)	Guarantees in case there are overlapping matches that the leftmost match is used. In case there are multiple candidates for the leftmost match the pattern which comes first in patterns is used. May not be used together with overlapping = True.

---

Find

Return the bytes offset of the first substring matching a pattern. If the pattern is not found, returns None.

member Find(pattern: string, ?literal: bool, ?strict: bool) : Expr

Parameters

Name	Type	Description
pattern	string	A valid regular expression pattern, compatible with the regex crate.
literal	bool (optional)	Treat pattern as a literal string, not as a regular expression.
strict	bool (optional)	Raise an error if the underlying pattern is not a valid regex, otherwise mask out with a null value.

---

FindMany

Find the indices of all matches of a pattern in a string.

member FindMany(
    patterns: Expr,
    ?asciiCaseInsensitive: bool,
    ?overlapping: bool,
    ?leftmost: bool
) : Expr

Parameters

Name	Type	Description
patterns	Expr	The pattern to search for.
asciiCaseInsensitive	bool (optional)	Whether to perform an ASCII-only case-insensitive search.
overlapping	bool (optional)	Whether to allow overlapping matches.
leftmost	bool (optional)	Whether to search from the left.

Returns: Expression of data type List<int>.

---

Head

Return the first n characters of each string in a String Series.

member Head(n: int) : Expr

Parameters

Name	Type	Description
n	int	Length of the slice When the n input is negative, head returns characters up to the n`th from the end of the string. For example, if n = -3, then all characters except the last three are returned.

Returns: Expression of data type String.

---

Join

Vertically concatenate the string values in the column to a single string value.

member Join(?delimiter: string, ?ignoreNulls: bool) : Expr

Parameters

Name	Type	Description
delimiter	string (optional)	The delimiter to insert between consecutive string values.
ignoreNulls	bool (optional)	Ignore null values (default). If set to False, null values will be propagated. This means that if the column contains any null values, the output is null.

Returns: Expression of data type String.

---

JsonDecode

Parse string values as JSON. Throws an error if invalid JSON strings are encountered.

member JsonDecode(dtype: DataTypeExpr) : Expr
member JsonDecode(dtype: DataType) : Expr

Parameters

Name	Type	Description
dtype	DataTypeExpr	The datatype to cast the extracted value to.

---

JsonPathMatch

Extract the first match from a JSON string using the provided JSONPath. Throws errors if invalid JSON strings are encountered. All return values are cast to String, regardless of the original value.

member JsonPathMatch(jsonPath: string) : Expr

Parameters

Name	Type	Description
jsonPath	string	A valid JSONPath query string.

Returns: Expression of data type String. Contains null values if original value is null or the json_path returns nothing.

---

LenBytes

Get length in bytes.

member LenBytes : unit -> Expr

---

LenChars

Return the length of each string as the number of characters.

member LenChars : unit -> Expr

Returns: Expression of data type UInt32.

---

Normalize

Returns the Unicode normal form of the string values.

member Normalize(form: NormalizationForm) : Expr

Parameters

Name	Type	Description
form	NormalizationForm	Unicode form to use.

---

PadEnd

Pad the end of the string until it reaches the given length.

member PadEnd(length: int, ?fillChar: string) : Expr

Parameters

Name	Type	Description
length	int	Pad the string until it reaches this length. Strings with length equal to or greater than this value are returned as-is.
fillChar	string (optional)	The character to pad the string with.

---

PadStart

Pad the start of the string until it reaches the given length.

member PadStart(length: int, ?fillChar: string) : Expr

Parameters

Name	Type	Description
length	int	Pad the string until it reaches this length. Strings with length equal to or greater than this value are returned as-is.
fillChar	string (optional)	The character to pad the string with.

---

Replace

Replace first matching regex/literal substring with a new string value.

member Replace(
    pattern: string,
    value: string,
    ?literal: bool,
    ?n: int
) : Expr

Parameters

Name	Type	Description
pattern	string	A valid regular expression pattern, compatible with the regex crate.
value	string	String that will replace the matched substring.
literal	bool (optional)	Treat pattern as a literal string, not a regex.
n	int (optional)	Number of matches to replace.

---

ReplaceAll

Replace all occurrences of a pattern with a value.

member ReplaceAll(pattern: string, value: string, ?literal: bool) : Expr

Parameters

Name	Type	Description
pattern	string	The pattern to search for.
value	string	The value to replace with.
literal	bool (optional)	Whether to interpret the pattern as literal value(not Regex).

---

ReplaceMany

Use the Aho-Corasick algorithm to replace many matches.

member ReplaceMany(
    patterns: Expr,
    replaceWith: Expr,
    ?asciiCaseInsensitive: bool,
    ?leftmost: bool
) : Expr

Parameters

Name	Type	Description
patterns	Expr	Expression yielding string patterns to search and replace.
replaceWith	Expr	Strings to replace where a pattern was a match. Length must match the length of patterns or have length 1. This can be broadcasted, so it supports many:one and many:many.
asciiCaseInsensitive	bool (optional)	Enable ASCII-aware case-insensitive matching.
leftmost	bool (optional)	Guarantees in case there are overlapping matches that the leftmost match is used.

---

Reverse

Returns string values in reversed order.

member Reverse : unit -> Expr

---

Slice

Slice the string by offset and length.

member Slice(offset: int64, ?length: uint64) : Expr

Parameters

Name	Type	Description
offset	int64	Start index.
length	uint64 (optional)	Length of the slice.

---

Split

Split the string by a substring.

member Split(
    separator: string,
    ?inclusive: bool,
    ?literal: bool,
    ?strict: bool
) : Expr

Parameters

Name	Type	Description
separator	string	-
inclusive	bool (optional)	If True, include the split character/string in the results.
literal	bool (optional)	Treat by as a literal string, not as a regular expression.
strict	bool (optional)	Raise an error if the underlying pattern is not a valid regex, otherwise mask out with a null value.

Returns: Expression/Series of data type String.

---

SplitExact

Split the string by a substring using n splits. Results in a struct of n+1 fields. If it cannot make n splits, the remaining field elements will be null.

member SplitExact(by: string, n: int, ?inclusive: bool) : Expr

Parameters

Name	Type	Description
by	string	Substring to split by.
n	int	Number of splits to make.
inclusive	bool (optional)	If True, include the split character/string in the results.

Returns: Expression/Series of data type Struct with fields of data type String.

---

SplitN

Split the string by a substring, restricted to returning at most n items.

If the number of possible splits is less than n-1, the remaining field elements will be null. If the number of possible splits is n-1 or greater, the last (nth) substring will contain the remainder of the string.

member SplitN(by: string, n: int) : Expr

Parameters

Name	Type	Description
by	string	Substring to split by.
n	int	Max number of items to return.

Returns: Expression/Series of data type Struct with fields of data type String.

---

StartsWith

Check if string starts with a specific prefix.

member StartsWith(prefix: string) : Expr

Parameters

Name	Type	Description
prefix	string	-

---

StripChars

Remove leading and trailing characters. If matches is null, whitespace is removed.

member StripChars(?characters: string) : Expr

Parameters

Name	Type	Description
characters	string (optional)	-

---

StripCharsEnd

Remove trailing characters (Right Trim). If 'matches' is omitted, whitespace is removed.

member StripCharsEnd(?characters: string) : Expr

Parameters

Name	Type	Description
characters	string (optional)	-

---

StripCharsStart

Remove leading characters (Left Trim). If 'matches' is omitted, whitespace is removed.

member StripCharsStart(?characters: string) : Expr

Parameters

Name	Type	Description
characters	string (optional)	-

---

StripPrefix

Remove a specific prefix string.

member StripPrefix(prefix: string) : Expr

Parameters

Name	Type	Description
prefix	string	-

---

StripSuffix

Remove a specific suffix string.

member StripSuffix(suffix: string) : Expr

Parameters

Name	Type	Description
suffix	string	-

---

Strptime

Convert a String column into a Date/Datetime/Time column.

member Strptime(
    dtype: DataType,
    ?format: string,
    ?strict: bool,
    ?exact: bool,
    ?cache: bool,
    ?ambiguous: Expr
) : Expr

Parameters

Name	Type	Description
dtype	DataType	The data type to convert into. Can be either Date, Datetime, or Time.
format	string (optional)	The parsing format (e.g., "%Y-%m-%d","yyyy-MM-dd"). Null for auto-inference.
strict	bool (optional)	Raise an error if any conversion fails.
exact	bool (optional)	Require an exact format match. If False, allow the format to match anywhere in the target string. Conversion to the Time type is always exact.
cache	bool (optional)	Use a cache of unique, converted dates to apply the datetime conversion.
ambiguous	Expr (optional)	Determine how to deal with ambiguous datetimes: 'raise' (default): raise 'earliest': use the earliest datetime 'latest': use the latest datetime 'null': set to null

---

Tail

Return the last n characters of each string in a String Series.

member Tail(n: int) : Expr

Parameters

Name	Type	Description
n	int	Length of the slice (integer or expression) When the n input is negative, head returns characters up to the n`th from the start of the string. For example, if n = -3, then all characters except the first three are returned.

Returns: Expression of data type String.

---

ToDate

Parse string to Date using a format string (e.g., "%Y-%m-%d", 'yyyy-MM-dd').

member ToDate(
    ?format: string,
    ?strict: bool,
    ?exact: bool,
    ?cache: bool
) : Expr

Parameters

Name	Type	Description
format	string (optional)	The parsing format (e.g., "%Y-%m-%d", 'yyyy-MM-dd'). Null for auto-inference.
strict	bool (optional)	If true, raises an error on parsing failure. If false, returns nulls.
exact	bool (optional)	If true, requires an exact match. If false, allows matching substrings.
cache	bool (optional)	Use a cache of unique converted dates to speed up parsing.

---

ToDatetime

Convert string to Datetime. If format is null, Polars will attempt to infer it.

member ToDatetime(
    ?format: string,
    ?timeUnit: TimeUnit,
    ?timeZone: string,
    ?strict: bool,
    ?exact: bool,
    ?cache: bool,
    ?ambiguous: Expr
) : Expr

Parameters

Name	Type	Description
format	string (optional)	The parsing format (e.g., "%Y-%m-%d","yyyy-MM-dd"). Null for auto-inference.
timeUnit	TimeUnit (optional)	Target time unit. Null to use default (usually Microseconds).
timeZone	string (optional)	Target time zone (e.g., "UTC", "Asia/Shanghai").
strict	bool (optional)	If true, raises an error on parsing failure. If false, returns nulls.
exact	bool (optional)	If true, requires an exact match. If false, allows matching substrings.
cache	bool (optional)	Use a cache of unique converted dates to speed up parsing.
ambiguous	Expr (optional)	Determine how to deal with ambiguous datetimes: 'raise' (default): raise 'earliest': use the earliest datetime 'latest': use the latest datetime 'null': set to null

---

ToDecimal

Convert a String column into a Decimal column.

member ToDecimal(scale: int) : Expr

Parameters

Name	Type	Description
scale	int	Number of digits after the comma to use for the decimals.

---

ToInteger

Convert a String column into an Integer column with the specified radix (base).

member ToInteger(?radix: int, ?dtype: DataType, ?strict: bool) : Expr

Parameters

Name	Type	Description
radix	int (optional)	Positive integer or expression which is the base of the string we are parsing. Default is 10.
dtype	DataType (optional)	Integer data type to cast the result to. Default is Int64.
strict	bool (optional)	If true, raises ComputeError on failure. If false, silently converts to Null.

Returns: Expression of destinated integer data type.

---

ToLowercase

Convert to lowercase.

member ToLowercase : unit -> Expr

---

ToTime

Convert a String column into a Time column.

member ToTime(
    ?format: string,
    ?strict: bool,
    ?exact: bool,
    ?cache: bool
) : Expr

Parameters

Name	Type	Description
format	string (optional)	The parsing format (e.g., "%H:%M:%S","HH-mm-ss"). Null for auto-inference.
strict	bool (optional)	Raise an error if any conversion fails.
exact	bool (optional)	If true, requires an exact match. If false, allows matching substrings.
cache	bool (optional)	Use a cache of unique, converted times to apply the conversion.

---

ToTitlecase

Modify strings to their titlecase equivalent.

This is a form of case transform where the first letter of each word is capitalized, with the rest of the word in lowercase. Non-alphanumeric characters define the word boundaries.

member ToTitlecase : unit -> Expr

---

ToUppercase

Convert to uppercase.

member ToUppercase : unit -> Expr

---

Zfill

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.

This method is intended for padding numeric strings. If your data contains non-ASCII characters, use pad_start() instead.

member Zfill(length: int) : Expr

Parameters

Name	Type	Description
length	int	Pad the string until it reaches this length. Strings with length equal to or greater than this value are returned as-is.

---