Function: string-limit

string-limit is a byte-compiled function defined in subr-x.el.gz.

Signature

(string-limit STRING LENGTH &optional END CODING-SYSTEM)

Documentation

Return a substring of STRING that is (up to) LENGTH characters long.

If STRING is shorter than or equal to LENGTH characters, return the entire string unchanged.

If STRING is longer than LENGTH characters, return a substring consisting of the first LENGTH characters of STRING. If END is non-nil, return the last LENGTH characters instead.

If CODING-SYSTEM is non-nil, STRING will be encoded before limiting, and LENGTH is interpreted as the number of bytes to limit the string to. The result will be a unibyte string that is shorter than LENGTH, but will not contain "partial" characters, even if CODING-SYSTEM encodes characters with several bytes per character.

When shortening strings for display purposes, truncate-string-to-width is almost always a better alternative than this function.

Other relevant functions are documented in the string group.

Probably introduced at or before Emacs version 28.1.

Shortdoc

;; string
(string-limit "foobar" 3)
    => "foo"
  (string-limit "foobar" 3 t)
    => "bar"
  (string-limit "foobar" 10)
    => "foobar"
  (string-limit "fo好" 3 nil 'utf-8)
    => "fo"

Source Code

;; Defined in /usr/src/emacs/lisp/emacs-lisp/subr-x.el.gz
(defun string-limit (string length &optional end coding-system)
  "Return a substring of STRING that is (up to) LENGTH characters long.
If STRING is shorter than or equal to LENGTH characters, return the
entire string unchanged.

If STRING is longer than LENGTH characters, return a substring
consisting of the first LENGTH characters of STRING.  If END is
non-nil, return the last LENGTH characters instead.

If CODING-SYSTEM is non-nil, STRING will be encoded before
limiting, and LENGTH is interpreted as the number of bytes to
limit the string to.  The result will be a unibyte string that is
shorter than LENGTH, but will not contain \"partial\" characters,
even if CODING-SYSTEM encodes characters with several bytes per
character.

When shortening strings for display purposes,
`truncate-string-to-width' is almost always a better alternative
than this function."
  (unless (natnump length)
    (signal 'wrong-type-argument (list 'natnump length)))
  (if coding-system
      (let ((result nil)
            (result-length 0)
            (index (if end (1- (length string)) 0)))
        ;; FIXME: This implementation, which uses encode-coding-char
        ;; to encode the string one character at a time, is in general
        ;; incorrect: coding-systems that produce prefix or suffix
        ;; bytes, such as ISO-2022-based or UTF-8/16 with BOM, will
        ;; produce those bytes for each character, instead of just
        ;; once for the entire string.  encode-coding-char attempts to
        ;; remove those extra bytes at least in some situations, but
        ;; it cannot do that in all cases.  And in any case, producing
        ;; what is supposed to be a UTF-16 or ISO-2022-CN encoded
        ;; string which lacks the BOM bytes at the beginning and the
        ;; charset designation sequences at the head and tail of the
        ;; result will definitely surprise the callers in some cases.
        (while (let ((encoded (encode-coding-char
                               (aref string index) coding-system)))
                 (and (<= (+ (length encoded) result-length) length)
                      (progn
                        (push encoded result)
                        (cl-incf result-length (length encoded))
                        (setq index (if end (1- index)
                                      (1+ index))))
                      (if end (> index -1)
                        (< index (length string)))))
          ;; No body.
          )
        (apply #'concat (if end result (nreverse result))))
    (cond
     ((<= (length string) length) string)
     (end (substring string (- (length string) length)))
     (t (substring string 0 length)))))