@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
+@c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/sequences
@node Sequences Arrays Vectors, Hash Tables, Lists, Top
sequence.
@defun sequencep object
-Returns @code{t} if @var{object} is a list, vector, or
-string, @code{nil} otherwise.
+Returns @code{t} if @var{object} is a list, vector, string,
+bool-vector, or char-table, @code{nil} otherwise.
@end defun
@defun length sequence
@cindex list length
@cindex vector length
@cindex sequence length
+@cindex char-table length
This function returns the number of elements in @var{sequence}. If
-@var{sequence} is a cons cell that is not a list (because the final
-@sc{cdr} is not @code{nil}), a @code{wrong-type-argument} error is
-signaled.
+@var{sequence} is a dotted list, a @code{wrong-type-argument} error is
+signaled. Circular lists may cause an infinite loop. For a
+char-table, the value returned is always one more than the maximum
+Emacs character code.
-@xref{List Elements}, for the related function @code{safe-length}.
+@xref{Definition of safe-length}, for the related function @code{safe-length}.
@example
@group
@end example
@end defun
+@noindent
+See also @code{string-bytes}, in @ref{Text Representations}.
+
@defun elt sequence index
@cindex elements of sequences
This function returns the element of @var{sequence} indexed by
-@var{index}. Legitimate values of @var{index} are integers ranging from
-0 up to one less than the length of @var{sequence}. If @var{sequence}
-is a list, then out-of-range values of @var{index} return @code{nil};
-otherwise, they trigger an @code{args-out-of-range} error.
+@var{index}. Legitimate values of @var{index} are integers ranging
+from 0 up to one less than the length of @var{sequence}. If
+@var{sequence} is a list, out-of-range values behave as for
+@code{nth}. @xref{Definition of nth}. Otherwise, out-of-range values
+trigger an @code{args-out-of-range} error.
@example
@group
@end example
This function generalizes @code{aref} (@pxref{Array Functions}) and
-@code{nth} (@pxref{List Elements}).
+@code{nth} (@pxref{Definition of nth}).
@end defun
@defun copy-sequence sequence
list. However, the actual values of the properties are shared.
@xref{Text Properties}.
+This function does not work for dotted lists. Trying to copy a
+circular list may cause an infinite loop.
+
See also @code{append} in @ref{Building Lists}, @code{concat} in
-@ref{Creating Strings}, and @code{vconcat} in @ref{Vectors}, for others
-ways to copy sequences.
+@ref{Creating Strings}, and @code{vconcat} in @ref{Vector Functions},
+for other ways to copy sequences.
@example
@group
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.
+specialized array; its elements must be characters. Each type of array
+has its own read syntax.
@xref{String Type}, and @ref{Vector Type}.
All four kinds of array share these characteristics:
change the length of an existing array.
@item
-The array is a constant, for evaluation---in other words, it evaluates
-to itself.
+For purposes of evaluation, the array is a constant---in other words,
+it evaluates to itself.
@item
The elements of an array may be referenced or changed with the functions
@end group
@group
(aref "abcdefg" 1)
- @result{} 98 ; @r{@samp{b} is @sc{ascii} code 98.}
+ @result{} 98 ; @r{@samp{b} is @acronym{ASCII} code 98.}
@end group
@end example
@end example
If @var{array} is a string and @var{object} is not a character, a
-@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{Splitting
-Characters}.
+@code{wrong-type-argument} error results. The function converts a
+unibyte string to multibyte if necessary to insert a character.
@end defun
@defun fillarray array object
@node Vectors
@section Vectors
-@cindex vector
+@cindex vector (type)
Arrays in Lisp, like arrays in most languages, are blocks of memory
whose elements can be accessed in constant time. A @dfn{vector} is a
@defun vconcat &rest sequences
@cindex copying vectors
This function returns a new vector containing all the elements of the
-@var{sequences}. The arguments @var{sequences} may be any kind of
-arrays, including lists, vectors, or strings. If no @var{sequences} are
-given, an empty vector is returned.
+@var{sequences}. The arguments @var{sequences} may be true lists,
+vectors, strings or bool-vectors. If no @var{sequences} are given, an
+empty vector is returned.
The value is a newly constructed vector that is not @code{eq} to any
existing vector.
arguments. This is a special feature to make it easy to access the entire
contents of a byte-code function object. @xref{Byte-Code Objects}.
-The @code{vconcat} function also allows integers as arguments. It
-converts them to strings of digits, making up the decimal print
-representation of the integer, and then uses the strings instead of the
-original integers. @strong{Don't use this feature; we plan to eliminate
-it. If you already use this feature, change your programs now!} The
-proper way to convert an integer to a decimal number in this way is with
-@code{format} (@pxref{Formatting Strings}) or @code{number-to-string}
-(@pxref{String Conversion}).
+In Emacs versions before 21, the @code{vconcat} function allowed
+integers as arguments, converting them to strings of digits, but that
+feature has been eliminated. The proper way to convert an integer to
+a decimal number in this way is with @code{format} (@pxref{Formatting
+Strings}) or @code{number-to-string} (@pxref{String Conversion}).
For other concatenation functions, see @code{mapconcat} in @ref{Mapping
Functions}, @code{concat} in @ref{Creating Strings}, and @code{append}
in @ref{Building Lists}.
@end defun
- The @code{append} function provides a way to convert a vector into a
-list with the same elements (@pxref{Building Lists}):
+ The @code{append} function also provides a way to convert a vector into a
+list with the same elements:
@example
@group
@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
+ A char-table can have a @dfn{parent}, which is another char-table. If
it does, then whenever the char-table specifies @code{nil} for a
particular character @var{c}, it inherits the value specified in the
parent. In other words, @code{(aref @var{char-table} @var{c})} returns
whenever the char-table does not specify any other non-@code{nil} value.
@defun make-char-table subtype &optional init
-@tindex make-char-table
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
@end defun
@defun char-table-p object
-@tindex char-table-p
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
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
-This function sets the default value of @var{char-table} to
-@var{new-default}.
+@defun set-char-table-default char-table char new-default
+This function sets the default value of generic character @var{char}
+in @var{char-table} to @var{new-default}.
-There is no special function to access the default value of a char-table.
-To do that, use @code{(char-table-range @var{char-table} nil)}.
+There is no special function to access default values in a char-table.
+To do that, use @code{char-table-range} (see below).
@end defun
@defun char-table-parent char-table
-@tindex char-table-parent
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
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
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
This function stores @var{value} in extra slot @var{n} of
@var{char-table}.
@end defun
it can also specify a value for an entire character set.
@defun char-table-range char-table range
-@tindex char-table-range
This returns the value specified in @var{char-table} for a range of
characters @var{range}. Here are the possibilities for @var{range}:
@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.
+A generic character stands for a character set, or a row of 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
This function sets the value in @var{char-table} for a range of
characters @var{range}. Here are the possibilities for @var{range}:
@end defun
@defun map-char-table function char-table
-@tindex map-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}---either
of arrays.
@defun make-bool-vector length initial
-@tindex make-bool-vector
-Return a new book-vector of @var{length} elements,
+Return a new bool-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
+ Here is an example of creating, examining, and updating a
+bool-vector. Note that the printed form represents up to 8 boolean
+values as a single character.
+
+@example
+(setq bv (make-bool-vector 5 t))
+ @result{} #&5"^_"
+(aref bv 1)
+ @result{} t
+(aset bv 3 nil)
+ @result{} nil
+bv
+ @result{} #&5"^W"
+@end example
+
+@noindent
+These results make sense because the binary codes for control-_ and
+control-W are 11111 and 10111, respectively.
+
+@ignore
+ arch-tag: fcf1084a-cd29-4adc-9f16-68586935b386
+@end ignore