diff lispref/sequences.texi @ 22138:d4ac295a98b3

*** empty log message ***

--- a/lispref/sequences.texi	Tue May 19 03:41:25 1998 +0000
+++ b/lispref/sequences.texi	Tue May 19 03:45:57 1998 +0000
@@ -82,7 +82,7 @@
 @sc{cdr} is not @code{nil}), a @code{wrong-type-argument} error is
 signaled.
 
-@xref{List Elements}, for the related function @code{safe-list}.
+@xref{List Elements}, for the related function @code{safe-length}.
 
 @example
 @group
@@ -132,11 +132,11 @@
 @end group
 @group
 (elt [1 2 3 4] 4)
-     @error{}Args out of range: [1 2 3 4], 4
+     @error{} Args out of range: [1 2 3 4], 4
 @end group
 @group
 (elt [1 2 3 4] -1)
-     @error{}Args out of range: [1 2 3 4], -1
+     @error{} Args out of range: [1 2 3 4], -1
 @end group
 @end example
 
@@ -218,12 +218,12 @@
 requires access time that is proportional to the position of the element
 in the list.
 
-  Emacs defines four types of array, both of which are one-dimensional:
-@dfn{strings}, @dfn{vectors}, @dfn{bool-vectors} and @dfn{char-tables}.
-A vector is a general array; its elements can be any Lisp objects.  A
-string is a specialized array; its elements must be characters (i.e.,
-integers between 0 and 255).  Each type of array has its own read
-syntax.  @xref{String Type}, and @ref{Vector Type}.
+  Emacs defines four types of array, all one-dimensional: @dfn{strings},
+@dfn{vectors}, @dfn{bool-vectors} and @dfn{char-tables}.  A vector is a
+general array; its elements can be any Lisp objects.  A string is a
+specialized array; its elements must be characters (i.e., integers
+between 0 and 255).  Each type of array has its own read syntax.
+@xref{String Type}, and @ref{Vector Type}.
 
   All four kinds of array share these characteristics:
 
@@ -347,8 +347,8 @@
 @code{wrong-type-argument} error results.  If @var{array} is a string
 and @var{object} is character, but @var{object} does not use the same
 number of bytes as the character currently stored in @code{(aref
-@var{object} @var{index})}, that is also an error.  @xref{Chars and
-Bytes}.
+@var{object} @var{index})}, that is also an error.  @xref{Splitting
+Characters}.
 @end defun
 
 @defun fillarray array object
@@ -520,19 +520,25 @@
 @node Char-Tables
 @section Char-Tables
 @cindex char-tables
+@cindex extra slots of char-table
 
   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 @code{aref} and @code{aset}, as with any array.
-Char-tables are constants when evaluated.
+elements with @code{aref} and @code{aset}, as with any array.  In
+addition, a char-table can have @dfn{extra slots} to hold additional
+data not associated with particular character codes.  Char-tables are
+constants when evaluated.
 
-@cindex extra slots of char-table
 @cindex subtype of char-table
-  Each char-table has a @dfn{subtype} which is a symbol.  In order to be
-a valid subtype, a symbol must have a @code{char-table-extra-slots}
-property which is an integer between 0 and 10.  This integer specifies
-the number of @dfn{extra slots} in the char-table.
+  Each char-table has a @dfn{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 @code{display-table} as the subtype, and syntax
+tables are char-tables with @code{syntax-table} as the subtype.  A valid
+subtype must have a @code{char-table-extra-slots} property which is an
+integer between 0 and 10.  This integer specifies the number of
+@dfn{extra slots} in the char-table.
 
 @cindex parent of char-table
   A char-table can have a @dfn{parent}. which is another char-table.  If
@@ -547,8 +553,8 @@
 @code{(aref @var{char-table} @var{c})} returns the default value
 whenever the char-table does not specify any other non-@code{nil} value.
 
+@defun make-char-table subtype &optional init
 @tindex make-char-table
-@defun make-char-table subtype &optional init
 Return a newly created char-table, with subtype @var{subtype}.  Each
 element is initialized to @var{init}, which defaults to @code{nil}.  You
 cannot alter the subtype of a char-table after the char-table is
@@ -558,19 +564,19 @@
 all char-tables have room for any valid character code as an index.
 @end defun
 
+@defun char-table-p object
 @tindex char-table-p
-@defun char-table-p object
 This function returns @code{t} if @var{object} is a char-table,
 otherwise @code{nil}.
 @end defun
 
+@defun char-table-subtype char-table
 @tindex char-table-subtype
-@defun char-table-subtype char-table
 This function returns the subtype symbol of @var{char-table}.
 @end defun
 
+@defun set-char-table-default char-table new-default
 @tindex set-char-table-default
-@defun set-char-table-default char-table new-default
 This function sets the default value of @var{char-table} to
 @var{new-default}.
 
@@ -578,26 +584,26 @@
 To do that, use @code{(char-table-range @var{char-table} nil)}.
 @end defun
 
+@defun char-table-parent char-table
 @tindex char-table-parent
-@defun char-table-parent char-table
 This function returns the parent of @var{char-table}.  The parent is
 always either @code{nil} or another char-table.
 @end defun
 
+@defun set-char-table-parent char-table new-parent
 @tindex set-char-table-parent
-@defun set-char-table-parent char-table new-parent
 This function sets the parent of @var{char-table} to @var{new-parent}.
 @end defun
 
+@defun char-table-extra-slot char-table n
 @tindex char-table-extra-slot
-@defun char-table-extra-slot char-table n
 This function returns the contents of extra slot @var{n} of
 @var{char-table}.  The number of extra slots in a char-table is
 determined by its subtype.
 @end defun
 
+@defun set-char-table-extra-slot char-table n value
 @tindex set-char-table-extra-slot
-@defun set-char-table-extra-slot char-table n value
 This function stores @var{value} in extra slot @var{n} of
 @var{char-table}.
 @end defun
@@ -605,28 +611,34 @@
   A char-table can specify an element value for a single character code;
 it can also specify a value for an entire character set.
 
+@defun char-table-range char-table range
 @tindex char-table-range
-@defun char-table-range char-table range
 This returns the value specified in @var{char-table} for a range of
-characters @var{range}.  Here @var{range} may be
+characters @var{range}.  Here are the possibilities for @var{range}:
 
 @table @asis
 @item @code{nil}
 Refers to the default value.
 
 @item @var{char}
-Refers to the element for character @var{char}.
+Refers to the element for character @var{char}
+(supposing @var{char} is a valid character code).
 
 @item @var{charset}
 Refers to the value specified for the whole character set
 @var{charset} (@pxref{Character Sets}).
+
+@item @var{generic-char}
+A generic character stands for a character set; specifying the generic
+character as argument is equivalent to specifying the character set
+name.  @xref{Splitting Characters}, for a description of generic characters.
 @end table
 @end defun
 
+@defun set-char-table-range char-table range value
 @tindex set-char-table-range
-@defun set-char-table-range char-table range value
 This function set the value in @var{char-table} for a range of
-characters @var{range}.  Here @var{range} may be
+characters @var{range}.  Here are the possibilities for @var{range}:
 
 @table @asis
 @item @code{nil}
@@ -636,24 +648,45 @@
 Refers to the whole range of character codes.
 
 @item @var{char}
-Refers to the element for character @var{char}.
+Refers to the element for character @var{char}
+(supposing @var{char} is a valid character code).
 
 @item @var{charset}
 Refers to the value specified for the whole character set
 @var{charset} (@pxref{Character Sets}).
+
+@item @var{generic-char}
+A generic character stands for a character set; specifying the generic
+character as argument is equivalent to specifying the character set
+name.  @xref{Splitting Characters}, for a description of generic characters.
 @end table
 @end defun
 
+@defun map-char-table function char-table
 @tindex map-char-table
-@defun map-char-table function char-table
 This function calls @var{function} for each element of @var{char-table}.
 @var{function} is called with two arguments, a key and a value.  The key
-is a possible @var{range} argument for @code{char-table-range}, and the
-value is @code{(char-table-range @var{char-table} @var{key})}.  Invalid
-character codes are never used as @var{key}.
+is a possible @var{range} argument for @code{char-table-range}---either
+a valid character or a generic character---and the value is
+@code{(char-table-range @var{char-table} @var{key})}.
 
 Overall, the key-value pairs passed to @var{function} describe all the
 values stored in @var{char-table}.
+
+The return value is always @code{nil}; to make this function useful,
+@var{function} should have side effects.  For example,
+here is how to examine each element of the syntax table:
+
+@example
+(map-char-table
+ #'(lambda (key value)
+     (setq accumulator
+           (cons (list key value) accumulator)))
+ (syntax-table))
+@result{}
+((475008 nil) (474880 nil) (474752 nil) (474624 nil)
+ ... (5 (3)) (4 (3)) (3 (3)) (2 (3)) (1 (3)) (0 (3)))
+@end example
 @end defun
 
 @node Bool-Vectors
@@ -671,13 +704,14 @@
 from that, you manipulate them with same functions used for other kinds
 of arrays.
 
+@defun make-bool-vector length initial
 @tindex make-bool-vector
-@defun make-bool-vector length initial
 Return a new book-vector of @var{length} elements,
 each one initialized to @var{initial}.
 @end defun
 
 @defun bool-vector-p object
+@tindex bool-vector-p
 This returns @code{t} if @var{object} is a bool-vector,
 and @code{nil} otherwise.
 @end defun