]> code.delx.au - gnu-emacs/commitdiff
Warning comments about subtleties of fetching characters from buffers/strings.
authorEli Zaretskii <eliz@gnu.org>
Fri, 6 Apr 2012 13:10:30 +0000 (16:10 +0300)
committerEli Zaretskii <eliz@gnu.org>
Fri, 6 Apr 2012 13:10:30 +0000 (16:10 +0300)
 src/buffer.h (FETCH_CHAR, FETCH_MULTIBYTE_CHAR):
 src/character.h (STRING_CHAR, STRING_CHAR_AND_LENGTH): Add comments
 about subtle differences between FETCH_CHAR* and STRING_CHAR*
 macros related to unification of CJK characters.  For the details,
 see the discussion following the message here:
 http://debbugs.gnu.org/cgi/bugreport.cgi?bug=11073#14.

src/ChangeLog
src/buffer.h
src/character.h

index ea770969818acbd31c419902d0a5cc7ca7cf7d70..af65d38a33b31c42fcab4deb1e53d825084c88e3 100644 (file)
@@ -1,3 +1,12 @@
+2012-04-06  Eli Zaretskii  <eliz@gnu.org>
+
+       * buffer.h (FETCH_CHAR, FETCH_MULTIBYTE_CHAR):
+       * character.h (STRING_CHAR, STRING_CHAR_AND_LENGTH): Add comments
+       about subtle differences between FETCH_CHAR* and STRING_CHAR*
+       macros related to unification of CJK characters.  For the details,
+       see the discussion following the message here:
+       http://debbugs.gnu.org/cgi/bugreport.cgi?bug=11073#14.
+
 2012-04-04  Chong Yidong  <cyd@gnu.org>
 
        * keyboard.c (Vdelayed_warnings_list): Doc fix.
index 3df4a95cf93f9ae14bd34e4c69164eaf313fa259..1635a847839b7c3d3e4254f2c59da7c53d41d449 100644 (file)
@@ -343,7 +343,8 @@ while (0)
  - (ptr - (current_buffer)->text->beg <= GPT_BYTE - BEG_BYTE ? 0 : GAP_SIZE) \
  + BEG_BYTE)
 
-/* Return character at byte position POS.  */
+/* Return character at byte position POS.  See the caveat WARNING for
+   FETCH_MULTIBYTE_CHAR below.  */
 
 #define FETCH_CHAR(pos)                                        \
   (!NILP (BVAR (current_buffer, enable_multibyte_characters))  \
@@ -359,7 +360,17 @@ extern unsigned char *_fetch_multibyte_char_p;
 
 /* Return character code of multi-byte form at byte position POS.  If POS
    doesn't point the head of valid multi-byte form, only the byte at
-   POS is returned.  No range checking.  */
+   POS is returned.  No range checking.
+
+   WARNING: The character returned by this macro could be "unified"
+   inside STRING_CHAR, if the original character in the buffer belongs
+   to one of the Private Use Areas (PUAs) of codepoints that Emacs
+   uses to support non-unified CJK characters.  If that happens,
+   CHAR_BYTES will return a value that is different from the length of
+   the original multibyte sequence stored in the buffer.  Therefore,
+   do _not_ use FETCH_MULTIBYTE_CHAR if you need to advance through
+   the buffer to the next character after fetching this one.  Instead,
+   use either FETCH_CHAR_ADVANCE or STRING_CHAR_AND_LENGTH.  */
 
 #define FETCH_MULTIBYTE_CHAR(pos)                                      \
   (_fetch_multibyte_char_p = (((pos) >= GPT_BYTE ? GAP_SIZE : 0)       \
index 5ae6cb8c49ca2a4e20350c2124a427be7db24de3..a829def428dcb0514f9a5057d2c535fc0fc2b154 100644 (file)
@@ -292,7 +292,9 @@ along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.  */
   } while (0)
 
 /* Return the character code of character whose multibyte form is at
-   P.  */
+   P.  Note that this macro unifies CJK characters whose codepoints
+   are in the Private Use Areas (PUAs), so it might return a different
+   codepoint from the one actually stored at P.  */
 
 #define STRING_CHAR(p)                                         \
   (!((p)[0] & 0x80)                                            \
@@ -309,7 +311,15 @@ along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.  */
 
 
 /* Like STRING_CHAR, but set ACTUAL_LEN to the length of multibyte
-   form.  */
+   form.
+
+   Note: This macro returns the actual length of the character's
+   multibyte sequence as it is stored in a buffer or string.  The
+   character it returns might have a different codepoint that has a
+   different multibyte sequence of a different legth, due to possible
+   unification of CJK characters inside string_char.  Therefore do NOT
+   assume that the length returned by this macro is identical to the
+   length of the multibyte sequence of the character it returns.  */
 
 #define STRING_CHAR_AND_LENGTH(p, actual_len)                  \
   (!((p)[0] & 0x80)                                            \