[−][src]Struct ropey::Rope
A utf8 text rope.
The time complexity of nearly all edit and query operations on Rope
are
worst-case O(log N)
in the length of the rope. Rope
is designed to
work efficiently even for huge (in the gigabytes) and pathological (all on
one line) texts.
Editing Operations
The primary editing operations on Rope
are insertion and removal of text.
For example:
let mut rope = Rope::from_str("Hello みんなさん!"); rope.remove(6..11); rope.insert(6, "world"); assert_eq!(rope, "Hello world!");
Query Operations
Rope
provides a rich set of efficient query functions, including querying
rope length in bytes/char
s/lines, fetching individual char
s or lines,
and converting between byte/char
/line indices. For example, to find the
starting char
index of a given line:
let rope = Rope::from_str("Hello みんなさん!\nHow are you?\nThis text has multiple lines!"); assert_eq!(rope.line_to_char(0), 0); assert_eq!(rope.line_to_char(1), 13); assert_eq!(rope.line_to_char(2), 26);
Slicing
You can take immutable slices of a Rope
using slice()
:
let mut rope = Rope::from_str("Hello みんなさん!"); let middle = rope.slice(3..8); assert_eq!(middle, "lo みん");
Cloning
Cloning Rope
s is extremely cheap, running in O(1)
time and taking a
small constant amount of memory for the new clone, regardless of text size.
This is accomplished by data sharing between Rope
clones. The memory
used by clones only grows incrementally as the their contents diverge due
to edits. All of this is thread safe, so clones can be sent freely
between threads.
The primary intended use-case for this feature is to allow asynchronous
processing of Rope
s. For example, saving a large document to disk in a
separate thread while the user continues to perform edits.
Implementations
impl Rope
[src]
pub fn new() -> Self
[src]
Creates an empty Rope
.
pub fn from_str(text: &str) -> Self
[src]
Creates a Rope
from a string slice.
Runs in O(N) time.
pub fn from_reader<T: Read>(reader: T) -> Result<Self>
[src]
Creates a Rope
from the output of a reader.
This is a convenience function. To do more sophisticated text loading,
see RopeBuilder
.
Runs in O(N) time.
Errors
- If the reader returns an error,
from_reader
stops and returns that error. - If non-utf8 data is encountered, an IO error with kind
InvalidData
is returned.
Note: some data from the reader is likely consumed even if there is an error.
pub fn write_to<T: Write>(&self, writer: T) -> Result<()>
[src]
Writes the contents of the Rope
to a writer.
This is a convenience function. To do more sophisticated text output,
see the Chunks
iterator.
Runs in O(N) time.
Errors
- If the writer returns an error,
write_to
stops and returns that error.
Note: some data may have been written even if an error is returned.
pub fn len_bytes(&self) -> usize
[src]
Total number of bytes in the Rope
.
Runs in O(1) time.
pub fn len_chars(&self) -> usize
[src]
Total number of chars in the Rope
.
Runs in O(1) time.
pub fn len_lines(&self) -> usize
[src]
Total number of lines in the Rope
.
Runs in O(1) time.
pub fn len_utf16_cu(&self) -> usize
[src]
Total number of utf16 code units that would be in Rope
if it were
encoded as utf16.
Ropey stores text internally as utf8, but sometimes it is necessary to interact with external APIs that still use utf16. This function is primarily intended for such situations, and is otherwise not very useful.
Runs in O(1) time.
pub fn capacity(&self) -> usize
[src]
Total size of the Rope
's text buffer space, in bytes.
This includes unoccupied text buffer space. You can calculate
the unoccupied space with capacity() - len_bytes()
. In general,
there will always be some unoccupied buffer space.
Runs in O(N) time.
pub fn shrink_to_fit(&mut self)
[src]
Shrinks the Rope
's capacity to the minimum possible.
This will rarely result in capacity() == len_bytes()
. Rope
stores text in a sequence of fixed-capacity chunks, so an exact fit
only happens for texts that are both a precise multiple of that
capacity and have code point boundaries that line up exactly with
the capacity boundaries.
After calling this, the difference between capacity()
and
len_bytes()
is typically under 1KB per megabyte of text in the
Rope
.
NOTE: calling this on a Rope
clone causes it to stop sharing
all data with its other clones. In such cases you will very likely
be increasing total memory usage despite shrinking the Rope
's
capacity.
Runs in O(N) time, and uses O(log N) additional space during shrinking.
pub fn insert(&mut self, char_idx: usize, text: &str)
[src]
Inserts text
at char index char_idx
.
Runs in O(M + log N) time, where N is the length of the Rope
and M
is the length of text
.
Panics
Panics if char_idx
is out of bounds (i.e. char_idx > len_chars()
).
pub fn insert_char(&mut self, char_idx: usize, ch: char)
[src]
Inserts a single char ch
at char index char_idx
.
Runs in O(log N) time.
Panics
Panics if char_idx
is out of bounds (i.e. char_idx > len_chars()
).
pub fn remove<R>(&mut self, char_range: R) where
R: RangeBounds<usize>,
[src]
R: RangeBounds<usize>,
Removes the text in the given char index range.
Uses range syntax, e.g. 2..7
, 2..
, etc. The range is in char
indices.
Runs in O(M + log N) time, where N is the length of the Rope
and M
is the length of the range being removed.
Example
let mut rope = Rope::from_str("Hello world!"); rope.remove(5..); assert_eq!("Hello", rope);
Panics
Panics if the start of the range is greater than the end, or if the
end is out of bounds (i.e. end > len_chars()
).
pub fn split_off(&mut self, char_idx: usize) -> Self
[src]
Splits the Rope
at char_idx
, returning the right part of
the split.
Runs in O(log N) time.
Panics
Panics if char_idx
is out of bounds (i.e. char_idx > len_chars()
).
pub fn append(&mut self, other: Self)
[src]
Appends a Rope
to the end of this one, consuming the other Rope
.
Runs in O(log N) time.
pub fn byte_to_char(&self, byte_idx: usize) -> usize
[src]
Returns the char index of the given byte.
Notes:
- If the byte is in the middle of a multi-byte char, returns the index of the char that the byte belongs to.
byte_idx
can be one-past-the-end, which will return one-past-the-end char index.
Runs in O(log N) time.
Panics
Panics if byte_idx
is out of bounds (i.e. byte_idx > len_bytes()
).
pub fn byte_to_line(&self, byte_idx: usize) -> usize
[src]
Returns the line index of the given byte.
Notes:
- Lines are zero-indexed. This is functionally equivalent to counting the line endings before the specified byte.
byte_idx
can be one-past-the-end, which will return the last line index.
Runs in O(log N) time.
Panics
Panics if byte_idx
is out of bounds (i.e. byte_idx > len_bytes()
).
pub fn char_to_byte(&self, char_idx: usize) -> usize
[src]
Returns the byte index of the given char.
Notes:
char_idx
can be one-past-the-end, which will return one-past-the-end byte index.
Runs in O(log N) time.
Panics
Panics if char_idx
is out of bounds (i.e. char_idx > len_chars()
).
pub fn char_to_line(&self, char_idx: usize) -> usize
[src]
Returns the line index of the given char.
Notes:
- Lines are zero-indexed. This is functionally equivalent to counting the line endings before the specified char.
char_idx
can be one-past-the-end, which will return the last line index.
Runs in O(log N) time.
Panics
Panics if char_idx
is out of bounds (i.e. char_idx > len_chars()
).
pub fn char_to_utf16_cu(&self, char_idx: usize) -> usize
[src]
Returns the utf16 code unit index of the given char.
Ropey stores text internally as utf8, but sometimes it is necessary to interact with external APIs that still use utf16. This function is primarily intended for such situations, and is otherwise not very useful.
Runs in O(log N) time.
Panics
Panics if char_idx
is out of bounds (i.e. char_idx > len_chars()
).
pub fn utf16_cu_to_char(&self, utf16_cu_idx: usize) -> usize
[src]
Returns the char index of the given utf16 code unit.
Ropey stores text internally as utf8, but sometimes it is necessary to interact with external APIs that still use utf16. This function is primarily intended for such situations, and is otherwise not very useful.
Note: if the utf16 code unit is in the middle of a char, returns the index of the char that it belongs to.
Runs in O(log N) time.
Panics
Panics if utf16_cu_idx
is out of bounds
(i.e. utf16_cu_idx > len_utf16_cu()
).
pub fn line_to_byte(&self, line_idx: usize) -> usize
[src]
Returns the byte index of the start of the given line.
Notes:
- Lines are zero-indexed.
line_idx
can be one-past-the-end, which will return one-past-the-end byte index.
Runs in O(log N) time.
Panics
Panics if line_idx
is out of bounds (i.e. line_idx > len_lines()
).
pub fn line_to_char(&self, line_idx: usize) -> usize
[src]
Returns the char index of the start of the given line.
Notes:
- Lines are zero-indexed.
line_idx
can be one-past-the-end, which will return one-past-the-end char index.
Runs in O(log N) time.
Panics
Panics if line_idx
is out of bounds (i.e. line_idx > len_lines()
).
pub fn byte(&self, byte_idx: usize) -> u8
[src]
Returns the byte at byte_idx
.
Runs in O(log N) time.
Panics
Panics if byte_idx
is out of bounds (i.e. byte_idx >= len_bytes()
).
pub fn char(&self, char_idx: usize) -> char
[src]
Returns the char at char_idx
.
Runs in O(log N) time.
Panics
Panics if char_idx
is out of bounds (i.e. char_idx >= len_chars()
).
pub fn line(&self, line_idx: usize) -> RopeSlice
[src]
Returns the line at line_idx
.
Note: lines are zero-indexed.
Runs in O(log N) time.
Panics
Panics if line_idx
is out of bounds (i.e. line_idx >= len_lines()
).
pub fn chunk_at_byte(&self, byte_idx: usize) -> (&str, usize, usize, usize)
[src]
Returns the chunk containing the given byte index.
Also returns the byte and char indices of the beginning of the chunk and the index of the line that the chunk starts on.
Note: for convenience, a one-past-the-end byte_idx
returns the last
chunk of the RopeSlice
.
The return value is organized as
(chunk, chunk_byte_idx, chunk_char_idx, chunk_line_idx)
.
Runs in O(log N) time.
Panics
Panics if byte_idx
is out of bounds (i.e. byte_idx > len_bytes()
).
pub fn chunk_at_char(&self, char_idx: usize) -> (&str, usize, usize, usize)
[src]
Returns the chunk containing the given char index.
Also returns the byte and char indices of the beginning of the chunk and the index of the line that the chunk starts on.
Note: for convenience, a one-past-the-end char_idx
returns the last
chunk of the RopeSlice
.
The return value is organized as
(chunk, chunk_byte_idx, chunk_char_idx, chunk_line_idx)
.
Runs in O(log N) time.
Panics
Panics if char_idx
is out of bounds (i.e. char_idx > len_chars()
).
pub fn chunk_at_line_break(
&self,
line_break_idx: usize
) -> (&str, usize, usize, usize)
[src]
&self,
line_break_idx: usize
) -> (&str, usize, usize, usize)
Returns the chunk containing the given line break.
Also returns the byte and char indices of the beginning of the chunk and the index of the line that the chunk starts on.
Note: for convenience, both the beginning and end of the rope are
considered line breaks for the purposes of indexing. For example, in
the string "Hello \n world!"
0 would give the first chunk, 1 would
give the chunk containing the newline character, and 2 would give the
last chunk.
The return value is organized as
(chunk, chunk_byte_idx, chunk_char_idx, chunk_line_idx)
.
Runs in O(log N) time.
Panics
Panics if line_break_idx
is out of bounds (i.e. line_break_idx > len_lines()
).
pub fn slice<R>(&self, char_range: R) -> RopeSlice where
R: RangeBounds<usize>,
[src]
R: RangeBounds<usize>,
Gets an immutable slice of the Rope
.
Uses range syntax, e.g. 2..7
, 2..
, etc.
Example
let rope = Rope::from_str("Hello world!"); let slice = rope.slice(..5); assert_eq!("Hello", slice);
Runs in O(log N) time.
Panics
Panics if the start of the range is greater than the end, or if the
end is out of bounds (i.e. end > len_chars()
).
pub fn bytes(&self) -> Bytes
[src]
Creates an iterator over the bytes of the Rope
.
Runs in O(log N) time.
pub fn bytes_at(&self, byte_idx: usize) -> Bytes
[src]
Creates an iterator over the bytes of the Rope
, starting at byte
byte_idx
.
If byte_idx == len_bytes()
then an iterator at the end of the
Rope
is created (i.e. next()
will return None
).
Runs in O(log N) time.
Panics
Panics if byte_idx
is out of bounds (i.e. byte_idx > len_bytes()
).
pub fn chars(&self) -> Chars
[src]
Creates an iterator over the chars of the Rope
.
Runs in O(log N) time.
pub fn chars_at(&self, char_idx: usize) -> Chars
[src]
Creates an iterator over the chars of the Rope
, starting at char
char_idx
.
If char_idx == len_chars()
then an iterator at the end of the
Rope
is created (i.e. next()
will return None
).
Runs in O(log N) time.
Panics
Panics if char_idx
is out of bounds (i.e. char_idx > len_chars()
).
pub fn lines(&self) -> Lines
[src]
Creates an iterator over the lines of the Rope
.
Runs in O(log N) time.
pub fn lines_at(&self, line_idx: usize) -> Lines
[src]
Creates an iterator over the lines of the Rope
, starting at line
line_idx
.
If line_idx == len_lines()
then an iterator at the end of the
Rope
is created (i.e. next()
will return None
).
Runs in O(log N) time.
Panics
Panics if line_idx
is out of bounds (i.e. line_idx > len_lines()
).
pub fn chunks(&self) -> Chunks
[src]
Creates an iterator over the chunks of the Rope
.
Runs in O(log N) time.
pub fn chunks_at_byte(&self, byte_idx: usize) -> (Chunks, usize, usize, usize)
[src]
Creates an iterator over the chunks of the Rope
, with the
iterator starting at the chunk containing byte_idx
.
Also returns the byte and char indices of the beginning of the first chunk to be yielded, and the index of the line that chunk starts on.
If byte_idx == len_bytes()
an iterator at the end of the Rope
(yielding None
on a call to next()
) is created.
The return value is organized as
(iterator, chunk_byte_idx, chunk_char_idx, chunk_line_idx)
.
Runs in O(log N) time.
Panics
Panics if byte_idx
is out of bounds (i.e. byte_idx > len_bytes()
).
pub fn chunks_at_char(&self, char_idx: usize) -> (Chunks, usize, usize, usize)
[src]
Creates an iterator over the chunks of the Rope
, with the
iterator starting at the chunk containing char_idx
.
Also returns the byte and char indices of the beginning of the first chunk to be yielded, and the index of the line that chunk starts on.
If char_idx == len_chars()
an iterator at the end of the Rope
(yielding None
on a call to next()
) is created.
The return value is organized as
(iterator, chunk_byte_idx, chunk_char_idx, chunk_line_idx)
.
Runs in O(log N) time.
Panics
Panics if char_idx
is out of bounds (i.e. char_idx > len_chars()
).
pub fn chunks_at_line_break(
&self,
line_break_idx: usize
) -> (Chunks, usize, usize, usize)
[src]
&self,
line_break_idx: usize
) -> (Chunks, usize, usize, usize)
Creates an iterator over the chunks of the Rope
, with the
iterator starting at the chunk containing line_break_idx
.
Also returns the byte and char indices of the beginning of the first chunk to be yielded, and the index of the line that chunk starts on.
Note: for convenience, both the beginning and end of the Rope
are
considered line breaks for the purposes of indexing. For example, in
the string "Hello \n world!"
0 would create an iterator starting on
the first chunk, 1 would create an iterator starting on the chunk
containing the newline character, and 2 would create an iterator at
the end of the Rope
(yielding None
on a call to next()
).
The return value is organized as
(iterator, chunk_byte_idx, chunk_char_idx, chunk_line_idx)
.
Runs in O(log N) time.
Panics
Panics if line_break_idx
is out of bounds (i.e. line_break_idx > len_lines()
).
Trait Implementations
impl Clone for Rope
[src]
impl Debug for Rope
[src]
impl Default for Rope
[src]
impl Display for Rope
[src]
impl Eq for Rope
[src]
impl<'a> From<&'a Rope> for String
[src]
impl<'a> From<&'a Rope> for Cow<'a, str>
[src]
Attempts to borrow the contents of the Rope
, but will convert to an
owned string if the contents is not contiguous in memory.
Runs in best case O(1), worst case O(N).
impl<'a> From<&'a str> for Rope
[src]
impl<'a> From<Cow<'a, str>> for Rope
[src]
impl From<Rope> for String
[src]
impl<'a> From<Rope> for Cow<'a, str>
[src]
impl<'a> From<RopeSlice<'a>> for Rope
[src]
Will share data where possible.
Runs in O(log N) time.
impl From<String> for Rope
[src]
impl<'a> FromIterator<&'a str> for Rope
[src]
fn from_iter<T>(iter: T) -> Self where
T: IntoIterator<Item = &'a str>,
[src]
T: IntoIterator<Item = &'a str>,
impl<'a> FromIterator<Cow<'a, str>> for Rope
[src]
fn from_iter<T>(iter: T) -> Self where
T: IntoIterator<Item = Cow<'a, str>>,
[src]
T: IntoIterator<Item = Cow<'a, str>>,
impl FromIterator<String> for Rope
[src]
fn from_iter<T>(iter: T) -> Self where
T: IntoIterator<Item = String>,
[src]
T: IntoIterator<Item = String>,
impl Ord for Rope
[src]
fn cmp(&self, other: &Rope) -> Ordering
[src]
#[must_use]fn max(self, other: Self) -> Self
1.21.0[src]
#[must_use]fn min(self, other: Self) -> Self
1.21.0[src]
#[must_use]fn clamp(self, min: Self, max: Self) -> Self
[src]
impl<'a> PartialEq<&'a str> for Rope
[src]
impl<'a> PartialEq<Cow<'a, str>> for Rope
[src]
fn eq(&self, other: &Cow<'a, str>) -> bool
[src]
#[must_use]fn ne(&self, other: &Rhs) -> bool
1.0.0[src]
impl PartialEq<Rope> for Rope
[src]
impl<'a> PartialEq<Rope> for &'a str
[src]
impl PartialEq<Rope> for str
[src]
impl<'a> PartialEq<Rope> for String
[src]
impl<'a> PartialEq<Rope> for Cow<'a, str>
[src]
impl<'a> PartialEq<Rope> for RopeSlice<'a>
[src]
impl<'a> PartialEq<RopeSlice<'a>> for Rope
[src]
fn eq(&self, other: &RopeSlice<'a>) -> bool
[src]
#[must_use]fn ne(&self, other: &Rhs) -> bool
1.0.0[src]
impl<'a> PartialEq<String> for Rope
[src]
impl PartialEq<str> for Rope
[src]
impl PartialOrd<Rope> for Rope
[src]
Auto Trait Implementations
impl RefUnwindSafe for Rope
impl Send for Rope
impl Sync for Rope
impl Unpin for Rope
impl UnwindSafe for Rope
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> ToOwned for T where
T: Clone,
[src]
T: Clone,
type Owned = T
The resulting type after obtaining ownership.
fn to_owned(&self) -> T
[src]
fn clone_into(&self, target: &mut T)
[src]
impl<T> ToString for T where
T: Display + ?Sized,
[src]
T: Display + ?Sized,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,