13.4 Character Conversions

These functions perform various transformations on characters, including case conversions.

[Function] character object

The function character coerces its argument to be a character if possible; see coerce.

(character x)  (coerce x ’character)


[Function] char-upcase char
[Function] char-downcase char

The argument char must be a character object. char-upcase attempts to convert its argument to an uppercase equivalent; char-downcase attempts to convert its argument to a lowercase equivalent.


[Function] digit-char weight &optional (radix 10)

All arguments must be integers. digit-char determines whether or not it is possible to construct a character object whose code is such that the result character has the weight weight when considered as a digit of the radix radix (see the predicate digit-char-p). It returns such a character if that is possible, and otherwise returns nil.

digit-char cannot return nil radix is between 2 and 36 inclusive, and weight is non-negative and less than radix.

If more than one character object can encode such a weight in the given radix, one will be chosen consistently by any given implementation; moreover, among the standard characters, uppercase letters are preferred to lowercase letters. For example:

(digit-char 7)  #\7
(digit-char 12)  nil
(digit-char 12 16)  #\C     ;not #\c
(digit-char 6 2)  nil
(digit-char 1 2)  #\1


[Function] char-int char

The argument char must be a character object. char-int returns a non-negative integer encoding the character object.

char-int returns the same integer char-code. Also,

(char= c1 c2)  (= (char-int c1) (char-int c2))

for characters c1 and c2.

This function is provided primarily for the purpose of hashing characters.


[Function] char-name char

The argument char must be a character object. If the character has a name, then that name (a string) is returned; otherwise nil is returned. All characters that are non-graphic (do not satisfy the predicate graphic-char-p) have names. Graphic characters may or may not have names.

The standard newline and space characters have the respective names Newline and Space. The semi-standard characters have the names Tab, Page, Rubout, Linefeed, Return, and Backspace.

Characters that have names can be notated as #\ followed by the name. (See section 22.1.4.) Although the name may be written in any case, it is stylish to capitalize it thus: #\Space.


[Function] name-char name

The argument name must be an object coerceable to a string as if by the function string. If the name is the same as the name of a character object (as determined by string-equal), that object is returned; otherwise nil is returned.