Function: string-width

string-width is a function defined in character.c.

Signature

(string-width STRING &optional FROM TO)

Documentation

Return width of STRING in columns when displayed in the current buffer.

Width of STRING is measured by how many columns it will occupy on the screen.

Optional arguments FROM and TO specify the substring of STRING to consider, and are interpreted as in substring.

Width of each character in STRING is generally taken according to char-width, but character compositions and the display table in effect are taken into consideration. Tabs in STRING are always assumed to occupy tab-width columns, although they might take fewer columns depending on the column where they begin on display. The effect of faces and fonts, including fonts used for non-Latin and other unusual characters, such as emoji, is ignored, as are display properties and invisible text.

For these reasons, the results are just an approximation, especially on GUI frames; for accurate dimensions of text as it will be displayed, use string-pixel-width or window-text-pixel-size instead.

Other relevant functions are documented in the string group.

View in manual

Probably introduced at or before Emacs version 20.1.

Shortdoc

;; string
(string-width "foo")
    => 3
  (string-width "avocado: 🥑")
    => 11

Aliases

gnus-correct-length (obsolete since 27.1)

Source Code

// Defined in /usr/src/emacs/src/character.c
{
  Lisp_Object val;
  ptrdiff_t ifrom, ito;

  CHECK_STRING (str);
  validate_subarray (str, from, to, SCHARS (str), &ifrom, &ito);
  XSETFASTINT (val, lisp_string_width (str, ifrom, ito, -1, NULL, NULL, true));
  return val;
}