Struct an_rope::Rope

pub struct Rope { /* fields omitted */ }

A Rope

This Rope implementation aims to eventually function as a superset of String, providing the same API plus additional methods. Therefore, code which uses String can easily be ported to use Rope.

Rope provides two APIs for editing a Rope: a destructive, append-in-place API whose methods match those of String, and a non-destructive, persistant API. The persistant API's methods have names prefixed with `, such aspush()andappend()`.

Methods

impl Rope

pub fn from_utf8(vec: Vec<u8>) -> Result<Rope, FromUtf8Error>

Converts a vector of bytes to a Rope.

If you are sure that the byte slice is valid UTF-8, and you don't want to incur the overhead of the validity check, there is an unsafe version of this function, from_utf8_unchecked(),` which has the same behavior but skips the check.

This method will take care to not copy the vector, for efficiency's sake.

Errors

Returns Err if the slice is not UTF-8 with a description as to why the provided bytes are not UTF-8. The vector you moved in is also included.

Examples

Basic usage:

use an_rope::Rope;

// some bytes, in a vector
let sparkle_heart = vec![240, 159, 146, 150];

// We know these bytes are valid, so we'll use `unwrap()`.
let sparkle_heart = Rope::from_utf8(sparkle_heart).unwrap();

assert_eq!(&sparkle_heart, "💖");

Incorrect bytes:

use an_rope::Rope;

// some invalid bytes, in a vector
let sparkle_heart = vec![0, 159, 146, 150];

assert!(Rope::from_utf8(sparkle_heart).is_err());

pub fn from_utf16(v: &[u16]) -> Result<Rope, FromUtf16Error>

Decode a UTF-16 encoded vector v into a Rope, returning Err if v contains any invalid data.

pub unsafe fn from_utf8_unchecked(bytes: Vec<u8>) -> Rope

Converts a vector of bytes to a Rope without checking that the vector contains valid UTF-8.

See the safe version, from_utf8(), for more details.

Safety

This function is unsafe because it does not check that the bytes passed to it are valid UTF-8. If this constraint is violated, it may cause memory unsafety issues with future users of the Rope, as the rest of the standard library assumes that Ropes are valid UTF-8.

Examples

Basic usage:

use an_rope::Rope;

// some bytes, in a vector
let sparkle_heart = vec![240, 159, 146, 150];

let sparkle_heart = unsafe {
    Rope::from_utf8_unchecked(sparkle_heart)
};

assert_eq!(&sparkle_heart, "💖");

pub fn new() -> Rope

Returns a new empty Rope

Examples

use an_rope::Rope;
let mut an_rope = Rope::new();
assert_eq!(an_rope.len(), 0);

pub fn len(&self) -> usize

Returns the length of this Rope

Examples

An empty Rope should have length 0.

use an_rope::Rope;
let mut an_empty_rope = Rope::new();
assert_eq!(an_empty_rope.len(), 0);

use an_rope::Rope;
let mut an_empty_rope = Rope::from(String::from(""));
assert_eq!(an_empty_rope.len(), 0);

A Rope with text should have length equal to the number of characters in the Rope.

use an_rope::Rope;
let mut an_rope = Rope::from(String::from("a string"));
assert_eq!(an_rope.len(), "a string".len());

pub fn is_empty(&self) -> bool

Returns true if this Rope is empty.

Examples

A Rope with no characters should be empty:

use an_rope::Rope;
let an_empty_rope = Rope::new();
assert!(an_empty_rope.is_empty());

use an_rope::Rope;
let an_empty_rope = Rope::from(String::from(""));
assert!(an_empty_rope.is_empty());

A Rope with characters should not be empty:

use an_rope::Rope;
let an_rope = Rope::from("a string");
assert!(!an_rope.is_empty());

pub fn insert<M>(&self, index: M, ch: char) -> Rope where
    M: Metric,
    Self: Measured<M>,
    NodeLink: Measured<M>,
    String: Measured<M>,
    str: Measured<M>, 

Insert ch into index in this Rope, returning a new Rope.

Returns

• A new Rope with ch inserted at index

Time Complexity

O(log n)

Panics

• If index is greater than the length of this Rope

Examples

Inserting at index 0 prepends rope to this Rope:

use an_rope::Rope;
let an_rope = Rope::from("bcd");
let new_rope = an_rope.insert(0, 'a');
assert_eq!(new_rope, Rope::from("abcd"));
assert_eq!(an_rope, Rope::from("bcd"));

Inserting at index len prepends char to this Rope:

use an_rope::Rope;
let an_rope = Rope::from("abc");
let new_rope = an_rope.insert(an_rope.len(), 'd');
assert_eq!(new_rope, Rope::from("abcd"));
assert_eq!(an_rope, Rope::from("abc"));

Inserting at an index in the middle inserts char at that index:

use an_rope::Rope;
let an_rope = Rope::from("acd");
let new_rope = an_rope.insert(1, 'b');
assert_eq!(new_rope, Rope::from("abcd"));
assert_eq!(an_rope, Rope::from("acd"));

pub fn delete<M: Metric>(&self, range: Range<M>) -> Rope where
    NodeLink: Measured<M>,
    String: Measured<M>,
    str: Measured<M>, 

pub fn insert_rope<M>(&self, index: M, rope: &Rope) -> Rope where
    M: Metric,
    Self: Measured<M>,
    NodeLink: Measured<M>,
    String: Measured<M>,
    str: Measured<M>, 

Insert rope into index in this Rope, returning a new Rope.

Returns

• A new Rope with rope inserted at index

Time Complexity

O(log n)

Panics

• If index is greater than the length of this Rope

Examples

Inserting at index 0 prepends rope to this Rope:

use an_rope::Rope;
let an_rope = Rope::from("cd");
let new_rope = an_rope.insert_rope(0, &Rope::from("ab"));
assert_eq!(new_rope, Rope::from("abcd"));
assert_eq!(an_rope, Rope::from("cd"));

Inserting at index len prepends rope to this Rope:

use an_rope::Rope;
let an_rope = Rope::from("ab");
let new_rope = an_rope.insert_rope(an_rope.len(), &Rope::from("cd"));
assert_eq!(new_rope, Rope::from("abcd"));
assert_eq!(an_rope, Rope::from("ab"));

Inserting at an index in the middle inserts rope at that index:

use an_rope::Rope;
let an_rope = Rope::from("ad");
let new_rope = an_rope.insert_rope(1, &Rope::from("bc"));
assert_eq!(new_rope, Rope::from("abcd"));
assert_eq!(an_rope, Rope::from("ad"))

pub fn insert_str<M>(&self, index: M, s: &str) -> Rope where
    M: Metric,
    Self: Measured<M>,
    NodeLink: Measured<M>,
    String: Measured<M>,
    str: Measured<M>, 

Insert s into index in this Rope, returning a new Rope.

Returns

• A new Rope with s inserted at index

Panics

• If index is greater than the length of this Rope

Time Complexity

O(log n)

Examples

Inserting at index 0 prepends s to this Rope:

use an_rope::Rope;
let an_rope = Rope::from("cd");
let an_rope = an_rope.insert_str(0, "ab");
assert_eq!(an_rope, Rope::from("abcd"));

Inserting at index len prepends s to this Rope:

use an_rope::Rope;
let an_rope = Rope::from("ab");
let new_rope = an_rope.insert_str(an_rope.len(), "cd");
assert_eq!(new_rope, Rope::from("abcd"));
assert_eq!(an_rope, Rope::from("ab"));

Inserting at an index in the middle inserts s at that index:

use an_rope::Rope;
let an_rope = Rope::from("ad");
let new_rope = an_rope.insert_str(1, "bc");
assert_eq!(an_rope, Rope::from("ad"));
assert_eq!(new_rope, Rope::from("abcd"));

pub fn append(&self, other: &Rope) -> Rope

Appends a Rope to the end of this Rope, returning a new Rope

Note that this is equivalent to using the + operator.

Examples

use an_rope::Rope;
let an_rope = Rope::from("abcd");
let another_rope = an_rope.append(&Rope::from("efgh"));
assert_eq!(&another_rope, "abcdefgh");
assert_eq!(&an_rope, "abcd");

pub fn prepend(&self, other: &Rope) -> Rope

Prepends a Rope to the end of this Rope, returning a new Rope

Examples

use an_rope::Rope;
let an_rope = Rope::from("efgh");
let another_rope = an_rope.prepend(&Rope::from("abcd"));
assert_eq!(&an_rope, "efgh");
assert_eq!(&another_rope, "abcdefgh");

use an_rope::Rope;
let an_rope = Rope::from("");
let another_rope = an_rope.prepend(&Rope::from("abcd"));
assert_eq!(&an_rope, "");
assert_eq!(&another_rope, "abcd");

use an_rope::Rope;
let an_rope = Rope::from("abcd");
let another_rope = an_rope.prepend(&Rope::from(""));
assert_eq!(&an_rope, "abcd");
assert_eq!(&another_rope, &an_rope);
assert_eq!(&another_rope, "abcd");

pub fn split<M: Metric>(&self, index: M) -> (Rope, Rope) where
    Self: Measured<M>,
    NodeLink: Measured<M>,
    String: Measured<M>,
    str: Measured<M>, 

Splits the rope into two ropes at the given index.

Examples

use an_rope::Rope;
let an_rope = Rope::from(String::from("abcd"));
let (ab, cd) = an_rope.split(2);
assert_eq!(ab, Rope::from(String::from("ab")));
assert_eq!(cd, Rope::from(String::from("cd")));

pub fn strings<'a>(&'a self) -> Box<Iterator<Item = &'a str> + 'a>

Returns an iterator over all the strings in this Rope

pub fn lines<'a>(&'a self) -> Box<Iterator<Item = RopeSlice<'a>> + 'a>

Returns an iterator over all the lines of text in this Rope.

pub fn bytes<'a>(&'a self) -> Box<Iterator<Item = u8> + 'a>

Returns an iterator over all the bytes in this Rope.

As a Rope consists of a sequence of bytes, we can iterate through a rope by byte. This method returns such an iterator.

pub fn chars<'a>(&'a self) -> Box<Iterator<Item = char> + 'a>

Returns an iterator over all the characters in this Rope.

As a Rope consists of valid UTF-8, we can iterate through a Rope by char. This method returns such an iterator.

It's important to remember that char represents a Unicode Scalar Value, and may not match your idea of what a 'character' is. Iteration over grapheme clusters may be what you actually want.

pub fn char_indices<'a>(&'a self) -> Box<Iterator<Item = (usize, char)> + 'a>

pub fn split_whitespace<'a>(&'a self) -> Box<Iterator<Item = &'a str> + 'a>

pub fn graphemes<'a>(&'a self) -> Box<Iterator<Item = &'a str> + 'a>

Returns an iterator over the grapheme clusters of self.

The iterator is over the extended grapheme clusters; as UAX#29recommends extended grapheme cluster boundaries for general processing.

pub fn unicode_words<'a>(&'a self) -> Box<Iterator<Item = &'a str> + 'a>

Returns an iterator over the words of self, separated on UAX#29 word boundaries.

Here, "words" are just those substrings which, after splitting onUAX#29 word boundaries, contain any alphanumeric characters. That is, the substring must contain at least one character with the Alphabetic property, or with General_Category=Number.

pub fn split_word_bounds<'a>(&'a self) -> Box<Iterator<Item = &'a str> + 'a>

Returns an iterator over substrings of self separated on UAX#29 word boundaries.

The concatenation of the substrings returned by this function is just the original string.

pub fn grapheme_indices(&self) -> GraphemeIndices

Returns an iterator over the grapheme clusters of self and their byte offsets. See graphemes() for more information.

Examples

let rope = Rope::from("a̐éö̲\r\n");
let gr_inds = rope.grapheme_indices()
                  .collect::<Vec<(usize, &str)>>();
let b: &[_] = &[(0, "a̐"), (3, "é"), (6, "ö̲"), (11, "\r\n")];

assert_eq!(&gr_inds[..], b);

pub fn split_word_bound_indices(&self) -> UWordBoundIndices

Returns an iterator over substrings of self, split on UAX#29 word boundaries, and their offsets. See split_word_bounds() for more information.

Example

let rope = Rope::from("Brr, it's 29.3°F!");
let swi1 = rope.split_word_bound_indices()
               .collect::<Vec<(usize, &str)>>();
let b: &[_] = &[ (0, "Brr"), (3, ","), (4, " "), (5, "it's")
               , (9, " "), (10, "29.3"),  (14, "°"), (16, "F")
               , (17, "!")];

assert_eq!(&swi1[..], b);

pub fn slice(&self, range: Range<usize>) -> RopeSlice

Trait Implementations

impl<T> From<T> for Rope where
    T: Into<NodeLink>, 

fn from(that: T) -> Self

Performs the conversion.

impl Clone for Rope

fn clone(&self) -> Rope

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Default for Rope

fn default() -> Rope

Returns the "default value" for a type.

impl<M> Measured<M> for Rope where
    M: Metric,
    NodeLink: Measured<M>,
    String: Measured<M>, 

fn to_byte_index(&self, index: M) -> Option<usize>

Convert the Metric into a byte index into the given Node

fn measure(&self) -> M

Apply Metric to Self

fn measure_weight(&self) -> M

Measure the weight of Node by this metric.

impl Debug for Rope

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

Formats the value using the given formatter.

impl Display for Rope

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

Formats the value using the given formatter.

impl Into<Vec<u8>> for Rope

fn into(self) -> Vec<u8>

Performs the conversion.

impl Eq for Rope

impl PartialEq for Rope

fn eq(&self, other: &Rope) -> bool

A rope equals another rope if all the bytes in both are equal.

Examples

use an_rope::Rope;
assert!(Rope::from("abcd") == Rope::from("abcd"));

use an_rope::Rope;
assert!(Rope::from("abcd") != Rope::from("ab"));

use an_rope::Rope;
assert!(Rope::from("abcd") != Rope::from("dcab"))

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<str> for Rope

fn eq(&self, other: &str) -> bool

A rope equals a string if all the bytes in the string equal the rope's.

Examples

use an_rope::Rope;
assert!(&Rope::from("abcd") == "abcd");

use an_rope::Rope;
assert!(&Rope::from("abcd") != "ab");

use an_rope::Rope;
assert!(&Rope::from("abcd") != "dcab");

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<String> for Rope

fn eq(&self, other: &String) -> bool

A rope equals a string if all the bytes in the string equal the rope's.

Examples

use an_rope::Rope;
assert!(Rope::from("abcd") == String::from("abcd"));

use an_rope::Rope;
assert!(Rope::from("abcd") != String::from("ab"));

use an_rope::Rope;
assert!(Rope::from("abcd") != String::from("dcab"));

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'a> Add for &'a Rope

type Output = Rope

The resulting type after applying the + operator.

fn add(self, other: Self) -> Rope

Non-destructively concatenate two Ropes, returning a new Rope.

Examples

use an_rope::Rope;
let rope = Rope::from(String::from("ab"));
assert_eq!( &rope + &Rope::from(String::from("cd"))
          , Rope::from(String::from("abcd")) );

impl Add for Rope

type Output = Rope

The resulting type after applying the + operator.

fn add(self, other: Self) -> Rope

Non-destructively concatenate two Ropes, returning a new Rope.

Examples

use an_rope::Rope;
let rope = Rope::from(String::from("ab"));
assert_eq!( rope + Rope::from(String::from("cd"))
          , Rope::from(String::from("abcd")) );

impl Add<String> for Rope

type Output = Rope

The resulting type after applying the + operator.

fn add(self, other: String) -> Rope

Non-destructively concatenate a Rope and a String.

Returns a new Rope

Examples

use an_rope::Rope;
let rope = Rope::from(String::from("ab"));
assert_eq!( rope + String::from("cd")
          , Rope::from(String::from("abcd")));

impl<'a, 'b> Add<&'b str> for &'a Rope

type Output = Rope

The resulting type after applying the + operator.

fn add(self, other: &'b str) -> Rope

Non-destructively concatenate a Rope and an &str.

Returns a new Rope

Examples

use an_rope::Rope;
let rope = Rope::from(String::from("ab"));
assert_eq!( &rope + "cd"
          , Rope::from(String::from("abcd")));

impl<'a> Add<&'a str> for Rope

type Output = Rope

The resulting type after applying the + operator.

fn add(self, other: &'a str) -> Rope

Non-destructively concatenate a Rope and an &str.

Returns a new Rope

Examples

use an_rope::Rope;
let rope = Rope::from(String::from("ab"));
assert_eq!( rope + "cd"
          , Rope::from(String::from("abcd")));

impl Index<usize> for Rope

type Output = str

The returned type after indexing.

fn index(&self, i: usize) -> &str

Recursively index the Rope to return the i th character.

Examples

use an_rope::Rope;
let an_rope = Rope::from(String::from("abcd"));
assert_eq!(&an_rope[0], "a");
assert_eq!(&an_rope[1], "b");
assert_eq!(&an_rope[2], "c");
assert_eq!(&an_rope[3], "d");

Time complexity

O(log n)

impl Index<Range<usize>> for Rope

type Output = str

The returned type after indexing.

fn index(&self, _i: Range<usize>) -> &str

Performs the indexing (container[index]) operation.

impl Index<RangeTo<usize>> for Rope

type Output = str

The returned type after indexing.

fn index(&self, _i: RangeTo<usize>) -> &str

Performs the indexing (container[index]) operation.

impl Index<RangeFrom<usize>> for Rope

type Output = str

The returned type after indexing.

fn index(&self, _i: RangeFrom<usize>) -> &str

Performs the indexing (container[index]) operation.

impl IndexMut<Range<usize>> for Rope

fn index_mut(&mut self, _i: Range<usize>) -> &mut str

Performs the mutable indexing (container[index]) operation.

impl IndexMut<RangeTo<usize>> for Rope

fn index_mut(&mut self, _i: RangeTo<usize>) -> &mut str

Performs the mutable indexing (container[index]) operation.

impl IndexMut<RangeFrom<usize>> for Rope

fn index_mut(&mut self, _i: RangeFrom<usize>) -> &mut str

Performs the mutable indexing (container[index]) operation.

impl FromIterator<char> for Rope

fn from_iter<I>(iter: I) -> Rope where
    I: IntoIterator<Item = char>, 

Creates a value from an iterator.

impl FromIterator<String> for Rope

fn from_iter<I>(iter: I) -> Rope where
    I: IntoIterator<Item = String>, 

Creates a value from an iterator.

impl FromIterator<Rope> for Rope

fn from_iter<I>(iter: I) -> Rope where
    I: IntoIterator<Item = Rope>, 

Creates a value from an iterator.

impl<'a> FromIterator<&'a char> for Rope

fn from_iter<I>(iter: I) -> Rope where
    I: IntoIterator<Item = &'a char>, 

Creates a value from an iterator.

impl<'a> FromIterator<&'a str> for Rope

fn from_iter<I>(iter: I) -> Rope where
    I: IntoIterator<Item = &'a str>, 

Creates a value from an iterator.