JumpRope Rust Library

For high-performance editing, use JumpRopeBuf. This wrapper provides a buffered API that attempts to merge consecutive editing runs (like multiple character insertions) before flushing them to the underlying JumpRope object. This can make editing up to 10x faster.

If a specific method you need is missing from JumpRopeBuf, you can call rope.borrow() or rope.as_mut() to flush pending changes and access the underlying JumpRope instance.

To use JumpRope in your Rust project, add it to your Cargo.toml file.

Note: JumpRope is optimized for large strings (e.g., source code files). For very small strings (less than 100 bytes), standard Rust String or small-string-optimized libraries like SmartString are recommended.

jumprope = "1.0.0"

There are several ways to read data back from a rope depending on your performance and allocation needs:

1. Convert to String: Use rope.to_string(). This is convenient but requires full allocations.
2. Iterate Characters: Use rope.chars() to iterate over Unicode characters.
3. Iterate Substrings (Fastest): Use rope.substrings() to get an iterator over &str chunks contained in the document. This is the most efficient method for reading content.
4. Slice Substrings: Use rope.slice_substrings(range) to read all content within a specific range (e.g., 10..20).

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

    let string = rope.slice_substrings(3..13).collect::<String>();
    assert_eq!(string, "Greetings!");
}

To execute the performance benchmarks comparing various rope implementations (including Jumprope, librope, ropey, xi-rope, and an-rope), navigate to the rope_benches directory and use the cargo run command with the --bench flag in release mode. The results are generated as a Criterion report accessible via HTML.

cargo run --release -- --bench

If you need to interface with languages like JavaScript, Java, or C# that use 2-byte UTF-16 offsets (wchars), you can enable the wchar_conversion feature. This allows $O(\log n)$ conversion between Unicode character offsets and wchar offsets.

Warning: This feature adds extra bookkeeping that slows down JumpRope by approximately 15%.

jumprope = { version = "1.0.0", features = ["wchar_conversion"] }

Use the chars() method to get an iterator over the individual char elements in the rope. Note that this is generally less efficient than using substrings() because it processes the rope character by character rather than in chunks.

use jumprope::JumpRope;

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

If you need to know the Unicode character count for each chunk (to avoid recalculating it), use substrings_with_len(). This returns an iterator yielding pairs of (&str, usize), where the usize is the number of Unicode characters in that specific substring.

Stability Warning: Like substrings(), the chunking logic is an internal detail and subject to change.

use jumprope::JumpRope;

let rope = JumpRope::from("oh hai");
for (s, char_len) in rope.substrings_with_len() {
    assert_eq!(s.chars().count(), char_len);
}

You can create a new JumpRope instance from any string-like type using JumpRope::from(). This is the standard way to initialize the data structure with existing content.

let rope = JumpRope::from("Hello, world!");

You can create a new, empty JumpRope using several methods depending on your requirements for determinism and entropy:

• JumpRope::new(): Creates an empty rope. In release mode, this uses entropy. In debug/test mode, it uses a fixed seed for determinism.
• JumpRope::new_from_entropy(): Creates an empty rope seeded from a high-entropy source.
• JumpRope::new_from_seed(seed: u64): Creates an empty rope using a specific u64 seed. This is useful for making benchmarks or tests entirely deterministic.

use jumprope::JumpRope;

// Deterministic for testing
let rope = JumpRope::new_from_seed(123);

// Random for production
let rope = JumpRope::new_from_entropy();