1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326
//! Ropey is a utf8 text rope for Rust. It is fast, robust, and can handle
//! huge texts and memory-incoherent edits with ease.
//!
//! Ropey's atomic unit of text is Unicode scalar values (or `char`s in Rust)
//! encoded as utf8. All of Ropey's editing and slicing operations are done
//! in terms of char indices which prevents accidental creation of invalid
//! utf8 data.
//!
//! The library is made up of four main components:
//!
//! - [`Rope`]: the main rope type.
//! - [`RopeSlice`]: an immutable view into part of a
//! `Rope`.
//! - [`iter`]: iterators over `Rope`/`RopeSlice` data.
//! - [`RopeBuilder`]: an efficient incremental
//! `Rope` builder.
//!
//!
//! # A Basic Example
//!
//! Let's say we want to open up a text file, replace the 516th line (the
//! writing was terrible!), and save it back to disk. It's contrived, but will
//! give a good sampling of the APIs and how they work together.
//!
//! ```no_run
//! # use std::io::Result;
//! use std::fs::File;
//! use std::io::{BufReader, BufWriter};
//! use ropey::Rope;
//!
//! # fn do_stuff() -> Result<()> {
//! // Load a text file.
//! let mut text = Rope::from_reader(
//! BufReader::new(File::open("my_great_book.txt")?)
//! )?;
//!
//! // Print the 516th line (zero-indexed) to see the terrible
//! // writing.
//! println!("{}", text.line(515));
//!
//! // Get the start/end char indices of the line.
//! let start_idx = text.line_to_char(515);
//! let end_idx = text.line_to_char(516);
//!
//! // Remove the line...
//! text.remove(start_idx..end_idx);
//!
//! // ...and replace it with something better.
//! text.insert(start_idx, "The flowers are... so... dunno.\n");
//!
//! // Print the changes, along with the previous few lines for context.
//! let start_idx = text.line_to_char(511);
//! let end_idx = text.line_to_char(516);
//! println!("{}", text.slice(start_idx..end_idx));
//!
//! // Write the file back out to disk.
//! text.write_to(
//! BufWriter::new(File::create("my_great_book.txt")?)
//! )?;
//! # Ok(())
//! # }
//! # do_stuff().unwrap();
//! ```
//!
//! More examples can be found in the `examples` directory of the git
//! repository. Many of those examples demonstrate doing non-trivial things
//! with Ropey such as grapheme handling, search-and-replace, and streaming
//! loading of non-utf8 text files.
//!
//!
//! # Low-level APIs
//!
//! Ropey also provides access to some of its low-level APIs, enabling client
//! code to efficiently work with a `Rope`'s data and implement new
//! functionality. The most important of those API's are:
//!
//! - The [`chunk_at_*()`](Rope::chunk_at_byte)
//! chunk-fetching methods of `Rope` and `RopeSlice`.
//! - The [`Chunks`](iter::Chunks) iterator.
//! - The functions in [`str_utils`] for operating on
//! `&str` slices.
//!
//! Internally, each `Rope` stores text as a segemented collection of utf8
//! strings. The chunk-fetching methods and `Chunks` iterator provide direct
//! access to those strings (or "chunks") as `&str` slices, allowing client
//! code to work directly with the underlying utf8 data.
//!
//! The chunk-fetching methods and `str_utils` functions are the basic
//! building blocks that Ropey itself uses to build much of its functionality.
//! For example, the [`Rope::byte_to_char()`]
//! method can be reimplemented as a free function like this:
//!
//! ```no_run
//! use ropey::{
//! Rope,
//! str_utils::byte_to_char_idx
//! };
//!
//! fn byte_to_char(rope: &Rope, byte_idx: usize) -> usize {
//! let (chunk, b, c, _) = rope.chunk_at_byte(byte_idx);
//! c + byte_to_char_idx(chunk, byte_idx - b)
//! }
//! ```
//!
//! And this will be just as efficient as Ropey's implementation.
//!
//! The chunk-fetching methods in particular are among the fastest functions
//! that Ropey provides, generally operating in the sub-hundred nanosecond
//! range for medium-sized (~200kB) documents on recent-ish computer systems.
//!
//!
//! # A Note About Line Endings
//!
//! Some of Ropey's APIs use the concept of line breaks or lines of text. In
//! all such APIs, Ropey treats the following unicode sequences as line
//! breaks:
//!
//! - `U+000A` — LF (Line Feed)
//! - `U+000B` — VT (Vertical Tab)
//! - `U+000C` — FF (Form Feed)
//! - `U+000D` — CR (Carriage Return)
//! - `U+0085` — NEL (Next Line)
//! - `U+2028` — Line Separator
//! - `U+2029` — Paragraph Separator
//! - `U+000D` `U+000A` — CRLF (Carriage Return + Line Feed)
//!
//! Additionally, Ropey treats line breaks as being a part of the line that
//! they mark the end of. That is to say, lines begin immediately _after_ a
//! line break. For example, the text `"Hello\nworld"` has two lines:
//! `"Hello\n"` and `"world"`. And the text `"Hello\nworld\n"` has three
//! lines: `"Hello\n"`, `"world\n"`, and `""`.
//!
//! CRLF pairs are always treated as a single line break, and are never split
//! across chunks. Note, however, that slicing can still split them.
#![allow(clippy::collapsible_if)]
#![allow(clippy::inline_always)]
#![allow(clippy::needless_return)]
#![allow(clippy::redundant_field_names)]
#![allow(clippy::type_complexity)]
extern crate smallvec;
mod crlf;
mod rope;
mod rope_builder;
mod slice;
mod tree;
pub mod iter;
pub mod str_utils;
use std::ops::Bound;
pub use crate::rope::Rope;
pub use crate::rope_builder::RopeBuilder;
pub use crate::slice::RopeSlice;
//==============================================================
// Error reporting types.
/// Ropey's result type.
pub type Result<T> = std::result::Result<T, Error>;
/// Ropey's error type.
#[derive(Clone, Copy)]
#[non_exhaustive]
pub enum Error {
/// Indicates that the passed byte index was out of bounds.
///
/// Contains the index attempted and the actual length of the
/// `Rope`/`RopeSlice` in bytes, in that order.
ByteIndexOutOfBounds(usize, usize),
/// Indicates that the passed char index was out of bounds.
///
/// Contains the index attempted and the actual length of the
/// `Rope`/`RopeSlice` in chars, in that order.
CharIndexOutOfBounds(usize, usize),
/// Indicates that the passed line index was out of bounds.
///
/// Contains the index attempted and the actual length of the
/// `Rope`/`RopeSlice` in lines, in that order.
LineIndexOutOfBounds(usize, usize),
/// Indicates that the passed utf16 code-unit index was out of
/// bounds.
///
/// Contains the index attempted and the actual length of the
/// `Rope`/`RopeSlice` in utf16 code units, in that order.
Utf16IndexOutOfBounds(usize, usize),
/// Indicates that a reversed char-index range (end < start) was
/// encountered.
///
/// Contains the [start, end) char indices of the range, in that order.
CharRangeInvalid(
usize, // Start.
usize, // End.
),
/// Indicates that the passed char-index range was partially or fully
/// out of bounds.
///
/// Contains the [start, end) char indices of the range and the actual
/// length of the `Rope`/`RopeSlice` in chars, in that order. When
/// either the start or end are `None`, that indicates a half-open range.
CharRangeOutOfBounds(
Option<usize>, // Start.
Option<usize>, // End.
usize, // Rope char length.
),
}
impl std::error::Error for Error {
fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
None
}
// Deprecated in std.
fn description(&self) -> &str {
""
}
// Deprecated in std.
fn cause(&self) -> Option<&dyn std::error::Error> {
None
}
}
impl std::fmt::Debug for Error {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match *self {
Error::ByteIndexOutOfBounds(index, len) => {
write!(
f,
"Byte index out of bounds: byte index {}, Rope/RopeSlice byte length {}",
index, len
)
}
Error::CharIndexOutOfBounds(index, len) => {
write!(
f,
"Char index out of bounds: char index {}, Rope/RopeSlice char length {}",
index, len
)
}
Error::LineIndexOutOfBounds(index, len) => {
write!(
f,
"Line index out of bounds: line index {}, Rope/RopeSlice line count {}",
index, len
)
}
Error::Utf16IndexOutOfBounds(index, len) => {
write!(f, "Utf16 code-unit index out of bounds: utf16 index {}, Rope/RopeSlice utf16 length {}", index, len)
}
Error::CharRangeInvalid(start_idx, end_idx) => {
write!(
f,
"Invalid char range {}..{}: start must be <= end",
start_idx, end_idx
)
}
Error::CharRangeOutOfBounds(start_idx_opt, end_idx_opt, len) => {
write!(f, "Char range out of bounds: char range ")?;
write_range(f, start_idx_opt, end_idx_opt)?;
write!(f, ", Rope/RopeSlice char length {}", len)
}
}
}
}
impl std::fmt::Display for Error {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
// Just re-use the debug impl.
std::fmt::Debug::fmt(self, f)
}
}
fn write_range(
f: &mut std::fmt::Formatter<'_>,
start_idx: Option<usize>,
end_idx: Option<usize>,
) -> std::fmt::Result {
match (start_idx, end_idx) {
(None, None) => {
write!(f, "..")
}
(Some(start), None) => {
write!(f, "{}..", start)
}
(None, Some(end)) => {
write!(f, "..{}", end)
}
(Some(start), Some(end)) => {
write!(f, "{}..{}", start, end)
}
}
}
//==============================================================
// Range handling utilities.
#[inline(always)]
pub(crate) fn start_bound_to_num(b: Bound<&usize>) -> Option<usize> {
match b {
Bound::Included(n) => Some(*n),
Bound::Excluded(n) => Some(*n + 1),
Bound::Unbounded => None,
}
}
#[inline(always)]
pub(crate) fn end_bound_to_num(b: Bound<&usize>) -> Option<usize> {
match b {
Bound::Included(n) => Some(*n + 1),
Bound::Excluded(n) => Some(*n),
Bound::Unbounded => None,
}
}