Common Lisp the Language, 2nd Edition

Next: Character Control-Bit Functions Up: Characters Previous: Character Construction and

# 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
``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.

`char-upcase` returns a character object with the same font and bits attributes as char, but with possibly a different code attribute. If the code is different from char's, then the predicate `lower-case-p` is true of char, and `upper-case-p` is true of the result character. Moreover, if `(char= (char-upcase x) x)` is not true, then it is true that

    (char= (char-downcase (char-upcase x)) x)

Similarly, `char-downcase` returns a character object with the same font and bits attributes as char, but with possibly a different code attribute. If the code is different from char's, then the predicate `upper-case-p` is true of char, and `lower-case-p` is true of the result character. Moreover, if `(char= (char-downcase x) x)` is not true, then it is true that

    (char= (char-upcase (char-downcase x)) x)

Note that the action of `char-upcase` and `char-downcase` may depend on the bits and font attributes of the character. In particular, they have no effect on a character with a non-zero bits attribute, because such characters are by definition not alphabetic. See `alpha-char-p`.

X3J13 voted in March 1989 (CHARACTER-PROPOSAL) to replace the notion of bits and font attributes with that of implementation-defined attributes. The effect of `char-upcase` and `char-downcase` is to preserve implementation-defined attributes.

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

All arguments must be integers. `digit-char` determines whether or not it is possible to construct a character object whose font attribute is font, and 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` if font is zero, 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

Note that no argument is provided for specifying the bits component of the returned character, because a digit cannot have a non-zero bits component. The reasoning is that every digit is graphic (see `digit-char-p`) and no graphic character has a non-zero bits component (see `graphic-char-p`).

X3J13 voted in March 1989 (CHARACTER-PROPOSAL) to eliminate the font argument from the specification of `digit-char`.

[Function]
`char-int char`

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

If the font and bits attributes of char are zero, then `char-int` returns the same integer `char-code` would. 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]
`int-char integer`

The argument must be a non-negative integer. `int-char` returns a character object `c` such that `(char-int c)` is equal to integer, if possible; otherwise `int-char` returns false.

X3J13 voted in March 1989 (CHARACTER-PROPOSAL) to eliminate `int-char`.

[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 have zero font and bits attributes and 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`.

`char-name` will only locate ``simple'' character names; it will not construct names such as `Control-Space` on the basis of the character's bits attribute.

The easiest way to get a name that includes the bits attribute of a character `c` is `(format nil "~:C" c)`.

[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.

Next: Character Control-Bit Functions Up: Characters Previous: Character Construction and