Document that {en,de}code-coding-string preserve match data

* lisp/international/mule.el (define-coding-system):
Require :pre-write-conversion and :post-read-conversion functions
to leave the match data untouched.
* src/coding.c (Fdecode_coding_string, Fencode_coding_string):
Document functions as match-data-preserving.

Suggested by Stefan Monnier (see bug#41445).

diff --git a/lisp/international/mule.el b/lisp/international/mule.el
index 72e8cad9d62f586968db0e57f980b3090ca08756..df71205d515affa6528a88219ffef662b7ebc518 100644 (file)
--- a/lisp/international/mule.el
+++ b/lisp/international/mule.el
@@ -769,11 +769,12 @@ decoded by the coding system itself and before any functions in
 `after-insert-functions' are called.  This function is passed one
 argument: the number of characters in the text to convert, with
 point at the start of the text.  The function should leave point
-unchanged, and should return the new character count.  Note that
-this function should avoid reading from files or receiving text
-from subprocesses -- anything that could invoke decoding; if it
-must do so, it should bind `coding-system-for-read' to a value
-other than the current coding-system, to avoid infinite recursion.
+and the match data unchanged, and should return the new character
+count.  Note that this function should avoid reading from files
+or receiving text from subprocesses -- anything that could invoke
+decoding; if it must do so, it should bind
+`coding-system-for-read' to a value other than the current
+coding-system, to avoid infinite recursion.
 
 `:pre-write-conversion'
 
@@ -781,13 +782,13 @@ VALUE must be a function to call after all functions in
 `write-region-annotate-functions' and `buffer-file-format' are
 called, and before the text is encoded by the coding system
 itself.  This function should convert the whole text in the
-current buffer.  For backward compatibility, this function is
-passed two arguments which can be ignored.  Note that this
-function should avoid writing to files or sending text to
-subprocesses -- anything that could invoke encoding; if it
-must do so, it should bind `coding-system-for-write' to a
-value other than the current coding-system, to avoid infinite
-recursion.
+current buffer, and leave the match data unchanged.  For backward
+compatibility, this function is passed two arguments which can be
+ignored.  Note that this function should avoid writing to files
+or sending text to subprocesses -- anything that could invoke
+encoding; if it must do so, it should bind
+`coding-system-for-write' to a value other than the current
+coding-system, to avoid infinite recursion.
 
 `:default-char'
 

diff --git a/src/coding.c b/src/coding.c
index 34f36d5a86a69dbfb89926d1ca2d1693dd377215..071124b4ef163ed3f526d7842dd9e5e54f853628 100644 (file)
--- a/src/coding.c
+++ b/src/coding.c
@@ -10395,7 +10395,7 @@ representation of the decoded text.
 
 This function sets `last-coding-system-used' to the precise coding system
 used (which may be different from CODING-SYSTEM if CODING-SYSTEM is
-not fully specified.)  */)
+not fully specified.)  The function does not change the match data.  */)
   (Lisp_Object string, Lisp_Object coding_system, Lisp_Object nocopy, Lisp_Object buffer)
 {
   return code_convert_string (string, coding_system, buffer,
@@ -10415,7 +10415,7 @@ case, the return value is the length of the encoded text.
 
 This function sets `last-coding-system-used' to the precise coding system
 used (which may be different from CODING-SYSTEM if CODING-SYSTEM is
-not fully specified.)  */)
+not fully specified.)  The function does not change the match data.  */)
   (Lisp_Object string, Lisp_Object coding_system, Lisp_Object nocopy, Lisp_Object buffer)
 {
   return code_convert_string (string, coding_system, buffer,