From 17f67602d92db520e3bcf011a214b4934f142adc Mon Sep 17 00:00:00 2001
From: Andras Schmelczer <andras@schmelczer.dev>
Date: Sun, 29 Jun 2025 15:48:50 +0100
Subject: [PATCH] Improve docs & api

---
 src/operation_transformation/edited_text.rs |  2 +-
 src/operation_transformation/operation.rs   |  4 ++--
 src/utils/side.rs                           |  2 ++
 src/utils/string_builder.rs                 | 24 +++++++++------------
 4 files changed, 15 insertions(+), 17 deletions(-)

diff --git a/src/operation_transformation/edited_text.rs b/src/operation_transformation/edited_text.rs
index 47cde49..34f42b8 100644
--- a/src/operation_transformation/edited_text.rs
+++ b/src/operation_transformation/edited_text.rs
@@ -222,7 +222,7 @@ where
             builder = operation.apply(builder);
         }
 
-        builder.build()
+        builder.take()
     }
 
     #[must_use]
diff --git a/src/operation_transformation/operation.rs b/src/operation_transformation/operation.rs
index ca2f128..652eb3e 100644
--- a/src/operation_transformation/operation.rs
+++ b/src/operation_transformation/operation.rs
@@ -421,7 +421,7 @@ mod tests {
         let mut builder = delete_operation.apply(builder);
         builder = retain_operation.apply(builder);
 
-        assert_eq!(builder.build(), "world");
+        assert_eq!(builder.take(), "world");
     }
 
     #[test]
@@ -434,6 +434,6 @@ mod tests {
         let mut builder = retain_operation.apply(builder);
         builder = insert_operation.apply(builder);
 
-        assert_eq!(builder.build(), "hello my friend");
+        assert_eq!(builder.take(), "hello my friend");
     }
 }
diff --git a/src/utils/side.rs b/src/utils/side.rs
index 54dba6f..2bfa426 100644
--- a/src/utils/side.rs
+++ b/src/utils/side.rs
@@ -3,6 +3,8 @@ use std::fmt::Display;
 #[cfg(feature = "serde")]
 use serde::{Deserialize, Serialize};
 
+/// Pretty-printable flag to tell which conflicting edit (side)
+/// an operation is associated with.
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum Side {
diff --git a/src/utils/string_builder.rs b/src/utils/string_builder.rs
index ee23fc6..1656224 100644
--- a/src/utils/string_builder.rs
+++ b/src/utils/string_builder.rs
@@ -51,21 +51,17 @@ impl StringBuilder<'_> {
         }
     }
 
-    /// Returns the currently built buffer and clears it.
+    /// Returns the currently built buffer and clears it to allow consuming
+    /// the result incrementally.
     pub fn take(&mut self) -> String {
-        let result = self.buffer.clone();
+        let result = self.buffer.clone(); // TODO: try removing this clone
         self.buffer.clear();
         result
     }
 
-    /// Finish building the string after copying the remaining original string
-    /// since the last insertion or deletion.
-    pub fn build(self) -> String { self.buffer }
-
     /// Get a slice of the remaining original string. The slice starts from
     /// where the next delete/retain operation would start and is of length
-    /// `length`. The implementation is quite suboptimal but it's only used
-    /// for debugging.
+    /// `length`.
     #[cfg(debug_assertions)]
     pub fn get_slice_from_remaining(&self, length: usize) -> String {
         let result = self.remaining.chars().take(length).collect::<String>();
@@ -92,7 +88,7 @@ mod tests {
         builder.retain(8);
         builder.insert(" eee");
 
-        assert_eq!(builder.build(), "ddd bbb ccc eee");
+        assert_eq!(builder.take(), "ddd bbb ccc eee");
 
         let original = "abcde";
         let mut builder = StringBuilder::new(original);
@@ -101,7 +97,7 @@ mod tests {
         builder.delete(3);
         builder.retain(1);
 
-        assert_eq!(builder.build(), "ae");
+        assert_eq!(builder.take(), "ae");
     }
 
     #[test]
@@ -110,7 +106,7 @@ mod tests {
         let mut builder = StringBuilder::new(original);
 
         builder.insert("test");
-        assert_eq!(builder.build(), "test");
+        assert_eq!(builder.take(), "test");
     }
 
     #[test]
@@ -122,7 +118,7 @@ mod tests {
         builder.insert("世界, "); // Insert "World, "
         builder.retain(2);
 
-        assert_eq!(builder.build(), "こんに世界, ちは");
+        assert_eq!(builder.take(), "こんに世界, ちは");
     }
 
     #[test]
@@ -145,7 +141,7 @@ mod tests {
         let mut builder = StringBuilder::new(original);
 
         builder.retain(original.len());
-        assert_eq!(builder.build(), original);
+        assert_eq!(builder.take(), original);
     }
 
     #[test]
@@ -155,6 +151,6 @@ mod tests {
 
         builder.delete(original.len());
         builder.insert("Hi");
-        assert_eq!(builder.build(), "Hi");
+        assert_eq!(builder.take(), "Hi");
     }
 }