tabsdata.tableframe.expr.string
TdExprStringNameSpace | |
TdExprStringNameSpace.contains | Evaluate if the string contains a pattern. |
TdExprStringNameSpace.contains_any | Evaluate if the string contains any of the given patterns. |
TdExprStringNameSpace.count_matches | Counts the ocurrrences of the given pattern in the string. |
TdExprStringNameSpace.ends_with | Evaluate if the string ends with. |
TdExprStringNameSpace.extract | Extract a pattern from the string. |
TdExprStringNameSpace.find | Find the position of the first occurrence of the given pattern. |
TdExprStringNameSpace.head | Extract the start of the string up to the given length. |
TdExprStringNameSpace.len_bytes | Return number of bytes (not chars) of a string. |
TdExprStringNameSpace.len_chars | Return number of chars (not bytes) of a string. |
TdExprStringNameSpace.pad_end | Pad string values at the end to the given length using the given fill character. |
TdExprStringNameSpace.pad_start | Pad string values at the front to the given length using the given fill character. |
TdExprStringNameSpace.replace | Replace the first occurence of a pattern with the given string. |
TdExprStringNameSpace.replace_all | Replace the all occurences of a pattern with the given string. |
TdExprStringNameSpace.replace_many | Replace the all occurences of any the given patterns with the given string. |
TdExprStringNameSpace.reverse | Reverse the string. |
TdExprStringNameSpace.slice | Extract the substring at the given offset for the given length. |
TdExprStringNameSpace.starts_with | Evaluate if the string start with. |
TdExprStringNameSpace.strip_chars | Trim string values. |
TdExprStringNameSpace.strip_chars_end | Trim string values from the end of the string. |
TdExprStringNameSpace.strip_chars_start | Trim string values from the start of the string. |
TdExprStringNameSpace.strip_prefix | Trim string values removing the given prefix |
TdExprStringNameSpace.strip_suffix | Trim string values removing the given suffix |
TdExprStringNameSpace.tail | Extract the end of the string up to the given length. |
TdExprStringNameSpace.to_date | Convert the string to a date. |
TdExprStringNameSpace.to_datetime | Convert the string to a datetime. |
TdExprStringNameSpace.to_integer | Covert a string to integer. |
TdExprStringNameSpace.to_lowercase | Return the lowercase of a string. |
TdExprStringNameSpace.to_time | Convert the string to a time. |
TdExprStringNameSpace.to_titlecase | Uppercase the first character and lowercase all the others ones of a string. |
TdExprStringNameSpace.to_uppercase | Return the uppercase of a string. |
TdExprStringNameSpace.zfill | Pad numeric string values at the start to the given length using zeros. |
to_tdexpr |
TdExprStringNameSpace
class TdExprStringNameSpace(expr: ExprStringNameSpace)
containsdef contains(
pattern: str | TdExpr,
literal: bool = False,
strict: bool = True,
) -> TdExpr
Evaluate if the string contains a pattern.
Parameters:
patternThe pattern to search for.
literalTake the pattern as a literal string (not a regex).
strictif the given pattern is not valid regex, raise an error.
Example:
>>> import tabsdata as td
>>>
>>> tf: td.TableFrame ...
>>>
>>> tf.select(td.col("a"), td.col("a").str.contains("ab").alias("contains"))
>>>
┌──────┬──────────┐
│ a ┆ contains │
│ --- ┆ --- │
│ str ┆ bool │
╞══════╪══════════╡
│ a ┆ false │
│ ab ┆ true │
│ b ┆ false │
│ xaby ┆ true │
│ null ┆ null │
└──────┴──────────┘
contains_anydef contains_any(patterns: IntoTdExpr, ascii_case_insensitive: bool = False) -> TdExpr
Evaluate if the string contains any of the given patterns.
Parameters:
patternsThe patterns to search for.
ascii_case_insensitiveIf true, the search is case-insensitive.
Example:
>>> import tabsdata as td
>>>
>>> tf: td.TableFrame ...
>>>
>>> tf.select(td.col("a"), td.col("a")
.str.contains_any(["a", "b"]).alias("contains_any"))
>>>
┌──────┬──────────────┐
│ a ┆ contains_any │
│ --- ┆ --- │
│ str ┆ bool │
╞══════╪══════════════╡
│ abc ┆ true │
│ axy ┆ true │
│ xyb ┆ true │
│ xyz ┆ false │
│ null ┆ null │
└──────┴──────────────┘
count_matchesdef count_matches(pattern: str | TdExpr, literal: bool = False) -> TdExpr
Counts the ocurrrences of the given pattern in the string.
Parameters:
patternThe pattern to extract.
literalTake the pattern as a literal string (not a regex).
Example:
>>> import tabsdata as td
>>>
>>> tf: td.TableFrame ...
>>>
>>> tf.select(td.col("a"), td.col("a")
.str.count_matches("b.").alias("count_matches"))
>>>
┌───────────┬───────────────┐
│ a ┆ count_matches │
│ --- ┆ --- │
│ str ┆ u32 │
╞═══════════╪═══════════════╡
│ a bAb c d ┆ 2 │
│ bCbb c d ┆ 2 │
│ bb ┆ 1 │
│ b ┆ 0 │
│ a ┆ 0 │
│ null ┆ null │
└───────────┴───────────────┘
ends_withdef ends_with(suffix: str | TdExpr) -> TdExpr
Evaluate if the string ends with.
Parameters:
suffixThe suffix to search for.
Example:
>>> import tabsdata as td
>>>
>>> tf: td.TableFrame ...
>>>
>>> tf.select(td.col("a"), td.col("a").str.ends_with("b").alias("ends_with"))
>>>
┌──────┬───────────┐
│ a ┆ ends_with │
│ --- ┆ --- │
│ str ┆ bool │
╞══════╪═══════════╡
│ a ┆ false │
│ ab ┆ true │
│ b ┆ true │
│ xaby ┆ false │
│ null ┆ null │
└──────┴───────────┘
extractdef extract(pattern: IntoTdExprColumn, group_index: int = 1) -> TdExpr
Extract a pattern from the string.
Parameters:
patternThe pattern to extract.
group_indexThe group index to extract.
Example:
>>> import tabsdata as td
>>>
>>> tf: td.TableFrame ...
>>>
>>> tf.select(td.col("a"), td.col("a").str.extract("(b.b)", 1).alias("extract"))
>>>
┌───────────┬─────────┐
│ a ┆ extract │
│ --- ┆ --- │
│ str ┆ str │
╞═══════════╪═════════╡
│ a bAb c d ┆ bAb │
│ bCbb c d ┆ bCb │
│ bb ┆ null │
│ null ┆ null │
└───────────┴─────────┘
finddef find(pattern: str | TdExpr, literal: bool = False, strict: bool = True) -> TdExpr
Find the position of the first occurrence of the given pattern.
Parameters:
patternThe pattern to search for.
literalTake the pattern as a literal string (not a regex).
strictif the given pattern is not valid regex, raise an error.
Example:
>>> import tabsdata as td
>>>
>>> tf: td.TableFrame ...
>>>
>>> tf.select(td.col("a"), td.col("a").str.find("b").alias("find"))
>>>
┌──────┬──────┐
│ a ┆ find │
│ --- ┆ --- │
│ str ┆ u32 │
╞══════╪══════╡
│ a ┆ null │
│ ab ┆ 1 │
│ b ┆ 0 │
│ xaby ┆ 2 │
│ null ┆ null │
└──────┴──────┘
headdef head(n: int | IntoTdExprColumn) -> TdExpr
Extract the start of the string up to the given length.
Parameters:
nThe length of the head.
Example:
>>> import tabsdata as td
>>>
>>> tf: td.TableFrame ...
>>>
>>> tf.select(td.col("a"), td.col("a").str.head(2).alias("head"))
>>>
┌──────┬──────┐
│ a ┆ head │
│ --- ┆ --- │
│ str ┆ str │
╞══════╪══════╡
│ abc ┆ ab │
│ a ┆ a │
│ null ┆ null │
└──────┴──────┘
len_bytesdef len_bytes() -> TdExpr
Return number of bytes (not chars) of a string.
Example:
>>> import tabsdata as td
>>>
>>> tf: td.TableFrame ...
>>>
>>> tf.select(td.col("a"), td.col("a").str.len_bytes().alias("len_bytes"))
>>>
┌──────┬────────────┐
│ a ┆ to_decimal │
│ --- ┆ --- │
│ str ┆ u32 │
╞══════╪════════════╡
│ ab ┆ 2 │
│ 再 ┆ 3 │
│ null ┆ null │
└──────┴────────────┘
len_charsdef len_chars() -> TdExpr
Return number of chars (not bytes) of a string.
Example:
>>> import tabsdata as td
>>>
>>> tf: td.TableFrame ...
>>>
>>> tf.select(td.col("a"), td.col("a").str.len_chars().alias("len_chars"))
>>>
┌──────┬────────────┐
│ a ┆ to_decimal │
│ --- ┆ --- │
│ str ┆ u32 │
╞══════╪════════════╡
│ ab ┆ 2 │
│ 再 ┆ 3 │
│ null ┆ null │
└──────┴────────────┘
pad_enddef pad_end(length: int, fill_char: str = ' ') -> TdExpr
Pad string values at the end to the given length using the given fill character.
Parameters:
lengthThe length to end pad the string to.
fill_charThe character to use for padding.
Example:
>>> import tabsdata as td
>>>
>>> tf: td.TableFrame ...
>>>
>>> tf.select(td.col("a"), td.col("a").str.pad_end(6, "-").alias("pad_end"))
>>>
┌────────┬─────────┐
│ a ┆ pad_end │
│ --- ┆ --- │
│ str ┆ str │
╞════════╪═════════╡
│ abc ┆ abc--- │
│ def ┆ def │
│ null ┆ null │
└────────┴─────────┘
pad_startdef pad_start(length: int, fill_char: str = ' ') -> TdExpr
Pad string values at the front to the given length using the given fill character.
Parameters:
lengthThe length to front pad the string to.
fill_charThe character to use for padding.
Example:
>>> import tabsdata as td
>>>
>>> tf: td.TableFrame ...
>>>
>>> tf.select(td.col("a"), td.col("a").str.pad_start(6, "-").alias("pad_start"))
>>>
┌────────┬───────────┐
│ a ┆ pad_start │
│ --- ┆ --- │
│ str ┆ str │
╞════════╪═══════════╡
│ abc ┆ ---abc │
│ def ┆ def │
│ null ┆ null │
└────────┴───────────┘
replacedef replace(
pattern: str | TdExpr,
value: str | TdExpr,
literal: bool = False,
n: int = 1,
) -> TdExpr
Replace the first occurence of a pattern with the given string.
Parameters:
patternThe pattern to replace.
valueThe value to replace the pattern with.
literalTake the pattern as a literal string (not a regex).
nNumber of matches to replace.
Example:
>>> import tabsdata as td
>>>
>>> tf: td.TableFrame ...
>>>
>>> tf.select(td.col("a"), td.col("a").str.replace("b", "X").alias("replace"))
>>>
┌───────────┬───────────┐
│ a ┆ replace │
│ --- ┆ --- │
│ str ┆ str │
╞═══════════╪═══════════╡
│ a bAb c d ┆ a XAb c d │
│ bCbb c d ┆ XCbb c d │
│ bb ┆ Xb │
│ b ┆ X │
│ a ┆ a │
│ null ┆ null │
└───────────┴───────────┘
replace_alldef replace_all(
pattern: str | TdExpr,
value: str | TdExpr,
literal: bool = False,
) -> TdExpr
Replace the all occurences of a pattern with the given string.
Parameters:
patternThe pattern to replace.
valueThe value to replace the pattern with.
literalTake the pattern as a literal string (not a regex).
Example:
>>> import tabsdata as td
>>>
>>> tf: td.TableFrame ...
>>>
>>> tf.select(td.col("a"), td.col("a").str.replace("b", "X").alias("replace"))
>>>
┌───────────┬─────────────┐
│ a ┆ replace_all │
│ --- ┆ --- │
│ str ┆ str │
╞═══════════╪═════════════╡
│ a bAb c d ┆ a XAX c d │
│ bCbb c d ┆ XCXX c d │
│ bb ┆ XX │
│ b ┆ X │
│ a ┆ a │
│ null ┆ null │
└───────────┴─────────────┘
replace_manydef replace_many(
patterns: IntoTdExpr | Mapping[str, str],
replace_with: IntoTdExpr | NoDefault = <no_default>,
ascii_case_insensitive: bool = False,
) -> TdExpr
Replace the all occurences of any the given patterns with the given string.
Parameters:
patternsThe patterns to replace.
replace_withThe value to replace the pattern with.
ascii_case_insensitiveIf true, the search is case-insensitive.
Example:
>>> import tabsdata as td
>>>
>>> tf: td.TableFrame ...
>>>
>>> tf.select(td.col("a"), td.col("a")
.str.replace_many(["a", "b"], "X").alias("replace_many"))
>>>
┌──────┬──────────────┐
│ a ┆ replace_many │
│ --- ┆ --- │
│ str ┆ str │
╞══════╪══════════════╡
│ abc ┆ XXc │
│ axy ┆ Xxy │
│ xyb ┆ xyX │
│ xyz ┆ xyz │
│ null ┆ null │
└──────┴──────────────┘
reversedef reverse() -> TdExpr
Reverse the string.
Example:
>>> import tabsdata as td
>>>
>>> tf: td.TableFrame ...
>>>
>>> tf.select(td.col("a"), td.col("a").str.reverse().alias("reverse"))
>>>
┌──────┬─────────┐
│ a ┆ reverse │
│ --- ┆ --- │
│ str ┆ str │
╞══════╪═════════╡
│ abc ┆ cba │
│ a ┆ a │
│ null ┆ null │
└──────┴─────────┘
slicedef slice(
offset: int | IntoTdExprColumn,
length: int | IntoTdExprColumn | None = None,
) -> TdExpr
Extract the substring at the given offset for the given length.
Parameters:
offsetThe offset to start the slice.
lengthThe length of the slice. If None, slice until the end of the string.
Example:
>>> import tabsdata as td
>>>
>>> tf: td.TableFrame ...
>>>
>>> tf.select(td.col("a"), td.col("a").str.slice(1,1).alias("slice"))
>>>
┌──────┬───────┐
│ a ┆ slice │
│ --- ┆ --- │
│ str ┆ str │
╞══════╪═══════╡
│ abc ┆ b │
│ a ┆ │
│ null ┆ null │
└──────┴───────┘
starts_withdef starts_with(prefix: str | TdExpr) -> TdExpr
Evaluate if the string start with.
Parameters:
prefixThe suffix to search for.
Example:
>>> import tabsdata as td
>>>
>>> tf: td.TableFrame ...
>>>
>>> tf.select(td.col("a"), td.col("a")
.str.starts_with("a").alias("starts_with"))
>>>
┌──────┬────────────┐
│ a ┆ start_with │
│ --- ┆ --- │
│ str ┆ bool │
╞══════╪════════════╡
│ a ┆ true │
│ ab ┆ true │
│ b ┆ false │
│ xaby ┆ false │
│ null ┆ null │
└──────┴────────────┘
strip_charsdef strip_chars(characters: IntoTdExpr = None) -> TdExpr
Trim string values.
Parameters:
charactersCharacters to trim from start and end of the string. All characteres in the given string are removed, regardless the order. Default is whitespace.
Example:
>>> import tabsdata as td
>>>
>>> tf: td.TableFrame ...
>>>
>>> tf.select(td.col("a"), td.col("a")
.str.strip_chars("a ").alias("strip_chars"))
>>>
┌─────────────────────────────────┬─────────────┐
│ a ┆ strip_chars │
│ --- ┆ --- │
│ str ┆ str │
╞═════════════════════════════════╪═════════════╡
│ acba cda … ┆ cba cd │
│ xy z ┆ xy z │
│ null ┆ null │
└─────────────────────────────────┴─────────────┘
strip_chars_enddef strip_chars_end(characters: IntoTdExpr = None) -> TdExpr
Trim string values from the end of the string.
Parameters:
charactersCharacters to trim from start of the string. All ending characteres in the given string are removed, regardless the order. Default is whitespace.
Example:
>>> import tabsdata as td
>>>
>>> tf: td.TableFrame ...
>>>
>>> tf.select(td.col("a"), td.col("a")
.str.strip_chars_end("dc ").alias("strip_chars_end"))
>>>
┌───────────────────────────────┬─────────────────┐
│ a ┆ strip_chars_end │
│ --- ┆ --- │
│ str ┆ str │
╞═══════════════════════════════╪═════════════════╡
│ cba cd ┆ cba │
│ xy z ┆ xy z │
│ null ┆ null │
└───────────────────────────────┴─────────────────┘
strip_chars_startdef strip_chars_start(characters: IntoTdExpr = None) -> TdExpr
Trim string values from the start of the string.
Parameters:
charactersCharacters to trim from start of the string. All starting characteres in the given string are removed, regardless the order. Default is whitespace.
Example:
>>> import tabsdata as td
>>>
>>> tf: td.TableFrame ...
>>>
>>> tf.select(td.col("a"), td.col("a")
.str.strip_chars_start("abc").alias("strip_chars_start"))
>>>
┌───────────────────────────────┬────────────────────────────┐
│ a ┆ strip_chars_start │
│ --- ┆ --- │
│ str ┆ str │
╞═══════════════════════════════╪════════════════════════════╡
│ cba cd ┆ cd │
│ xy z ┆ xy z │
│ null ┆ null │
└───────────────────────────────┴────────────────────────────┘
strip_prefixdef strip_prefix(prefix: IntoTdExpr) -> TdExpr
Trim string values removing the given prefix
Parameters:
prefixPrefix to remove from the string.
Example:
>>> import tabsdata as td
>>>
>>> tf: td.TableFrame ...
>>>
>>> tf.select(td.col("a"), td.col("a")
.str.strip_prefix("cb").alias("strip_prefix"))
>>>
┌───────────────────────────────┬─────────────────┐
│ a ┆ strip_prefix │
│ --- ┆ --- │
│ str ┆ str │
╞═══════════════════════════════╪═════════════════╡
│ cba cd ┆ a cd │
│ bx ┆ bx │
│ null ┆ null │
└───────────────────────────────┴─────────────────┘
strip_suffixdef strip_suffix(suffix: IntoTdExpr) -> TdExpr
Trim string values removing the given suffix
Parameters:
suffixSuffix to remove from the string.
Example:
>>> import tabsdata as td
>>>
>>> tf: td.TableFrame ...
>>>
>>> tf.select(td.col("a"), td.col("a")
.str.strip_suffix("cd").alias("strip_suffix"))
>>>
┌───────────────────────────────┬─────────────────┐
│ a ┆ strip_suffix │
│ --- ┆ --- │
│ str ┆ str │
╞═══════════════════════════════╪═════════════════╡
│ cba cd ┆ cba │
│ bx ┆ bx │
│ null ┆ null │
└───────────────────────────────┴─────────────────┘
taildef tail(n: int | IntoTdExprColumn) -> TdExpr
Extract the end of the string up to the given length.
Parameters:
nThe length of the tail.
Example:
>>> import tabsdata as td
>>>
>>> tf: td.TableFrame ...
>>>
>>> tf.select(td.col("a"), td.col("a").str.tail(2).alias("tail"))
>>>
┌──────┬──────┐
│ a ┆ tail │
│ --- ┆ --- │
│ str ┆ str │
╞══════╪══════╡
│ abc ┆ bc │
│ a ┆ a │
│ null ┆ null │
└──────┴──────┘
to_datedef to_date(fmt: str | None = None, strict: bool = True) -> TdExpr
Convert the string to a date.
Parameters:
fmtThe date format string (default %Y-%m-%d) [formats] (https://docs.rs/chrono/0.4.19/chrono/format/strftime/index.html).
strictWhether to parse the date strictly.
Example:
>>> import tabsdata as td
>>>
>>> tf: td.TableFrame ...
>>>
>>> tf.select(td.col("a"), td.col("a").str.to_date().alias("to_date"))
>>>
┌────────────┬────────────┐
│ a ┆ to_date │
│ --- ┆ --- │
│ str ┆ date │
╞════════════╪════════════╡
│ 2024-12-13 ┆ 2024-12-13 │
│ 2024-12-15 ┆ 2024-12-15 │
│ null ┆ null │
└────────────┴────────────┘
to_datetimedef to_datetime(
fmt: str | None = None,
time_unit: TimeUnit | None = None,
time_zone: str | None = None,
strict: bool = True,
ambiguous: Ambiguous | TdExpr = 'raise',
) -> TdExpr
Convert the string to a datetime.
to_integerdef to_integer(base: int | IntoTdExprColumn = 10, strict: bool = True) -> TdExpr
Covert a string to integer.
Parameters:
baseThe base of the integer.
strictIf true, raise an error if the string is not a valid integer.
Example:
>>> import tabsdata as td
>>>
>>> tf: td.TableFrame ...
>>>
>>> tf.select(td.col("a"), td.col("a")
.str.to_integer(strict=False).alias("to_integer"))
>>>
┌──────┬────────────┐
│ a ┆ to_integer │
│ --- ┆ --- │
│ str ┆ i64 │
╞══════╪════════════╡
│ 1 ┆ 1 │
│ 2.2 ┆ null │
│ a ┆ null │
│ null ┆ null │
└──────┴────────────┘
to_lowercasedef to_lowercase() -> TdExpr
Return the lowercase of a string.
Example:
>>> import tabsdata as td
>>>
>>> tf: td.TableFrame ...
>>>
>>> tf.select(td.col("a"), td.col("a").str.to_lowercase().alias("to_lowercase"))
>>>
┌──────┬───────────────┐
│ a ┆ to_lowerrcase │
│ --- ┆ --- │
│ str ┆ u32 │
╞══════╪═══════════════╡
│ aB ┆ ab │
│ null ┆ null │
└──────┴───────────────┘
to_timedef to_time(fmt: str | None = None, strict: bool = True, cache: bool = True) -> TdExpr
Convert the string to a time.
Parameters:
fmtThe time format string (default %H:%M:%S) [formats] (https://docs.rs/chrono/0.4.19/chrono/format/strftime/index.html).
strictWhether to parse the date strictly.
cacheWhether to cache the date.
Example:
>>> import tabsdata as td
>>>
>>> tf: td.TableFrame ...
>>>
>>> tf.select(td.col("a"), td.col("a").str.to_time().alias("to_time"))
>>>
┌─────────────────────┬─────────────────────┐
│ a ┆ to_datetime │
│ --- ┆ --- │
│ str ┆ datetime[μs] │
╞═════════════════════╪═════════════════════╡
│ 2024-12-13 08:45:34 ┆ 2024-12-13 08:45:34 │
│ 2024-12-15 18:33:00 ┆ 2024-12-15 18:33:00 │
│ null ┆ null │
└─────────────────────┴─────────────────────┘
to_titlecasedef to_titlecase() -> TdExpr
Uppercase the first character and lowercase all the others ones of a string.
Example:
>>> import tabsdata as td
>>>
>>> tf: td.TableFrame ...
>>>
>>> tf.select(td.col("a"), td.col("a").str.to_titlecase().alias("titlecase"))
>>>
┌──────┬───────────┐
│ a ┆ titlecase │
│ --- ┆ --- │
│ str ┆ str │
╞══════╪═══════════╡
│ ab ┆ Ab │
│ Ab ┆ Ab │
│ AB ┆ Ab │
│ aB ┆ Ab │
│ null ┆ null │
└──────┴───────────┘
to_uppercasedef to_uppercase() -> TdExpr
Return the uppercase of a string.
Example:
>>> import tabsdata as td
>>>
>>> tf: td.TableFrame ...
>>>
>>> tf.select(td.col("a"), td.col("a").str.to_uppercase().alias("to_uppercase"))
>>>
┌──────┬──────────────┐
│ a ┆ to_uppercase │
│ --- ┆ --- │
│ str ┆ u32 │
╞══════╪══════════════╡
│ aB ┆ AB │
│ null ┆ null │
└──────┴──────────────┘
zfilldef zfill(length: int | IntoTdExprColumn) -> TdExpr
Pad numeric string values at the start to the given length using zeros.
Parameters:
lengthThe length to end pad the string to.
Example:
>>> import tabsdata as td
>>>
>>> tf: td.TableFrame ...
>>>
>>> tf.select(td.col("a"), td.col("a").str.zfill(2).alias("zfill"))
>>>
┌──────┬───────┐
│ a ┆ zfill │
│ --- ┆ --- │
│ str ┆ str │
╞══════╪═══════╡
│ 0 ┆ 00 │
│ 1 ┆ 01 │
│ 1000 ┆ 1000 │
│ null ┆ null │
└──────┴───────┘
to_tdexpr
def to_tdexpr(expr: Expr) -> TdExpr