Splitting and Partitioning | StringZilla for Python

§ Eager Splits Returning `Strings`

split(separator, maxsplit=∞, keepseparator=False, skip_empty=False) — split on a substring separator; unlike str.split, an empty separator leaves the text whole instead of raising.
rsplit(separator, maxsplit=∞, keepseparator=False, skip_empty=False) — same, scanning from the right.
split_byteset(separators, maxsplit=∞, keepseparator=False, skip_empty=False) — split on any single byte from the separators set.
rsplit_byteset(separators, maxsplit=∞, keepseparator=False, skip_empty=False) — same, from the right.
splitlines(keeplinebreaks=False, maxsplit=∞) — split on line breaks.

maxsplit caps the number of separators consumed, so 0 leaves the text whole, while a negative value or the default means unlimited. keepseparator keeps the matched separator attached to the parts. skip_empty drops zero-length parts, so a part keeping its separator is never dropped. Without maxsplit and keepseparator, a one-byte separator, a byteset, and splitlines split the whole text in one native pass straight into the tape.

import stringzilla as sz

assert list(map(str, sz.String("a,b,c").split(","))) == ["a", "b", "c"]
assert list(map(str, sz.String("a,b,c").rsplit(",", maxsplit=1))) == ["a,b", "c"]
assert list(map(str, sz.String("a,b;c").split_byteset(",;"))) == ["a", "b", "c"]
assert list(map(str, sz.String("a\nb\nc").splitlines())) == ["a", "b", "c"]

§ Lazy Split Iterators

Each eager split has a lazy counterpart that yields String views one at a time without building the whole Strings. They take the same arguments.

split_iter(separator, maxsplit=∞, keepseparator=False, skip_empty=False)
rsplit_iter(separator, maxsplit=∞, keepseparator=False, skip_empty=False)
split_byteset_iter(separators, maxsplit=∞, keepseparator=False, skip_empty=False)
rsplit_byteset_iter(separators, maxsplit=∞, keepseparator=False, skip_empty=False)

The reverse iterators yield the last field first.

import stringzilla as sz

for field in sz.String("2024-01-15").split_iter("-"):
    print(field)                                       # 2024, then 01, then 15

assert str(next(iter(sz.String("a/b/c").rsplit_iter("/")))) == "c"
assert sum(1 for _ in sz.String("a,b,c").split_iter(",")) == 3

§ Joining

join(strings) concatenates strings with the String between every two, as str.join does, into a new String. A Strings is read in place, any other iterable of str and bytes-like objects through a snapshot of it, and the result is measured first and written once.

import stringzilla as sz

assert str(sz.String(", ").join(["Ada", "Grace", "Linus"])) == "Ada, Grace, Linus"
assert str(sz.String("\n").join(sz.String("a b c").split())) == "a\nb\nc"

§ Partitioning

partition(separator) — return a 3-tuple (head, separator, tail) split at the first occurrence; if not found returns (self, '', '').
rpartition(separator) — same, at the last occurrence; if not found returns ('', '', self).

import stringzilla as sz

assert tuple(map(str, sz.String("a=b=c").partition("="))) == ("a", "=", "b=c")
assert tuple(map(str, sz.String("a=b=c").rpartition("="))) == ("a=b", "=", "c")

API

Types

FindSplitsText-splitting iterator for efficient string processing.

__init__.pyi:2003 ↗

class FindSplits

Provides lazy evaluation of string splits without materializing all results.

Created by

String.split_iter()
String.rsplit_iter()
String.split_byteset_iter()
String.rsplit_byteset_iter()

Features

Memory-efficient: yields results one at a time
Forward and reverse iteration support
Character set and string separator support

Examples

>>> # split_iter streams parts lazily - prefer it over split() on large inputs:
>>> for field in sz.String('2024-01-15').split_iter('-'):
...     print(field)
2024
01
15

Functions

partitionSplit the string into a 3-tuple around the first occurrence of a separator.

__init__.pyi:490 ↗

def partition(
    text: _StringLike,
    separator: _StringLike,
    *,
    capabilities: Capability | None = None,
) -> tuple[String, String, String]

Returns: tuple: A 3-tuple (head, separator, tail), or (self, '', '') if the separator is not found.

Parameters

`text_StringLike`		The string object.
`separator_StringLike`		The separator to partition by.
`capabilitiesCapability \| None`		Capabilities to run, defaulting to the CPU's enabled ones.

Examples

>>> tuple(map(str, sz.String('a=b=c').partition('=')))
('a', '=', 'b=c')

rpartitionSplit the string into a 3-tuple around the last occurrence of a separator.

__init__.pyi:507 ↗

def rpartition(
    text: _StringLike,
    separator: _StringLike,
    *,
    capabilities: Capability | None = None,
) -> tuple[String, String, String]

Returns: tuple: A 3-tuple (head, separator, tail). If the separator is not found, returns ('', '', self).

Parameters

`text_StringLike`		The string object.
`separator_StringLike`		The separator to partition by.
`capabilitiesCapability \| None`		Capabilities to run, defaulting to the CPU's enabled ones.

Examples

>>> tuple(map(str, sz.String('a=b=c').rpartition('=')))
('a=b', '=', 'c')

splitSplit a string by a separator, like str.split.

__init__.pyi:722 ↗

def split(
    text: _StringLike,
    separator: _StringLike,
    maxsplit: int = -1,
    keepseparator: bool = False,
    skip_empty: bool = False,
    *,
    capabilities: Capability | None = None,
) -> Strings

Returns: Strings: The parts, copied onto a tape of their own.

Parameters

`text_StringLike`		The string object.
`separator_StringLike`		The separator to split by; an empty one leaves the text whole.
`maxsplitint`		Maximum number of splits, defaulting to no limit.
`keepseparatorbool`		Include the separator in results, defaulting to False.
`skip_emptybool`		Skip empty segments, defaulting to False.
`capabilitiesCapability \| None`		Capabilities to run, defaulting to the CPU's enabled ones.

Examples

>>> list(map(str, sz.String('a,b,c').split(',')))
['a', 'b', 'c']

rsplitSplit a string by a separator starting from the end, like str.rsplit.

__init__.pyi:748 ↗

def rsplit(
    text: _StringLike,
    separator: _StringLike,
    maxsplit: int = -1,
    keepseparator: bool = False,
    skip_empty: bool = False,
    *,
    capabilities: Capability | None = None,
) -> Strings

Returns: Strings: The parts, copied onto a tape of their own.

Parameters

`text_StringLike`		The string object.
`separator_StringLike`		The separator to split by; an empty one leaves the text whole.
`maxsplitint`		Maximum number of splits, defaulting to no limit.
`keepseparatorbool`		Include the separator in results, defaulting to False.
`skip_emptybool`		Skip empty segments, defaulting to False.
`capabilitiesCapability \| None`		Capabilities to run, defaulting to the CPU's enabled ones.

Examples

>>> list(map(str, sz.String('a,b,c').rsplit(',')))
['a', 'b', 'c']

split_bytesetSplit a string by a set of character separators.

__init__.pyi:774 ↗

def split_byteset(
    text: _StringLike,
    separators: _StringLike,
    maxsplit: int = -1,
    keepseparator: bool = False,
    skip_empty: bool = False,
    *,
    capabilities: Capability | None = None,
) -> Strings

Returns: Strings: The parts, copied onto a tape of their own.

Parameters

`text_StringLike`		The string object.
`separators_StringLike`		A string containing separator characters.
`maxsplitint`		Maximum number of splits, defaulting to no limit.
`keepseparatorbool`		Include separators in results, defaulting to False.
`skip_emptybool`		Skip empty segments, defaulting to False.
`capabilitiesCapability \| None`		Capabilities to run, defaulting to the CPU's enabled ones.

Examples

>>> list(map(str, sz.String('a,b;c').split_byteset(',;')))
['a', 'b', 'c']

rsplit_bytesetSplit a string by a set of character separators in reverse order.

__init__.pyi:800 ↗

def rsplit_byteset(
    text: _StringLike,
    separators: _StringLike,
    maxsplit: int = -1,
    keepseparator: bool = False,
    skip_empty: bool = False,
    *,
    capabilities: Capability | None = None,
) -> Strings

Returns: Strings: The parts, copied onto a tape of their own.

Parameters

`text_StringLike`		The string object.
`separators_StringLike`		A string containing separator characters.
`maxsplitint`		Maximum number of splits, defaulting to no limit.
`keepseparatorbool`		Include separators in results, defaulting to False.
`skip_emptybool`		Skip empty segments, defaulting to False.
`capabilitiesCapability \| None`		Capabilities to run, defaulting to the CPU's enabled ones.

Examples

>>> list(map(str, sz.String('a,b;c').rsplit_byteset(',;')))
['a', 'b', 'c']

split_iterCreate an iterator for splitting a string by a separator.

__init__.pyi:826 ↗

def split_iter(
    text: _StringLike,
    separator: _StringLike,
    maxsplit: int = -1,
    keepseparator: bool = False,
    skip_empty: bool = False,
    *,
    capabilities: Capability | None = None,
) -> FindSplits

Returns: iterator: An iterator yielding split substrings.

Parameters

`text_StringLike`		The string object.
`separator_StringLike`		The separator to split by; an empty one leaves the text whole.
`maxsplitint`		Maximum number of splits, defaulting to no limit.
`keepseparatorbool`		Include separator in results, defaulting to False.
`skip_emptybool`		Skip empty segments, defaulting to False.
`capabilitiesCapability \| None`		Capabilities to run, defaulting to the CPU's enabled ones.

Examples

>>> # Stream parts lazily instead of materializing a list (that is what split() is for):
>>> sum(1 for _ in sz.String('a,b,c').split_iter(','))
3

rsplit_iterCreate an iterator for splitting a string by a separator in reverse order.

__init__.pyi:853 ↗

def rsplit_iter(
    text: _StringLike,
    separator: _StringLike,
    maxsplit: int = -1,
    keepseparator: bool = False,
    skip_empty: bool = False,
    *,
    capabilities: Capability | None = None,
) -> FindSplits

Returns: iterator: An iterator yielding split substrings in reverse.

Parameters

`text_StringLike`		The string object.
`separator_StringLike`		The separator to split by; an empty one leaves the text whole.
`maxsplitint`		Maximum number of splits, defaulting to no limit.
`keepseparatorbool`		Include separator in results, defaulting to False.
`skip_emptybool`		Skip empty segments, defaulting to False.
`capabilitiesCapability \| None`		Capabilities to run, defaulting to the CPU's enabled ones.

Examples

>>> # Iterates from the end; the first yielded part is the last field:
>>> str(next(iter(sz.String('a/b/c').rsplit_iter('/'))))
'c'

split_byteset_iterCreate an iterator for splitting a string by a set of character separators.

__init__.pyi:880 ↗

def split_byteset_iter(
    text: _StringLike,
    separators: _StringLike,
    maxsplit: int = -1,
    keepseparator: bool = False,
    skip_empty: bool = False,
    *,
    capabilities: Capability | None = None,
) -> FindSplits

Returns: iterator: An iterator yielding split substrings.

Parameters

`text_StringLike`		The string object.
`separators_StringLike`		A string containing separator characters.
`maxsplitint`		Maximum number of splits, defaulting to no limit.
`keepseparatorbool`		Include separators in results, defaulting to False.
`skip_emptybool`		Skip empty segments, defaulting to False.
`capabilitiesCapability \| None`		Capabilities to run, defaulting to the CPU's enabled ones.

Examples

>>> # Splits on ANY byte in the set, streamed lazily:
>>> str(next(iter(sz.String('a,b;c').split_byteset_iter(',;'))))
'a'

rsplit_byteset_iterCreate an iterator for splitting a string by a set of character separators in reverse order.

__init__.pyi:907 ↗

def rsplit_byteset_iter(
    text: _StringLike,
    separators: _StringLike,
    maxsplit: int = -1,
    keepseparator: bool = False,
    skip_empty: bool = False,
    *,
    capabilities: Capability | None = None,
) -> FindSplits

Returns: iterator: An iterator yielding split substrings in reverse.

Parameters

`text_StringLike`		The string object.
`separators_StringLike`		A string containing separator characters.
`maxsplitint`		Maximum number of splits, defaulting to no limit.
`keepseparatorbool`		Include separators in results, defaulting to False.
`skip_emptybool`		Skip empty segments, defaulting to False.
`capabilitiesCapability \| None`		Capabilities to run, defaulting to the CPU's enabled ones.

Examples

>>> # Reverse byteset split; first yielded part is the last field:
>>> str(next(iter(sz.String('a,b;c').rsplit_byteset_iter(',;'))))
'c'

splitlinesSplit a string by line breaks, like str.splitlines.

__init__.pyi:934 ↗

def splitlines(
    text: _StringLike,
    keeplinebreaks: bool = False,
    maxsplit: int = -1,
    *,
    capabilities: Capability | None = None,
) -> Strings

Returns: Strings: The lines, copied onto a tape of their own.

Parameters

`text_StringLike`		The string object.
`keeplinebreaksbool`		Include line breaks in the results, defaulting to False.
`maxsplitint`		Maximum number of splits, defaulting to no limit.
`capabilitiesCapability \| None`		Capabilities to run, defaulting to the CPU's enabled ones.

Examples

>>> list(map(str, sz.String('a\nb\nc').splitlines()))
['a', 'b', 'c']

§ Eager Splits Returning Strings

§ Lazy Split Iterators

§ Joining

§ Partitioning

API

Types

Created by

Features

Examples

Functions

Parameters

Examples

Parameters

Examples

Parameters

Examples

Parameters

Examples

Parameters

Examples

Parameters

Examples

Parameters

Examples

Parameters

Examples

Parameters

Examples

Parameters

Examples

Parameters

Examples

§ Eager Splits Returning `Strings`