10.7 Conversion of Characters and Strings

This section describes functions for conversions between characters, strings and integers. format and prin1-to-string (see Output Functions) can also convert Lisp objects into strings. read-from-string (see Input Functions) can “convert” a string representation of a Lisp object into an object.

See Documentation, for functions that produce textual descriptions of text characters and general input events (single-key-description and text-char-description). These functions are used primarily for making help messages.

Function: char-to-string character

This function returns a new string with a length of one character. The value of character, modulo 256, is used to initialize the element of the string.

This function is similar to make-string with an integer argument of 1. (See Creating Strings.) This conversion can also be done with format using the ‘%c’ format specification. (See Formatting Strings.)

(char-to-string ?x)
     ⇒ "x"
(char-to-string (+ 256 ?x))
     ⇒ "x"
(make-string 1 ?x)
     ⇒ "x"

Function: string-to-char string

This function returns the first character in string. If the string is empty, the function returns 0. (Under XEmacs 19, the value is also 0 when the first character of string is the null character, ASCII code 0.)

(string-to-char "ABC")
     ⇒ ?A   ;; Under SXemacs.
     ⇒ 65   ;; Under XEmacs 19.
(string-to-char "xyz")
     ⇒ ?x   ;; Under SXEmacs.
     ⇒ 120  ;; Under XEmacs 19.
(string-to-char "")
     ⇒ nil  ;; Under SXEmacs.
     ⇒ 0    ;; Under XEmacs 20.
(string-to-char "\000")
     ⇒ ?\^ ;; Under SXEmacs.
     ⇒ 0    ;; Under XEmacs 20.

This function may be eliminated in the future if it does not seem useful enough to retain.

Function: number-to-string number

This function returns a string consisting of the printed representation of number, which may be an integer or a floating point number. The value starts with a sign if the argument is negative.

(number-to-string 256)
     ⇒ "256"
(number-to-string -23)
     ⇒ "-23"
(number-to-string -23.5)
     ⇒ "-23.5"

int-to-string is a semi-obsolete alias for this function.

See also the function format in Formatting Strings.

Function: string-to-number string &optional base

This function returns the numeric value represented by string, read in base. It skips spaces and tabs at the beginning of string, then reads as much of string as it can interpret as a number. (On some systems it ignores other whitespace at the beginning, not just spaces and tabs.) If the first character after the ignored whitespace is not a digit or a minus sign, this function returns 0.

If base is not specified, it defaults to ten. With base other than ten, only integers can be read.

(string-to-number "256")
     ⇒ 256
(string-to-number "25 is a perfect square.")
     ⇒ 25
(string-to-number "X256")
     ⇒ 0
(string-to-number "-4.5")
     ⇒ -4.5
(string-to-number "ffff" 16)
     ⇒ 65535

string-to-int is an obsolete alias for this function.