lispref/sequences.texi

   1 @c -*-texinfo-*-
   2 @c This is part of the GNU Emacs Lisp Reference Manual.
   3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
   4 @c See the file elisp.texi for copying conditions.
   5 @setfilename ../info/sequences
   6 @node Sequences Arrays Vectors, Symbols, Lists, Top
   7 @chapter Sequences, Arrays, and Vectors
   8 @cindex sequence
   9
  10   Recall that the @dfn{sequence} type is the union of three other Lisp
  11 types: lists, vectors, and strings.  In other words, any list is a
  12 sequence, any vector is a sequence, and any string is a sequence.  The
  13 common property that all sequences have is that each is an ordered
  14 collection of elements.
  15
  16   An @dfn{array} is a single primitive object that has a slot for each
  17 elements.  All the elements are accessible in constant time, but the
  18 length of an existing array cannot be changed.  Strings and vectors are
  19 the two types of arrays.
  20
  21   A list is a sequence of elements, but it is not a single primitive
  22 object; it is made of cons cells, one cell per element.  Finding the
  23 @var{n}th element requires looking through @var{n} cons cells, so
  24 elements farther from the beginning of the list take longer to access.
  25 But it is possible to add elements to the list, or remove elements.
  26
  27   The following diagram shows the relationship between these types:
  28
  29 @example
  30 @group
  31           ___________________________________
  32          |                                   |
  33          |          Sequence                 |
  34          |  ______   ______________________  |
  35          | |      | |                      | |
  36          | | List | |         Array        | |
  37          | |      | |  ________   _______  | |
  38          | |______| | |        | |       | | |
  39          |          | | Vector | | String| | |
  40          |          | |________| |_______| | |
  41          |          |______________________| |
  42          |___________________________________|
  43 @end group
  44 @end example
  45
  46   The elements of vectors and lists may be any Lisp objects.  The
  47 elements of strings are all characters.
  48
  49 @menu
  50 * Sequence Functions::    Functions that accept any kind of sequence.
  51 * Arrays::                Characteristics of arrays in Emacs Lisp.
  52 * Array Functions::       Functions specifically for arrays.
  53 * Vectors::               Special characteristics of Emacs Lisp vectors.
  54 * Vector Functions::      Functions specifically for vectors.
  55 @end menu
  56
  57 @node Sequence Functions
  58 @section Sequences
  59
  60   In Emacs Lisp, a @dfn{sequence} is either a list, a vector or a
  61 string.  The common property that all sequences have is that each is an
  62 ordered collection of elements.  This section describes functions that
  63 accept any kind of sequence.
  64
  65 @defun sequencep object
  66 Returns @code{t} if @var{object} is a list, vector, or
  67 string, @code{nil} otherwise.
  68 @end defun
  69
  70 @defun copy-sequence sequence
  71 @cindex copying sequences
  72 Returns a copy of @var{sequence}.  The copy is the same type of object
  73 as the original sequence, and it has the same elements in the same order.
  74
  75 Storing a new element into the copy does not affect the original
  76 @var{sequence}, and vice versa.  However, the elements of the new
  77 sequence are not copies; they are identical (@code{eq}) to the elements
  78 of the original.  Therefore, changes made within these elements, as
  79 found via the copied sequence, are also visible in the original
  80 sequence.
  81
  82 If the sequence is a string with text properties, the property list in
  83 the copy is itself a copy, not shared with the original's property
  84 list.  However, the actual values of the properties are shared.
  85 @xref{Text Properties}.
  86
  87 See also @code{append} in @ref{Building Lists}, @code{concat} in
  88 @ref{Creating Strings}, and @code{vconcat} in @ref{Vectors}, for others
  89 ways to copy sequences.
  90
  91 @example
  92 @group
  93 (setq bar '(1 2))
  94      @result{} (1 2)
  95 @end group
  96 @group
  97 (setq x (vector 'foo bar))
  98      @result{} [foo (1 2)]
  99 @end group
 100 @group
 101 (setq y (copy-sequence x))
 102      @result{} [foo (1 2)]
 103 @end group
 104
 105 @group
 106 (eq x y)
 107      @result{} nil
 108 @end group
 109 @group
 110 (equal x y)
 111      @result{} t
 112 @end group
 113 @group
 114 (eq (elt x 1) (elt y 1))
 115      @result{} t
 116 @end group
 117
 118 @group
 119 ;; @r{Replacing an element of one sequence.}
 120 (aset x 0 'quux)
 121 x @result{} [quux (1 2)]
 122 y @result{} [foo (1 2)]
 123 @end group
 124
 125 @group
 126 ;; @r{Modifying the inside of a shared element.}
 127 (setcar (aref x 1) 69)
 128 x @result{} [quux (69 2)]
 129 y @result{} [foo (69 2)]
 130 @end group
 131 @end example
 132 @end defun
 133
 134 @defun length sequence
 135 @cindex string length
 136 @cindex list length
 137 @cindex vector length
 138 @cindex sequence length
 139 Returns the number of elements in @var{sequence}.  If @var{sequence} is
 140 a cons cell that is not a list (because the final @sc{cdr} is not
 141 @code{nil}), a @code{wrong-type-argument} error is signaled.
 142
 143 @example
 144 @group
 145 (length '(1 2 3))
 146     @result{} 3
 147 @end group
 148 @group
 149 (length ())
 150     @result{} 0
 151 @end group
 152 @group
 153 (length "foobar")
 154     @result{} 6
 155 @end group
 156 @group
 157 (length [1 2 3])
 158     @result{} 3
 159 @end group
 160 @end example
 161 @end defun
 162
 163 @defun elt sequence index
 164 @cindex elements of sequences
 165 This function returns the element of @var{sequence} indexed by
 166 @var{index}.  Legitimate values of @var{index} are integers ranging from
 167 0 up to one less than the length of @var{sequence}.  If @var{sequence}
 168 is a list, then out-of-range values of @var{index} return @code{nil};
 169 otherwise, they trigger an @code{args-out-of-range} error.
 170
 171 @example
 172 @group
 173 (elt [1 2 3 4] 2)
 174      @result{} 3
 175 @end group
 176 @group
 177 (elt '(1 2 3 4) 2)
 178      @result{} 3
 179 @end group
 180 @group
 181 (char-to-string (elt "1234" 2))
 182      @result{} "3"
 183 @end group
 184 @group
 185 (elt [1 2 3 4] 4)
 186      @error{}Args out of range: [1 2 3 4], 4
 187 @end group
 188 @group
 189 (elt [1 2 3 4] -1)
 190      @error{}Args out of range: [1 2 3 4], -1
 191 @end group
 192 @end example
 193
 194 This function generalizes @code{aref} (@pxref{Array Functions}) and
 195 @code{nth} (@pxref{List Elements}).
 196 @end defun
 197
 198 @node Arrays
 199 @section Arrays
 200 @cindex array
 201
 202   An @dfn{array} object has slots that hold a number of other Lisp
 203 objects, called the elements of the array.  Any element of an array may
 204 be accessed in constant time.  In contrast, an element of a list
 205 requires access time that is proportional to the position of the element
 206 in the list.
 207
 208   When you create an array, you must specify how many elements it has.
 209 The amount of space allocated depends on the number of elements.
 210 Therefore, it is impossible to change the size of an array once it is
 211 created; you cannot add or remove elements.  However, you can replace an
 212 element with a different value.
 213
 214   Emacs defines two types of array, both of which are one-dimensional:
 215 @dfn{strings} and @dfn{vectors}.  A vector is a general array; its
 216 elements can be any Lisp objects.  A string is a specialized array; its
 217 elements must be characters (i.e., integers between 0 and 255).  Each
 218 type of array has its own read syntax.  @xref{String Type}, and
 219 @ref{Vector Type}.
 220
 221   Both kinds of array share these characteristics:
 222
 223 @itemize @bullet
 224 @item
 225 The first element of an array has index zero, the second element has
 226 index 1, and so on.  This is called @dfn{zero-origin} indexing.  For
 227 example, an array of four elements has indices 0, 1, 2, @w{and 3}.
 228
 229 @item
 230 The elements of an array may be referenced or changed with the functions
 231 @code{aref} and @code{aset}, respectively (@pxref{Array Functions}).
 232 @end itemize
 233
 234   In principle, if you wish to have an array of text characters, you
 235 could use either a string or a vector.  In practice, we always choose
 236 strings for such applications, for four reasons:
 237
 238 @itemize @bullet
 239 @item
 240 They occupy one-fourth the space of a vector of the same elements.
 241
 242 @item
 243 Strings are printed in a way that shows the contents more clearly
 244 as characters.
 245
 246 @item
 247 Strings can hold text properties.  @xref{Text Properties}.
 248
 249 @item
 250 Many of the specialized editing and I/O facilities of Emacs accept only
 251 strings.  For example, you cannot insert a vector of characters into a
 252 buffer the way you can insert a string.  @xref{Strings and Characters}.
 253 @end itemize
 254
 255   By contrast, for an array of keyboard input characters (such as a key
 256 sequence), a vector may be necessary, because many keyboard input
 257 characters are outside the range that will fit in a string.  @xref{Key
 258 Sequence Input}.
 259
 260 @node Array Functions
 261 @section Functions that Operate on Arrays
 262
 263   In this section, we describe the functions that accept both strings
 264 and vectors.
 265
 266 @defun arrayp object
 267 This function returns @code{t} if @var{object} is an array (i.e., either a
 268 vector or a string).
 269
 270 @example
 271 @group
 272 (arrayp [a])
 273 @result{} t
 274 (arrayp "asdf")
 275 @result{} t
 276 @end group
 277 @end example
 278 @end defun
 279
 280 @defun aref array index
 281 @cindex array elements
 282 This function returns the @var{index}th element of @var{array}.  The
 283 first element is at index zero.
 284
 285 @example
 286 @group
 287 (setq primes [2 3 5 7 11 13])
 288      @result{} [2 3 5 7 11 13]
 289 (aref primes 4)
 290      @result{} 11
 291 (elt primes 4)
 292      @result{} 11
 293 @end group
 294
 295 @group
 296 (aref "abcdefg" 1)
 297      @result{} 98           ; @r{@samp{b} is @sc{ASCII} code 98.}
 298 @end group
 299 @end example
 300
 301 See also the function @code{elt}, in @ref{Sequence Functions}.
 302 @end defun
 303
 304 @defun aset array index object
 305 This function sets the @var{index}th element of @var{array} to be
 306 @var{object}.  It returns @var{object}.
 307
 308 @example
 309 @group
 310 (setq w [foo bar baz])
 311      @result{} [foo bar baz]
 312 (aset w 0 'fu)
 313      @result{} fu
 314 w
 315      @result{} [fu bar baz]
 316 @end group
 317
 318 @group
 319 (setq x "asdfasfd")
 320      @result{} "asdfasfd"
 321 (aset x 3 ?Z)
 322      @result{} 90
 323 x
 324      @result{} "asdZasfd"
 325 @end group
 326 @end example
 327
 328 If @var{array} is a string and @var{object} is not a character, a
 329 @code{wrong-type-argument} error results.
 330 @end defun
 331
 332 @defun fillarray array object
 333 This function fills the array @var{array} with @var{object}, so that
 334 each element of @var{array} is @var{object}.  It returns @var{array}.
 335
 336 @example
 337 @group
 338 (setq a [a b c d e f g])
 339      @result{} [a b c d e f g]
 340 (fillarray a 0)
 341      @result{} [0 0 0 0 0 0 0]
 342 a
 343      @result{} [0 0 0 0 0 0 0]
 344 @end group
 345 @group
 346 (setq s "When in the course")
 347      @result{} "When in the course"
 348 (fillarray s ?-)
 349      @result{} "------------------"
 350 @end group
 351 @end example
 352
 353 If @var{array} is a string and @var{object} is not a character, a
 354 @code{wrong-type-argument} error results.
 355 @end defun
 356
 357 The general sequence functions @code{copy-sequence} and @code{length}
 358 are often useful for objects known to be arrays.  @xref{Sequence Functions}.
 359
 360 @node Vectors
 361 @section Vectors
 362 @cindex vector
 363
 364   Arrays in Lisp, like arrays in most languages, are blocks of memory
 365 whose elements can be accessed in constant time.  A @dfn{vector} is a
 366 general-purpose array; its elements can be any Lisp objects.  (The other
 367 kind of array in Emacs Lisp is the @dfn{string}, whose elements must be
 368 characters.)  Vectors in Emacs serve as syntax tables (vectors of
 369 integers), as obarrays (vectors of symbols), and in keymaps (vectors of
 370 commands).  They are also used internally as part of the representation
 371 of a byte-compiled function; if you print such a function, you will see
 372 a vector in it.
 373
 374   In Emacs Lisp, the indices of the elements of a vector start from zero
 375 and count up from there.
 376
 377   Vectors are printed with square brackets surrounding the elements.
 378 Thus, a vector whose elements are the symbols @code{a}, @code{b} and
 379 @code{a} is printed as @code{[a b a]}.  You can write vectors in the
 380 same way in Lisp input.
 381
 382   A vector, like a string or a number, is considered a constant for
 383 evaluation: the result of evaluating it is the same vector.  This does
 384 not evaluate or even examine the elements of the vector.
 385 @xref{Self-Evaluating Forms}.
 386
 387   Here are examples of these principles:
 388
 389 @example
 390 @group
 391 (setq avector [1 two '(three) "four" [five]])
 392      @result{} [1 two (quote (three)) "four" [five]]
 393 (eval avector)
 394      @result{} [1 two (quote (three)) "four" [five]]
 395 (eq avector (eval avector))
 396      @result{} t
 397 @end group
 398 @end example
 399
 400 @node Vector Functions
 401 @section Functions That Operate on Vectors
 402
 403   Here are some functions that relate to vectors:
 404
 405 @defun vectorp object
 406 This function returns @code{t} if @var{object} is a vector.
 407
 408 @example
 409 @group
 410 (vectorp [a])
 411      @result{} t
 412 (vectorp "asdf")
 413      @result{} nil
 414 @end group
 415 @end example
 416 @end defun
 417
 418 @defun vector &rest objects
 419 This function creates and returns a vector whose elements are the
 420 arguments, @var{objects}.
 421
 422 @example
 423 @group
 424 (vector 'foo 23 [bar baz] "rats")
 425      @result{} [foo 23 [bar baz] "rats"]
 426 (vector)
 427      @result{} []
 428 @end group
 429 @end example
 430 @end defun
 431
 432 @defun make-vector length object
 433 This function returns a new vector consisting of @var{length} elements,
 434 each initialized to @var{object}.
 435
 436 @example
 437 @group
 438 (setq sleepy (make-vector 9 'Z))
 439      @result{} [Z Z Z Z Z Z Z Z Z]
 440 @end group
 441 @end example
 442 @end defun
 443
 444 @defun vconcat &rest sequences
 445 @cindex copying vectors
 446 This function returns a new vector containing all the elements of the
 447 @var{sequences}.  The arguments @var{sequences} may be lists, vectors,
 448 or strings.  If no @var{sequences} are given, an empty vector is
 449 returned.
 450
 451 The value is a newly constructed vector that is not @code{eq} to any
 452 existing vector.
 453
 454 @example
 455 @group
 456 (setq a (vconcat '(A B C) '(D E F)))
 457      @result{} [A B C D E F]
 458 (eq a (vconcat a))
 459      @result{} nil
 460 @end group
 461 @group
 462 (vconcat)
 463      @result{} []
 464 (vconcat [A B C] "aa" '(foo (6 7)))
 465      @result{} [A B C 97 97 foo (6 7)]
 466 @end group
 467 @end example
 468
 469 The @code{vconcat} function also allows integers as arguments.  It
 470 converts them to strings of digits, making up the decimal print
 471 representation of the integer, and then uses the strings instead of the
 472 original integers.  @strong{Don't use this feature; we plan to eliminate
 473 it.  If you already use this feature, change your programs now!}  The
 474 proper way to convert an integer to a decimal number in this way is with
 475 @code{format} (@pxref{Formatting Strings}) or @code{number-to-string}
 476 (@pxref{String Conversion}).
 477
 478 For other concatenation functions, see @code{mapconcat} in @ref{Mapping
 479 Functions}, @code{concat} in @ref{Creating Strings}, and @code{append}
 480 in @ref{Building Lists}.
 481 @end defun
 482
 483   The @code{append} function provides a way to convert a vector into a
 484 list with the same elements (@pxref{Building Lists}):
 485
 486 @example
 487 @group
 488 (setq avector [1 two (quote (three)) "four" [five]])
 489      @result{} [1 two (quote (three)) "four" [five]]
 490 (append avector nil)
 491      @result{} (1 two (quote (three)) "four" [five])
 492 @end group
 493 @end example