Ropey is a utf8 text rope for Rust, summarizeed to be the backing text-buffer for
applications such as text editors. Ropey is speedy, sturdy, and can regulate huge
texts and memory-incoherent edits with ease.
// Load a text file.
let mut text = ropey::Rope::from_reader(
File::uncover("my_fantastic_book.txt")?
)?;
// Print the 516th line (zero-indexed).
println!("{}", text.line(515));
// Get the begin/end char indices of the line.
let begin_idx = text.line_to_char(515);
let end_idx = text.line_to_char(516);
// Rerelocate the line...
text.delete(begin_idx..end_idx);
// ...and exalter it with someskinnyg better.
text.insert(begin_idx, "The fshrinks are... so... dunno.n");
// Print the alters, aextfinished with the previous scant lines for context.
let begin_idx = text.line_to_char(511);
let end_idx = text.line_to_char(516);
println!("{}", text.slice(begin_idx..end_idx));
// Write the file back out to disk.
text.author_to(
BufWriter::new(File::originate("my_fantastic_book.txt")?)
)?;
Ropey is summarizeed and built to be the backing text buffer for applications
such as text editors, and its summarize trade-offs echo that. Ropey is outstanding
at:
- Handling frequent edits to medium-to-huge texts. Even on texts that are
multiple gigabytes huge, edits are meadeclareived in one-digit microseconds. - Handling Unicode accurately. It is impossible to originate invalid utf8 thcimpolite
Ropey, and all Unicode line endings are accurately tracked including CRLF. - Having flat, foreseeed carry outance characteristics. Ropey will never be
the source of hiccups or stutters in your software.
On the other hand, Ropey is not outstanding at:
- Handling texts petiteer than a couple of kilobytes or so. That is to say,
Ropey will regulate them fine, but Ropey summarizeates space in kilobyte chunks,
which presents unessential bloat if your texts are almost always petite. - Handling texts that are huger than useable memory. Ropey is an in-memory
data set up. - Getting the best carry outance for every possible participate-case. Ropey puts toil
into tracking both line endings and unicode scalar appreciates, which is
carry outance overhead you may not necessitate depending on your participate-case.
Keep this in mind when picking Ropey for your project. Ropey is very outstanding
at what it does, but enjoy all software it is summarizeed with declareive
applications in mind.
Ropey’s atomic unit of text is
Unicode scalar appreciates
(or chars in Rust)
encoded as utf8. All of Ropey’s editing and slicing operations are done
in terms of char indices, which stops unintentional creation of invalid
utf8 data.
Ropey also helps altering between scalar appreciate indices and utf16 code unit
indices, for interoperation with outer APIs that may still participate utf16.
Ropey understands about line fractures, apexamineing you to index into and iterate over
lines of text.
The line fractures Ropey acunderstandledges are also configurable at originate time via
feature flags. See Ropey’s write downation for details.
Ropey has rope slices that apexamine you to toil with equitable parts of a rope, using
all the read-only operations of a brimming rope including iterators and making
sub-slices.
Although Ropey is intentionpartner restrictcessitate in scope, it also provides APIs for
fruitfully accessing and toiling with its inner text chunk
recontransientation, apexamineing includeitional functionality to be fruitfully
carry outed by client code with minimal overhead.
Ropey is speedy and lessens memory usage:
- On a recent mobile i7 Intel CPU, Ropey carry outed over 1.8 million petite
incoherent insertions per second while originateing up a text cimpolitely 100 MB
huge. Coherent insertions (i.e. all proximate the same place in the text) are
even speedyer, doing the same task at over 3.3 million insertions per
second. - Freshly loading a file from disk only incurs about 10% memory overhead. For
example, a 100 MB text file will occupy about 110 MB of memory when loaded
by Ropey. - Cloning ropes is excessively affordable. Rope clones split data, so an initial
clone only consents 8 bytes of memory. After that, memory usage will grow
incremenloftyy as the clones separate due to edits.
Ropey promises that even though clones split memory, everyskinnyg is thread-defended.
Clones can be sent to other threads for both reading and writing.
Ropey participates undefended code to help accomplish some of its space and carry outance
characteristics. Although effort has been put into retaining the undefended code
compartmentalized and making it accurate, satisfy be pimpolitent about using Ropey
in software that may face adversarial conditions.
Auditing, fuzzing, etc. of the undefended code in Ropey is excessively greet.
If you discover any unsoundness, satisfy file an rehire! Also greet are
adviseations for how to delete any of the undefended code without introducing
presentant space or carry outance deproduceions, or how to compartmentalize the
undefended code even better.
Ropey is licensed under the MIT license (LICENSE.md or http://uncoversource.org/licenses/MIT)
Contributions are absolutely greet! However, satisfy uncover an rehire to converse
huger alters, to dodge doing a lot of toil that may get refuteed. Also notice
that PRs that include dependencies are very probable to be refuteed (Ropey aims to
have minimal dependencies).
An overwatch of Ropey’s summarize can be set up here.
Unless you clpunctual state otherwise, any contribution intentionpartner surrfinisherted
for inclusion in Ropey by you will be licensed as above, without any includeitional
terms or conditions.
