[elpa] externals/compat 9ab3081959 26/84: Add string-pixel-width from Emacs 29

[ELPA Syncer]

branch: externals/compat
commit 9ab3081959fd47d368e216c41c4f6d6875fd095b
Author: Philip Kaludercic <philipk@posteo.net>
Commit: Philip Kaludercic <philipk@posteo.net>

    Add string-pixel-width from Emacs 29
---
 compat-29.el | 12 ++++++++++++
 compat.texi  | 35 +++++++++++++++++++++++++++++++++++
 2 files changed, 47 insertions(+)

diff --git a/compat-29.el b/compat-29.el
index 757f9e76ee..4389289105 100644
--- a/compat-29.el
+++ b/compat-29.el
@@ -311,5 +311,17 @@ than this function."
      (end (substring string (- (length string) length)))
      (t (substring string 0 length)))))
 
+;;* UNTESTED
+(compat-defun string-pixel-width (string)
+  "Return the width of STRING in pixels."
+  (if (zerop (length string))
+      0
+    ;; Keeping a work buffer around is more efficient than creating a
+    ;; new temporary buffer.
+    (with-current-buffer (get-buffer-create " *string-pixel-width*")
+      (delete-region (point-min) (point-max))
+      (insert string)
+      (car (compat--buffer-text-pixel-size nil nil t)))))
+
 (provide 'compat-29)
 ;;; compat-29.el ends here
diff --git a/compat.texi b/compat.texi
index c1e61be279..f19c884df5 100644
--- a/compat.texi
+++ b/compat.texi
@@ -2446,6 +2446,41 @@ optional @code{buffer-list} argument.  Optional third 
argument
 @xref{Buffer List,,,elisp}.
 @end defun
 
+@c copied from lispref/display.texi
+@defun string-pixel-width string
+This is a convenience function that uses @code{window-text-pixel-size}
+to compute the width of @var{string} (in pixels).
+
+@xref{Size of Displayed Text,,,elisp}.
+@end defun
+
+@c copied from lispref/display.texi
+@defun string-glyph-split string
+When character compositions are in effect, sequence of characters can
+be composed for display to form @emph{grapheme clusters}, for example
+to display accented characters, or ligatures, or Emoji, or when
+complex text shaping requires that for some scripts.  When that
+happens, characters no longer map in a simple way to display columns,
+and display layout decisions with such strings, such as truncating too
+wide strings, can be a complex job.  This function helps in performing
+suvh jobs: it splits up its argument @var{string} into a list of
+substrings, where each substring produces a single grapheme cluster
+that should be displayed as a unit.  Lisp programs can then use this
+list to construct visually-valid substrings of @var{string} which will
+look correctly on display, or compute the width of any substring of
+@var{string} by adding the width of its constituents in the returned
+list, etc.
+
+For instance, if you want to display a string without the first glyph,
+you can say:
+
+@example
+(apply #'insert (cdr (string-glyph-split string))))
+@end example
+
+@xref{Size of Displayed Text,,,elisp}.
+@end defun
+
 
 
 @subsection Prefixed Definitions