6.6 Char-Tables

A char-table is much like a vector, except that it is indexed by character codes. Any valid character code, without modifiers, can be used as an index in a char-table. You can access a char-table's elements with aref and aset, as with any array. In addition, a char-table can have extra slots to hold additional data not associated with particular character codes. Char-tables are constants when evaluated.

Each char-table has a subtype which is a symbol. The subtype has two purposes: to distinguish char-tables meant for different uses, and to control the number of extra slots. For example, display tables are char-tables with display-table as the subtype, and syntax tables are char-tables with syntax-table as the subtype. A valid subtype must have a char-table-extra-slots property which is an integer between 0 and 10. This integer specifies the number of extra slots in the char-table.

A char-table can have a parent, which is another char-table. If it does, then whenever the char-table specifies nil for a particular character c, it inherits the value specified in the parent. In other words, (aref char-table c) returns the value from the parent of char-table if char-table itself specifies nil.

A char-table can also have a default value. If so, then (aref char-table c) returns the default value whenever the char-table does not specify any other non-nil value.

Function: make-char-table subtype &optional init

Return a newly created char-table, with subtype subtype. Each element is initialized to init, which defaults to nil. You cannot alter the subtype of a char-table after the char-table is created.

There is no argument to specify the length of the char-table, because all char-tables have room for any valid character code as an index.

Function: char-table-p object

This function returns t if object is a char-table, otherwise nil.

Function: char-table-subtype char-table

This function returns the subtype symbol of char-table.

Function: set-char-table-default char-table new-default

This function sets the default value of char-table to new-default.

There is no special function to access the default value of a char-table. To do that, use (char-table-range char-table nil).

Function: char-table-parent char-table

This function returns the parent of char-table. The parent is always either nil or another char-table.

Function: set-char-table-parent char-table new-parent

This function sets the parent of char-table to new-parent.

Function: char-table-extra-slot char-table n

This function returns the contents of extra slot n of char-table. The number of extra slots in a char-table is determined by its subtype.

Function: set-char-table-extra-slot char-table n value

This function stores value in extra slot n of char-table.

A char-table can specify an element value for a single character code; it can also specify a value for an entire character set.

Function: char-table-range char-table range

This returns the value specified in char-table for a range of characters range. Here are the possibilities for range:

nil

Refers to the default value.

char

Refers to the element for character char (supposing char is a valid character code).

charset

Refers to the value specified for the whole character set charset (see section 33.5 Character Sets).

generic-char

A generic character stands for a character set; specifying the generic character as argument is equivalent to specifying the character set name. See section 33.7 Splitting Characters, for a description of generic characters.

Function: set-char-table-range char-table range value

This function sets the value in char-table for a range of characters range. Here are the possibilities for range:

nil

Refers to the default value.

t

Refers to the whole range of character codes.

char

Refers to the element for character char (supposing char is a valid character code).

charset

Refers to the value specified for the whole character set charset (see section 33.5 Character Sets).

generic-char

A generic character stands for a character set; specifying the generic character as argument is equivalent to specifying the character set name. See section 33.7 Splitting Characters, for a description of generic characters.

Function: map-char-table function char-table

This function calls function for each element of char-table. function is called with two arguments, a key and a value. The key is a possible range argument for char-table-range---either a valid character or a generic character--and the value is (char-table-range char-table key).

Overall, the key-value pairs passed to function describe all the values stored in char-table.

The return value is always nil; to make this function useful, function should have side effects. For example, here is how to examine each element of the syntax table:

(let (accumulator) (map-char-table #'(lambda (key value) (setq accumulator (cons (list key value) accumulator))) (syntax-table)) accumulator) => ((475008 nil) (474880 nil) (474752 nil) (474624 nil) ... (5 (3)) (4 (3)) (3 (3)) (2 (3)) (1 (3)) (0 (3)))