elisp: Char-Tables
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. Like vectors, char-tables are
constants when evaluated, and can hold elements of any type.
Each char-table has a “subtype”, a symbol, which serves two purposes:
• The subtype provides an easy way to tell what the char-table is
for. For instance, display tables are char-tables with
‘display-table’ as the subtype, and syntax tables are char-tables
with ‘syntax-table’ as the subtype. The subtype can be queried
using the function ‘char-table-subtype’, described below.
• The subtype controls the number of “extra slots” in the char-table.
This number is specified by the subtype’s ‘char-table-extra-slots’
symbol property (
Symbol Properties), whose value should be
an integer between 0 and 10. If the subtype has no such symbol
property, the char-table has no extra slots.
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 (a symbol).
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.
If SUBTYPE has the ‘char-table-extra-slots’ symbol property, that
specifies the number of extra slots in the char-table. This should
be an integer between 0 and 10; otherwise, ‘make-char-table’ raises
an error. If SUBTYPE has no ‘char-table-extra-slots’ symbol
property (Property Lists), the char-table has no extra
slots.
-- Function: char-table-p object
This function returns ‘t’ if OBJECT is a char-table, and ‘nil’
otherwise.
-- Function: char-table-subtype char-table
This function returns the subtype symbol of CHAR-TABLE.
There is no special function to access default values in a
char-table. To do that, use ‘char-table-range’ (see below).
-- 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 (zero based) 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 (zero based) 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).
‘(FROM . TO)’
A cons cell refers to all the characters in the inclusive
range ‘[FROM..TO]’.
-- 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).
‘(FROM . TO)’
A cons cell refers to all the characters in the inclusive
range ‘[FROM..TO]’.
-- Function: map-char-table function char-table
This function calls its argument FUNCTION for each element of
CHAR-TABLE that has a non-‘nil’ value. The call to FUNCTION is
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 cons
cell ‘(FROM . TO)’, specifying a range of characters that share the
same value. The value is what ‘(char-table-range CHAR-TABLE KEY)’
returns.
Overall, the key-value pairs passed to FUNCTION describe all the
values stored in CHAR-TABLE.
The return value is always ‘nil’; to make calls to ‘map-char-table’
useful, FUNCTION should have side effects. For example, here is
how to examine the elements of the syntax table:
(let (accumulator)
(map-char-table
#'(lambda (key value)
(setq accumulator
(cons (list
(if (consp key)
(list (car key) (cdr key))
key)
value)
accumulator)))
(syntax-table))
accumulator)
⇒
(((2597602 4194303) (2)) ((2597523 2597601) (3))
... (65379 (5 . 65378)) (65378 (4 . 65379)) (65377 (1))
... (12 (0)) (11 (3)) (10 (12)) (9 (0)) ((0 8) (3)))
Info Catalog
elisp: Vector Functions
elisp: Sequences Arrays Vectors
elisp: Bool-Vectors