BistrBuilder

class bistring.BistrBuilder(original)

Bases: object

Bidirectionally transformed string builer.

A BistrBuilder builds a transformed version of a source string iteratively. Each builder has an immutable original string, a current string, and the in-progress modified string, with alignments between each. For example:

original: |The| |quick,| |brown| |🦊| |jumps| |over| |the| |lazy| |🐶|
          |   | |      | |     | |  \ \     \ \    \ \   \ \    \ \   \
current:  |The| |quick,| |brown| |fox| |jumps| |over| |the| |lazy| |dog|
          |   | |      / /     /
modified: |the| |quick| |brown| ...

The modified string is built in pieces by calling replace() to change n characters of the current string into new ones in the modified string. Convenience methods like skip(), insert(), and discard() are implemented on top of this basic primitive.

>>> b = BistrBuilder('The quick, brown 🦊 jumps over the lazy 🐶')
>>> b.skip(17)
>>> b.peek(1)
'🦊'
>>> b.replace(1, 'fox')
>>> b.skip(21)
>>> b.peek(1)
'🐶'
>>> b.replace(1, 'dog')
>>> b.is_complete
True
>>> b.rewind()
>>> b.peek(3)
'The'
>>> b.replace(3, 'the')
>>> b.skip(1)
>>> b.peek(6)
'quick,'
>>> b.replace(6, 'quick')
>>> b.skip_rest()
>>> s = b.build()
>>> s.modified
'the quick brown fox jumps over the lazy dog'
Parameters

original (Union[str, bistr]) – The string to start from.

property original: str

The original string being modified.

Return type

str

property current: str

The current string before modifications.

Return type

str

property modified: str

The modified string as built so far.

Return type

str

property alignment: bistring._alignment.Alignment

The alignment built so far from self.current to self.modified.

Return type

Alignment

property position: int

The position of the builder in self.current.

Return type

int

property remaining: int

The number of characters of the current string left to process.

Return type

int

property is_complete: bool

Whether we’ve completely processed the string. In other words, whether the modified string aligns with the end of the current string.

Return type

bool

peek(n)

Peek at the next n characters of the original string.

Return type

str

skip(n)

Skip the next n characters, copying them unchanged.

Return type

None

skip_rest()

Skip the rest of the string, copying it unchanged.

Return type

None

insert(string)

Insert a substring into the string.

Return type

None

discard(n)

Discard a portion of the original string.

Return type

None

discard_rest()

Discard the rest of the original string.

Return type

None

replace(n, repl)

Replace the next n characters with a new string.

Return type

None

append(bs)

Append a bistr. The original value of the bistr must match the current string being processed.

Return type

None

skip_match(regex)

Skip a substring matching a regex, copying it unchanged.

Parameters

regex (Union[str, Pattern[str]]) – The (possibly compiled) regular expression to match.

Return type

bool

Returns

Whether a match was found.

discard_match(regex)

Discard a substring that matches a regex.

Parameters

regex (Union[str, Pattern[str]]) – The (possibly compiled) regular expression to match.

Return type

bool

Returns

Whether a match was found.

replace_match(regex, repl)

Replace a substring that matches a regex.

Parameters
Return type

bool

Returns

Whether a match was found.

replace_next(regex, repl)

Replace the next occurence of a regex.

Parameters
Return type

bool

Returns

Whether a match was found.

replace_all(regex, repl)

Replace all occurences of a regex.

Parameters
Return type

None

build()

Build the bistr.

Return type

bistr

Returns

A bistr from the original string to the new modified string.

Raises

ValueError if the modified string is not completely built yet.

rewind()

Reset this builder to apply another transformation.

Raises

ValueError if the modified string is not completely built yet.

Return type

None