Struct JumpRope

#[repr(C)]
pub struct JumpRope { /* private fields */ }

Implementations

impl JumpRope

A rope is a “rich string” data structure for storing fancy strings, like the contents of a text editor. See module level documentation for more information.

pub fn new() -> Self

Creates and returns a new, empty rope.

In release mode this method is an alias for new_from_entropy. But when compiled for testing (or in debug mode), we use a fixed seed in order to keep tests fully deterministic.

Note using this method in wasm significantly increases bundle size. Use new_with_seed instead.

pub fn new_from_entropy() -> Self

Creates a new, empty rope seeded from an entropy source.

pub fn new_from_seed(seed: u64) -> Self

Creates a new, empty rope using an RNG seeded from the passed u64 parameter.

The performance of this library with any particular data set will vary by a few percent within a range based on the seed provided. It may be useful to fix the seed within tests or benchmarks in order to make the program entirely deterministic, though bear in mind:

• Jumprope will always use a fixed seed

pub fn len_chars(&self) -> usize

Return the length of the rope in unicode characters. Note this is not the same as either the number of bytes the characters take, or the number of grapheme clusters in the string.

This method returns the length in constant-time (O(1)).

Example

assert_eq!("↯".len(), 3);

let rope = JumpRope::from("↯");
assert_eq!(rope.len_chars(), 1);

// The unicode snowman grapheme cluster needs 2 unicode characters.
let snowman = JumpRope::from("☃️");
assert_eq!(snowman.len_chars(), 2);

pub fn len_wchars(&self) -> usize

String length in wide characters (as would be reported by javascript / C# / etc).

The byte length of this string when encoded to UTF16 will be exactly rope.len_wchars() * 2.

pub fn is_ascii_only(&self) -> bool

Does the rope only contain ASCII characters? (Unicode codepoints < 128). There are some optimizations that can be done if this is true.

impl JumpRope

pub fn insert(&mut self, pos: usize, contents: &str)

Insert new content into the rope. The content is inserted at the specified unicode character offset, which is different from a byte offset for non-ASCII characters.

Example

let mut rope = JumpRope::from("--");
rope.insert(1, "hi there");
assert_eq!(rope.to_string(), "-hi there-");

If the position names a location past the end of the rope, it is truncated.

pub fn remove(&mut self, range: Range<usize>)

Delete a span of unicode characters from the rope. The span is specified in unicode characters, not bytes.

Any attempt to delete past the end of the rope will be silently ignored.

Example

let mut rope = JumpRope::from("Whoa dawg!");
rope.remove(4..9); // delete " dawg"
assert_eq!(rope.to_string(), "Whoa!");

pub fn replace(&mut self, range: Range<usize>, content: &str)

Replace the specified range with new content. This is equivalent to calling remove followed by insert, but it is simpler and faster.

Example

let mut rope = JumpRope::from("Hi Mike!");
rope.replace(3..7, "Duane"); // replace "Mike" with "Duane"
assert_eq!(rope.to_string(), "Hi Duane!");

pub fn len_bytes(&self) -> usize

Get the number of bytes used for the UTF8 representation of the rope. This will always match the .len() property of the equivalent String.

Note: This is only useful in specific situations - like preparing a byte buffer for saving or sending over the internet. In many cases it is preferable to use len_chars.

Example

let str = "κόσμε"; // "Cosmos" in ancient greek
assert_eq!(str.len(), 11); // 11 bytes over the wire

let rope = JumpRope::from(str);
assert_eq!(rope.len_bytes(), str.len());

pub fn is_empty(&self) -> bool

Returns true if the rope contains no elements.

pub fn check(&self)

pub fn mem_size(&self) -> usize

This method counts the number of bytes of memory allocated in the rope. This is purely for debugging.

Notes:

• This method (its existence, its signature and its return value) is not considered part of the stable API provided by jumprope. This may disappear or change in point releases.
• This method walks the entire rope. It has time complexity O(n).
• If a rope is owned inside another structure, this method will double-count the bytes stored in the rope’s head.

impl JumpRope

These methods are only available if the wchar_conversion feature is enabled.

pub fn chars_to_wchars(&self, chars: usize) -> usize

Convert from a unicode character count to a wchar index, like what you’d use in Javascript, Java or C#.

pub fn wchars_to_chars(&self, wchars: usize) -> usize

Convert a wchar index back to a unicode character count.

NOTE: This method’s behaviour is undefined if the wchar offset is invalid. Eg, given a rope with contents 𐆚 (a single character with wchar length 2), wchars_to_chars(1) is undefined and may panic / change in future versions of diamond types.

pub fn insert_at_wchar(&mut self, pos_wchar: usize, contents: &str) -> usize

Insert the given utf8 string into the rope at the specified wchar position. This is compatible with NSString, Javascript, etc.

Returns the insertion position in characters.

NOTE: This method’s behaviour is undefined if the wchar offset is invalid. Eg, given a rope with contents 𐆚 (a single character with wchar length 2), insert_at_wchar(1, ...) is undefined and may panic / change in future versions of diamond types.

pub fn remove_at_wchar(&mut self, range: Range<usize>)

Remove items from the rope, specified by the passed range. The indexes are interpreted as wchar offsets (like you’d get in javascript / C# / etc).

NOTE: This method’s behaviour is undefined if the wchar offset is invalid. Eg, given a rope with contents 𐆚 (a single character with wchar length 2), remove_at_wchar(1..2) is undefined and may panic / change in future versions of diamond types.

pub fn replace_at_wchar(&mut self, range: Range<usize>, content: &str)

Replace the characters in the specified wchar range with content.

NOTE: This method’s behaviour is undefined if the wchar offset is invalid. Eg, given a rope with contents 𐆚 (a single character with wchar length 2), replace_at_wchar(1..2, ...) is undefined and may panic / change in future versions of diamond types.

impl JumpRope

pub fn substrings(&self) -> Substrings<'_>

Iterate over the rope, visiting each substring in str chunks. Whenever possible, this is the best way for a program to read back the contents of a rope, because it avoids allocating memory or copying the characters themselves (as you get with .to_string() or .chars()).

Stability Warning

This iterator will always return all the characters in document order, but the particular way characters are grouped together is based on internal implementation details. Thus it might change in arbitrary ways at any time. Your application should not depend on the specifics of this chunking.

Example

let rope = JumpRope::from("oh hai");
let mut string = String::new();
for str in rope.substrings() {
    string.push_str(str);
}
assert_eq!(string, "oh hai");

pub fn substrings_with_len(&self) -> ContentIter<'_>

Iterate over all substrings in the rope, but also yield the unicode character length for each item. A caller could obviously recalculate these lengths from the provided &str objects, but since the unicode lengths are known this allows small optimizations.

The iterator yields pairs of (str, char_len).

Stability Warning

This iterator will always return all the characters in document order, but the particular way characters are grouped together is based on internal implementation details. Thus it might change in arbitrary ways at any time. Your application should not depend on the specifics of this chunking.

Example

let rope = JumpRope::from("oh hai");
let mut string = String::new();
for (str, char_len) in rope.substrings_with_len() {
    assert_eq!(str.chars().count(), char_len);
    string.push_str(str);
}
assert_eq!(string, "oh hai");

pub fn chars(&self) -> Chars<'_>

Get an iterator over all characters in the rope.

In most cases this will be less efficient than using substrings to iterate over all &str items contained in the rope.

Example

let rope = JumpRope::from("oh hai");
assert_eq!("oh hai", rope.chars().collect::<String>());

pub fn slice_substrings(&self, range: Range<usize>) -> SubstringsInRange<'_>

Iterate through all the substrings within the specified unicode character range in the document.

Example

let rope = JumpRope::from("xxxGreetings!xxx");
let mut string = String::new();
for s in rope.slice_substrings(3..rope.len_chars() - 3) {
    string.push_str(s);
}
assert_eq!(string, "Greetings!");

pub fn slice_substrings_with_len(&self, range: Range<usize>) -> SliceIter<'_>

Iterate through chunks across a character range in the document.

Example

let rope = JumpRope::from("xxxGreetings!xxx");
let mut string = String::new();
for (str, char_len) in rope.slice_substrings_with_len(3..rope.len_chars() - 3) {
    assert_eq!(str.chars().count(), char_len);
    string.push_str(str);
}
assert_eq!(string, "Greetings!");

Or more simply:

let rope = JumpRope::from("xxxGreetings!xxx");
let string = rope.slice_substrings_with_len(3..13).map(|(str, _len)| str).collect::<String>();
assert_eq!(string, "Greetings!");

pub fn slice_chars(&self, range: Range<usize>) -> CharsInRange<'_>

Iterate through characters in the rope within the specified range. The range is specified using unicode characters, not bytes.

Example

let rope = JumpRope::from("xxxGreetings!xxx");

assert_eq!("Greetings!",
    rope.slice_chars(3..rope.len_chars() - 3).collect::<String>()
);

pub fn to_string(&self) -> String

Trait Implementations

impl AsMut<JumpRope> for JumpRopeBuf

fn as_mut(&mut self) -> &mut JumpRope

Flush changes into the rope and mutably borrow the rope.

impl Clone for JumpRope

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for JumpRope

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

Formats the value using the given formatter.

impl Default for JumpRope

fn default() -> Self

Returns the “default value” for a type.

impl Display for JumpRope

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

Formats the value using the given formatter.

impl Drop for JumpRope

fn drop(&mut self)

Executes the destructor for this type.

impl<'a> Extend<&'a str> for JumpRope

fn extend<T: IntoIterator<Item = &'a str>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl From<JumpRope> for JumpRopeBuf

fn from(rope: JumpRope) -> Self

Converts to this type from the input type.

impl<S: AsRef<str>> From<S> for JumpRope

fn from(str: S) -> Self

Converts to this type from the input type.

impl PartialEq<JumpRope> for JumpRopeBuf

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

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<T: AsRef<str>> PartialEq<T> for JumpRope

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

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 for JumpRope

fn eq(&self, other: &JumpRope) -> 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 Eq for JumpRope

impl Send for JumpRope

JumpRope is Send and Sync, because the only way to (safely) mutate the rope is via a &mut reference.

impl Sync for JumpRope