Struct Text

pub struct Text {
    pub br_indexes: EolIndexes,
    pub old_br_indexes: EolIndexes,
    pub text: String,
    /* private fields */
}

An efficient way to store and process changes made to a text.

Any method that performs a change on the text also accepts an Updateable which will be provided with a view of some of the computed values. In case you do not want to provide an Updateable you may simply provide a &mut () as the argument.

Fields

br_indexes: EolIndexes

The EOL byte positions of the text.

In case of multibyte EOL patterns (such as \r\n) the values point to the last byte.

If modifying a Text, the changes should also be reflected in EolIndexes. This is already done when interacting with the implemented methods, but if the string is manually modified you should reflect to changes here as well.

old_br_indexes: EolIndexes

The EOL positions of the text, from the previous update.

The same rules and restrictions that apply to the current EolIndexes also apply here. With one exception, that is until the first update is provided the value will not store any information. Calling any of the values methods before an update is processed will very likely result in a panic.

This is provided to the Updateable passed to Self::update to avoid recalculating positions.

text: String

The text that is stored.

When an insertion is performed on line count, a line break is inserted. This means the string stored is not always an exact one to one copy of its source. If you are to compare the text with its source you may want to normalize their EOL bytes before doing so.

When manually modifying the string outside of the provided methods, it is up to the user to assure that Text.br_indexes is alligned with what is present in the string. Not doing so will result in a panic or incorrect results. If you are only modifying the value through the provided methods, and only reading from the value, this is not an issue as the implemented methods guarantee that all of the fields are in sync with each other. Before manually modifying the value, the current br_indexes field should be cloned to old_br_indexes and the changes made on the text should also be reflected to br_indexes.

This is required to correctly update an Updateable if one is provided.

Implementations

impl Text

pub fn new(text: String) -> Self

Creates a new Text that expects UTF-8 encoded positions.

You should generally prefer this method instead of Text::new_utf16 or Text::new_utf32 and then transform the positions manually when using multiple encoding positions.

pub fn new_utf16(text: String) -> Self

Creates a new Text that expects UTF-16 encoded positions.

pub fn new_utf32(text: String) -> Self

Creates a new Text that expects UTF-32 encoded positions.

pub fn update<'a, U: Updateable, C: Into<Change<'a>>>( &mut self, change: C, updateable: &mut U, ) -> Result<()>

Perform an a change on the text.

The positions in the provided Change will be transformed to the expected encoding depending on how the Text was constructed.

pub fn delete<U: Updateable>( &mut self, start: GridIndex, end: GridIndex, updateable: &mut U, ) -> Result<()>

Delete between the start and end GridIndex with the end being exclusive.

Updates the current EolIndexes to align to the string. The GridIndex columns value is clamped to the end of the string excluding the EOL bytes.

Panics

If the EolIndexes of Text has a length of zero.

pub fn insert<U: Updateable>( &mut self, s: &str, at: GridIndex, updateable: &mut U, ) -> Result<()>

Insert the provided string at the provided GridIndex.

Updates the current EolIndexes to align to the string. The GridIndex columns value is clamped to the end of the string excluding the EOL bytes.

Panics

If the EolIndexes of Text has a length of zero.

pub fn replace<U: Updateable>( &mut self, s: &str, start: GridIndex, end: GridIndex, updateable: &mut U, ) -> Result<()>

Replace start..end with the provided string.

Updates the current EolIndexes to align to the string. The GridIndex columns value is clamped to the end of the string excluding the EOL bytes.

This is more optimized than calling String::replace_range and then updating the EolIndexes manually.

Panics

If the EolIndexes of Text has a length of zero.

pub fn replace_full<U: Updateable>( &mut self, s: Cow<'_, str>, updateable: &mut U, ) -> Result<()>

pub fn get_row(&self, nth: usize) -> Option<&str>

Get the nth row.

The returned slice is trimmed for any EOL bytes. Returns None if the nth row does not exist.

pub fn lines(&self) -> TextLines<'_>

Returns an Iterator over the lines present in the Text.

The Iterator implementation of TextLines is optimized so it is usually a good idea to use the iterator to get string slices.

Panics

If any of the fields of Text is out of sync, the iterator may panic or return incorrect results.

Trait Implementations

impl Clone for Text

fn clone(&self) -> Text

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Text

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Text

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for Text

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.