Struct Text 

pub struct Text { /* private fields */ }

A text, as a value.

Clone is cheap: the rope shares its structure, so a clone is not a copy of the text but the same text, held elsewhere. That is what lets a background task, a history entry or a preview hold one without anybody duplicating a buffer, and it is why a clone keeps the same Revision — only a change mints a new one.

The text never contains a carriage return. A \r\n or a lone \r in the input becomes \n on construction, so every layer above measures, wraps and addresses exactly one kind of line break. Restoring a file’s original line endings on save is the caller’s business; it has the file, this does not.

Implementations

impl Text

pub fn new() -> Self

An empty text: one row, zero characters.

pub fn revision(&self) -> Revision

Which state this text is. Every Position carries the revision it was built against, so one made against an earlier state is refused rather than read as some other place.

pub fn len_bytes(&self) -> usize

pub fn len_chars(&self) -> usize

pub fn line_count(&self) -> usize

Number of logical rows. A trailing newline opens a final empty row, so "a\n" is two rows and the cursor can sit on the second.

pub fn line(&self, row: usize) -> Option<Cow<'_, str>>

Row row without its line break, or None if there is no such row.

Borrowed when the row sits inside one of the rope’s chunks, owned when it straddles two. Nothing above holds a duplicate of the document, so a full pass over the text costs what it costs and a partial pass costs less.

pub fn line_len_chars(&self, row: usize) -> Option<usize>

Length of row row in Unicode scalars, excluding its line break.

pub fn lines(&self) -> impl Iterator<Item = Cow<'_, str>>

Every row, without line breaks.

pub fn slice(&self, span: Span) -> Option<Cow<'_, str>>

The text within span.

None when the span addresses another revision of the text.

pub fn is_stale(&self, position: Position) -> bool

Whether position addresses a state this text has moved on from.

pub fn position(&self, row: usize, column: Column) -> Option<Position>

The position at (row, column), or None if this text cannot address it.

Refused rather than approximated: past the end of the row, past the last row, or partway through a grapheme cluster all yield None. A caller that gets None has asked for somewhere that does not exist, and a keystroke that does nothing is recoverable in a way one that edits the wrong place is not.

pub fn position_at_byte(&self, byte: usize) -> Option<Position>

The position at byte offset byte, or None if that offset is past the end, inside a character, or inside a grapheme cluster.

pub fn position_at_byte_snapped(&self, byte: usize) -> Option<Position>

The position at the start of the grapheme cluster containing byte.

This one approximates, which is why it says so in its name. It exists for offsets that arrive from somewhere with a different idea of where a character ends — an external editor reporting a cursor in bytes, say — where refusing would drop the update entirely. Anything originating inside this crate should use Self::position_at_byte and be told it was wrong.

None only when byte is past the end of the text.

pub fn start(&self) -> Position

The first position in the text.

pub fn end(&self) -> Position

The position just past the last character.

pub fn full_span(&self) -> Span

The whole text as one span.

pub fn span(&self, a: Position, b: Position) -> Option<Span>

An ordered span between two positions of this text.

Order does not matter: the span comes back with its ends the right way round. None when either position addresses another revision — which is also the only place two positions are checked against each other, and the reason Position is not Ord.

Trait Implementations

impl Clone for Text

fn clone(&self) -> Text

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 Display for Text

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

Formats the value using the given formatter.

impl From<&str> for Text

fn from(s: &str) -> Self

Takes s as the text’s content, normalising \r\n and lone \r to \n.