Warn against using `length' to compute display width of a string.

 doc/lispref/strings.texi (String Basics):
 doc/lispref/sequences.texi (Sequence Functions): Mention that `length' is
 not appropriate for computing the string width on display; add a
 cross-reference to the description of `string-width'.  (Bug#10978)

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 06d5c5418755177fbce5bcab04e8c94e03e66ae7..201128b97571bafa7db350fb6c74bd5bfd5de734 100644 (file)
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,5 +1,10 @@
 2012-03-10  Eli Zaretskii  <eliz@gnu.org>
 
+       * strings.texi (String Basics):
+       * sequences.texi (Sequence Functions): Mention that `length' is
+       not appropriate for computing the string width on display; add a
+       cross-reference to the description of `string-width'.  (Bug#10978)
+
        * eval.texi (Autoloading): Minor change of wording.
 
 2012-03-10  Chong Yidong  <cyd@gnu.org>

diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi
index 94f1bf666d21a1258d594cf9fdde30b0bb238d18..50f75da2de85444a07e637bd9a484db623c61a67 100644 (file)
--- a/doc/lispref/sequences.texi
+++ b/doc/lispref/sequences.texi
@@ -108,6 +108,11 @@ Emacs character code.
 @noindent
 See also @code{string-bytes}, in @ref{Text Representations}.
 
+If you need to compute the width of a string on display, you should
+use @code{string-width} (@pxref{Width}), not @code{length}, since
+@code{length} only counts the number of characters, but does not
+account for the display width of each character.
+
 @defun elt sequence index
 @cindex elements of sequences
 This function returns the element of @var{sequence} indexed by

diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index bbb75f1474d0fc238cd2a0b2978763c6e830b47b..64d0986493ac3b8aedebac09310f569068a2e86f 100644 (file)
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -51,7 +51,9 @@ C are terminated by a character with @acronym{ASCII} code 0.)
 operate on them with the general array and sequence functions.
 (@xref{Sequences Arrays Vectors}.)  For example, you can access or
 change individual characters in a string using the functions @code{aref}
-and @code{aset} (@pxref{Array Functions}).
+and @code{aset} (@pxref{Array Functions}).  However, note that
+@code{length} should @emph{not} be used for computing the width of a
+string on display; use @code{string-width} (@pxref{Width}) instead.
 
   There are two text representations for non-@acronym{ASCII} characters in
 Emacs strings (and in buffers): unibyte and multibyte (@pxref{Text