Struct ropey::Rope
[−]
[src]
pub struct Rope { /* fields omitted */ }
A utf8 text rope.
Rope
's atomic unit of data is Unicode scalar values (or char
s in Rust).
Except where otherwise documented, all methods that index into a rope
or return an index into a rope do so by char
index. This makes the API's
intuitive and prevents accidentally creating a Rope with invalid utf8 data.
The primary editing operations available for Rope
are insertion of text,
deletion of text, splitting a Rope
in two, and appending one Rope
to
another. For example:
let mut rope = Rope::from_str("Hello みんなさん!"); rope.remove(6, 11); rope.insert(6, "world"); assert_eq!(rope, "Hello world!");
Cloning Rope
's is extremely cheap, taking only a few instructions and
8 bytes of memory, regardless of text size. This is accomplished by data
sharing between Rope
clones, and the memory used by clones only grows
incrementally as the their contents diverge due to edits. All of this
is thread safe, and clones can be sent freely between threads.
Rope
tracks line endings and has efficient API's for working with lines.
You can convert between char
and line index, determining which line a
given char
is on or the char
index of the beginning of a line:
let rope = Rope::from_str("Hello individual!\nHow are you?\nThis text has multiple lines!"); assert_eq!(rope.char_to_line(5), 0); assert_eq!(rope.char_to_line(21), 1); assert_eq!(rope.line_to_char(0), 0); assert_eq!(rope.line_to_char(1), 18); assert_eq!(rope.line_to_char(2), 31);
Rope
is written to be fast and memory efficient. Except where otherwise
documented, all editing and query operations execute in worst-case
O(log N)
time in the length of the rope. It is designed to work
efficiently even for huge (in the gigabytes) and pathological (all on one
line) texts. It should be able to handle just about anything you can throw
at it.
Methods
impl Rope
[src]
fn new() -> Rope
[src]
Creates an empty Rope
.
fn from_str(text: &str) -> Rope
[src]
Creates a Rope
from a string slice.
Runs in O(N) time.
fn from_reader<T: Read>(reader: T) -> Result<Rope>
[src]
Creates a Rope
from the output of a reader.
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.
fn len_bytes(&self) -> usize
[src]
Total number of bytes in the Rope
.
Runs in O(1) time.
fn len_chars(&self) -> usize
[src]
Total number of chars in the Rope
.
Runs in O(1) time.
fn len_lines(&self) -> usize
[src]
Total number of lines in the Rope
.
Runs in O(1) time.
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.
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 and grapheme 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.
fn insert(&mut self, char_idx: usize, text: &str)
[src]
Inserts text
at char index char_idx
.
Panics
Panics if char_idx
is out of bounds (i.e. char_idx > len_chars()
).
fn remove(&mut self, start: usize, end: usize)
[src]
Removes the text in char range start..end
.
Panics
Panics if start
is greater than end
or end
is out of bounds
(i.e. end > len_chars()
).
fn split_off(&mut self, char_idx: usize) -> Rope
[src]
Splits the Rope
at char_idx
, returning the right part of
the split.
Panics
Panics if char_idx
is out of bounds (i.e. char_idx > len_chars()
).
fn append(&mut self, other: Rope)
[src]
Appends a Rope
to the end of this one, consuming the other Rope
.
fn char_to_line(&self, char_idx: usize) -> usize
[src]
Returns the line index of the given char.
Notes:
- Lines are zero-indexed.
- If
char_idx
is one-past-the-end, then one-past-the-end line index is returned. This is mainly unintuitive for empty ropes, which will return a line index of 1 for achar_idx
of zero. Otherwise it behaves as expected.
Panics
Panics if char_idx
is out of bounds (i.e. char_idx > len_chars()
).
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.
Panics
Panics if line_idx
is out of bounds (i.e. line_idx > len_lines()
).
fn char(&self, char_idx: usize) -> char
[src]
Returns the char at char_idx
.
Panics
Panics if char_idx
is out of bounds (i.e. char_idx >= len_chars()
).
fn line(&self, line_idx: usize) -> RopeSlice
[src]
Returns the line at line_idx
.
Note: lines are zero-indexed.
Panics
Panics if line_idx
is out of bounds (i.e. line_idx >= len_lines()
).
fn is_grapheme_boundary(&self, char_idx: usize) -> bool
[src]
Returns whether char_idx
is a grapheme cluster boundary or not.
Panics
Panics if char_idx
is out of bounds (i.e. char_idx > len_chars()
).
fn prev_grapheme_boundary(&self, char_idx: usize) -> usize
[src]
Returns the char index of the grapheme cluster boundary to the left
of char_idx
.
This excludes any boundary that might be at char_idx
itself, unless
char_idx
is at the beginning of the rope.
Panics
Panics if char_idx
is out of bounds (i.e. char_idx > len_chars()
).
fn next_grapheme_boundary(&self, char_idx: usize) -> usize
[src]
Returns the char index of the grapheme cluster boundary to the right
of char_idx
.
This excludes any boundary that might be at char_idx
itself, unless
char_idx
is at the end of the rope.
Panics
Panics if char_idx
is out of bounds (i.e. char_idx > len_chars()
).
fn slice(&self, start: usize, end: usize) -> RopeSlice
[src]
Returns an immutable slice of the Rope
in the char range start..end
.
Panics
Panics if start
is greater than end
or end
is out of bounds
(i.e. end > len_chars()
).
fn bytes(&self) -> Bytes
[src]
Creates an iterator over the bytes of the Rope
.
fn chars(&self) -> Chars
[src]
Creates an iterator over the chars of the Rope
.
fn graphemes(&self) -> Graphemes
[src]
Creates an iterator over the grapheme clusters of the Rope
.
fn lines(&self) -> Lines
[src]
Creates an iterator over the lines of the Rope
.
fn chunks(&self) -> Chunks
[src]
Creates an iterator over the chunks of the Rope
.
fn to_string(&self) -> String
[src]
Returns the entire text of the Rope
as a newly allocated String.
fn to_slice(&self) -> RopeSlice
[src]
Returns a slice to the entire contents of the Rope
.
Mainly just a convenience method, since the RangeArgument
trait
isn't stabilized yet.
Trait Implementations
impl Clone for Rope
[src]
fn clone(&self) -> Rope
[src]
Returns a copy of the value. Read more
fn clone_from(&mut self, source: &Self)
1.0.0[src]
Performs copy-assignment from source
. Read more
impl Debug for Rope
[src]
impl Display for Rope
[src]
fn fmt(&self, f: &mut Formatter) -> Result
[src]
Formats the value using the given formatter. Read more
impl Default for Rope
[src]
impl<'a> PartialEq<Rope> for Rope
[src]
fn eq(&self, other: &Rope) -> bool
[src]
This method tests for self
and other
values to be equal, and is used by ==
. Read more
fn ne(&self, other: &Rhs) -> bool
1.0.0[src]
This method tests for !=
.
impl<'a> PartialEq<&'a str> for Rope
[src]
fn eq(&self, other: &&'a str) -> bool
[src]
This method tests for self
and other
values to be equal, and is used by ==
. Read more
fn ne(&self, other: &Rhs) -> bool
1.0.0[src]
This method tests for !=
.
impl PartialEq<str> for Rope
[src]
fn eq(&self, other: &str) -> bool
[src]
This method tests for self
and other
values to be equal, and is used by ==
. Read more
fn ne(&self, other: &Rhs) -> bool
1.0.0[src]
This method tests for !=
.
impl<'a> PartialEq<String> for Rope
[src]
fn eq(&self, other: &String) -> bool
[src]
This method tests for self
and other
values to be equal, and is used by ==
. Read more
fn ne(&self, other: &Rhs) -> bool
1.0.0[src]
This method tests for !=
.
impl<'a> PartialEq<Cow<'a, str>> for Rope
[src]
fn eq(&self, other: &Cow<'a, str>) -> bool
[src]
This method tests for self
and other
values to be equal, and is used by ==
. Read more
fn ne(&self, other: &Rhs) -> bool
1.0.0[src]
This method tests for !=
.