Common Lisp the Language, 2nd Edition


next up previous contents index
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.

old_change_begin
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)

old_change_end

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.

change_begin
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.
change_end


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

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


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

old_change_begin

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

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


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

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


[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 up previous contents index
Next: Character Control-Bit Functions Up: Characters Previous: Character Construction and


AI.Repository@cs.cmu.edu