From 798c88e559e1c458ac6daf942b7525ea5ab2ee92 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 15 Dec 2025 09:03:15 +0000
Subject: [PATCH] Add documentation for string replacement length limitation

Documented that for string objects, the replacement text must have the
same length as the original matched text due to store-substring limitations.

Co-authored-by: Kinneyzhang <38454496+Kinneyzhang@users.noreply.github.com>
---
 tp.el | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/tp.el b/tp.el
index 2cc4eb2..9a3d318 100644
--- a/tp.el
+++ b/tp.el
@@ -1101,6 +1101,11 @@ OBJECT can be a buffer or string; nil defaults to current buffer.
 
 Returns the number of successful matches.
 
+Note: For string objects, the replacement text must have the same length
+as the original matched text, since strings have fixed length in Emacs.
+If the replacement is shorter, only that portion will be replaced.
+If the replacement is longer, it will be truncated.
+
 Example:
   ;; Upcase all matched text
   (tp-forward-do #\\='upcase \\='marker nil my-string 3)"
@@ -1115,6 +1120,7 @@ Example:
        (when (and new-text (not (equal new-text text)))
          (if (stringp obj)
              ;; For strings, we need to replace in-place
+             ;; Note: store-substring has length restrictions
              (progn
                (store-substring obj start new-text))
            ;; For buffers, delete and insert
@@ -1165,6 +1171,11 @@ OBJECT can be a buffer or string; nil defaults to current buffer.
 
 Returns the number of successful matches.
 
+Note: For string objects, the replacement text must have the same length
+as the original matched text, since strings have fixed length in Emacs.
+If the replacement is shorter, only that portion will be replaced.
+If the replacement is longer, it will be truncated.
+
 Example:
   ;; Upcase all matched text
   (tp-backward-do #\\='upcase \\='marker nil my-string 3)"
@@ -1179,6 +1190,7 @@ Example:
        (when (and new-text (not (equal new-text text)))
          (if (stringp obj)
              ;; For strings, we need to replace in-place
+             ;; Note: store-substring has length restrictions
              (progn
                (store-substring obj start new-text))
            ;; For buffers, delete and insert
@@ -1308,6 +1320,11 @@ of FUNCTION replaces the matched text in the string or buffer.
 
 Returns the number of matches processed.
 
+Note: For string objects, the replacement text must have the same length
+as the original matched text, since strings have fixed length in Emacs.
+If the replacement is shorter, only that portion will be replaced.
+If the replacement is longer, it will be truncated.
+
 Example:
   ;; Upcase all matched text
   (tp-search-map #\\='upcase my-string \\='marker)"