Struct Text

pub struct Text(/* private fields */);

The text in a given Area

Implementations

impl Text

pub fn search_fwd<R: RegexPattern>( &mut self, pat: R, range: impl TextRange, ) -> Result<impl Iterator<Item = R::Match> + '_, Box<Error>>

pub fn search_rev<R: RegexPattern>( &mut self, pat: R, range: impl TextRange, ) -> Result<impl Iterator<Item = R::Match> + '_, Box<Error>>

Returns an iterator over the reverse matches of the regex

pub fn matches( &mut self, pat: impl RegexPattern, range: impl TextRange, ) -> Result<bool, Box<Error>>

Returns true if the pattern is found in the given range

This is unanchored by default, if you want an anchored search, use the "^$" characters.

impl Text

pub fn new() -> Self

Returns a new empty Text

pub fn new_with_cursors() -> Self

pub fn builder() -> Builder

Returns a Builder for Text

This builder can be used to iteratively create text, by assuming that the user wants no* Tag overlap, and that they want to construct the Text in Tag/content pairs.

use duat_core::text::{Tag, Text, text};
let mut builder = Text::builder();

pub fn len(&self) -> Point

The Point at the end of the text

pub fn is_empty(&self) -> bool

Whether or not there are any characters in the Text

This ignores the last '\n' in the Text, since it is always there no matter what.

Notes

This does not check for tags, so with a Tag::Ghost, there could actually be a “string” of characters on the Text, it just wouldn’t be considered real “text”.

pub fn char_at(&self, point: Point) -> Option<char>

The char at the Point’s position

pub fn buffers(&self, range: impl TextRange) -> Buffers<'_>

An Iterator over the bytes of the Text

pub fn strs(&self, range: impl TextRange) -> Strs<'_>

An Iterator over the &strs of the Text

Note

The reason why this function returns two strings is that the contents of the text are stored in a GapBuffer, which works with two strings.

If you want to iterate over them, you can do the following:

let text = Text::new();
text.strs((p1, p2)).flat_map(str::chars);

Do note that you should avoid iterators like str::lines, as they will separate the line that is partially owned by each &str:

let broken_up_line = [
    "This is line 1, business as usual.\nThis is line 2, but it",
    "is broken into two separate strings.\nSo 4 lines would be counted, \
     instead of 3",
];

TextRange behavior:

If you give a single usize/Point, it will be interpreted as a range from.

pub fn lines( &mut self, range: impl TextRange, ) -> impl DoubleEndedIterator<Item = (usize, &str)> + '_

Returns an iterator over the lines in a given range

The lines are inclusive, that is, it will iterate over the whole line, not just the parts within the range.

pub fn bytes(&self) -> &Bytes

The inner bytes of the Text

pub fn bytes_mut(&mut self) -> &mut Bytes

The inner bytes of the Text, mutably

Do note that this mutability isn’t actually for modifying the Bytes themselves, but instead it is used by some methods to read said bytes, like make_contiguous or lines

pub fn indent(&self, p: Point, area: &impl Area, cfg: PrintCfg) -> usize

Gets the indentation level on the current line

pub fn add_reader(&mut self, reader_cfg: impl ReaderCfg) -> Result<(), Text>

Adds a Reader to this Text

A Reader will be informed of every change done to this Text, and can add or remove Tags accordingly. Examples of Readers are the [tree-sitter] parser, and regex parsers. Those can be used for, among other things, syntax hightlighting.

pub fn get_reader<R: Reader>(&mut self) -> Option<R::PublicReader<'_>>

pub fn point_at(&self, b: usize) -> Point

The Point corresponding to the byte position, 0 indexed

If the byte position would fall in between two characters (because the first one comprises more than one byte), the first character is chosen as the Point where the byte is located.

Panics

Will panic if b is greater than the length of the text

pub fn point_at_char(&self, c: usize) -> Point

The Point associated with a char position, 0 indexed

Panics

Will panic if c is greater than the number of chars in the text.

pub fn point_at_line(&self, l: usize) -> Point

The Point where the lth line starts, 0 indexed

If l == number_of_lines, returns the last point of the text.

Panics

Will panic if l is greater than the number of lines on the text

pub fn points_of_line(&self, l: usize) -> [Point; 2]

The start and end Points for a given l line

If l == number_of_lines, these points will be the same.

Panics

Will panic if the number l is greater than the number of lines on the text

pub fn len_points(&self) -> (Point, Option<Point>)

The points at the end of the text

This will essentially return the last point of the text, alongside the last possible Point of any Tag::Ghost at the end of the text.

pub fn last_point(&self) -> Option<Point>

The last Point associated with a char

This will give the Point of the last char of the text. The difference between this method and len is that it will return a Point one position earlier than it. If the text is completely empty, it will return None.

pub fn ghost_max_points_at(&self, at: usize) -> (Point, Option<Point>)

The maximum points in the atth byte

This point is essentially the point at that byte, plus the last possible Point of any Tag::Ghosts in that position.

pub fn points_after(&self, tp: impl TwoPoints) -> Option<(Point, Option<Point>)>

Points visually after the TwoPoints

If the TwoPoints in question is concealed, treats the next visible character as the first character, and returns the points of the next visible character.

This method is useful if you want to iterator reversibly right after a certain point, thus including the character of said point.

pub fn visual_line_start(&self, p: impl TwoPoints) -> (Point, Option<Point>)

The visual start of the line

This point is defined not by where the line actually begins, but by where the last ‘\n’ was located. For example, if Tags create ghost text or omit text from multiple different lines, this point may differ from where in the Text the physical line actually begins.

pub fn get_ghost(&self, id: GhostId) -> Option<&Text>

pub fn replace_range(&mut self, range: impl TextRange, edit: impl ToString)

Replaces a range in the Text

TextRange behavior:

If you give a single usize/Point, it will be interpreted as a range from.

pub fn update_range( &mut self, start: impl FnOnce(&Text) -> Point, end: impl FnOnce(&Text) -> Point, )

This is used by Areas in order to update visible text

In order to not update too much, an Area will request that a region of the Text (usually roughly what is shown on screen) to be updated, rather than the whole Text.

This should be done within the Area::print and Area::print_with functions.

pub fn undo(&mut self)

Undoes the last moment, if there was one

pub fn redo(&mut self)

Redoes the last moment in the history, if there is one

pub fn apply_and_process_changes(&mut self, changes: Vec<Change<&str>>)

pub fn new_moment(&mut self)

Finishes the current moment and adds a new one to the history

pub fn to_string(&self) -> String

Clones the inner Bytes as a String

This function will also cut out a final ‘\n’ from the string.

pub fn write_to(&self, writer: impl Write) -> Result<usize>

Writes the contents of this Text to a writer

pub fn has_unsaved_changes(&self) -> bool

Wether or not the content has changed since the last write

Returns true only if the actual bytes of the Text have been changed, ignoring Tags and all the other things, since those are not written to the filesystem.

pub fn insert_tag(&mut self, key: Key, tag: Tag)

Inserts a Tag at the given position

pub fn remove_tags(&mut self, range: impl TextRange, keys: impl Keys)

Removes the Tags of a key from a region

Caution

While it is fine to do this on your own widgets, you should refrain from using this function in a Files Text, as it must iterate over all tags in the file, so if there are a lot of other tags, this operation may be slow.

TextRange behavior

If you give it a Point or usize, it will be treated as a one byte range.

pub fn clear_tags(&mut self)

Removes all Tags

Refrain from using this function on Files, as there may be other Tag providers, and you should avoid messing with their tags.

pub fn enable_cursors(&mut self)

Enables the usage of Cursors in this Text

This is automatically done whenever you use the EditHelper struct.

pub fn iter_fwd(&self, at: impl TwoPoints) -> FwdIter<'_>

A forward iterator of the chars and tags of the Text

pub fn iter_rev(&self, at: impl TwoPoints) -> RevIter<'_>

A reverse iterator of the chars and tags of the Text

pub fn chars_fwd(&self, p: Point) -> impl Iterator<Item = (Point, char)> + '_

A forward iterator of the chars of the Text

Each char will be accompanied by a Point, which is the position where said character starts, e.g. Point::default() for the first character

pub fn chars_rev(&self, p: Point) -> impl Iterator<Item = (Point, char)> + '_

A reverse iterator of the chars of the Text

Each char will be accompanied by a Point, which is the position where said character starts, e.g. Point::default() for the first character

pub fn tags_fwd( &self, b: usize, ) -> Peekable<impl Iterator<Item = (usize, RawTag)> + Clone + 'a>

A forward iterator over the Tags of the Text

This iterator will consider some Tags before b, since their ranges may overlap with b

Note

Duat works fine with Tags in the middle of a codepoint, but external utilizers may not, so keep that in mind.

pub fn tags_rev( &self, b: usize, ) -> Peekable<impl Iterator<Item = (usize, RawTag)> + Clone + 'a>

An reverse iterator over the Tags of the Text

This iterator will consider some Tags ahead of b, since their ranges may overlap with b

Note

Duat works fine with Tags in the middle of a codepoint, but external utilizers may not, so keep that in mind.

pub fn raw_tags_fwd(&self, b: usize) -> impl Iterator<Item = (usize, RawTag)>

pub fn raw_tags_rev(&self, b: usize) -> impl Iterator<Item = (usize, RawTag)>

pub fn cursors(&self) -> Option<&Cursors>

The Cursors printed to this Text, if they exist

pub fn cursors_mut(&mut self) -> Option<&mut Cursors>

A mut reference to this Text’s Cursors if they exist

pub fn contiguous(&mut self, range: impl TextRange) -> &str

Gets a single &str from a given range

This is the equivalent of calling Bytes::make_contiguous and Bytes::get_contiguous. While this takes less space in code, calling the other two functions means that you won’t be mutably borrowing the Bytes anymore, so if that matters to you, you should do that.

pub fn make_contiguous(&mut self, range: impl TextRange)

Moves the GapBuffer’s gap, so that the range is whole

The return value is the value of the gap, if the second &str is the contiguous one.

pub fn get_contiguous(&self, range: impl TextRange) -> Option<&str>

Assumes that the range given is contiguous in self

You MUST call make_contiguous before using this function. The sole purpose of this function is to not keep the Bytes mutably borrowed.

Trait Implementations

impl Clone for Text

fn clone(&self) -> Self

Returns a duplicate 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 Default for Text

fn default() -> Self

Returns the “default value” for a type.

impl From<&PathBuf> for Text

fn from(value: &PathBuf) -> Self

Converts to this type from the input type.

impl From<&str> for Text

fn from(value: &str) -> Self

Converts to this type from the input type.

impl From<Arc<str>> for Text

fn from(value: Arc<str>) -> Self

Converts to this type from the input type.

impl From<Box<dyn Error>> for Text

fn from(value: Box<dyn Error>) -> Self

Converts to this type from the input type.

impl From<Box<str>> for Text

fn from(value: Box<str>) -> Self

Converts to this type from the input type.

impl From<Error> for Text

fn from(value: Error) -> Self

Converts to this type from the input type.

impl From<Rc<str>> for Text

fn from(value: Rc<str>) -> Self

Converts to this type from the input type.

impl From<String> for Text

fn from(value: String) -> Self

Converts to this type from the input type.

impl From<Text> for BuilderPart<String, Text>

fn from(value: Text) -> Self

Converts to this type from the input type.

impl<U: Ui> From<Text> for State<U, Text>

fn from(value: Text) -> Self

Converts to this type from the input type.

impl From<char> for Text

fn from(value: char) -> Self

Converts to this type from the input type.

impl From<f32> for Text

fn from(value: f32) -> Self

Converts to this type from the input type.

impl From<f64> for Text

fn from(value: f64) -> Self

Converts to this type from the input type.

impl From<i128> for Text

fn from(value: i128) -> Self

Converts to this type from the input type.

impl From<i16> for Text

fn from(value: i16) -> Self

Converts to this type from the input type.

impl From<i32> for Text

fn from(value: i32) -> Self

Converts to this type from the input type.

impl From<i64> for Text

fn from(value: i64) -> Self

Converts to this type from the input type.

impl From<i8> for Text

fn from(value: i8) -> Self

Converts to this type from the input type.

impl From<isize> for Text

fn from(value: isize) -> Self

Converts to this type from the input type.

impl From<u128> for Text

fn from(value: u128) -> Self

Converts to this type from the input type.

impl From<u16> for Text

fn from(value: u16) -> Self

Converts to this type from the input type.

impl From<u32> for Text

fn from(value: u32) -> Self

Converts to this type from the input type.

impl From<u64> for Text

fn from(value: u64) -> Self

Converts to this type from the input type.

impl From<u8> for Text

fn from(value: u8) -> Self

Converts to this type from the input type.

impl From<usize> for Text

fn from(value: usize) -> Self

Converts to this type from the input type.

impl PartialEq<&str> for Text

fn eq(&self, other: &&str) -> 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.

impl PartialEq<String> for Text

fn eq(&self, other: &String) -> 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.

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.