Allow `string-limit' to work on encoded strings

* doc/lispref/strings.texi (Creating Strings): Document it.

* lisp/emacs-lisp/subr-x.el (string-limit): Allow limiting on
encoded strings.

1 files changed, 8 insertions, 1 deletions

diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 19b91471ed3..1e5f52ddfdd 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -394,12 +394,19 @@ there are individual words that are longer than @var{length}, these
 will not be shortened.
 @end defun
 
-@defun string-limit string length &optional end
+@defun string-limit string length &optional end coding-system
 If @var{string} is shorter than @var{length}, @var{string} is returned
 as is.  Otherwise, return a substring of @var{string} consisting of
 the first @var{length} characters.  If the optional @var{end}
 parameter is given, return a string of the @var{length} last
 characters instead.
+
+If @var{coding-system} is non-@code{nil}, @var{string} will be encoded
+before limiting, and the result will be a unibyte string that's
+shorter than @code{length}.  If @var{string} contains characters that
+are encoded into several bytes (for instance, when using
+@code{utf-8}), the resulting unibyte string is never truncated in the
+middle of a character representation.
 @end defun
 
 @defun string-lines string &optional omit-nulls