X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/a9f0a989a17f47f9d25b7a426b4e82a8ff684ee4..a72c2d97a8df00371150fe9d3dffd84559fd0479:/lispref/sequences.texi diff --git a/lispref/sequences.texi b/lispref/sequences.texi index 26263831d1..982c9ffead 100644 --- a/lispref/sequences.texi +++ b/lispref/sequences.texi @@ -1,9 +1,10 @@ @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 +@c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/sequences -@node Sequences Arrays Vectors, Symbols, Lists, Top +@node Sequences Arrays Vectors, Hash Tables, Lists, Top @chapter Sequences, Arrays, and Vectors @cindex sequence @@ -68,8 +69,8 @@ elements. This section describes functions that accept any kind of 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 @@ -77,12 +78,14 @@ string, @code{nil} otherwise. @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 @@ -108,13 +111,21 @@ signaled. @end example @end defun +@defun string-bytes string +@cindex string, number of bytes +This function returns the number of bytes in @var{string}. +If @var{string} is a multibyte string, this is greater than +@code{(length @var{string})}. +@end defun + @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 @@ -141,7 +152,7 @@ otherwise, they trigger an @code{args-out-of-range} error. @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 @@ -161,9 +172,12 @@ the copy is itself a copy, not shared with the original's property 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 @@ -221,8 +235,8 @@ in the list. 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: @@ -238,8 +252,8 @@ The length of the array is fixed once you create it; you cannot 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 @@ -312,7 +326,7 @@ first element is at index zero. @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 @@ -344,11 +358,8 @@ x @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 @@ -465,9 +476,9 @@ each initialized to @var{object}. @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. @@ -491,14 +502,11 @@ The @code{vconcat} function also allows byte-code function objects as 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} @@ -541,7 +549,7 @@ 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 + 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 @@ -554,7 +562,6 @@ specifies @code{nil}. 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 @@ -565,45 +572,38 @@ all char-tables have room for any valid character code as an index. @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 @@ -612,7 +612,6 @@ This function stores @var{value} in extra slot @var{n} of 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}: @@ -629,15 +628,15 @@ 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. +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 set the value in @var{char-table} for a range of +This function sets the value in @var{char-table} for a range of characters @var{range}. Here are the possibilities for @var{range}: @table @asis @@ -663,7 +662,6 @@ name. @xref{Splitting Characters}, for a description of generic characters. @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 @@ -678,11 +676,13 @@ The return value is always @code{nil}; to make this function useful, 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)) +(let (accumulator) + (map-char-table + #'(lambda (key value) + (setq accumulator + (cons (list key value) accumulator))) + (syntax-table)) + accumulator) @result{} ((475008 nil) (474880 nil) (474752 nil) (474624 nil) ... (5 (3)) (4 (3)) (3 (3)) (2 (3)) (1 (3)) (0 (3))) @@ -705,14 +705,34 @@ from that, you manipulate them with same functions used for other kinds 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