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 with_, such as with_push() and with_append().

Methods

impl Rope

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());

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.

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, "💖");

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);

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());

fn insert(&mut self, index: usize, ch: char)

Insert char into index in this Rope,

Panics

• If index is greater than the length of this Rope

Time Complexity

O(log n)

Examples

Inserting at index 0 prepends char to this Rope:

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

Inserting at index len prepends char to this Rope:

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

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

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

fn with_insert(&self, index: usize, ch: char) -> Rope

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.with_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.with_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.with_insert(1, 'b');
assert_eq!(new_rope, Rope::from("abcd"));
assert_eq!(an_rope, Rope::from("acd"));

fn insert_rope(&mut self, index: usize, rope: Rope)

Insert rope into index in this Rope,

Consumes rope.

Panics

• If index is greater than the length of this Rope

Time Complexity

O(log n)

Examples

Inserting at index 0 prepends rope to this Rope:

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

Inserting at index len prepends rope to this Rope:

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

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

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

fn with_insert_rope(&self, index: usize, rope: Rope) -> Rope

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

Consumes 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.with_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.with_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.with_insert_rope(1, Rope::from("bc"));
assert_eq!(new_rope, Rope::from("abcd"));
assert_eq!(an_rope, Rope::from("ad"))

fn insert_str(&mut self, index: usize, s: &str)

Insert string slice s into index in this Rope,

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 mut an_rope = Rope::from("cd");
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 mut an_rope = Rope::from("ab");
an_rope.insert_str(2, "cd");
assert_eq!(an_rope, Rope::from("abcd"));

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

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

fn with_insert_str(&self, index: usize, s: &str) -> Rope

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.with_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.with_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.with_insert_str(1, "bc");
assert_eq!(an_rope, Rope::from("ad"));
assert_eq!(new_rope, Rope::from("abcd"));

fn append(&mut self, other: Rope)

Appends a Rope to the end of this Rope, updating it in place.

Note that this is equivalent to using the += operator.

Examples

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

fn with_append(&self, other: Rope) -> Rope

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

Consumes other.

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.with_append(Rope::from("efgh"));
assert_eq!(&another_rope, "abcdefgh");
assert_eq!(&an_rope, "abcd");

fn prepend(&mut self, other: Rope)

Prepends a Rope to the front of this Rope, modifying it in place.

Consumes other.

Examples

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

fn with_prepend(&self, other: Rope) -> Rope

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

Consumes other.

Examples

use an_rope::Rope;
let an_rope = Rope::from("efgh");
let another_rope = an_rope.with_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.with_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.with_prepend(Rope::from(""));
assert_eq!(&an_rope, "abcd");
assert_eq!(&another_rope, &an_rope);
assert_eq!(&another_rope, "abcd");

fn split(self, index: usize) -> (Rope, Rope)

Splits the rope into two ropes at the given index.

Consumes this rope.

Examples

use an_rope::Rope;
let mut 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")));

fn strings<'a>(&'a self) -> impl Iterator<Item=&'a str>

Returns an iterator over all the strings in this Rope

fn into_strings<'a>(self) -> impl Iterator<Item=String> + 'a

Returns a move iterator over all the strings in this Rope

Consumes self.

fn bytes<'a>(&'a self) -> impl 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.

fn chars<'a>(&'a self) -> impl 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.

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

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

fn lines<'a>(&'a self) -> impl Iterator<Item=&'a str> + 'a

fn graphemes<'a>(&'a self) -> impl Iterator<Item=&'a str>

Returns an iterator over the grapheme clusters of this Rope

This is the iterator returned by Node::into_iter.

fn slice<'a, R>(&'a self, range: R) -> RopeSlice<'a> where R: RangeArgument<usize>

Returns an immutable slice of this Rope between the given indices.

Arguments

• range: A RangeArgument specifying the range to slice. This can be produced by range syntax like .., a.., ..b or c..d.

Panics

If the start or end indices of the range to slice exceed the length of this Rope.

Examples

#![feature(collections)]
#![feature(collections_range)]

extern crate collections;
extern crate an_rope;
use collections::range::RangeArgument;
use an_rope::Rope;

let rope = Rope::from("this is an example string");
assert_eq!(&rope.slice(4..6), "is");

fn slice_mut<'a, R>(&'a mut self, range: R) -> RopeSliceMut<'a> where R: RangeArgument<usize>

Returns an mutable slice of this Rope between the given indices.

Arguments

• range: A RangeArgument specifying the range to slice. This can be produced by range syntax like .., a.., ..b or c..d.

Panics

If the start or end indices of the range to slice exceed the length of this Rope.

Examples

#![feature(collections)]
#![feature(collections_range)]

extern crate collections;
extern crate an_rope;
use collections::range::RangeArgument;
use an_rope::Rope;

let mut rope = Rope::from("this is an example string");
assert_eq!(&mut rope.slice_mut(4..6), "is");

Trait Implementations

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 Debug 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 From<String> for Rope

fn from(string: String) -> Rope

Performs the conversion.

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

fn from(string: &'a str) -> Rope

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<'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 AddAssign for Rope

fn add_assign(&mut self, other: Rope)

Concatenate two Ropes mutably.

Examples

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

impl AddAssign<String> for Rope

fn add_assign(&mut self, string: String)

Concatenate a String onto a Rope mutably.

Examples

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

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

fn add_assign(&mut self, string: &'a str)

Concatenate an &str onto a Rope mutably.

Examples

use an_rope::Rope;
let mut rope = Rope::from(String::from("ab"));
rope += String::from("cd");
assert_eq!(rope, 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

The method for 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

The method for 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

The method for the indexing (container[index]) operation

impl IndexMut<Range<usize>> for Rope

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

The method for the mutable indexing (container[index]) operation

impl IndexMut<RangeTo<usize>> for Rope

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

The method for the mutable indexing (container[index]) operation

impl IndexMut<RangeFrom<usize>> for Rope

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

The method for the mutable indexing (container[index]) operation

impl<'a> Borrow<RopeSlice<'a>> for &'a Rope

fn borrow(&self) -> &RopeSlice<'a>

Immutably borrows from an owned value.

impl Extend<char> for Rope

fn extend<T>(&mut self, iter: T) where T: IntoIterator<Item=char>

Extends a collection with the contents of an iterator.

impl Extend<String> for Rope

fn extend<T>(&mut self, iter: T) where T: IntoIterator<Item=String>

Extends a collection with the contents of an iterator.

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

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

Extends a collection with the contents of an iterator.

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

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

Extends a collection with the contents of an iterator.

impl Extend<Rope> for Rope

fn extend<T>(&mut self, iter: T) where T: IntoIterator<Item=Rope>

Extends a collection with the contents of an iterator.