.EL File Format – Strings and characters

Characters

The syntax ?C reads as the code point of C. A character code is at most #x3FFFFF (max-char); codes up to #x10FFFF are Unicode, the rest are raw bytes and other Emacs-specific characters. The bits above 21 are modifier bits (meta, control, shift, hyper, super, alt) and are used by key events, not by text.

Since Emacs 30 a \x that is not followed by hex digits is an error. Predicates and tools: characterp, char-or-string-p, char-uppercase-p, upcase and downcase (which also accept a character), char-width, get-char-code-property, char-to-string, string-to-char, char-from-name and char-to-name (Emacs 30), max-char, unibyte-char-to-multibyte, multibyte-char-to-unibyte.

String syntax

A string is written between double quotes. Newlines are allowed inside. The escapes are those of characters, with these additions and differences:

"tab:\t newline:\n"
"A long line that \
continues here"
"caf\u00e9 \N{GREEK SMALL LETTER LAMDA} \x41\ B"

Multibyte and unibyte

A multibyte string holds characters, stored internally as an extension of UTF-8. A unibyte string holds bytes 0 to 255. The reader makes a string multibyte if it contains a non-ASCII character or a \u, \U or \N escape, and unibyte otherwise (octal and hex escapes in the range 128 to 255 give raw bytes). Functions: multibyte-string-p, string-to-multibyte, string-to-unibyte, string-as-unibyte, string-bytes, string-make-multibyte, string-make-unibyte. From Emacs 31, aset on a unibyte string needs a byte value, and on a multibyte string both the old and the new character must be ASCII, so that a string never changes between unibyte and multibyte or in byte length.

String functions

string-lines handles a trailing newline differently from Emacs 29 on, as the NEWS for that version states.

format and format-message

(format STRING &rest OBJECTS) returns STRING with each % directive replaced. A directive is %[FIELD$][FLAGS][WIDTH][.PRECISION]CHAR. format-message does the same and additionally converts the quotes `like this' in the format string according to text-quoting-style.

(format "%-6s|%5d|%05.1f|%x" "ab" 42 3.14159 255)  ; => "ab    |   42|003.1|ff"
(format "%2$s %1$s" "world" "hello")                ; => "hello world"
(format "%S" "q")                                    ; => "\"q\""

The binary-as-unsigned variable, an experiment that changed how negative numbers print in %x, was removed in Emacs 31. format-spec (library format-spec) is a separate function that replaces %X keys from an alist and supports the same flags; its SPLIT argument was added in Emacs 28.

Text properties on strings

A string can carry properties for ranges of characters. The printed and read form is #("hello world" 0 5 (face bold)): the text, then triples of start, end and a property list.

The standard properties and the buffer side are on Buffers and text.

Documentation strings

A documentation string is the optional string after the arguments of a defun or after the value of a defvar. Conventions in the manual: the first line is a complete sentence that summarises the object, because apropos shows only that line; arguments are named in capitals; the string uses the quoting `like this' or the curved quotes directly, and the help system converts them.

substitute-command-keys does the conversion. In source code the backslash in the markup must be doubled ("\\[forward-char]"). The variable text-quoting-style is curve, straight or grave; nil picks the best that the display supports. Emacs 29 added a byte-compiler warning for some quoting mistakes in docstrings, and since Emacs 30 a string returned by a function or macro is never taken as a docstring.

Coding systems

encode-coding-string turns a string into a unibyte string in a coding system (utf-8, iso-8859-1, utf-16le, …) and decode-coding-string does the reverse. Related: coding-system-p, detect-coding-string, check-coding-system, encode-coding-region, decode-coding-region, find-coding-systems-string. The line-ending variants are the suffixes -unix, -dos and -mac. The coding system of a source file is set by the coding: cookie (File structure).

Not described

Known, not yet covered

• Reference: printing and reading of objects (prin1, princ, print-escape-newlines, read-from-string) and the full set of print- variables.
• Reference: character sets, charsets, input methods, character properties from the Unicode database and the bidirectional text functions.
• Reference: the complete list of coding systems and the rules of auto-coding-alist.
• Reference: the extended format rules for non-ASCII text in widths, and for %c with raw bytes.

See also

• Lexical structure – how the reader recognises character and string literals
• Regexps and syntax tables – string-match and replace-regexp-in-string
• Buffers and text – text properties in buffers
• File structure – encodings and the coding cookie
• Strings and Characters – the manual’s chapter
• Tips for Documentation Strings – the manual’s conventions