This is gcl.info, produced by makeinfo version 6.7 from gcl.texi.

This is a Texinfo GNU Common Lisp Manual based on the draft ANSI
standard for Common Lisp.

   Copyright 1994 William F. Schelter

INFO-DIR-SECTION GNU Common Lisp
START-INFO-DIR-ENTRY
* gcl: (gcl.info). GNU Common Lisp Manual
END-INFO-DIR-ENTRY


File: gcl.info,  Node: boole-1,  Next: logand,  Prev: boole,  Up: Numbers Dictionary

12.2.61 boole-1, boole-2, boole-and, boole-andc1, boole-andc2,
--------------------------------------------------------------

boole-c1, boole-c2, boole-clr, boole-eqv, boole-ior,
----------------------------------------------------

boole-nand, boole-nor, boole-orc1, boole-orc2, boole-set,
---------------------------------------------------------

boole-xor
---------

                                                    [Constant Variable]

Constant Value::
................

The identity and nature of the values of each of these variables is
implementation-dependent, except that it must be distinct from each of
the values of the others, and it must be a valid first argument to the
function boole.

Description::
.............

Each of these constants has a value which is one of the sixteen possible
bit-wise logical operation specifiers.

Examples::
..........

      (boole boole-ior 1 16) =>  17
      (boole boole-and -2 5) =>  4
      (boole boole-eqv 17 15) =>  -31

See Also::
..........

*note boole::


File: gcl.info,  Node: logand,  Next: logbitp,  Prev: boole-1,  Up: Numbers Dictionary

12.2.62 logand, logandc1, logandc2, logeqv, logior,
---------------------------------------------------

lognand, lognor, lognot, logorc1, logorc2,
------------------------------------------

logxor
------

                                                             [Function]

   'logand' &rest integers => result-integer

   'logandc' 1 => integer-1 integer-2 result-integer 'logandc' 2 =>
integer-1 integer-2 result-integer 'logeqv' &rest integers =>
result-integer

   'logior' &rest integers => result-integer

   'lognand' integer-1 integer-2 => result-integer

   'lognor' integer-1 integer-2 => result-integer

   'lognot' integer => result-integer

   'logorc' 1 => integer-1 integer-2 result-integer 'logorc' 2 =>
integer-1 integer-2 result-integer 'logxor' &rest integers =>
result-integer

Arguments and Values::
......................

integers--integers.

   integer--an integer.

   integer-1--an integer.

   integer-2--an integer.

   result-integer--an integer.

Description::
.............

The functions logandc1, logandc2, logand, logeqv, logior, lognand,
lognor, lognot, logorc1, logorc2, and logxor perform bit-wise logical
operations on their arguments, that are treated as if they were binary.

   Figure 12-17 lists the meaning of each of the functions.  Where an
'identity' is shown, it indicates the value yielded by the function when
no arguments are supplied.

  Function  Identity  Operation performed                         
  logandc1  --       and complement of integer-1 with integer-2  
  logandc2  --       and integer-1 with complement of integer-2  
  logand    -1        and                                         
  logeqv    -1        equivalence (exclusive nor)                 
  logior    0         inclusive or                                
  lognand   --       complement of integer-1 and integer-2       
  lognor    --       complement of integer-1 or integer-2        
  lognot    --       complement                                  
  logorc1   --       or complement of integer-1 with integer-2   
  logorc2   --       or integer-1 with complement of integer-2   
  logxor    0         exclusive or                                

       Figure 12-17: Bit-wise Logical Operations on Integers     


   Negative integers are treated as if they were in two's-complement
notation.

Examples::
..........

      (logior 1 2 4 8) =>  15
      (logxor 1 3 7 15) =>  10
      (logeqv) =>  -1
      (logand 16 31) =>  16
      (lognot 0) =>  -1
      (lognot 1) =>  -2
      (lognot -1) =>  0
      (lognot (1+ (lognot 1000))) =>  999

     ;;; In the following example, m is a mask.  For each bit in
     ;;; the mask that is a 1, the corresponding bits in x and y are
     ;;; exchanged.  For each bit in the mask that is a 0, the
     ;;; corresponding bits of x and y are left unchanged.
      (flet ((show (m x y)
               (format t "~
                       m x y)))
        (let ((m #o007750)
              (x #o452576)
              (y #o317407))
          (show m x y)
          (let ((z (logand (logxor x y) m)))
            (setq x (logxor z x))
            (setq y (logxor z y))
            (show m x y))))
      |>  m = #o007750
      |>  x = #o452576
      |>  y = #o317407
      |>
      |>  m = #o007750
      |>  x = #o457426
      |>  y = #o312557
     =>  NIL

Exceptional Situations::
........................

Should signal type-error if any argument is not an integer.

See Also::
..........

*note boole::

Notes::
.......

(logbitp k -1) returns true for all values of k.

   Because the following functions are not associative, they take
exactly two arguments rather than any number of arguments.

      (lognand n1 n2) == (lognot (logand n1 n2))
      (lognor n1 n2) == (lognot (logior n1 n2))
      (logandc1 n1 n2) == (logand (lognot n1) n2)
      (logandc2 n1 n2) == (logand n1 (lognot n2))
      (logiorc1 n1 n2) == (logior (lognot n1) n2)
      (logiorc2 n1 n2) == (logior n1 (lognot n2))
      (logbitp j (lognot x)) == (not (logbitp j x))


File: gcl.info,  Node: logbitp,  Next: logcount,  Prev: logand,  Up: Numbers Dictionary

12.2.63 logbitp [Function]
--------------------------

'logbitp' index integer => generalized-boolean

Arguments and Values::
......................

index--a non-negative integer.

   integer--an integer.

   generalized-boolean--a generalized boolean.

Description::
.............

logbitp is used to test the value of a particular bit in integer, that
is treated as if it were binary.  The value of logbitp is true if the
bit in integer whose index is index (that is, its weight is 2^index) is
a one-bit; otherwise it is false.

   Negative integers are treated as if they were in two's-complement
notation.

Examples::
..........

      (logbitp 1 1) =>  false
      (logbitp 0 1) =>  true
      (logbitp 3 10) =>  true
      (logbitp 1000000 -1) =>  true
      (logbitp 2 6) =>  true
      (logbitp 0 6) =>  false

Exceptional Situations::
........................

Should signal an error of type type-error if index is not a non-negative
integer.  Should signal an error of type type-error if integer is not an
integer.

Notes::
.......

      (logbitp k n) == (ldb-test (byte 1 k) n)


File: gcl.info,  Node: logcount,  Next: logtest,  Prev: logbitp,  Up: Numbers Dictionary

12.2.64 logcount [Function]
---------------------------

'logcount' integer => number-of-on-bits

Arguments and Values::
......................

integer--an integer.

   number-of-on-bits--a non-negative integer.

Description::
.............

Computes and returns the number of bits in the two's-complement binary
representation of integer that are 'on' or 'set'.  If integer is
negative, the 0 bits are counted; otherwise, the 1 bits are counted.

Examples::
..........

      (logcount 0) =>  0
      (logcount -1) =>  0
      (logcount 7) =>  3
      (logcount  13) =>  3 ;Two's-complement binary: ...0001101
      (logcount -13) =>  2 ;Two's-complement binary: ...1110011
      (logcount  30) =>  4 ;Two's-complement binary: ...0011110
      (logcount -30) =>  4 ;Two's-complement binary: ...1100010
      (logcount (expt 2 100)) =>  1
      (logcount (- (expt 2 100))) =>  100
      (logcount (- (1+ (expt 2 100)))) =>  1

Exceptional Situations::
........................

Should signal type-error if its argument is not an integer.

Notes::
.......

Even if the implementation does not represent integers internally in
two's complement binary, logcount behaves as if it did.

   The following identity always holds:

         (logcount x)
      == (logcount (- (+ x 1)))
      == (logcount (lognot x))


File: gcl.info,  Node: logtest,  Next: byte,  Prev: logcount,  Up: Numbers Dictionary

12.2.65 logtest [Function]
--------------------------

'logtest' integer-1 integer-2 => generalized-boolean

Arguments and Values::
......................

integer-1--an integer.

   integer-2--an integer.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if any of the bits designated by the 1's in integer-1 is 1
in integer-2; otherwise it is false.  integer-1 and integer-2 are
treated as if they were binary.

   Negative integer-1 and integer-2 are treated as if they were
represented in two's-complement binary.

Examples::
..........

      (logtest 1 7) =>  true
      (logtest 1 2) =>  false
      (logtest -2 -1) =>  true
      (logtest 0 -1) =>  false

Exceptional Situations::
........................

Should signal an error of type type-error if integer-1 is not an
integer.  Should signal an error of type type-error if integer-2 is not
an integer.

Notes::
.......

      (logtest x y) == (not (zerop (logand x y)))


File: gcl.info,  Node: byte,  Next: deposit-field,  Prev: logtest,  Up: Numbers Dictionary

12.2.66 byte, byte-size, byte-position [Function]
-------------------------------------------------

'byte' size position => bytespec

   'byte-size' bytespec => size

   'byte-position' bytespec => position

Arguments and Values::
......................

size, position--a non-negative integer.

   bytespec--a byte specifier.

Description::
.............

byte returns a byte specifier that indicates a byte of width size and
whose bits have weights 2^position + size - 1\/ through 2^position, and
whose representation is implementation-dependent.

   byte-size returns the number of bits specified by bytespec.

   byte-position returns the position specified by bytespec.

Examples::
..........

      (setq b (byte 100 200)) =>  #<BYTE-SPECIFIER size 100 position 200>
      (byte-size b) =>  100
      (byte-position b) =>  200

See Also::
..........

*note ldb:: , *note dpb::

Notes::
.......

      (byte-size (byte j k)) == j
      (byte-position (byte j k)) == k

   A byte of size of 0 is permissible; it refers to a byte of width
zero.  For example,

      (ldb (byte 0 3) #o7777) =>  0
      (dpb #o7777 (byte 0 3) 0) =>  0


File: gcl.info,  Node: deposit-field,  Next: dpb,  Prev: byte,  Up: Numbers Dictionary

12.2.67 deposit-field [Function]
--------------------------------

'deposit-field' newbyte bytespec integer => result-integer

Arguments and Values::
......................

newbyte--an integer.

   bytespec--a byte specifier.

   integer--an integer.

   result-integer--an integer.

Description::
.............

Replaces a field of bits within integer; specifically, returns an
integer that contains the bits of newbyte within the byte specified by
bytespec, and elsewhere contains the bits of integer.

Examples::
..........

      (deposit-field 7 (byte 2 1) 0) =>  6
      (deposit-field -1 (byte 4 0) 0) =>  15
      (deposit-field 0 (byte 2 1) -3) =>  -7

See Also::
..........

*note byte:: , *note dpb::

Notes::
.......

      (logbitp j (deposit-field m (byte s p) n))
      == (if (and (>= j p) (< j (+ p s)))
             (logbitp j m)
             (logbitp j n))

   deposit-field is to mask-field as dpb is to ldb.


File: gcl.info,  Node: dpb,  Next: ldb,  Prev: deposit-field,  Up: Numbers Dictionary

12.2.68 dpb [Function]
----------------------

'dpb' newbyte bytespec integer => result-integer

Pronunciation::
...............

pronounced ,de 'pib or pronounced ,de 'pe b or pronounced 'd\=e 'p\=e
'b\=e

Arguments and Values::
......................

newbyte--an integer.

   bytespec--a byte specifier.

   integer--an integer.

   result-integer--an integer.

Description::
.............

dpb (deposit byte) is used to replace a field of bits within integer.
dpb returns an integer that is the same as integer except in the bits
specified by bytespec.

   Let s be the size specified by bytespec; then the low s bits of
newbyte appear in the result in the byte specified by bytespec.  Newbyte
is interpreted as being right-justified, as if it were the result of
ldb.

Examples::
..........

      (dpb 1 (byte 1 10) 0) =>  1024
      (dpb -2 (byte 2 10) 0) =>  2048
      (dpb 1 (byte 2 10) 2048) =>  1024

See Also::
..........

*note byte:: , *note deposit-field:: , *note ldb::

Notes::
.......

      (logbitp j (dpb m (byte s p) n))
      == (if (and (>= j p) (< j (+ p s)))
             (logbitp (- j p) m)
             (logbitp j n))

   In general,

      (dpb x (byte 0 y) z) =>  z

   for all valid values of x, y, and z.

   Historically, the name "dpb" comes from a DEC PDP-10 assembly
language instruction meaning "deposit byte."


File: gcl.info,  Node: ldb,  Next: ldb-test,  Prev: dpb,  Up: Numbers Dictionary

12.2.69 ldb [Accessor]
----------------------

'ldb' bytespec integer => byte

   (setf (' ldb' bytespec place) new-byte)

Pronunciation::
...............

pronounced 'lid ib or pronounced 'lid e b or pronounced 'el 'd\=e 'b\=e

Arguments and Values::
......................

bytespec--a byte specifier.

   integer--an integer.

   byte, new-byte--a non-negative integer.

Description::
.............

ldb extracts and returns the byte of integer specified by bytespec.

   ldb returns an integer in which the bits with weights 2^(s-1) through
2^0 are the same as those in integer with weights 2^(p+s-1) through 2^p,
and all other bits zero; s is (byte-size bytespec) and p is
(byte-position bytespec).

   setf may be used with ldb to modify a byte within the integer that is
stored in a given place.

   The order of evaluation, when an ldb form is supplied to setf, is
exactly left-to-right.

   The effect is to perform a dpb operation and then store the result
back into the place.

Examples::
..........

      (ldb (byte 2 1) 10) =>  1
      (setq a (list 8)) =>  (8)
      (setf (ldb (byte 2 1) (car a)) 1) =>  1
      a =>  (10)

See Also::
..........

*note byte:: , byte-position, byte-size, *note dpb::

Notes::
.......

      (logbitp j (ldb (byte s p) n))
         == (and (< j s) (logbitp (+ j p) n))

   In general,

      (ldb (byte 0 x) y) =>  0

   for all valid values of x and y.

   Historically, the name "ldb" comes from a DEC PDP-10 assembly
language instruction meaning "load byte."


File: gcl.info,  Node: ldb-test,  Next: mask-field,  Prev: ldb,  Up: Numbers Dictionary

12.2.70 ldb-test [Function]
---------------------------

'ldb-test' bytespec integer => generalized-boolean

Arguments and Values::
......................

bytespec--a byte specifier.

   integer--an integer.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if any of the bits of the byte in integer specified by
bytespec is non-zero; otherwise returns false.

Examples::
..........

      (ldb-test (byte 4 1) 16) =>  true
      (ldb-test (byte 3 1) 16) =>  false
      (ldb-test (byte 3 2) 16) =>  true

See Also::
..........

*note byte:: , *note ldb:: , *note zerop::

Notes::
.......

      (ldb-test bytespec n) ==
      (not (zerop (ldb bytespec n))) ==
      (logtest (ldb bytespec -1) n)


File: gcl.info,  Node: mask-field,  Next: most-positive-fixnum,  Prev: ldb-test,  Up: Numbers Dictionary

12.2.71 mask-field [Accessor]
-----------------------------

'mask-field' bytespec integer => masked-integer

   (setf (' mask-field' bytespec place) new-masked-integer)

Arguments and Values::
......................

bytespec--a byte specifier.

   integer--an integer.

   masked-integer, new-masked-integer--a non-negative integer.

Description::
.............

mask-field performs a "mask" operation on integer.  It returns an
integer that has the same bits as integer in the byte specified by
bytespec, but that has zero-bits everywhere else.

   setf may be used with mask-field to modify a byte within the integer
that is stored in a given place.  The effect is to perform a
deposit-field operation and then store the result back into the place.

Examples::
..........

      (mask-field (byte 1 5) -1) =>  32
      (setq a 15) =>  15
      (mask-field (byte 2 0) a) =>  3
      a =>  15
      (setf (mask-field (byte 2 0) a) 1) =>  1
      a =>  13

See Also::
..........

*note byte:: , *note ldb::

Notes::
.......

      (ldb bs (mask-field bs n)) == (ldb bs n)
      (logbitp j (mask-field (byte s p) n))
        == (and (>= j p) (< j s) (logbitp j n))
      (mask-field bs n) == (logand n (dpb -1 bs 0))


File: gcl.info,  Node: most-positive-fixnum,  Next: decode-float,  Prev: mask-field,  Up: Numbers Dictionary

12.2.72 most-positive-fixnum, most-negative-fixnum [Constant Variable]
----------------------------------------------------------------------

Constant Value::
................

implementation-dependent.

Description::
.............

most-positive-fixnum is that fixnum closest in value to positive
infinity provided by the implementation,

   and greater than or equal to both 2^15 - 1 and array-dimension-limit.

   most-negative-fixnum is that fixnum closest in value to negative
infinity provided by the implementation,

   and less than or equal to -2^15.


File: gcl.info,  Node: decode-float,  Next: float,  Prev: most-positive-fixnum,  Up: Numbers Dictionary

12.2.73 decode-float, scale-float, float-radix, float-sign,
-----------------------------------------------------------

float-digits, float-precision, integer-decode-float
---------------------------------------------------

                                                             [Function]

   'decode-float' float => significand, exponent, sign

   'scale-float' float integer => scaled-float

   'float-radix' float => float-radix

   'float-sign' float-1 &optional float-2 => signed-float

   'float-digits' float => digits1

   'float-precision' float => digits2

   'integer-decode-float' float => significand, exponent, integer-sign

Arguments and Values::
......................

digits1--a non-negative integer.

   digits2--a non-negative integer.

   exponent--an integer.

   float--a float.

   float-1--a float.

   float-2--a float.

   float-radix--an integer.

   integer--a non-negative integer.

   integer-sign--the integer -1, or the integer 1.

   scaled-float--a float.

   sign--A float of the same type as float but numerically equal to 1.0
or -1.0.

   signed-float--a float.

   significand--a float.

Description::
.............

decode-float computes three values that characterize float.  The first
value is of the same type as float and represents the significand.  The
second value represents the exponent to which the radix (notated in this
description by b) must be raised to obtain the value that, when
multiplied with the first result, produces the absolute value of float.
If float is zero, any integer value may be returned, provided that the
identity shown for scale-float holds.  The third value is of the same
type as float and is 1.0 if float is greater than or equal to zero or
-1.0 otherwise.

   decode-float divides float by an integral power of b so as to bring
its value between 1/b (inclusive) and~1 (exclusive), and returns the
quotient as the first value.  If float is zero, however, the result
equals the absolute value of float (that is, if there is a negative
zero, its significand is considered to be a positive zero).

   scale-float returns (* float (expt (float b float) integer))\/, where
b is the radix of the floating-point representation.  float is not
necessarily between 1/b and~1.

   float-radix returns the radix of float.

   float-sign returns a number z such that z and float-1 have the same
sign and also such that z and float-2 have the same absolute value.  If
float-2 is not supplied, its value is (float 1 float-1).  If an
implementation has distinct representations for negative zero and
positive zero, then (float-sign -0.0) => -1.0.

   float-digits returns the number of radix b digits used in the
representation of float (including any implicit digits, such as a
"hidden bit").

   float-precision returns the number of significant radix b digits
present in float; if float is a float zero, then the result is an
integer zero.

   For normalized floats, the results of float-digits and
float-precision are the same, but the precision is less than the number
of representation digits for a denormalized or zero number.

   integer-decode-float computes three values that characterize float -
the significand scaled so as to be an integer, and the same last two
values that are returned by decode-float.  If float is zero,
integer-decode-float returns zero as the first value.  The second value
bears the same relationship to the first value as for decode-float:

      (multiple-value-bind (signif expon sign)
                           (integer-decode-float f)
        (scale-float (float signif f) expon)) == (abs f)

Examples::
..........

      ;; Note that since the purpose of this functionality is to expose
      ;; details of the implementation, all of these examples are necessarily
      ;; very implementation-dependent.  Results may vary widely.
      ;; Values shown here are chosen consistently from one particular implementation.
      (decode-float .5) =>  0.5, 0, 1.0
      (decode-float 1.0) =>  0.5, 1, 1.0
      (scale-float 1.0 1) =>  2.0
      (scale-float 10.01 -2) =>  2.5025
      (scale-float 23.0 0) =>  23.0
      (float-radix 1.0) =>  2
      (float-sign 5.0) =>  1.0
      (float-sign -5.0) =>  -1.0
      (float-sign 0.0) =>  1.0
      (float-sign 1.0 0.0) =>  0.0
      (float-sign 1.0 -10.0) =>  10.0
      (float-sign -1.0 10.0) =>  -10.0
      (float-digits 1.0) =>  24
      (float-precision 1.0) =>  24
      (float-precision least-positive-single-float) =>  1
      (integer-decode-float 1.0) =>  8388608, -23, 1

Affected By::
.............

The implementation's representation for floats.

Exceptional Situations::
........................

The functions decode-float, float-radix, float-digits, float-precision,
and integer-decode-float should signal an error if their only argument
is not a float.

   The function scale-float should signal an error if its first argument
is not a float or if its second argument is not an integer.

   The function float-sign should signal an error if its first argument
is not a float or if its second argument is supplied but is not a float.

Notes::
.......

The product of the first result of decode-float or integer-decode-float,
of the radix raised to the power of the second result, and of the third
result is exactly equal to the value of float.

      (multiple-value-bind (signif expon sign)
                           (decode-float f)
        (scale-float signif expon))
     == (abs f)

   and

      (multiple-value-bind (signif expon sign)
                           (decode-float f)
        (* (scale-float signif expon) sign))
     == f


File: gcl.info,  Node: float,  Next: floatp,  Prev: decode-float,  Up: Numbers Dictionary

12.2.74 float [Function]
------------------------

'float' number &optional prototype => float

Arguments and Values::
......................

number--a real.

   prototype--a float.

   float--a float.

Description::
.............

float converts a

   real

   number to a float.

   If a prototype is supplied, a float is returned that is
mathematically equal to number but has the same format as prototype.

   If prototype is not supplied, then if the number is already a float,
it is returned; otherwise, a float is returned that is mathematically
equal to number but is a single float.

Examples::
..........

      (float 0) =>  0.0
      (float 1 .5) =>  1.0
      (float 1.0) =>  1.0
      (float 1/2) =>  0.5
     =>  1.0d0
     OR=> 1.0
      (eql (float 1.0 1.0d0) 1.0d0) =>  true

See Also::
..........

*note coerce::


File: gcl.info,  Node: floatp,  Next: most-positive-short-float,  Prev: float,  Up: Numbers Dictionary

12.2.75 floatp [Function]
-------------------------

'floatp' object generalized-boolean

Arguments and Values::
......................

object--an object.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if object is of type float; otherwise, returns false.

Examples::
..........

      (floatp 1.2d2) =>  true
      (floatp 1.212) =>  true
      (floatp 1.2s2) =>  true
      (floatp (expt 2 130)) =>  false

Notes::
.......

      (floatp object) == (typep object 'float)


File: gcl.info,  Node: most-positive-short-float,  Next: short-float-epsilon,  Prev: floatp,  Up: Numbers Dictionary

12.2.76 most-positive-short-float, least-positive-short-float,
--------------------------------------------------------------

least-positive-normalized-short-float,
--------------------------------------

most-positive-double-float, least-positive-double-float,
--------------------------------------------------------

least-positive-normalized-double-float,
---------------------------------------

most-positive-long-float, least-positive-long-float,
----------------------------------------------------

least-positive-normalized-long-float,
-------------------------------------

most-positive-single-float, least-positive-single-float,
--------------------------------------------------------

least-positive-normalized-single-float,
---------------------------------------

most-negative-short-float, least-negative-short-float,
------------------------------------------------------

least-negative-normalized-short-float,
--------------------------------------

most-negative-single-float, least-negative-single-float,
--------------------------------------------------------

least-negative-normalized-single-float,
---------------------------------------

most-negative-double-float, least-negative-double-float,
--------------------------------------------------------

least-negative-normalized-double-float,
---------------------------------------

most-negative-long-float, least-negative-long-float,
----------------------------------------------------

least-negative-normalized-long-float
------------------------------------

                                                    [Constant Variable]

Constant Value::
................

implementation-dependent.

Description::
.............

These constant variables provide a way for programs to examine the
implementation-defined limits for the various float formats.

   Of these variables, each which has "-normalized" in its name must
have a value which is a normalized float, and each which does not have
"-normalized" in its name may have a value which is either a normalized
float or a denormalized float, as appropriate.

   Of these variables, each which has "short-float" in its name must
have a value which is a short float, each which has "single-float" in
its name must have a value which is a single float, each which has
"double-float" in its name must have a value which is a double float,
and each which has "long-float" in its name must have a value which is a
long float.

*
     most-positive-short-float, most-positive-single-float,
     most-positive-double-float, most-positive-long-float

     Each of these constant variables has as its value the positive
     float of the largest magnitude (closest in value to, but not equal
     to, positive infinity) for the float format implied by its name.

*
     least-positive-short-float, least-positive-normalized-short-float,
     least-positive-single-float,
     least-positive-normalized-single-float,
     least-positive-double-float,
     least-positive-normalized-double-float, least-positive-long-float,
     least-positive-normalized-long-float

     Each of these constant variables has as its value the smallest
     positive (nonzero) float for the float format implied by its name.

*
     least-negative-short-float, least-negative-normalized-short-float,
     least-negative-single-float,
     least-negative-normalized-single-float,
     least-negative-double-float,
     least-negative-normalized-double-float, least-negative-long-float,
     least-negative-normalized-long-float

     Each of these constant variables has as its value the negative
     (nonzero) float of the smallest magnitude for the float format
     implied by its name.  (If an implementation supports minus zero as
     a different object from positive zero, this value must not be minus
     zero.)

*
     most-negative-short-float, most-negative-single-float,
     most-negative-double-float, most-negative-long-float

     Each of these constant variables has as its value the negative
     float of the largest magnitude (closest in value to, but not equal
     to, negative infinity) for the float format implied by its name.

Notes::
.......


File: gcl.info,  Node: short-float-epsilon,  Next: arithmetic-error,  Prev: most-positive-short-float,  Up: Numbers Dictionary

12.2.77 short-float-epsilon, short-float-negative-epsilon,
----------------------------------------------------------

single-float-epsilon, single-float-negative-epsilon,
----------------------------------------------------

double-float-epsilon, double-float-negative-epsilon,
----------------------------------------------------

long-float-epsilon, long-float-negative-epsilon
-----------------------------------------------

                                                    [Constant Variable]

Constant Value::
................

implementation-dependent.

Description::
.............

The value of each of the constants short-float-epsilon,
single-float-epsilon, double-float-epsilon, and long-float-epsilon is
the smallest positive float \epsilon of the given format, such that the
following expression is true when evaluated:

   (not (= (float 1 \epsilon) (+ (float 1 \epsilon) \epsilon)))\/

   The value of each of the constants short-float-negative-epsilon,
single-float-negative-epsilon, double-float-negative-epsilon, and
long-float-negative-epsilon is the smallest positive float \epsilon of
the given format, such that the following expression is true when
evaluated:

   (not (= (float 1 \epsilon) (- (float 1 \epsilon) \epsilon)))\/


File: gcl.info,  Node: arithmetic-error,  Next: arithmetic-error-operands,  Prev: short-float-epsilon,  Up: Numbers Dictionary

12.2.78 arithmetic-error [Condition Type]
-----------------------------------------

Class Precedence List::
.......................

arithmetic-error, error, serious-condition, condition, t

Description::
.............

The type arithmetic-error consists of error conditions that occur during
arithmetic operations.  The operation and operands are initialized with
the initialization arguments named :operation and :operands to
make-condition, and are accessed by the functions
arithmetic-error-operation and arithmetic-error-operands.

See Also::
..........

arithmetic-error-operation, *note arithmetic-error-operands::


File: gcl.info,  Node: arithmetic-error-operands,  Next: division-by-zero,  Prev: arithmetic-error,  Up: Numbers Dictionary

12.2.79 arithmetic-error-operands, arithmetic-error-operation [Function]
------------------------------------------------------------------------

'arithmetic-error-operands' condition => operands

   'arithmetic-error-operation' condition => operation

Arguments and Values::
......................

condition--a condition of type arithmetic-error.

   operands--a list.

   operation--a function designator.

Description::
.............

arithmetic-error-operands returns a list of the operands which were used
in the offending call to the operation that signaled the condition.

   arithmetic-error-operation returns a list of the offending operation
in the offending call that signaled the condition.

See Also::
..........

arithmetic-error, *note Conditions::

Notes::
.......


File: gcl.info,  Node: division-by-zero,  Next: floating-point-invalid-operation,  Prev: arithmetic-error-operands,  Up: Numbers Dictionary

12.2.80 division-by-zero [Condition Type]
-----------------------------------------

Class Precedence List::
.......................

division-by-zero, arithmetic-error, error, serious-condition, condition,
t

Description::
.............

The type division-by-zero consists of error conditions that occur
because of division by zero.


File: gcl.info,  Node: floating-point-invalid-operation,  Next: floating-point-inexact,  Prev: division-by-zero,  Up: Numbers Dictionary

12.2.81 floating-point-invalid-operation [Condition Type]
---------------------------------------------------------

Class Precedence List::
.......................

floating-point-invalid-operation, arithmetic-error, error,
serious-condition, condition, t

Description::
.............

The type floating-point-invalid-operation consists of error conditions
that occur because of certain floating point traps.

   It is implementation-dependent whether floating point traps occur,
and whether or how they may be enabled or disabled.  Therefore,
conforming code may establish handlers for this condition, but must not
depend on its being signaled.


File: gcl.info,  Node: floating-point-inexact,  Next: floating-point-overflow,  Prev: floating-point-invalid-operation,  Up: Numbers Dictionary

12.2.82 floating-point-inexact [Condition Type]
-----------------------------------------------

Class Precedence List::
.......................

floating-point-inexact, arithmetic-error, error, serious-condition,
condition, t

Description::
.............

The type floating-point-inexact consists of error conditions that occur
because of certain floating point traps.

   It is implementation-dependent whether floating point traps occur,
and whether or how they may be enabled or disabled.  Therefore,
conforming code may establish handlers for this condition, but must not
depend on its being signaled.


File: gcl.info,  Node: floating-point-overflow,  Next: floating-point-underflow,  Prev: floating-point-inexact,  Up: Numbers Dictionary

12.2.83 floating-point-overflow [Condition Type]
------------------------------------------------

Class Precedence List::
.......................

floating-point-overflow, arithmetic-error, error, serious-condition,
condition, t

Description::
.............

The type floating-point-overflow consists of error conditions that occur
because of floating-point overflow.


File: gcl.info,  Node: floating-point-underflow,  Prev: floating-point-overflow,  Up: Numbers Dictionary

12.2.84 floating-point-underflow [Condition Type]
-------------------------------------------------

Class Precedence List::
.......................

floating-point-underflow, arithmetic-error, error, serious-condition,
condition, t

Description::
.............

The type floating-point-underflow consists of error conditions that
occur because of floating-point underflow.


File: gcl.info,  Node: Characters,  Next: Conses,  Prev: Numbers (Numbers),  Up: Top

13 Characters
*************

* Menu:

* Character Concepts::
* Characters Dictionary::


File: gcl.info,  Node: Character Concepts,  Next: Characters Dictionary,  Prev: Characters,  Up: Characters

13.1 Character Concepts
=======================

* Menu:

* Introduction to Characters::
* Introduction to Scripts and Repertoires::
* Character Attributes::
* Character Categories::
* Identity of Characters::
* Ordering of Characters::
* Character Names::
* Treatment of Newline during Input and Output::
* Character Encodings::
* Documentation of Implementation-Defined Scripts::


File: gcl.info,  Node: Introduction to Characters,  Next: Introduction to Scripts and Repertoires,  Prev: Character Concepts,  Up: Character Concepts

13.1.1 Introduction to Characters
---------------------------------

A character is an object that represents a unitary token (e.g., a
letter, a special symbol, or a "control character") in an aggregate
quantity of text (e.g., a string or a text stream).

   Common Lisp allows an implementation to provide support for
international language characters as well as characters used in
specialized arenas (e.g., mathematics).

   The following figures contain lists of defined names applicable to
characters.

   Figure 13-1 lists some defined names relating to character attributes
and character predicates.

  alpha-char-p     char-not-equal     char>            
  alphanumericp    char-not-greaterp  char>=           
  both-case-p      char-not-lessp     digit-char-p     
  char-code-limit  char/=             graphic-char-p   
  char-equal       char<              lower-case-p     
  char-greaterp    char<=             standard-char-p  
  char-lessp       char=              upper-case-p     

       Figure 13-1: Character defined names - 1      


   Figure 13-2 lists some character construction and conversion defined
names.

  char-code      char-name    code-char   
  char-downcase  char-upcase  digit-char  
  char-int       character    name-char   

  Figure 13-2: Character defined names - 2



File: gcl.info,  Node: Introduction to Scripts and Repertoires,  Next: Character Attributes,  Prev: Introduction to Characters,  Up: Character Concepts

13.1.2 Introduction to Scripts and Repertoires
----------------------------------------------

* Menu:

* Character Scripts::
* Character Repertoires::


File: gcl.info,  Node: Character Scripts,  Next: Character Repertoires,  Prev: Introduction to Scripts and Repertoires,  Up: Introduction to Scripts and Repertoires

13.1.2.1 Character Scripts
..........................

A script is one of possibly several sets that form an exhaustive
partition of the type character.

   The number of such sets and boundaries between them is
implementation-defined.  Common Lisp does not require these sets to be
types, but an implementation is permitted to define such types as an
extension.  Since no character from one script can ever be a member of
another script, it is generally more useful to speak about character
repertoires.

   Although the term "script" is chosen for definitional compatibility
with ISO terminology, no conforming implementation is required to use
any particular scripts standardized by ISO or by any other standards
organization.

   Whether and how the script or scripts used by any given
implementation are named is implementation-dependent.


File: gcl.info,  Node: Character Repertoires,  Prev: Character Scripts,  Up: Introduction to Scripts and Repertoires

13.1.2.2 Character Repertoires
..............................

A repertoire is a type specifier for a subtype of type character.

   This term is generally used when describing a collection of
characters independent of their coding.  Characters in repertoires are
only identified by name, by glyph, or by character description.

   A repertoire can contain characters from several scripts, and a
character can appear in more than one repertoire.

   For some examples of repertoires, see the coded character standards
ISO 8859/1, ISO 8859/2, and ISO 6937/2.  Note, however, that although
the term "repertoire" is chosen for definitional compatibility with ISO
terminology, no conforming implementation is required to use repertoires
standardized by ISO or any other standards organization.


File: gcl.info,  Node: Character Attributes,  Next: Character Categories,  Prev: Introduction to Scripts and Repertoires,  Up: Character Concepts

13.1.3 Character Attributes
---------------------------

Characters have only one standardized attribute: a code.  A character's
code is a non-negative integer.  This code is composed from a character
script and a character label in an implementation-dependent way.  See
the functions char-code and code-char.

   Additional, implementation-defined attributes of characters are also
permitted so that, for example, two characters with the same code may
differ in some other, implementation-defined way.

   For any implementation-defined attribute there is a distinguished
value called the null value for that attribute.  A character for which
each implementation-defined attribute has the null value for that
attribute is called a simple character.  If the implementation has no
implementation-defined attributes, then all characters are simple
characters.


File: gcl.info,  Node: Character Categories,  Next: Identity of Characters,  Prev: Character Attributes,  Up: Character Concepts

13.1.4 Character Categories
---------------------------

There are several (overlapping) categories of characters that have no
formally associated type but that are nevertheless useful to name.  They
include graphic characters, alphabetic_1 characters, characters with
case (uppercase and lowercase characters), numeric characters,
alphanumeric characters, and digits (in a given radix).

   For each implementation-defined attribute of a character, the
documentation for that implementation must specify whether characters
that differ only in that attribute are permitted to differ in whether
are not they are members of one of the aforementioned categories.

   Note that these terms are defined independently of any special syntax
which might have been enabled in the current readtable.

* Menu:

* Graphic Characters::
* Alphabetic Characters::
* Characters With Case::
* Uppercase Characters::
* Lowercase Characters::
* Corresponding Characters in the Other Case::
* Case of Implementation-Defined Characters::
* Numeric Characters::
* Alphanumeric Characters::
* Digits in a Radix::


File: gcl.info,  Node: Graphic Characters,  Next: Alphabetic Characters,  Prev: Character Categories,  Up: Character Categories

13.1.4.1 Graphic Characters
...........................

Characters that are classified as graphic , or displayable, are each
associated with a glyph, a visual representation of the character.

   A graphic character is one that has a standard textual representation
as a single glyph, such as A or * or =.  Space, which effectively has a
blank glyph, is defined to be a graphic.

   Of the standard characters, newline is non-graphic and all others are
graphic; see *note Standard Characters::.

   Characters that are not graphic are called non-graphic .

   Non-graphic characters are sometimes informally called "formatting
characters" or "control characters."

   #\Backspace, #\Tab, #\Rubout, #\Linefeed, #\Return, and #\Page, if
they are supported by the implementation, are non-graphic.


File: gcl.info,  Node: Alphabetic Characters,  Next: Characters With Case,  Prev: Graphic Characters,  Up: Character Categories

13.1.4.2 Alphabetic Characters
..............................

The alphabetic_1 characters are a subset of the graphic characters.  Of
the standard characters, only these are the alphabetic_1 characters:

   A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

   a b c d e f g h i j k l m n o p q r s t u v w x y z

   Any implementation-defined character that has case must be
alphabetic_1.  For each implementation-defined graphic character that
has no case, it is implementation-defined whether that character is
alphabetic_1.


File: gcl.info,  Node: Characters With Case,  Next: Uppercase Characters,  Prev: Alphabetic Characters,  Up: Character Categories

13.1.4.3 Characters With Case
.............................

The characters with case are a subset of the alphabetic_1 characters.  A
character with case has the property of being either uppercase or
lowercase.  Every character with case is in one-to-one correspondence
with some other character with the opposite case.


File: gcl.info,  Node: Uppercase Characters,  Next: Lowercase Characters,  Prev: Characters With Case,  Up: Character Categories

13.1.4.4 Uppercase Characters
.............................

An uppercase character is one that has a corresponding lowercase
character that is different (and can be obtained using char-downcase).

   Of the standard characters, only these are uppercase characters:

   A B C D E F G H I J K L M N O P Q R S T U V W X Y Z


File: gcl.info,  Node: Lowercase Characters,  Next: Corresponding Characters in the Other Case,  Prev: Uppercase Characters,  Up: Character Categories

13.1.4.5 Lowercase Characters
.............................

A lowercase character is one that has a corresponding uppercase
character that is different (and can be obtained using char-upcase).

   Of the standard characters, only these are lowercase characters:

   a b c d e f g h i j k l m n o p q r s t u v w x y z


File: gcl.info,  Node: Corresponding Characters in the Other Case,  Next: Case of Implementation-Defined Characters,  Prev: Lowercase Characters,  Up: Character Categories

13.1.4.6 Corresponding Characters in the Other Case
...................................................

The uppercase standard characters A through Z mentioned above
respectively correspond to the lowercase standard characters a through z
mentioned above.  For example, the uppercase character E corresponds to
the lowercase character e, and vice versa.


File: gcl.info,  Node: Case of Implementation-Defined Characters,  Next: Numeric Characters,  Prev: Corresponding Characters in the Other Case,  Up: Character Categories

13.1.4.7 Case of Implementation-Defined Characters
..................................................

An implementation may define that other implementation-defined graphic
characters have case.  Such definitions must always be done in
pairs--one uppercase character in one-to-one correspondence with one
lowercase character.


File: gcl.info,  Node: Numeric Characters,  Next: Alphanumeric Characters,  Prev: Case of Implementation-Defined Characters,  Up: Character Categories

13.1.4.8 Numeric Characters
...........................

The numeric characters are a subset of the graphic characters.  Of the
standard characters, only these are numeric characters:

   0 1 2 3 4 5 6 7 8 9

   For each implementation-defined graphic character that has no case,
the implementation must define whether or not it is a numeric character.


File: gcl.info,  Node: Alphanumeric Characters,  Next: Digits in a Radix,  Prev: Numeric Characters,  Up: Character Categories

13.1.4.9 Alphanumeric Characters
................................

The set of alphanumeric characters is the union of the set of
alphabetic_1 characters and the set of numeric characters.


File: gcl.info,  Node: Digits in a Radix,  Prev: Alphanumeric Characters,  Up: Character Categories

13.1.4.10 Digits in a Radix
...........................

What qualifies as a digit depends on the radix (an integer between 2 and
36, inclusive).  The potential digits are:

   0 1 2 3 4 5 6 7 8 9 A B C D E F G H I J K L M N O P Q R S T U V W X Y
Z

   Their respective weights are 0, 1, 2, ...  35.  In any given radix n,
only the first n potential digits are considered to be digits.  For
example, the digits in radix 2 are 0 and 1, the digits in radix 10 are 0
through 9, and the digits in radix 16 are 0 through F.

   Case is not significant in digits; for example, in radix 16, both F
and f are digits with weight 15.


File: gcl.info,  Node: Identity of Characters,  Next: Ordering of Characters,  Prev: Character Categories,  Up: Character Concepts

13.1.5 Identity of Characters
-----------------------------

Two characters that are eql, char=, or char-equal are not necessarily
eq.


File: gcl.info,  Node: Ordering of Characters,  Next: Character Names,  Prev: Identity of Characters,  Up: Character Concepts

13.1.6 Ordering of Characters
-----------------------------

The total ordering on characters is guaranteed to have the following
properties:

*
     If two characters have the same implementation-defined attributes,
     then their ordering by char< is consistent with the numerical
     ordering by the predicate < on their code attributes.

*
     If two characters differ in any attribute, then they are not char=.

     [Reviewer Note by Barmar: I wonder if we should say that the
     ordering may be dependent on the implementation-defined
     attributes.]

*
     The total ordering is not necessarily the same as the total
     ordering on the integers produced by applying char-int to the
     characters.

*
     While alphabetic_1 standard characters of a given case must obey a
     partial ordering, they need not be contiguous; it is permissible
     for uppercase and lowercase characters to be interleaved.  Thus
     (char<= #\a x #\z) is not a valid way of determining whether or not
     x is a lowercase character.

   Of the standard characters, those which are alphanumeric obey the
following partial ordering:

      A<B<C<D<E<F<G<H<I<J<K<L<M<N<O<P<Q<R<S<T<U<V<W<X<Y<Z
      a<b<c<d<e<f<g<h<i<j<k<l<m<n<o<p<q<r<s<t<u<v<w<x<y<z
      0<1<2<3<4<5<6<7<8<9
      either 9<A or Z<0
      either 9<a or z<0

   This implies that, for standard characters, alphabetic_1 ordering
holds within each case (uppercase and lowercase), and that the numeric
characters as a group are not interleaved with alphabetic characters.
However, the ordering or possible interleaving of uppercase characters
and lowercase characters is implementation-defined.


File: gcl.info,  Node: Character Names,  Next: Treatment of Newline during Input and Output,  Prev: Ordering of Characters,  Up: Character Concepts

13.1.7 Character Names
----------------------

The following character names must be present in all conforming
implementations:

Newline
     The character that represents the division between lines.  An
     implementation must translate between #\Newline, a single-character
     representation, and whatever external representation(s) may be
     used.

Space
     The space or blank character.

   The following names are semi-standard; if an implementation supports
them, they should be used for the described characters and no others.

Rubout
     The rubout or delete character.

Page
     The form-feed or page-separator character.

Tab
     The tabulate character.

Backspace
     The backspace character.

Return
     The carriage return character.

Linefeed
     The line-feed character.

   In some implementations, one or more of these character names might
denote a standard character; for example, #\Linefeed and #\Newline might
be the same character in some implementations.


File: gcl.info,  Node: Treatment of Newline during Input and Output,  Next: Character Encodings,  Prev: Character Names,  Up: Character Concepts

13.1.8 Treatment of Newline during Input and Output
---------------------------------------------------

When the character #\Newline is written to an output file, the
implementation must take the appropriate action to produce a line
division.  This might involve writing out a record or translating
#\Newline to a CR/LF sequence.  When reading, a corresponding reverse
transformation must take place.


File: gcl.info,  Node: Character Encodings,  Next: Documentation of Implementation-Defined Scripts,  Prev: Treatment of Newline during Input and Output,  Up: Character Concepts

13.1.9 Character Encodings
--------------------------

A character is sometimes represented merely by its code, and sometimes
by another integer value which is composed from the code and all
implementation-defined attributes (in an implementation-defined way that
might vary between Lisp images even in the same implementation).  This
integer, returned by the function char-int, is called the character's
"encoding."  There is no corresponding function from a character's
encoding back to the character, since its primary intended uses include
things like hashing where an inverse operation is not really called for.


File: gcl.info,  Node: Documentation of Implementation-Defined Scripts,  Prev: Character Encodings,  Up: Character Concepts

13.1.10 Documentation of Implementation-Defined Scripts
-------------------------------------------------------

An implementation must document the character scripts it supports.  For
each character script supported, the documentation must describe at
least the following:

*
     Character labels, glyphs, and descriptions.  Character labels must
     be uniquely named using only Latin capital letters A-Z, hyphen (-),
     and digits 0-9.
*
     Reader canonicalization.  Any mechanisms by which read treats
     different characters as equivalent must be documented.
*
     The impact on char-upcase, char-downcase, and the case-sensitive
     format directives.  In particular, for each character with case,
     whether it is uppercase or lowercase, and which character is its
     equivalent in the opposite case.
*
     The behavior of the case-insensitive functions char-equal,
     char-not-equal, char-lessp, char-greaterp, char-not-greaterp, and
     char-not-lessp.
*
     The behavior of any character predicates; in particular, the
     effects of alpha-char-p, lower-case-p, upper-case-p, both-case-p,
     graphic-char-p, and alphanumericp.
*
     The interaction with file I/O, in particular, the supported coded
     character sets (for example, ISO8859/1-1987) and external encoding
     schemes supported are documented.


File: gcl.info,  Node: Characters Dictionary,  Prev: Character Concepts,  Up: Characters

13.2 Characters Dictionary
==========================

* Menu:

* character (System Class)::
* base-char::
* standard-char::
* extended-char::
* char=::
* character::
* characterp::
* alpha-char-p::
* alphanumericp::
* digit-char::
* digit-char-p::
* graphic-char-p::
* standard-char-p::
* char-upcase::
* upper-case-p::
* char-code::
* char-int::
* code-char::
* char-code-limit::
* char-name::
* name-char::


File: gcl.info,  Node: character (System Class),  Next: base-char,  Prev: Characters Dictionary,  Up: Characters Dictionary

13.2.1 character [System Class]
-------------------------------

Class Precedence List::
.......................

character, t

Description::
.............

A character is an object that represents a unitary token in an aggregate
quantity of text; see *note Character Concepts::.

   The types base-char and extended-char form an exhaustive partition of
the type character.

See Also::
..........

*note Character Concepts::, *note Sharpsign Backslash::, *note Printing
Characters::


File: gcl.info,  Node: base-char,  Next: standard-char,  Prev: character (System Class),  Up: Characters Dictionary

13.2.2 base-char [Type]
-----------------------

Supertypes::
............

base-char, character, t

Description::
.............

The type base-char is defined as the upgraded array element type of
standard-char.  An implementation can support additional subtypes of
type character (besides the ones listed in this standard) that might or
might not be supertypes of type base-char.  In addition, an
implementation can define base-char to be the same type as character.

   Base characters are distinguished in the following respects:

1.
     The type standard-char is a subrepertoire of the type base-char.
2.
     The selection of base characters that are not standard characters
     is implementation defined.
3.
     Only objects of the type base-char can be elements of a base
     string.
4.
     No upper bound is specified for the number of characters in the
     base-char repertoire; the size of that repertoire is
     implementation-defined.  The lower bound is~96, the number of
     standard characters.

   Whether a character is a base character depends on the way that an
implementation represents strings, and not any other properties of the
implementation or the host operating system.  For example, one
implementation might encode all strings as characters having 16-bit
encodings, and another might have two kinds of strings: those with
characters having 8-bit encodings and those with characters having
16-bit encodings.  In the first implementation, the type base-char is
equivalent to the type character: there is only one kind of string.  In
the second implementation, the base characters might be those characters
that could be stored in a string of characters having 8-bit encodings.
In such an implementation, the type base-char is a proper subtype of the
type character.

   The type standard-char is a

   subtype of type base-char.


File: gcl.info,  Node: standard-char,  Next: extended-char,  Prev: base-char,  Up: Characters Dictionary

13.2.3 standard-char [Type]
---------------------------

Supertypes::
............

standard-char,

   base-char,

   character, t

Description::
.............

A fixed set of 96 characters required to be present in all conforming
implementations.  Standard characters are defined in *note Standard
Characters::.

   Any character that is not simple is not a standard character.

See Also::
..........

*note Standard Characters::


File: gcl.info,  Node: extended-char,  Next: char=,  Prev: standard-char,  Up: Characters Dictionary

13.2.4 extended-char [Type]
---------------------------

Supertypes::
............

extended-char, character, t

Description::
.............

The type extended-char is equivalent to the type (and character (not
base-char)).

Notes::
.......

The type extended-char might have no elements_4 in implementations in
which all characters are of type base-char.


File: gcl.info,  Node: char=,  Next: character,  Prev: extended-char,  Up: Characters Dictionary

13.2.5 char=, char/=, char<, char>, char<=, char>=,
---------------------------------------------------

char-equal, char-not-equal, char-lessp, char-greaterp, char-not-greaterp,
-------------------------------------------------------------------------

char-not-lessp
--------------

                                                             [Function]

   'char=' &rest characters^+ => generalized-boolean

   'char/=' &rest characters^+ => generalized-boolean

   'char<' &rest characters^+ => generalized-boolean

   'char>' &rest characters^+ => generalized-boolean

   'char<=' &rest characters^+ => generalized-boolean

   'char>=' &rest characters^+ => generalized-boolean

   'char-equal' &rest characters^+ => generalized-boolean

   'char-not-equal' &rest characters^+ => generalized-boolean

   'char-lessp' &rest characters^+ => generalized-boolean

   'char-greaterp' &rest characters^+ => generalized-boolean

   'char-not-greaterp' &rest characters^+ => generalized-boolean

   'char-not-lessp' &rest characters^+ => generalized-boolean

Arguments and Values::
......................

character--a character.

   generalized-boolean--a generalized boolean.

Description::
.............

These predicates compare characters.

   char= returns true if all characters are the same; otherwise, it
returns false.

   If two characters differ in any implementation-defined attributes,
then they are not char=.

   char/= returns true if all characters are different; otherwise, it
returns false.

   char< returns true if the characters are monotonically increasing;
otherwise, it returns false.

   If two characters have identical implementation-defined attributes,
then their ordering by char< is consistent with the numerical ordering
by the predicate < on their codes.

   char> returns true if the characters are monotonically decreasing;
otherwise, it returns false.

   If two characters have identical implementation-defined attributes,
then their ordering by char> is consistent with the numerical ordering
by the predicate > on their codes.

   char<= returns true if the characters are monotonically
nondecreasing; otherwise, it returns false.

   If two characters have identical implementation-defined attributes,
then their ordering by char<= is consistent with the numerical ordering
by the predicate <= on their codes.

   char>= returns true if the characters are monotonically
nonincreasing; otherwise, it returns false.

   If two characters have identical implementation-defined attributes,
then their ordering by char>= is consistent with the numerical ordering
by the predicate >= on their codes.

   char-equal, char-not-equal, char-lessp, char-greaterp,
char-not-greaterp, and char-not-lessp are similar to char=, char/=,
char<, char>, char<=, char>=, respectively, except that they ignore
differences in case and

   might have an implementation-defined behavior for non-simple
characters.  For example, an implementation might define that
char-equal, etc.  ignore certain implementation-defined attributes.  The
effect, if any, of each implementation-defined attribute upon these
functions must be specified as part of the definition of that attribute.

Examples::
..........

      (char= #\d #\d) =>  true
      (char= #\A #\a) =>  false
      (char= #\d #\x) =>  false
      (char= #\d #\D) =>  false
      (char/= #\d #\d) =>  false
      (char/= #\d #\x) =>  true
      (char/= #\d #\D) =>  true
      (char= #\d #\d #\d #\d) =>  true
      (char/= #\d #\d #\d #\d) =>  false
      (char= #\d #\d #\x #\d) =>  false
      (char/= #\d #\d #\x #\d) =>  false
      (char= #\d #\y #\x #\c) =>  false
      (char/= #\d #\y #\x #\c) =>  true
      (char= #\d #\c #\d) =>  false
      (char/= #\d #\c #\d) =>  false
      (char< #\d #\x) =>  true
      (char<= #\d #\x) =>  true
      (char< #\d #\d) =>  false
      (char<= #\d #\d) =>  true
      (char< #\a #\e #\y #\z) =>  true
      (char<= #\a #\e #\y #\z) =>  true
      (char< #\a #\e #\e #\y) =>  false
      (char<= #\a #\e #\e #\y) =>  true
      (char> #\e #\d) =>  true
      (char>= #\e #\d) =>  true
      (char> #\d #\c #\b #\a) =>  true
      (char>= #\d #\c #\b #\a) =>  true
      (char> #\d #\d #\c #\a) =>  false
      (char>= #\d #\d #\c #\a) =>  true
      (char> #\e #\d #\b #\c #\a) =>  false
      (char>= #\e #\d #\b #\c #\a) =>  false
      (char> #\z #\A) =>  implementation-dependent
      (char> #\Z #\a) =>  implementation-dependent
      (char-equal #\A #\a) =>  true
      (stable-sort (list #\b #\A #\B #\a #\c #\C) #'char-lessp)
     =>  (#\A #\a #\b #\B #\c #\C)
      (stable-sort (list #\b #\A #\B #\a #\c #\C) #'char<)
     =>  (#\A #\B #\C #\a #\b #\c) ;Implementation A
     =>  (#\a #\b #\c #\A #\B #\C) ;Implementation B
     =>  (#\a #\A #\b #\B #\c #\C) ;Implementation C
     =>  (#\A #\a #\B #\b #\C #\c) ;Implementation D
     =>  (#\A #\B #\a #\b #\C #\c) ;Implementation E

Exceptional Situations::
........................

Should signal an error of type program-error if at least one character
is not supplied.

See Also::
..........

*note Character Syntax::, *note Documentation of Implementation-Defined
Scripts::

Notes::
.......

If characters differ in their code attribute or any
implementation-defined attribute, they are considered to be different by
char=.

   There is no requirement that (eq c1 c2) be true merely because (char=
c1 c2) is true.  While eq can distinguish two characters that char= does
not, it is distinguishing them not as characters, but in some sense on
the basis of a lower level implementation characteristic.  If (eq c1 c2)
is true, then (char= c1 c2) is also true.  eql and equal compare
characters in the same way that char= does.

   The manner in which case is used by char-equal, char-not-equal,
char-lessp, char-greaterp, char-not-greaterp, and char-not-lessp implies
an ordering for standard characters such that A=a, B=b, and so on, up to
Z=z, and furthermore either 9<A or Z<0.


File: gcl.info,  Node: character,  Next: characterp,  Prev: char=,  Up: Characters Dictionary

13.2.6 character [Function]
---------------------------

'character' character => denoted-character

Arguments and Values::
......................

character--a character designator.

   denoted-character--a character.

Description::
.............

Returns the character denoted by the character designator.

Examples::
..........

      (character #\a) =>  #\a
      (character "a") =>  #\a
      (character 'a) =>  #\A
      (character '\a) =>  #\a
      (character 65.) is an error.
      (character 'apple) is an error.

Exceptional Situations::
........................

Should signal an error of type type-error if object is not a character
designator.

See Also::
..........

*note coerce::

Notes::
.......

      (character object) == (coerce object 'character)


File: gcl.info,  Node: characterp,  Next: alpha-char-p,  Prev: character,  Up: Characters Dictionary

13.2.7 characterp [Function]
----------------------------

'characterp' object => generalized-boolean

Arguments and Values::
......................

object--an object.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if object is of type character; otherwise, returns false.

Examples::
..........

      (characterp #\a) =>  true
      (characterp 'a) =>  false
      (characterp "a") =>  false
      (characterp 65.) =>  false
      (characterp #\Newline) =>  true
      ;; This next example presupposes an implementation
      ;; in which #\Rubout is an implementation-defined character.
      (characterp #\Rubout) =>  true

See Also::
..........

*note character:: (type and function), *note typep::

Notes::
.......

      (characterp object) == (typep object 'character)


File: gcl.info,  Node: alpha-char-p,  Next: alphanumericp,  Prev: characterp,  Up: Characters Dictionary

13.2.8 alpha-char-p [Function]
------------------------------

'alpha-char-p' character => generalized-boolean

Arguments and Values::
......................

character--a character.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if character is an alphabetic_1 character; otherwise,
returns false.

Examples::
..........

      (alpha-char-p #\a) =>  true
      (alpha-char-p #\5) =>  false
      (alpha-char-p #\Newline) =>  false
      ;; This next example presupposes an implementation
      ;; in which #\\alpha is a defined character.
      (alpha-char-p #\\alpha) =>  implementation-dependent

Affected By::
.............

None.  (In particular, the results of this predicate are independent of
any special syntax which might have been enabled in the current
readtable.)

Exceptional Situations::
........................

Should signal an error of type type-error if character is not a
character.

See Also::
..........

*note alphanumericp:: , *note Documentation of Implementation-Defined
Scripts::


File: gcl.info,  Node: alphanumericp,  Next: digit-char,  Prev: alpha-char-p,  Up: Characters Dictionary

13.2.9 alphanumericp [Function]
-------------------------------

'alphanumericp' character => generalized-boolean

Arguments and Values::
......................

character--a character.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if character is an alphabetic_1 character or a numeric
character; otherwise, returns false.

Examples::
..........

      (alphanumericp #\Z) =>  true
      (alphanumericp #\9) =>  true
      (alphanumericp #\Newline) =>  false
      (alphanumericp #\#) =>  false

Affected By::
.............

None.  (In particular, the results of this predicate are independent of
any special syntax which might have been enabled in the current
readtable.)

Exceptional Situations::
........................

Should signal an error of type type-error if character is not a
character.

See Also::
..........

*note alpha-char-p:: , *note graphic-char-p:: , *note digit-char-p::

Notes::
.......

Alphanumeric characters are graphic as defined by graphic-char-p.  The
alphanumeric characters are a subset of the graphic characters.  The
standard characters A through Z, a through z, and 0 through 9 are
alphanumeric characters.

      (alphanumericp x)
        == (or (alpha-char-p x) (not (null (digit-char-p x))))


File: gcl.info,  Node: digit-char,  Next: digit-char-p,  Prev: alphanumericp,  Up: Characters Dictionary

13.2.10 digit-char [Function]
-----------------------------

'digit-char' weight &optional radix => char

Arguments and Values::
......................

weight--a non-negative integer.

   radix--a radix.  The default is 10.

   char--a character or false.

Description::
.............

If weight is less than radix, digit-char returns a character which has
that weight when considered as a digit in the specified radix.  If the
resulting character is to be an alphabetic_1 character, it will be an
uppercase character.

   If weight is greater than or equal to radix, digit-char returns
false.

Examples::
..........

      (digit-char 0) =>  #\0
      (digit-char 10 11) =>  #\A
      (digit-char 10 10) =>  false
      (digit-char 7) =>  #\7
      (digit-char 12) =>  false
      (digit-char 12 16) =>  #\C  ;not #\c
      (digit-char 6 2) =>  false
      (digit-char 1 2) =>  #\1

See Also::
..........

*note digit-char-p:: , *note graphic-char-p:: , *note Character Syntax::

Notes::
.......


File: gcl.info,  Node: digit-char-p,  Next: graphic-char-p,  Prev: digit-char,  Up: Characters Dictionary

13.2.11 digit-char-p [Function]
-------------------------------

'digit-char-p' char &optional radix => weight

Arguments and Values::
......................

char--a character.

   radix--a radix.  The default is 10.

   weight--either a non-negative integer less than radix, or false.

Description::
.............

Tests whether char is a digit in the specified radix (i.e., with a
weight less than radix).  If it is a digit in that radix, its weight is
returned as an integer; otherwise nil is returned.

Examples::
..........

      (digit-char-p #\5)    =>  5
      (digit-char-p #\5 2)  =>  false
      (digit-char-p #\A)    =>  false
      (digit-char-p #\a)    =>  false
      (digit-char-p #\A 11) =>  10
      (digit-char-p #\a 11) =>  10
      (mapcar #'(lambda (radix)
                  (map 'list #'(lambda (x) (digit-char-p x radix))
                       "059AaFGZ"))
              '(2 8 10 16 36))
      =>  ((0 NIL NIL NIL NIL NIL NIL NIL)
          (0 5 NIL NIL NIL NIL NIL NIL)
          (0 5 9 NIL NIL NIL NIL NIL)
          (0 5 9 10 10 15 NIL NIL)
          (0 5 9 10 10 15 16 35))

Affected By::
.............

None.  (In particular, the results of this predicate are independent of
any special syntax which might have been enabled in the current
readtable.)

See Also::
..........

*note alphanumericp::

Notes::
.......

Digits are graphic characters.


File: gcl.info,  Node: graphic-char-p,  Next: standard-char-p,  Prev: digit-char-p,  Up: Characters Dictionary

13.2.12 graphic-char-p [Function]
---------------------------------

'graphic-char-p' char => generalized-boolean

Arguments and Values::
......................

char--a character.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if character is a graphic character; otherwise, returns
false.

Examples::
..........

      (graphic-char-p #\G) =>  true
      (graphic-char-p #\#) =>  true
      (graphic-char-p #\Space) =>  true
      (graphic-char-p #\Newline) =>  false

Exceptional Situations::
........................

Should signal an error of type type-error if character is not a
character.

See Also::
..........

*note read:: , *note Character Syntax::, *note Documentation of
Implementation-Defined Scripts::


File: gcl.info,  Node: standard-char-p,  Next: char-upcase,  Prev: graphic-char-p,  Up: Characters Dictionary

13.2.13 standard-char-p [Function]
----------------------------------

'standard-char-p' character => generalized-boolean

Arguments and Values::
......................

character--a character.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if character is of type standard-char; otherwise, returns
false.

Examples::
..........

      (standard-char-p #\Space) =>  true
      (standard-char-p #\~) =>  true
      ;; This next example presupposes an implementation
      ;; in which #\Bell is a defined character.
      (standard-char-p #\Bell) =>  false

Exceptional Situations::
........................

Should signal an error of type type-error if character is not a
character.


File: gcl.info,  Node: char-upcase,  Next: upper-case-p,  Prev: standard-char-p,  Up: Characters Dictionary

13.2.14 char-upcase, char-downcase [Function]
---------------------------------------------

'char-upcase' character => corresponding-character

   'char-downcase' character => corresponding-character

Arguments and Values::
......................

character, corresponding-character--a character.

Description::
.............

If character is a lowercase character, char-upcase returns the
corresponding uppercase character.  Otherwise, char-upcase just returns
the given character.

   If character is an uppercase character, char-downcase returns the
corresponding lowercase character.  Otherwise, char-downcase just
returns the given character.

   The result only ever differs from character in its code attribute;
all implementation-defined attributes are preserved.

Examples::
..........

      (char-upcase #\a) =>  #\A
      (char-upcase #\A) =>  #\A
      (char-downcase #\a) =>  #\a
      (char-downcase #\A) =>  #\a
      (char-upcase #\9) =>  #\9
      (char-downcase #\9) =>  #\9
      (char-upcase #\@) =>  #\@
      (char-downcase #\@) =>  #\@
      ;; Note that this next example might run for a very long time in
      ;; some implementations if CHAR-CODE-LIMIT happens to be very large
      ;; for that implementation.
      (dotimes (code char-code-limit)
        (let ((char (code-char code)))
          (when char
            (unless (cond ((upper-case-p char) (char= (char-upcase (char-downcase char)) char))
                          ((lower-case-p char) (char= (char-downcase (char-upcase char)) char))
                          (t (and (char= (char-upcase (char-downcase char)) char)
                                  (char= (char-downcase (char-upcase char)) char))))
              (return char)))))
     =>  NIL

Exceptional Situations::
........................

Should signal an error of type type-error if character is not a
character.

See Also::
..........

*note upper-case-p:: , *note alpha-char-p:: , *note Characters With
Case::, *note Documentation of Implementation-Defined Scripts::

Notes::
.......

If the corresponding-char is different than character, then both the
character and the corresponding-char have case.

   Since char-equal ignores the case of the characters it compares, the
corresponding-character is always the same as character under
char-equal.


File: gcl.info,  Node: upper-case-p,  Next: char-code,  Prev: char-upcase,  Up: Characters Dictionary

13.2.15 upper-case-p, lower-case-p, both-case-p [Function]
----------------------------------------------------------

'upper-case-p' character => generalized-boolean

   'lower-case-p' character => generalized-boolean

   'both-case-p' character => generalized-boolean

Arguments and Values::
......................

character--a character.

   generalized-boolean--a generalized boolean.

Description::
.............

These functions test the case of a given character.

   upper-case-p returns true if character is an uppercase character;
otherwise, returns false.

   lower-case-p returns true if character is a lowercase character;
otherwise, returns false.

   both-case-p returns true if character is a character with case;
otherwise, returns false.

Examples::
..........

      (upper-case-p #\A) =>  true
      (upper-case-p #\a) =>  false
      (both-case-p #\a) =>  true
      (both-case-p #\5) =>  false
      (lower-case-p #\5) =>  false
      (upper-case-p #\5) =>  false
      ;; This next example presupposes an implementation
      ;; in which #\Bell is an implementation-defined character.
      (lower-case-p #\Bell) =>  false

Exceptional Situations::
........................

Should signal an error of type type-error if character is not a
character.

See Also::
..........

*note char-upcase:: , char-downcase, *note Characters With Case::, *note
Documentation of Implementation-Defined Scripts::


File: gcl.info,  Node: char-code,  Next: char-int,  Prev: upper-case-p,  Up: Characters Dictionary

13.2.16 char-code [Function]
----------------------------

'char-code' character => code

Arguments and Values::
......................

character--a character.

   code--a character code.

Description::
.............

char-code returns the code attribute of character.

Examples::
..........

     ;; An implementation using ASCII character encoding
     ;; might return these values:
     (char-code #\$) =>  36
     (char-code #\a) =>  97

Exceptional Situations::
........................

Should signal an error of type type-error if character is not a
character.

See Also::
..........

*note char-code-limit::


File: gcl.info,  Node: char-int,  Next: code-char,  Prev: char-code,  Up: Characters Dictionary

13.2.17 char-int [Function]
---------------------------

'char-int' character => integer

Arguments and Values::
......................

character--a character.

   integer--a non-negative integer.

Description::
.............

Returns a non-negative integer encoding the character object.  The
manner in which the integer is computed is implementation-dependent.  In
contrast to sxhash, the result is not guaranteed to be independent of
the particular Lisp image.

   If character has no implementation-defined attributes, the results of
char-int and char-code are the same.

      (char= c1 c2) == (= (char-int c1) (char-int c2))

   for characters c1 and c2.

Examples::
..........

      (char-int #\A) =>  65       ; implementation A
      (char-int #\A) =>  577      ; implementation B
      (char-int #\A) =>  262145   ; implementation C

See Also::
..........

*note char-code::


File: gcl.info,  Node: code-char,  Next: char-code-limit,  Prev: char-int,  Up: Characters Dictionary

13.2.18 code-char [Function]
----------------------------

'code-char' code => char-p

Arguments and Values::
......................

code--a character code.

   char-p--a character or nil.

Description::
.............

Returns a character with the code attribute given by code.  If no such
character exists and one cannot be created, nil is returned.

Examples::
..........

     (code-char 65.) =>  #\A  ;in an implementation using ASCII codes
     (code-char (char-code #\Space)) =>  #\Space  ;in any implementation

Affected By::
.............

The implementation's character encoding.

See Also::
..........

*note char-code::

Notes::
.......


File: gcl.info,  Node: char-code-limit,  Next: char-name,  Prev: code-char,  Up: Characters Dictionary

13.2.19 char-code-limit [Constant Variable]
-------------------------------------------

Constant Value::
................

A non-negative integer, the exact magnitude of which is
implementation-dependent, but which is not less than 96 (the number of
standard characters).

Description::
.............

The upper exclusive bound on the value returned by the function
char-code.

See Also::
..........

*note char-code::

Notes::
.......

The value of char-code-limit might be larger than the actual number of
characters supported by the implementation.


File: gcl.info,  Node: char-name,  Next: name-char,  Prev: char-code-limit,  Up: Characters Dictionary

13.2.20 char-name [Function]
----------------------------

'char-name' character => name

Arguments and Values::
......................

character--a character.

   name--a string or nil.

Description::
.............

Returns a string that is the name of the character, or nil if the
character has no name.

   All non-graphic characters are required to have names unless they
have some implementation-defined attribute which is not null.  Whether
or not other characters have names is implementation-dependent.

   The standard characters <Newline> and <Space> have the respective
names "Newline" and "Space".  The semi-standard characters <Tab>,
<Page>, <Rubout>, <Linefeed>, <Return>, and <Backspace> (if they are
supported by the implementation) have the respective names "Tab",
"Page", "Rubout", "Linefeed", "Return", and "Backspace" (in the
indicated case, even though name lookup by "#\" and by the function
name-char is not case sensitive).

Examples::
..........

      (char-name #\ ) =>  "Space"
      (char-name #\Space) =>  "Space"
      (char-name #\Page) =>  "Page"

      (char-name #\a)
     =>  NIL
     OR=> "LOWERCASE-a"
     OR=> "Small-A"
     OR=> "LA01"

      (char-name #\A)
     =>  NIL
     OR=> "UPPERCASE-A"
     OR=> "Capital-A"
     OR=> "LA02"

      ;; Even though its CHAR-NAME can vary, #\A prints as #\A
      (prin1-to-string (read-from-string (format nil "#\\~A" (or (char-name #\A) "A"))))
     =>  "#\\A"

Exceptional Situations::
........................

Should signal an error of type type-error if character is not a
character.

See Also::
..........

*note name-char:: , *note Printing Characters::

Notes::
.......

Non-graphic characters having names are written by the Lisp printer as
"#\" followed by the their name; see *note Printing Characters::.


File: gcl.info,  Node: name-char,  Prev: char-name,  Up: Characters Dictionary

13.2.21 name-char [Function]
----------------------------

'name-char' name => char-p

Arguments and Values::
......................

name--a string designator.

   char-p--a character or nil.

Description::
.............

Returns the character object whose name is name (as determined by
string-equal--i.e., lookup is not case sensitive).  If such a character
does not exist, nil is returned.

Examples::
..........

     (name-char 'space) =>  #\Space
     (name-char "space") =>  #\Space
     (name-char "Space") =>  #\Space
     (let ((x (char-name #\a)))
       (or (not x) (eql (name-char x) #\a))) =>  true

Exceptional Situations::
........................

Should signal an error of type type-error if name is not a string
designator.

See Also::
..........

*note char-name::


File: gcl.info,  Node: Conses,  Next: Arrays,  Prev: Characters,  Up: Top

14 Conses
*********

* Menu:

* Cons Concepts::
* Conses Dictionary::


File: gcl.info,  Node: Cons Concepts,  Next: Conses Dictionary,  Prev: Conses,  Up: Conses

14.1 Cons Concepts
==================

A cons is a compound data object having two components called the car
and the cdr.

  car  cons    rplacd  
  cdr  rplaca          

  Figure 14-1: Some defined names relating to conses.


   Depending on context, a group of connected conses can be viewed in a
variety of different ways.  A variety of operations is provided to
support each of these various views.

* Menu:

* Conses as Trees::
* Conses as Lists::


File: gcl.info,  Node: Conses as Trees,  Next: Conses as Lists,  Prev: Cons Concepts,  Up: Cons Concepts

14.1.1 Conses as Trees
----------------------

A tree is a binary recursive data structure made up of conses and atoms:
the conses are themselves also trees (sometimes called "subtrees" or
"branches"), and the atoms are terminal nodes (sometimes called leaves
).  Typically, the leaves represent data while the branches establish
some relationship among that data.

  caaaar  caddar  cdar       nsubst         
  caaadr  cadddr  cddaar     nsubst-if      
  caaar   caddr   cddadr     nsubst-if-not  
  caadar  cadr    cddar      nthcdr         
  caaddr  cdaaar  cdddar     sublis         
  caadr   cdaadr  cddddr     subst          
  caar    cdaar   cdddr      subst-if       
  cadaar  cdadar  cddr       subst-if-not   
  cadadr  cdaddr  copy-tree  tree-equal     
  cadar   cdadr   nsublis                   

  Figure 14-2: Some defined names relating to trees.


* Menu:

* General Restrictions on Parameters that must be Trees::


File: gcl.info,  Node: General Restrictions on Parameters that must be Trees,  Prev: Conses as Trees,  Up: Conses as Trees

14.1.1.1 General Restrictions on Parameters that must be Trees
..............................................................

Except as explicitly stated otherwise, for any standardized function
that takes a parameter that is required to be a tree, the consequences
are undefined if that tree is circular.


File: gcl.info,  Node: Conses as Lists,  Prev: Conses as Trees,  Up: Cons Concepts

14.1.2 Conses as Lists
----------------------

A list is a chain of conses in which the car of each cons is an element
of the list, and the cdr of each cons is either the next link in the
chain or a terminating atom.

   A proper list is a list terminated by the empty list.  The empty list
is a proper list, but is not a cons.

   An improper list is a list that is not a proper list; that is, it is
a circular list or a dotted list.

   A dotted list is a list that has a terminating atom that is not the
empty list.  A non-nil atom by itself is not considered to be a list of
any kind--not even a dotted list.

   A circular list is a chain of conses that has no termination because
some cons in the chain is the cdr of a later cons.

  append      last           nbutlast  rest       
  butlast     ldiff          nconc     revappend  
  copy-alist  list           ninth     second     
  copy-list   list*          nreconc   seventh    
  eighth      list-length    nth       sixth      
  endp        make-list      nthcdr    tailp      
  fifth       member         pop       tenth      
  first       member-if      push      third      
  fourth      member-if-not  pushnew              

  Figure 14-3: Some defined names relating to lists.


* Menu:

* Lists as Association Lists::
* Lists as Sets::
* General Restrictions on Parameters that must be Lists::


File: gcl.info,  Node: Lists as Association Lists,  Next: Lists as Sets,  Prev: Conses as Lists,  Up: Conses as Lists

14.1.2.1 Lists as Association Lists
...................................

An association list is a list of conses representing an association of
keys with values, where the car of each cons is the key and the cdr is
the value associated with that key.

  acons  assoc-if      pairlis  rassoc-if      
  assoc  assoc-if-not  rassoc   rassoc-if-not  

  Figure 14-4: Some defined names related to assocation lists.



File: gcl.info,  Node: Lists as Sets,  Next: General Restrictions on Parameters that must be Lists,  Prev: Lists as Association Lists,  Up: Conses as Lists

14.1.2.2 Lists as Sets
......................

Lists are sometimes viewed as sets by considering their elements
unordered and by assuming there is no duplication of elements.

  adjoin         nset-difference    set-difference    union  
  intersection   nset-exclusive-or  set-exclusive-or         
  nintersection  nunion             subsetp                  

       Figure 14-5: Some defined names related to sets.     



File: gcl.info,  Node: General Restrictions on Parameters that must be Lists,  Prev: Lists as Sets,  Up: Conses as Lists

14.1.2.3 General Restrictions on Parameters that must be Lists
..............................................................

Except as explicitly specified otherwise, any standardized function that
takes a parameter that is required to be a list should be prepared to
signal an error of type type-error if the value received is a dotted
list.

   Except as explicitly specified otherwise, for any standardized
function that takes a parameter that is required to be a list, the
consequences are undefined if that list is circular.


File: gcl.info,  Node: Conses Dictionary,  Prev: Cons Concepts,  Up: Conses

14.2 Conses Dictionary
======================

* Menu:

* list (System Class)::
* null (System Class)::
* cons (System Class)::
* atom (Type)::
* cons::
* consp::
* atom::
* rplaca::
* car::
* copy-tree::
* sublis::
* subst::
* tree-equal::
* copy-list::
* list (Function)::
* list-length::
* listp::
* make-list::
* push::
* pop::
* first::
* nth::
* endp::
* null::
* nconc::
* append::
* revappend::
* butlast::
* last::
* ldiff::
* nthcdr::
* rest::
* member (Function)::
* mapc::
* acons::
* assoc::
* copy-alist::
* pairlis::
* rassoc::
* get-properties::
* getf::
* remf::
* intersection::
* adjoin::
* pushnew::
* set-difference::
* set-exclusive-or::
* subsetp::
* union::


File: gcl.info,  Node: list (System Class),  Next: null (System Class),  Prev: Conses Dictionary,  Up: Conses Dictionary

14.2.1 list [System Class]
--------------------------

Class Precedence List::
.......................

list, sequence, t

Description::
.............

A list is a chain of conses in which the car of each cons is an element
of the list, and the cdr of each cons is either the next link in the
chain or a terminating atom.

   A proper list is a chain of conses terminated by the empty list , (),
which is itself a proper list.  A dotted list is a list which has a
terminating atom that is not the empty list.  A circular list is a chain
of conses that has no termination because some cons in the chain is the
cdr of a later cons.

   Dotted lists and circular lists are also lists, but usually the
unqualified term "list" within this specification means proper list.
Nevertheless, the type list unambiguously includes dotted lists and
circular lists.

   For each element of a list there is a cons.  The empty list has no
elements and is not a cons.

   The types cons and null form an exhaustive partition of the type
list.

See Also::
..........

*note Left-Parenthesis::, *note Printing Lists and Conses::


File: gcl.info,  Node: null (System Class),  Next: cons (System Class),  Prev: list (System Class),  Up: Conses Dictionary

14.2.2 null [System Class]
--------------------------

Class Precedence List::
.......................

null, symbol, list, sequence, t

Description::
.............

The only object of type null is nil, which represents the empty list and
can also be notated ().

See Also::
..........

*note Symbols as Tokens::, *note Left-Parenthesis::, *note Printing
Symbols::


File: gcl.info,  Node: cons (System Class),  Next: atom (Type),  Prev: null (System Class),  Up: Conses Dictionary

14.2.3 cons [System Class]
--------------------------

Class Precedence List::
.......................

cons, list, sequence, t

Description::
.............

A cons is a compound object having two components, called the car and
cdr.  These form a dotted pair.  Each component can be any object.

Compound Type Specifier Kind::
..............................

Specializing.

Compound Type Specifier Syntax::
................................

('cons'{[car-typespec [cdr-typespec]]})

Compound Type Specifier Arguments::
...................................

car-typespec--a type specifier, or the symbol *.  The default is the
symbol *.

   cdr-typespec--a type specifier, or the symbol *.  The default is the
symbol *.

Compound Type Specifier Description::
.....................................

This denotes the set of conses whose car is constrained to be of type
car-typespec and whose cdr is constrained to be of type cdr-typespec.
(If either car-typespec or cdr-typespec is *, it is as if the type t had
been denoted.)

See Also::
..........

*note Left-Parenthesis::, *note Printing Lists and Conses::


File: gcl.info,  Node: atom (Type),  Next: cons,  Prev: cons (System Class),  Up: Conses Dictionary

14.2.4 atom [Type]
------------------

Supertypes::
............

atom, t

Description::
.............

It is equivalent to (not cons).


File: gcl.info,  Node: cons,  Next: consp,  Prev: atom (Type),  Up: Conses Dictionary

14.2.5 cons [Function]
----------------------

'cons' object-1 object-2 => cons

Arguments and Values::
......................

object-1--an object.

   object-2--an object.

   cons--a cons.

Description::
.............

Creates a fresh cons, the car of which is object-1 and the cdr of which
is object-2.

Examples::
..........

      (cons 1 2) =>  (1 . 2)
      (cons 1 nil) =>  (1)
      (cons nil 2) =>  (NIL . 2)
      (cons nil nil) =>  (NIL)
      (cons 1 (cons 2 (cons 3 (cons 4 nil)))) =>  (1 2 3 4)
      (cons 'a 'b) =>  (A . B)
      (cons 'a (cons 'b (cons 'c '()))) =>  (A B C)
      (cons 'a '(b c d)) =>  (A B C D)

See Also::
..........

*note list (Function)::

Notes::
.......

If object-2 is a list, cons can be thought of as producing a new list
which is like it but has object-1 prepended.


File: gcl.info,  Node: consp,  Next: atom,  Prev: cons,  Up: Conses Dictionary

14.2.6 consp [Function]
-----------------------

'consp' object => generalized-boolean

Arguments and Values::
......................

object--an object.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if object is of type cons; otherwise, returns false.

Examples::
..........

      (consp nil) =>  false
      (consp (cons 1 2)) =>  true

   The empty list is not a cons, so

      (consp '()) == (consp 'nil) =>  false

See Also::
..........

*note listp::

Notes::
.......

      (consp object) == (typep object 'cons) == (not (typep object 'atom)) == (typep object '(not atom))


File: gcl.info,  Node: atom,  Next: rplaca,  Prev: consp,  Up: Conses Dictionary

14.2.7 atom [Function]
----------------------

'atom' object => generalized-boolean

Arguments and Values::
......................

object--an object.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if object is of type atom; otherwise, returns false.

Examples::
..........

      (atom 'sss) =>  true
      (atom (cons 1 2)) =>  false
      (atom nil) =>  true
      (atom '()) =>  true
      (atom 3) =>  true

Notes::
.......

      (atom object) == (typep object 'atom) == (not (consp object))
      == (not (typep object 'cons)) == (typep object '(not cons))


File: gcl.info,  Node: rplaca,  Next: car,  Prev: atom,  Up: Conses Dictionary

14.2.8 rplaca, rplacd [Function]
--------------------------------

'rplaca' cons object => cons

   'rplacd' cons object => cons

Pronunciation::
...............

rplaca: pronounced ,r\=e 'plak e or pronounced ,re 'plak e

   rplacd: pronounced ,r\=e 'plak de or pronounced ,re 'plak de or
pronounced ,r\=e 'plak d\=e or pronounced ,re 'plak d\=e

Arguments and Values::
......................

cons--a cons.

   object--an object.

Description::
.............

rplaca replaces the car of the cons with object.

   rplacd replaces the cdr of the cons with object.

Examples::
..........

      (defparameter *some-list* (list* 'one 'two 'three 'four)) =>  *some-list*
      *some-list* =>  (ONE TWO THREE . FOUR)
      (rplaca *some-list* 'uno) =>  (UNO TWO THREE . FOUR)
      *some-list* =>  (UNO TWO THREE . FOUR)
      (rplacd (last *some-list*) (list 'IV)) =>  (THREE IV)
      *some-list* =>  (UNO TWO THREE IV)

Side Effects::
..............

The cons is modified.

   Should signal an error of type type-error if cons is not a cons.


File: gcl.info,  Node: car,  Next: copy-tree,  Prev: rplaca,  Up: Conses Dictionary

14.2.9 car, cdr,
----------------

caar, cadr, cdar, cddr,
-----------------------

caaar, caadr, cadar, caddr, cdaar, cdadr, cddar, cdddr,
-------------------------------------------------------

caaaar, caaadr, caadar, caaddr, cadaar, cadadr, caddar, cadddr,
---------------------------------------------------------------

cdaaar, cdaadr, cdadar, cdaddr, cddaar, cddadr, cdddar, cddddr
--------------------------------------------------------------

                                                             [Accessor]

   'car' x => object (setf ('car' x) new-object)

   'cdr' x => object (setf ('cdr' x) new-object)

   '\vksip 5pt' x => object (setf ('\vksip 5pt' x) new-object)

   'caar' x => object (setf ('caar' x) new-object)

   'cadr' x => object (setf ('cadr' x) new-object)

   'cdar' x => object (setf ('cdar' x) new-object)

   'cddr' x => object (setf ('cddr' x) new-object)

   '\vksip 5pt' x => object (setf ('\vksip 5pt' x) new-object)

   'caaar' x => object (setf ('caaar' x) new-object)

   'caadr' x => object (setf ('caadr' x) new-object)

   'cadar' x => object (setf ('cadar' x) new-object)

   'caddr' x => object (setf ('caddr' x) new-object)

   'cdaar' x => object (setf ('cdaar' x) new-object)

   'cdadr' x => object (setf ('cdadr' x) new-object)

   'cddar' x => object (setf ('cddar' x) new-object)

   'cdddr' x => object (setf ('cdddr' x) new-object)

   '\vksip 5pt' x => object (setf ('\vksip 5pt' x) new-object)

   'caaaar' x => object (setf ('caaaar' x) new-object)

   'caaadr' x => object (setf ('caaadr' x) new-object)

   'caadar' x => object (setf ('caadar' x) new-object)

   'caaddr' x => object (setf ('caaddr' x) new-object)

   'cadaar' x => object (setf ('cadaar' x) new-object)

   'cadadr' x => object (setf ('cadadr' x) new-object)

   'caddar' x => object (setf ('caddar' x) new-object)

   'cadddr' x => object (setf ('cadddr' x) new-object)

   'cdaaar' x => object (setf ('cdaaar' x) new-object)

   'cdaadr' x => object (setf ('cdaadr' x) new-object)

   'cdadar' x => object (setf ('cdadar' x) new-object)

   'cdaddr' x => object (setf ('cdaddr' x) new-object)

   'cddaar' x => object (setf ('cddaar' x) new-object)

   'cddadr' x => object (setf ('cddadr' x) new-object)

   'cdddar' x => object (setf ('cdddar' x) new-object)

   'cddddr' x => object (setf ('cddddr' x) new-object)

Pronunciation::
...............

cadr: pronounced 'ka ,de r

   caddr: pronounced 'kad e ,de r or pronounced 'ka ,dude r

   cdr: pronounced 'ku ,de r

   cddr: pronounced 'kud e ,de r or pronounced 'ke ,dude r

Arguments and Values::
......................

x--a list.

   object--an object.

   new-object--an object.

Description::
.............

If x is a cons, car returns the car of that cons.  If x is nil, car
returns nil.

   If x is a cons, cdr returns the cdr of that cons.  If x is nil, cdr
returns nil.

   Functions are provided which perform compositions of up to four car
and cdr operations.  Their names consist of a C, followed by two, three,
or four occurrences of A or D, and finally an R.  The series of A's and
D's in each function's name is chosen to identify the series of car and
cdr operations that is performed by the function.  The order in which
the A's and D's appear is the inverse of the order in which the
corresponding operations are performed.  Figure 14-6 defines the
relationships precisely.

  This place ...  Is equivalent to this place ...  
  (caar x)        (car (car x))                    
  (cadr x)        (car (cdr x))                    
  (cdar x)        (cdr (car x))                    
  (cddr x)        (cdr (cdr x))                    
  (caaar x)       (car (car (car x)))              
  (caadr x)       (car (car (cdr x)))              
  (cadar x)       (car (cdr (car x)))              
  (caddr x)       (car (cdr (cdr x)))              
  (cdaar x)       (cdr (car (car x)))              
  (cdadr x)       (cdr (car (cdr x)))              
  (cddar x)       (cdr (cdr (car x)))              
  (cdddr x)       (cdr (cdr (cdr x)))              
  (caaaar x)      (car (car (car (car x))))        
  (caaadr x)      (car (car (car (cdr x))))        
  (caadar x)      (car (car (cdr (car x))))        
  (caaddr x)      (car (car (cdr (cdr x))))        
  (cadaar x)      (car (cdr (car (car x))))        
  (cadadr x)      (car (cdr (car (cdr x))))        
  (caddar x)      (car (cdr (cdr (car x))))        
  (cadddr x)      (car (cdr (cdr (cdr x))))        
  (cdaaar x)      (cdr (car (car (car x))))        
  (cdaadr x)      (cdr (car (car (cdr x))))        
  (cdadar x)      (cdr (car (cdr (car x))))        
  (cdaddr x)      (cdr (car (cdr (cdr x))))        
  (cddaar x)      (cdr (cdr (car (car x))))        
  (cddadr x)      (cdr (cdr (car (cdr x))))        
  (cdddar x)      (cdr (cdr (cdr (car x))))        
  (cddddr x)      (cdr (cdr (cdr (cdr x))))        

         Figure 14-6: CAR and CDR variants        


   setf can also be used with any of these functions to change an
existing component of x, but setf will not make new components.  So, for
example, the car of a cons can be assigned with setf of car, but the car
of nil cannot be assigned with setf of car.  Similarly, the car of the
car of a cons whose car is a cons can be assigned with setf of caar, but
neither nil nor a cons whose car is nil can be assigned with setf of
caar.

   The argument x is permitted to be a dotted list or a circular list.

Examples::
..........

      (car nil) =>  NIL
      (cdr '(1 . 2)) =>  2
      (cdr '(1 2)) =>  (2)
      (cadr '(1 2)) =>  2
      (car '(a b c)) =>  A
      (cdr '(a b c)) =>  (B C)

Exceptional Situations::
........................

The functions car and cdr should signal type-error if they receive an
argument which is not a list.  The other functions (caar, cadr, ...
cddddr) should behave for the purpose of error checking as if defined by
appropriate calls to car and cdr.

See Also::
..........

*note rplaca:: , *note first:: , *note rest::

Notes::
.......

The car of a cons can also be altered by using rplaca, and the cdr of a
cons can be altered by using rplacd.

     (car x)    == (first x)
     (cadr x)   == (second x) == (car (cdr x))
     (caddr x)  == (third x)  == (car (cdr (cdr x)))
     (cadddr x) == (fourth x) == (car (cdr (cdr (cdr x))))


File: gcl.info,  Node: copy-tree,  Next: sublis,  Prev: car,  Up: Conses Dictionary

14.2.10 copy-tree [Function]
----------------------------

'copy-tree' tree => new-tree

Arguments and Values::
......................

tree--a tree.

   new-tree--a tree.

Description::
.............

Creates a copy of a tree of conses.

   If tree is not a cons, it is returned; otherwise, the result is a new
cons of the results of calling copy-tree on the car and cdr of tree.  In
other words, all conses in the tree represented by tree are copied
recursively, stopping only when non-conses are encountered.

   copy-tree does not preserve circularities and the sharing of
substructure.

Examples::
..........

      (setq object (list (cons 1 "one")
                         (cons 2 (list 'a 'b 'c))))
     =>  ((1 . "one") (2 A B C))
      (setq object-too object) =>  ((1 . "one") (2 A B C))
      (setq copy-as-list (copy-list object))
      (setq copy-as-alist (copy-alist object))
      (setq copy-as-tree (copy-tree object))
      (eq object object-too) =>  true
      (eq copy-as-tree object) =>  false
      (eql copy-as-tree object) =>  false
      (equal copy-as-tree object) =>  true
      (setf (first (cdr (second object))) "a"
            (car (second object)) "two"
            (car object) '(one . 1)) =>  (ONE . 1)
      object =>  ((ONE . 1) ("two" "a" B C))
      object-too =>  ((ONE . 1) ("two" "a" B C))
      copy-as-list =>  ((1 . "one") ("two" "a" B C))
      copy-as-alist =>  ((1 . "one") (2 "a" B C))
      copy-as-tree =>  ((1 . "one") (2 A B C))

See Also::
..........

*note tree-equal::


File: gcl.info,  Node: sublis,  Next: subst,  Prev: copy-tree,  Up: Conses Dictionary

14.2.11 sublis, nsublis [Function]
----------------------------------

'sublis' alist tree &key key test test-not => new-tree

   'nsublis' alist tree &key key test test-not => new-tree

Arguments and Values::
......................

alist--an association list.

   tree--a tree.

   test--a designator for a function of two arguments that returns a
generalized boolean.

   test-not--a designator for a function of two arguments that returns a
generalized boolean.

   key--a designator for a function of one argument, or nil.

   new-tree--a tree.

Description::
.............

sublis makes substitutions for objects in tree (a structure of conses).
nsublis is like sublis but destructively modifies the relevant parts of
the tree.

   sublis looks at all subtrees and leaves of tree; if a subtree or leaf
appears as a key in alist (that is, the key and the subtree or leaf
satisfy the test), it is replaced by the object with which that key is
associated.  This operation is non-destructive.  In effect, sublis can
perform several subst operations simultaneously.

   If sublis succeeds, a new copy of tree is returned in which each
occurrence of such a subtree or leaf is replaced by the object with
which it is associated.  If no changes are made, the original tree is
returned.  The original tree is left unchanged, but the result tree may
share cells with it.

   nsublis is permitted to modify tree but otherwise returns the same
values as sublis.

Examples::
..........

      (sublis '((x . 100) (z . zprime))
              '(plus x (minus g z x p) 4 . x))
     =>  (PLUS 100 (MINUS G ZPRIME 100 P) 4 . 100)
      (sublis '(((+ x y) . (- x y)) ((- x y) . (+ x y)))
              '(* (/ (+ x y) (+ x p)) (- x y))
              :test #'equal)
     =>  (* (/ (- X Y) (+ X P)) (+ X Y))
      (setq tree1 '(1 (1 2) ((1 2 3)) (((1 2 3 4)))))
     =>  (1 (1 2) ((1 2 3)) (((1 2 3 4))))
      (sublis '((3 . "three")) tree1)
     =>  (1 (1 2) ((1 2 "three")) (((1 2 "three" 4))))
      (sublis '((t . "string"))
               (sublis '((1 . "") (4 . 44)) tree1)
               :key #'stringp)
     =>  ("string" ("string" 2) (("string" 2 3)) ((("string" 2 3 44))))
      tree1 =>  (1 (1 2) ((1 2 3)) (((1 2 3 4))))
      (setq tree2 '("one" ("one" "two") (("one" "Two" "three"))))
     =>  ("one" ("one" "two") (("one" "Two" "three")))
      (sublis '(("two" . 2)) tree2)
     =>  ("one" ("one" "two") (("one" "Two" "three")))
      tree2 =>  ("one" ("one" "two") (("one" "Two" "three")))
      (sublis '(("two" . 2)) tree2 :test 'equal)
     =>  ("one" ("one" 2) (("one" "Two" "three")))

      (nsublis '((t . 'temp))
                tree1
                :key #'(lambda (x) (or (atom x) (< (list-length x) 3))))
     =>  ((QUOTE TEMP) (QUOTE TEMP) QUOTE TEMP)

Side Effects::
..............

nsublis modifies tree.

See Also::
..........

*note subst:: ,

   *note Compiler Terminology::,

   *note Traversal Rules and Side Effects::

Notes::
.......

The :test-not parameter is deprecated.

   Because the side-effecting variants (e.g., nsublis) potentially
change the path that is being traversed, their effects in the presence
of shared or circular structure structure may vary in surprising ways
when compared to their non-side-effecting alternatives.  To see this,
consider the following side-effect behavior, which might be exhibited by
some implementations:

      (defun test-it (fn)
        (let* ((shared-piece (list 'a 'b))
               (data (list shared-piece shared-piece)))
          (funcall fn '((a . b) (b . a)) data)))
      (test-it #'sublis) =>  ((B A) (B A))
      (test-it #'nsublis) =>  ((A B) (A B))


File: gcl.info,  Node: subst,  Next: tree-equal,  Prev: sublis,  Up: Conses Dictionary

14.2.12 subst, subst-if, subst-if-not, nsubst, nsubst-if, nsubst-if-not
-----------------------------------------------------------------------

                                                             [Function]

   'subst' new old tree &key key test test-not => new-tree

   'subst-if' new predicate tree &key key => new-tree

   'subst-if-not' new predicate tree &key key => new-tree

   'nsubst' new old tree &key key test test-not => new-tree

   'nsubst-if' new predicate tree &key key => new-tree

   'nsubst-if-not' new predicate tree &key key => new-tree

Arguments and Values::
......................

new--an object.

   old--an object.

   predicate--a symbol that names a function, or a function of one
argument that returns a generalized boolean value.

   tree--a tree.

   test--a designator for a function of two arguments that returns a
generalized boolean.

   test-not--a designator for a function of two arguments that returns a
generalized boolean.

   key--a designator for a function of one argument, or nil.

   new-tree--a tree.

Description::
.............

subst, subst-if, and subst-if-not perform substitution operations on
tree.  Each function searches tree for occurrences of a particular old
item of an element or subexpression that satisfies the test.

   nsubst, nsubst-if, and nsubst-if-not are like subst, subst-if, and
subst-if-not respectively, except that the original tree is modified.

   subst makes a copy of tree, substituting new for every subtree or
leaf of tree (whether the subtree or leaf is a car or a cdr of its
parent) such that old and the subtree or leaf satisfy the test.

   nsubst is a destructive version of subst.  The list structure of tree
is altered by destructively replacing with new each leaf of the tree
such that old and the leaf satisfy the test.

   For subst, subst-if, and subst-if-not, if the functions succeed, a
new copy of the tree is returned in which each occurrence of such an
element is replaced by the new element or subexpression.  If no changes
are made, the original tree may be returned.  The original tree is left
unchanged, but the result tree may share storage with it.

   For nsubst, nsubst-if, and nsubst-if-not the original tree is
modified and returned as the function result, but the result may not be
eq to tree.

Examples::
..........

      (setq tree1 '(1 (1 2) (1 2 3) (1 2 3 4))) =>  (1 (1 2) (1 2 3) (1 2 3 4))
      (subst "two" 2 tree1) =>  (1 (1 "two") (1 "two" 3) (1 "two" 3 4))
      (subst "five" 5 tree1) =>  (1 (1 2) (1 2 3) (1 2 3 4))
      (eq tree1 (subst "five" 5 tree1)) =>  implementation-dependent
      (subst 'tempest 'hurricane
             '(shakespeare wrote (the hurricane)))
     =>  (SHAKESPEARE WROTE (THE TEMPEST))
      (subst 'foo 'nil '(shakespeare wrote (twelfth night)))
     =>  (SHAKESPEARE WROTE (TWELFTH NIGHT . FOO) . FOO)
      (subst '(a . cons) '(old . pair)
             '((old . spice) ((old . shoes) old . pair) (old . pair))
             :test #'equal)
     =>  ((OLD . SPICE) ((OLD . SHOES) A . CONS) (A . CONS))

      (subst-if 5 #'listp tree1) =>  5
      (subst-if-not '(x) #'consp tree1)
     =>  (1 X)

      tree1 =>  (1 (1 2) (1 2 3) (1 2 3 4))
      (nsubst 'x 3 tree1 :key #'(lambda (y) (and (listp y) (third y))))
     =>  (1 (1 2) X X)
      tree1 =>  (1 (1 2) X X)

Side Effects::
..............

nsubst, nsubst-if, and nsubst-if-not might alter the tree structure of
tree.

See Also::
..........

*note substitute:: , nsubstitute,

   *note Compiler Terminology::,

   *note Traversal Rules and Side Effects::

Notes::
.......

The :test-not parameter is deprecated.

   The functions subst-if-not and nsubst-if-not are deprecated.

   One possible definition of subst:

      (defun subst (old new tree &rest x &key test test-not key)
        (cond ((satisfies-the-test old tree :test test
                                      :test-not test-not :key key)
              new)
             ((atom tree) tree)
             (t (let ((a (apply #'subst old new (car tree) x))
                      (d (apply #'subst old new (cdr tree) x)))
                  (if (and (eql a (car tree))
                           (eql d (cdr tree)))
                      tree
                      (cons a d))))))


File: gcl.info,  Node: tree-equal,  Next: copy-list,  Prev: subst,  Up: Conses Dictionary

14.2.13 tree-equal [Function]
-----------------------------

'tree-equal' tree-1 tree-2 &key test test-not => generalized-boolean

Arguments and Values::
......................

tree-1--a tree.

   tree-2--a tree.

   test--a designator for a function of two arguments that returns a
generalized boolean.

   test-not--a designator for a function of two arguments that returns a
generalized boolean.

   generalized-boolean--a generalized boolean.

Description::
.............

tree-equal tests whether two trees are of the same shape and have the
same leaves.  tree-equal returns true if tree-1 and tree-2 are both
atoms and satisfy the test, or if they are both conses and the car of
tree-1 is tree-equal to the car of tree-2 and the cdr of tree-1 is
tree-equal to the cdr of tree-2.  Otherwise, tree-equal returns false.

   tree-equal recursively compares conses but not any other objects that
have components.

   The first argument to the :test or :test-not function is tree-1 or a
car or cdr of tree-1; the second argument is tree-2 or a car or cdr of
tree-2.

Examples::
..........

      (setq tree1 '(1 (1 2))
            tree2 '(1 (1 2))) =>  (1 (1 2))
      (tree-equal tree1 tree2) =>  true
      (eql tree1 tree2) =>  false
      (setq tree1 '('a ('b 'c))
            tree2 '('a ('b 'c))) =>  ('a ('b 'c))
     =>  ((QUOTE A) ((QUOTE B) (QUOTE C)))
      (tree-equal tree1 tree2 :test 'eq) =>  true

Exceptional Situations::
........................

The consequences are undefined if both tree-1 and tree-2 are circular.

See Also::
..........

*note equal:: ,

   *note Traversal Rules and Side Effects::

Notes::
.......

The :test-not parameter is deprecated.


File: gcl.info,  Node: copy-list,  Next: list (Function),  Prev: tree-equal,  Up: Conses Dictionary

14.2.14 copy-list [Function]
----------------------------

'copy-list' list => copy

Arguments and Values::
......................

list--a proper list or a dotted list.

   copy--a list.

Description::
.............

Returns a copy of list.  If list is a dotted list, the resulting list
will also be a dotted list.

   Only the list structure of list is copied; the elements of the
resulting list are the same as the corresponding elements of the given
list.

Examples::
..........

      (setq lst (list 1 (list 2 3))) =>  (1 (2 3))
      (setq slst lst) =>  (1 (2 3))
      (setq clst (copy-list lst)) =>  (1 (2 3))
      (eq slst lst) =>  true
      (eq clst lst) =>  false
      (equal clst lst) =>  true
      (rplaca lst "one") =>  ("one" (2 3))
      slst =>  ("one" (2 3))
      clst =>  (1 (2 3))
      (setf (caadr lst) "two") =>  "two"
      lst =>  ("one" ("two" 3))
      slst =>  ("one" ("two" 3))
      clst =>  (1 ("two" 3))

Exceptional Situations::
........................

The consequences are undefined if list is a circular list.

See Also::
..........

*note copy-alist:: , *note copy-seq:: , *note copy-tree::

Notes::
.......

The copy created is equal to list, but not eq.


File: gcl.info,  Node: list (Function),  Next: list-length,  Prev: copy-list,  Up: Conses Dictionary

14.2.15 list, list* [Function]
------------------------------

'list' &rest objects => list

   'list*' &rest objects^+ => result

Arguments and Values::
......................

object--an object.

   list--a list.

   result--an object.

Description::
.............

list returns a list containing the supplied objects.

   list* is like list except that the last argument to list becomes the
car of the last cons constructed, while the last argument to list*
becomes the cdr of the last cons constructed.  Hence, any given call to
list* always produces one fewer conses than a call to list with the same
number of arguments.

   If the last argument to list* is a list, the effect is to construct a
new list which is similar, but which has additional elements added to
the front corresponding to the preceding arguments of list*.

   If list* receives only one object, that object is returned,
regardless of whether or not it is a list.

Examples::
..........

      (list 1) =>  (1)
      (list* 1) =>  1
      (setq a 1) =>  1
      (list a 2) =>  (1 2)
      '(a 2) =>  (A 2)
      (list 'a 2) =>  (A 2)
      (list* a 2) =>  (1 . 2)
      (list) =>  NIL ;i.e., ()
      (setq a '(1 2)) =>  (1 2)
      (eq a (list* a)) =>  true
      (list 3 4 'a (car '(b . c)) (+ 6 -2)) =>  (3 4 A B 4)
      (list* 'a 'b 'c 'd) == (cons 'a (cons 'b (cons 'c 'd))) =>  (A B C . D)
      (list* 'a 'b 'c '(d e f)) =>  (A B C D E F)

See Also::
..........

*note cons::

Notes::
.......

      (list* x) == x


File: gcl.info,  Node: list-length,  Next: listp,  Prev: list (Function),  Up: Conses Dictionary

14.2.16 list-length [Function]
------------------------------

'list-length' list => length

Arguments and Values::
......................

list--a proper list or a circular list.

   length--a non-negative integer, or nil.

Description::
.............

Returns the length of list if list is a proper list.  Returns nil if
list is a circular list.

Examples::
..........

      (list-length '(a b c d)) =>  4
      (list-length '(a (b c) d)) =>  3
      (list-length '()) =>  0
      (list-length nil) =>  0
      (defun circular-list (&rest elements)
        (let ((cycle (copy-list elements)))
          (nconc cycle cycle)))
      (list-length (circular-list 'a 'b)) =>  NIL
      (list-length (circular-list 'a)) =>  NIL
      (list-length (circular-list)) =>  0

Exceptional Situations::
........................

Should signal an error of type type-error if list is not a proper list
or a circular list.

See Also::
..........

*note length::

Notes::
.......

list-length could be implemented as follows:

      (defun list-length (x)
        (do ((n 0 (+ n 2))           ;Counter.
             (fast x (cddr fast))    ;Fast pointer: leaps by 2.
             (slow x (cdr slow)))    ;Slow pointer: leaps by 1.
            (nil)
          ;; If fast pointer hits the end, return the count.
          (when (endp fast) (return n))
          (when (endp (cdr fast)) (return (+ n 1)))
          ;; If fast pointer eventually equals slow pointer,
          ;;  then we must be stuck in a circular list.
          ;; (A deeper property is the converse: if we are
          ;;  stuck in a circular list, then eventually the
          ;;  fast pointer will equal the slow pointer.
          ;;  That fact justifies this implementation.)
          (when (and (eq fast slow) (> n 0)) (return nil))))



File: gcl.info,  Node: listp,  Next: make-list,  Prev: list-length,  Up: Conses Dictionary

14.2.17 listp [Function]
------------------------

'listp' object => generalized-boolean

Arguments and Values::
......................

object--an object.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if object is of type list; otherwise, returns false.

Examples::
..........

      (listp nil) =>  true
      (listp (cons 1 2)) =>  true
      (listp (make-array 6)) =>  false
      (listp t) =>  false

See Also::
..........

*note consp::

Notes::
.......

If object is a cons, listp does not check whether object is a proper
list; it returns true for any kind of list.

      (listp object) == (typep object 'list) == (typep object '(or cons null))


File: gcl.info,  Node: make-list,  Next: push,  Prev: listp,  Up: Conses Dictionary

14.2.18 make-list [Function]
----------------------------

'make-list' size &key initial-element => list

Arguments and Values::
......................

size--a non-negative integer.

   initial-element--an object.  The default is nil.

   list--a list.

Description::
.............

Returns a list of length given by size, each of the elements of which is
initial-element.

Examples::
..........

      (make-list 5) =>  (NIL NIL NIL NIL NIL)
      (make-list 3 :initial-element 'rah) =>  (RAH RAH RAH)
      (make-list 2 :initial-element '(1 2 3)) =>  ((1 2 3) (1 2 3))
      (make-list 0) =>  NIL ;i.e., ()
      (make-list 0 :initial-element 'new-element) =>  NIL

Exceptional Situations::
........................

Should signal an error of type type-error if size is not a non-negative
integer.

See Also::
..........

*note cons:: , *note list (Function)::


File: gcl.info,  Node: push,  Next: pop,  Prev: make-list,  Up: Conses Dictionary

14.2.19 push [Macro]
--------------------

'push' item place => new-place-value

Arguments and Values::
......................

item--an object.

   place--a place, the value of which may be any object.

   new-place-value--a list (the new value of place).

Description::
.............

push prepends item to the list that is stored in place, stores the
resulting list in place, and returns the list.

   For information about the evaluation of subforms of place, see *note
Evaluation of Subforms to Places::.

Examples::
..........

      (setq llst '(nil)) =>  (NIL)
      (push 1 (car llst)) =>  (1)
      llst =>  ((1))
      (push 1 (car llst)) =>  (1 1)
      llst =>  ((1 1))
      (setq x '(a (b c) d)) =>  (A (B C) D)
      (push 5 (cadr x)) =>  (5 B C)
      x =>  (A (5 B C) D)

Side Effects::
..............

The contents of place are modified.

See Also::
..........

*note pop:: , *note pushnew:: , *note Generalized Reference::

Notes::
.......

The effect of (push item place) is equivalent to

      (setf place (cons item place))

   except that the subforms of place are evaluated only once, and item
is evaluated before place.


File: gcl.info,  Node: pop,  Next: first,  Prev: push,  Up: Conses Dictionary

14.2.20 pop [Macro]
-------------------

'pop' place => element

Arguments and Values::
......................

place--a place, the value of which is a list (possibly, but necessarily,
a dotted list or circular list).

   element--an object (the car of the contents of place).

Description::
.............

pop reads the value of place, remembers the car of the list which was
retrieved, writes the cdr of the list back into the place, and finally
yields the car of the originally retrieved list.

   For information about the evaluation of subforms of place, see *note
Evaluation of Subforms to Places::.

Examples::
..........

      (setq stack '(a b c)) =>  (A B C)
      (pop stack) =>  A
      stack =>  (B C)
      (setq llst '((1 2 3 4))) =>  ((1 2 3 4))
      (pop (car llst)) =>  1
      llst =>  ((2 3 4))

Side Effects::
..............

The contents of place are modified.

See Also::
..........

*note push:: , *note pushnew:: , *note Generalized Reference::

Notes::
.......

The effect of (pop place) is roughly equivalent to

      (prog1 (car place) (setf place (cdr place)))

   except that the latter would evaluate any subforms of place three
times, while pop evaluates them only once.


File: gcl.info,  Node: first,  Next: nth,  Prev: pop,  Up: Conses Dictionary

14.2.21 first, second, third, fourth, fifth,
--------------------------------------------

sixth, seventh, eighth, ninth, tenth
------------------------------------

                                                             [Accessor]

   'first' list => object (setf ('first' list) new-object)

   'second' list => object (setf ('second' list) new-object)

   'third' list => object (setf ('third' list) new-object)

   'fourth' list => object (setf ('fourth' list) new-object)

   'fifth' list => object (setf ('fifth' list) new-object)

   'sixth' list => object (setf ('sixth' list) new-object)

   'seventh' list => object (setf ('seventh' list) new-object)

   'eighth' list => object (setf ('eighth' list) new-object)

   'ninth' list => object (setf ('ninth' list) new-object)

   'tenth' list => object (setf ('tenth' list) new-object)

Arguments and Values::
......................

list--a list,

   which might be a dotted list or a circular list.

   object, new-object--an object.

Description::
.............

The functions first, second, third, fourth, fifth, sixth, seventh,
eighth, ninth, and tenth access the first, second, third, fourth, fifth,
sixth, seventh, eighth, ninth, and tenth elements of list, respectively.
Specifically,

      (first list)    ==  (car list)
      (second list)   ==  (car (cdr list))
      (third list)    ==  (car (cddr list))
      (fourth list)   ==  (car (cdddr list))
      (fifth list)    ==  (car (cddddr list))
      (sixth list)    ==  (car (cdr (cddddr list)))
      (seventh list)  ==  (car (cddr (cddddr list)))
      (eighth list)   ==  (car (cdddr (cddddr list)))
      (ninth list)    ==  (car (cddddr (cddddr list)))
      (tenth list)    ==  (car (cdr (cddddr (cddddr list))))

   setf can also be used with any of these functions to change an
existing component.  The same equivalences apply.  For example:

      (setf (fifth list) new-object) == (setf (car (cddddr list)) new-object)

Examples::
..........

      (setq lst '(1 2 3 (4 5 6) ((V)) vi 7 8 9 10))
     =>  (1 2 3 (4 5 6) ((V)) VI 7 8 9 10)
      (first lst) =>  1
      (tenth lst) =>  10
      (fifth lst) =>  ((V))
      (second (fourth lst)) =>  5
      (sixth '(1 2 3)) =>  NIL
      (setf (fourth lst) "four") =>  "four"
      lst =>  (1 2 3 "four" ((V)) VI 7 8 9 10)

See Also::
..........

*note car:: , *note nth::

Notes::
.......

first is functionally equivalent to car, second is functionally
equivalent to cadr, third is functionally equivalent to caddr, and
fourth is functionally equivalent to cadddr.

   The ordinal numbering used here is one-origin, as opposed to the
zero-origin numbering used by nth:

      (fifth x) == (nth 4 x)


File: gcl.info,  Node: nth,  Next: endp,  Prev: first,  Up: Conses Dictionary

14.2.22 nth [Accessor]
----------------------

'nth' n list => object

   (setf (' nth' n list) new-object)

Arguments and Values::
......................

n--a non-negative integer.

   list--a list,

   which might be a dotted list or a circular list.

   object--an object.

   new-object--an object.

Description::
.............

nth locates the nth element of list, where the car of the list is the
"zeroth" element.

   Specifically,

      (nth n list) == (car (nthcdr n list))

   nth may be used to specify a place to setf.

   Specifically,

      (setf (nth n list) new-object) == (setf (car (nthcdr n list)) new-object)

Examples::
..........

      (nth 0 '(foo bar baz)) =>  FOO
      (nth 1 '(foo bar baz)) =>  BAR
      (nth 3 '(foo bar baz)) =>  NIL
      (setq 0-to-3 (list 0 1 2 3)) =>  (0 1 2 3)
      (setf (nth 2 0-to-3) "two") =>  "two"
      0-to-3 =>  (0 1 "two" 3)

See Also::
..........

*note elt:: , *note first:: , *note nthcdr::


File: gcl.info,  Node: endp,  Next: null,  Prev: nth,  Up: Conses Dictionary

14.2.23 endp [Function]
-----------------------

'endp' list => generalized-boolean

Arguments and Values::
......................

list--a list,

   which might be a dotted list or a circular list.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if list is the empty list.  Returns false if list is a
cons.

Examples::
..........

      (endp nil) =>  true
      (endp '(1 2)) =>  false
      (endp (cddr '(1 2))) =>  true

Exceptional Situations::
........................

Should signal an error of type type-error if list is not a list.

Notes::
.......

The purpose of endp is to test for the end of proper list.  Since endp
does not descend into a cons, it is well-defined to pass it a dotted
list.  However, if shorter "lists" are iteratively produced by calling
cdr on such a dotted list and those "lists" are tested with endp, a
situation that has undefined consequences will eventually result when
the non-nil atom (which is not in fact a list) finally becomes the
argument to endp.  Since this is the usual way in which endp is used, it
is conservative programming style and consistent with the intent of endp
to treat endp as simply a function on proper lists which happens not to
enforce an argument type of proper list except when the argument is
atomic.


File: gcl.info,  Node: null,  Next: nconc,  Prev: endp,  Up: Conses Dictionary

14.2.24 null [Function]
-----------------------

'null' object => boolean

Arguments and Values::
......................

object--an object.

   boolean--a boolean.

Description::
.............

Returns t if object is the empty list; otherwise, returns nil.

Examples::
..........

      (null '()) =>  T
      (null nil) =>  T
      (null t) =>  NIL
      (null 1) =>  NIL

See Also::
..........

*note not::

Notes::
.......

null is intended to be used to test for the empty list whereas not is
intended to be used to invert a boolean (or generalized boolean).
Operationally, null and not compute the same result; which to use is a
matter of style.

      (null object) == (typep object 'null) == (eq object '())


File: gcl.info,  Node: nconc,  Next: append,  Prev: null,  Up: Conses Dictionary

14.2.25 nconc [Function]
------------------------

'nconc' &rest lists => concatenated-list

Arguments and Values::
......................

list--each but the last must be a list (which might be a dotted list but
must not be a circular list); the last list may be any object.

   concatenated-list--a list.

Description::
.............

Returns a list that is the concatenation of lists.  If no lists are
supplied, (nconc) returns nil.

   nconc is defined using the following recursive relationship:

      (nconc) =>  ()
      (nconc nil . lists) == (nconc . lists)
      (nconc list) =>  list
      (nconc list-1 list-2) == (progn (rplacd (last list-1) list-2) list-1)
      (nconc list-1 list-2 . lists) == (nconc (nconc list-1 list-2) . lists)

Examples::
..........

      (nconc) =>  NIL
      (setq x '(a b c)) =>  (A B C)
      (setq y '(d e f)) =>  (D E F)
      (nconc x y) =>  (A B C D E F)
      x =>  (A B C D E F)

   Note, in the example, that the value of x is now different, since its
last cons has been rplacd'd to the value of y.  If (nconc x y) were
evaluated again, it would yield a piece of a circular list, whose
printed representation would be (A B C D E F D E F D E F ...), repeating
forever; if the *print-circle* switch were non-nil, it would be printed
as (A B C . #1=(D E F . #1#)).

      (setq foo (list 'a 'b 'c 'd 'e)
            bar (list 'f 'g 'h 'i 'j)
            baz (list 'k 'l 'm)) =>  (K L M)
      (setq foo (nconc foo bar baz)) =>  (A B C D E F G H I J K L M)
      foo =>  (A B C D E F G H I J K L M)
      bar =>  (F G H I J K L M)
      baz =>  (K L M)

      (setq foo (list 'a 'b 'c 'd 'e)
            bar (list 'f 'g 'h 'i 'j)
            baz (list 'k 'l 'm)) =>  (K L M)
      (setq foo (nconc nil foo bar nil baz)) =>  (A B C D E F G H I J K L M)
      foo =>  (A B C D E F G H I J K L M)
      bar =>  (F G H I J K L M)
      baz =>  (K L M)

Side Effects::
..............

The lists are modified rather than copied.

See Also::
..........

*note append:: , *note concatenate::


File: gcl.info,  Node: append,  Next: revappend,  Prev: nconc,  Up: Conses Dictionary

14.2.26 append [Function]
-------------------------

'append' &rest lists => result

Arguments and Values::
......................

list--each must be a proper list except the last, which may be any
object.

   result--an object.  This will be a list unless the last list was not
a list and all preceding lists were null.

Description::
.............

append returns a new list that is the concatenation of the copies.
lists are left unchanged; the list structure of each of lists except the
last is copied.  The last argument is not copied; it becomes the cdr of
the final dotted pair of the concatenation of the preceding lists, or is
returned directly if there are no preceding non-empty lists.

Examples::
..........

      (append '(a b c) '(d e f) '() '(g)) =>  (A B C D E F G)
      (append '(a b c) 'd) =>  (A B C . D)
      (setq lst '(a b c)) =>  (A B C)
      (append lst '(d)) =>  (A B C D)
      lst =>  (A B C)
      (append) =>  NIL
      (append 'a) =>  A

See Also::
..........

*note nconc:: , *note concatenate::


File: gcl.info,  Node: revappend,  Next: butlast,  Prev: append,  Up: Conses Dictionary

14.2.27 revappend, nreconc [Function]
-------------------------------------

'revappend' list tail => result-list

   'nreconc' list tail => result-list

Arguments and Values::
......................

list--a proper list.

   tail--an object.

   result-list--an object.

Description::
.............

revappend constructs a copy_2 of list, but with the elements in reverse
order.  It then appends (as if by nconc) the tail to that reversed list
and returns the result.

   nreconc reverses the order of elements in list (as if by nreverse).
It then appends (as if by nconc) the tail to that reversed list and
returns the result.

   The resulting list shares list structure with tail.

Examples::
..........

      (let ((list-1 (list 1 2 3))
            (list-2 (list 'a 'b 'c)))
        (print (revappend list-1 list-2))
        (print (equal list-1 '(1 2 3)))
        (print (equal list-2 '(a b c))))
      |>  (3 2 1 A B C)
      |>  T
      |>  T
     =>  T

      (revappend '(1 2 3) '()) =>  (3 2 1)
      (revappend '(1 2 3) '(a . b)) =>  (3 2 1 A . B)
      (revappend '() '(a b c)) =>  (A B C)
      (revappend '(1 2 3) 'a) =>  (3 2 1 . A)
      (revappend '() 'a) =>  A   ;degenerate case

      (let ((list-1 '(1 2 3))
            (list-2 '(a b c)))
        (print (nreconc list-1 list-2))
        (print (equal list-1 '(1 2 3)))
        (print (equal list-2 '(a b c))))
      |>  (3 2 1 A B C)
      |>  NIL
      |>  T
     =>  T


Side Effects::
..............

revappend does not modify either of its arguments.  nreconc is permitted
to modify list but not tail.

   Although it might be implemented differently, nreconc is constrained
to have side-effect behavior equivalent to:

      (nconc (nreverse list) tail)

See Also::
..........

*note reverse:: , nreverse, *note nconc::

Notes::
.......

The following functional equivalences are true, although good
implementations will typically use a faster algorithm for achieving the
same effect:

      (revappend list tail) == (nconc (reverse list) tail)
      (nreconc list tail) == (nconc (nreverse list) tail)


File: gcl.info,  Node: butlast,  Next: last,  Prev: revappend,  Up: Conses Dictionary

14.2.28 butlast, nbutlast [Function]
------------------------------------

'butlast' list &optional n => result-list

   'nbutlast' list &optional n => result-list

Arguments and Values::
......................

list--a list,

   which might be a dotted list but must not be a circular list.

   n--a non-negative integer.

   result-list--a list.

Description::
.............

butlast returns a copy of list from which the last n

   conses

   have been omitted.  If n is not supplied, its value is 1.  If there
are fewer than n

   conses

   in list, nil is returned and, in the case of nbutlast, list is not
modified.

   nbutlast is like butlast, but nbutlast may modify list.  It changes
the cdr of the cons n+1 from the end of the list to nil.

Examples::
..........

      (setq lst '(1 2 3 4 5 6 7 8 9)) =>  (1 2 3 4 5 6 7 8 9)
      (butlast lst) =>  (1 2 3 4 5 6 7 8)
      (butlast lst 5) =>  (1 2 3 4)
      (butlast lst (+ 5 5)) =>  NIL
      lst =>  (1 2 3 4 5 6 7 8 9)
      (nbutlast lst 3) =>  (1 2 3 4 5 6)
      lst =>  (1 2 3 4 5 6)
      (nbutlast lst 99) =>  NIL
      lst =>  (1 2 3 4 5 6)
      (butlast '(a b c d)) =>  (A B C)
      (butlast '((a b) (c d))) =>  ((A B))
      (butlast '(a)) =>  NIL
      (butlast nil) =>  NIL
      (setq foo (list 'a 'b 'c 'd)) =>  (A B C D)
      (nbutlast foo) =>  (A B C)
      foo =>  (A B C)
      (nbutlast (list 'a)) =>  NIL
      (nbutlast '()) =>  NIL

Exceptional Situations::
........................

Should signal an error of type type-error if list is not a proper list
or a dotted list.

   Should signal an error of type type-error if n is not a non-negative
integer.

Notes::
.......

      (butlast list n) == (ldiff list (last list n))


File: gcl.info,  Node: last,  Next: ldiff,  Prev: butlast,  Up: Conses Dictionary

14.2.29 last [Function]
-----------------------

'last' list &optional n => tail

Arguments and Values::
......................

list--a list,

   which might be a dotted list but must not be a circular list.

   n--a non-negative integer.  The default is 1.

   tail--an object.

Description::
.............

last returns the last n conses (not the last n elements) of list).  If
list is (), last returns ().

   If n is zero, the atom that terminates list is returned.  If n is
greater than or equal to the number of cons cells in list, the result is
list.

Examples::
..........

      (last nil) =>  NIL
      (last '(1 2 3)) =>  (3)
      (last '(1 2 . 3)) =>  (2 . 3)
      (setq x (list 'a 'b 'c 'd)) =>  (A B C D)
      (last x) =>  (D)
      (rplacd (last x) (list 'e 'f)) x =>  (A B C D E F)
      (last x) =>  (F)

      (last '(a b c))   =>  (C)

      (last '(a b c) 0) =>  ()
      (last '(a b c) 1) =>  (C)
      (last '(a b c) 2) =>  (B C)
      (last '(a b c) 3) =>  (A B C)
      (last '(a b c) 4) =>  (A B C)

      (last '(a . b) 0) =>  B
      (last '(a . b) 1) =>  (A . B)
      (last '(a . b) 2) =>  (A . B)

Exceptional Situations::
........................

The consequences are undefined if list is a circular list.

   Should signal an error of type type-error if n is not a non-negative
integer.

See Also::
..........

*note butlast:: , *note nth::

Notes::
.......

The following code could be used to define last.

      (defun last (list &optional (n 1))
        (check-type n (integer 0))
        (do ((l list (cdr l))
             (r list)
             (i 0 (+ i 1)))
            ((atom l) r)
          (if (>= i n) (pop r))))


File: gcl.info,  Node: ldiff,  Next: nthcdr,  Prev: last,  Up: Conses Dictionary

14.2.30 ldiff, tailp [Function]
-------------------------------

'ldiff' list object => result-list

   'tailp' object list => generalized-boolean

Arguments and Values::
......................

list--a list,

   which might be a dotted list.

   object--an object.

   result-list--a list.

   generalized-boolean--a generalized boolean.

Description::
.............

If object is the same as some tail of list, tailp returns true;
otherwise, it returns false.

   If object is the same as some tail of list, ldiff returns a fresh
list of the elements of list that precede object in the list structure
of list; otherwise, it returns a copy_2 of list.

Examples::
..........

      (let ((lists '#((a b c) (a b c . d))))
        (dotimes (i (length lists)) ()
          (let ((list (aref lists i)))
            (format t "~2&list=~S ~21T(tailp object list)~
                       ~44T(ldiff list object)~
              (let ((objects (vector list (cddr list) (copy-list (cddr list))
                                     '(f g h) '() 'd 'x)))
                (dotimes (j (length objects)) ()
                  (let ((object (aref objects j)))
                    (format t "~& object=~S ~21T~S ~44T~S"
                            object (tailp object list) (ldiff list object))))))))
      |>
      |>  list=(A B C)         (tailp object list)    (ldiff list object)
      |>   object=(A B C)      T                      NIL
      |>   object=(C)          T                      (A B)
      |>   object=(C)          NIL                    (A B C)
      |>   object=(F G H)      NIL                    (A B C)
      |>   object=NIL          T                      (A B C)
      |>   object=D            NIL                    (A B C)
      |>   object=X            NIL                    (A B C)
      |>
      |>  list=(A B C . D)     (tailp object list)    (ldiff list object)
      |>   object=(A B C . D)  T                      NIL
      |>   object=(C . D)      T                      (A B)
      |>   object=(C . D)      NIL                    (A B C . D)
      |>   object=(F G H)      NIL                    (A B C . D)
      |>   object=NIL          NIL                    (A B C . D)
      |>   object=D            T                      (A B C)
      |>   object=X            NIL                    (A B C . D)
     =>  NIL

Side Effects::
..............

Neither ldiff nor tailp modifies either of its arguments.

Exceptional Situations::
........................

Should be prepared to signal an error of type type-error if list is not
a proper list or a dotted list.

See Also::
..........

*note set-difference::

Notes::
.......

If the list is a circular list, tailp will reliably yield a value only
if the given object is in fact a tail of list.  Otherwise, the
consequences are unspecified: a given implementation which detects the
circularity must return false, but since an implementation is not
obliged to detect such a situation, tailp might just loop indefinitely
without returning in that case.

   tailp could be defined as follows:

      (defun tailp (object list)
        (do ((list list (cdr list)))
            ((atom list) (eql list object))
           (if (eql object list)
               (return t))))

   and ldiff could be defined by:

     (defun ldiff (list object)
       (do ((list list (cdr list))
            (r '() (cons (car list) r)))
           ((atom list)
            (if (eql list object) (nreverse r) (nreconc r list)))
         (when (eql object list)
           (return (nreverse r)))))


File: gcl.info,  Node: nthcdr,  Next: rest,  Prev: ldiff,  Up: Conses Dictionary

14.2.31 nthcdr [Function]
-------------------------

'nthcdr' n list => tail

Arguments and Values::
......................

n--a non-negative integer.

   list--a list,

   which might be a dotted list or a circular list.

   tail--an object.

Description::
.............

Returns the tail of list that would be obtained by calling cdr n times
in succession.

Examples::
..........

      (nthcdr 0 '()) =>  NIL
      (nthcdr 3 '()) =>  NIL
      (nthcdr 0 '(a b c)) =>  (A B C)
      (nthcdr 2 '(a b c)) =>  (C)
      (nthcdr 4 '(a b c)) =>  ()
      (nthcdr 1 '(0 . 1)) =>  1

      (locally (declare (optimize (safety 3)))
        (nthcdr 3 '(0 . 1)))
      Error: Attempted to take CDR of 1.

Exceptional Situations::
........................

Should signal an error of type type-error if n is not a non-negative
integer.

   For n being an integer greater than 1, the error checking done by
(nthcdr n list) is the same as for (nthcdr (- n 1) (cdr list)); see the
function cdr.

See Also::
..........

cdr, *note nth:: , *note rest::


File: gcl.info,  Node: rest,  Next: member (Function),  Prev: nthcdr,  Up: Conses Dictionary

14.2.32 rest [Accessor]
-----------------------

'rest' list => tail

   (setf (' rest' list) new-tail)

Arguments and Values::
......................

list--a list,

   which might be a dotted list or a circular list.

   tail--an object.

Description::
.............

rest performs the same operation as cdr, but mnemonically complements
first.  Specifically,

      (rest list) == (cdr list)
      (setf (rest list) new-tail) == (setf (cdr list) new-tail)

Examples::
..........

      (rest '(1 2)) =>  (2)
      (rest '(1 . 2)) =>  2
      (rest '(1)) =>  NIL
      (setq *cons* '(1 . 2)) =>  (1 . 2)
      (setf (rest *cons*) "two") =>  "two"
      *cons* =>  (1 . "two")

See Also::
..........

cdr, *note nthcdr::

Notes::
.......

rest is often preferred stylistically over cdr when the argument is to
being subjectively viewed as a list rather than as a cons.


File: gcl.info,  Node: member (Function),  Next: mapc,  Prev: rest,  Up: Conses Dictionary

14.2.33 member, member-if, member-if-not [Function]
---------------------------------------------------

'member' item list &key key test test-not => tail

   'member-if' predicate list &key key => tail

   'member-if-not' predicate list &key key => tail

Arguments and Values::
......................

item--an object.

   list--a proper list.

   predicate--a designator for a function of one argument that returns a
generalized boolean.

   test--a designator for a function of two arguments that returns a
generalized boolean.

   test-not--a designator for a function of two arguments that returns a
generalized boolean.

   key--a designator for a function of one argument, or nil.

   tail--a list.

Description::
.............

member, member-if, and member-if-not each search list for item or for a
top-level element that satisfies the test.  The argument to the
predicate function is an element of list.

   If some element satisfies the test, the tail of list beginning with
this element is returned; otherwise nil is returned.

   list is searched on the top level only.

Examples::
..........

      (member 2 '(1 2 3)) =>  (2 3)
      (member 2 '((1 . 2) (3 . 4)) :test-not #'= :key #'cdr) =>  ((3 . 4))
      (member 'e '(a b c d)) =>  NIL

      (member-if #'listp '(a b nil c d)) =>  (NIL C D)
      (member-if #'numberp '(a #\Space 5/3 foo)) =>  (5/3 FOO)
      (member-if-not #'zerop
                      '(3 6 9 11 . 12)
                      :key #'(lambda (x) (mod x 3))) =>  (11 . 12)

Exceptional Situations::
........................

Should be prepared to signal an error of type type-error if list is not
a proper list.

See Also::
..........

*note find:: , *note position:: ,

   *note Traversal Rules and Side Effects::

Notes::
.......

The :test-not parameter is deprecated.

   The function member-if-not is deprecated.

   In the following

      (member 'a '(g (a y) c a d e a f)) =>  (A D E A F)

   the value returned by member is identical to the portion of the list
beginning with a.  Thus rplaca on the result of member can be used to
alter the part of the list where a was found (assuming a check has been
made that member did not return nil).


File: gcl.info,  Node: mapc,  Next: acons,  Prev: member (Function),  Up: Conses Dictionary

14.2.34 mapc, mapcar, mapcan, mapl, maplist, mapcon [Function]
--------------------------------------------------------------

'mapc' function &rest lists^+ => list-1

   'mapcar' function &rest lists^+ => result-list

   'mapcan' function &rest lists^+ => concatenated-results

   'mapl' function &rest lists^+ => list-1

   'maplist' function &rest lists^+ => result-list

   'mapcon' function &rest lists^+ => concatenated-results

Arguments and Values::
......................

function--a designator for a function that must take as many arguments
as there are lists.

   list--a proper list.

   list-1--the first list (which must be a proper list).

   result-list--a list.

   concatenated-results--a list.

Description::
.............

The mapping operation involves applying function to successive sets of
arguments in which one argument is obtained from each sequence.  Except
for mapc and mapl, the result contains the results returned by function.
In the cases of mapc and mapl, the resulting sequence is list.

   function is called first on all the elements with index 0, then on
all those with index 1, and so on.  result-type specifies the type of
the resulting sequence.

   If function is a symbol, it is coerced to a function as if by
symbol-function.

   mapcar operates on successive elements of the lists.  function is
applied to the first element of each list, then to the second element of
each list, and so on.  The iteration terminates when the shortest list
runs out, and excess elements in other lists are ignored.  The value
returned by mapcar is a list of the results of successive calls to
function.

   mapc is like mapcar except that the results of applying function are
not accumulated.  The list argument is returned.

   maplist is like mapcar except that function is applied to successive
sublists of the lists.  function is first applied to the lists
themselves, and then to the cdr of each list, and then to the cdr of the
cdr of each list, and so on.

   mapl is like maplist except that the results of applying function are
not accumulated; list-1 is returned.

   mapcan and mapcon are like mapcar and maplist respectively, except
that the results of applying function are combined into a list by the
use of nconc rather than list.  That is,

      (mapcon f x1 ... xn)
        == (apply #'nconc (maplist f x1 ... xn))

   and similarly for the relationship between mapcan and mapcar.

Examples::
..........

      (mapcar #'car '((1 a) (2 b) (3 c))) =>  (1 2 3)
      (mapcar #'abs '(3 -4 2 -5 -6)) =>  (3 4 2 5 6)
      (mapcar #'cons '(a b c) '(1 2 3)) =>  ((A . 1) (B . 2) (C . 3))

      (maplist #'append '(1 2 3 4) '(1 2) '(1 2 3))
     =>  ((1 2 3 4 1 2 1 2 3) (2 3 4 2 2 3))
      (maplist #'(lambda (x) (cons 'foo x)) '(a b c d))
     =>  ((FOO A B C D) (FOO B C D) (FOO C D) (FOO D))
      (maplist #'(lambda (x) (if (member (car x) (cdr x)) 0 1)) '(a b a c d b c))
     =>  (0 0 1 0 1 1 1)
     ;An entry is 1 if the corresponding element of the input
     ;  list was the last instance of that element in the input list.

      (setq dummy nil) =>  NIL
      (mapc #'(lambda (&rest x) (setq dummy (append dummy x)))
             '(1 2 3 4)
             '(a b c d e)
             '(x y z)) =>  (1 2 3 4)
      dummy =>  (1 A X 2 B Y 3 C Z)

      (setq dummy nil) =>  NIL
      (mapl #'(lambda (x) (push x dummy)) '(1 2 3 4)) =>  (1 2 3 4)
      dummy =>  ((4) (3 4) (2 3 4) (1 2 3 4))

      (mapcan #'(lambda (x y) (if (null x) nil (list x y)))
               '(nil nil nil d e)
               '(1 2 3 4 5 6)) =>  (D 4 E 5)
      (mapcan #'(lambda (x) (and (numberp x) (list x)))
               '(a 1 b c 3 4 d 5))
     =>  (1 3 4 5)

   In this case the function serves as a filter; this is a standard Lisp
idiom using mapcan.

      (mapcon #'list '(1 2 3 4)) =>  ((1 2 3 4) (2 3 4) (3 4) (4))

Exceptional Situations::
........................

Should be prepared to signal an error of type type-error if any list is
not a proper list.

See Also::
..........

*note dolist:: , *note map:: ,

   *note Traversal Rules and Side Effects::


File: gcl.info,  Node: acons,  Next: assoc,  Prev: mapc,  Up: Conses Dictionary

14.2.35 acons [Function]
------------------------

'acons' key datum alist => new-alist

Arguments and Values::
......................

key--an object.

   datum--an object.

   alist--an association list.

   new-alist--an association list.

Description::
.............

Creates a fresh cons, the cdr of which is alist and the car of which is
another fresh cons, the car of which is key and the cdr of which is
datum.

Examples::
..........

      (setq alist '()) =>  NIL
      (acons 1 "one" alist) =>  ((1 . "one"))
      alist =>  NIL
      (setq alist (acons 1 "one" (acons 2 "two" alist))) =>  ((1 . "one") (2 . "two"))
      (assoc 1 alist) =>  (1 . "one")
      (setq alist (acons 1 "uno" alist)) =>  ((1 . "uno") (1 . "one") (2 . "two"))
      (assoc 1 alist) =>  (1 . "uno")

See Also::
..........

*note assoc:: , *note pairlis::

Notes::
.......

     (acons key datum alist) == (cons (cons key datum) alist)


File: gcl.info,  Node: assoc,  Next: copy-alist,  Prev: acons,  Up: Conses Dictionary

14.2.36 assoc, assoc-if, assoc-if-not [Function]
------------------------------------------------

'assoc' item alist &key key test test-not => entry

   'assoc-if' predicate alist &key key => entry

   'assoc-if-not' predicate alist &key key => entry

Arguments and Values::
......................

item--an object.

   alist--an association list.

   predicate--a designator for a function of one argument that returns a
generalized boolean.

   test--a designator for a function of two arguments that returns a
generalized boolean.

   test-not--a designator for a function of two arguments that returns a
generalized boolean.

   key--a designator for a function of one argument, or nil.

   entry--a cons that is an element of alist, or nil.

Description::
.............

assoc, assoc-if, and assoc-if-not return the first cons in alist whose
car satisfies the test, or nil if no such cons is found.

   For assoc, assoc-if, and assoc-if-not, if nil appears in alist in
place of a pair, it is ignored.

Examples::
..........

      (setq values '((x . 100) (y . 200) (z . 50))) =>  ((X . 100) (Y . 200) (Z . 50))
      (assoc 'y values) =>  (Y . 200)
      (rplacd (assoc 'y values) 201) =>  (Y . 201)
      (assoc 'y values) =>  (Y . 201)
      (setq alist '((1 . "one")(2 . "two")(3 . "three")))
     =>  ((1 . "one") (2 . "two") (3 . "three"))
      (assoc 2 alist) =>  (2 . "two")
      (assoc-if #'evenp alist) =>  (2 . "two")
      (assoc-if-not #'(lambda(x) (< x 3)) alist) =>  (3 . "three")
      (setq alist '(("one" . 1)("two" . 2))) =>  (("one" . 1) ("two" . 2))
      (assoc "one" alist) =>  NIL
      (assoc "one" alist :test #'equalp) =>  ("one" . 1)
      (assoc "two" alist :key #'(lambda(x) (char x 2))) =>  NIL
      (assoc #\o alist :key #'(lambda(x) (char x 2))) =>  ("two" . 2)
      (assoc 'r '((a . b) (c . d) (r . x) (s . y) (r . z))) =>   (R . X)
      (assoc 'goo '((foo . bar) (zoo . goo))) =>  NIL
      (assoc '2 '((1 a b c) (2 b c d) (-7 x y z))) =>  (2 B C D)
      (setq alist '(("one" . 1) ("2" . 2) ("three" . 3)))
     =>  (("one" . 1) ("2" . 2) ("three" . 3))
      (assoc-if-not #'alpha-char-p alist
                    :key #'(lambda (x) (char x 0))) =>  ("2" . 2)

Exceptional Situations::
........................

Should be prepared to signal an error of type type-error if alist is not
an association list.

See Also::
..........

*note rassoc:: , *note find:: , *note member (Function):: , *note
position:: ,

   *note Traversal Rules and Side Effects::

Notes::
.......

The :test-not parameter is deprecated.

   The function assoc-if-not is deprecated.

   It is possible to rplacd the result of assoc, provided that it is not
nil, in order to "update" alist.

   The two expressions

      (assoc item list :test fn)

   and

      (find item list :test fn :key #'car)

   are equivalent in meaning with one exception: if nil appears in alist
in place of a pair, and item is nil, find will compute the car of the
nil in alist, find that it is equal to item, and return nil, whereas
assoc will ignore the nil in alist and continue to search for an actual
cons whose car is nil.


File: gcl.info,  Node: copy-alist,  Next: pairlis,  Prev: assoc,  Up: Conses Dictionary

14.2.37 copy-alist [Function]
-----------------------------

'copy-alist' alist => new-alist

Arguments and Values::
......................

alist--an association list.

   new-alist--an association list.

Description::
.............

copy-alist returns a copy of alist.

   The list structure of alist is copied, and the elements of alist
which are conses are also copied (as conses only).  Any other objects
which are referred to, whether directly or indirectly, by the alist
continue to be shared.

Examples::
..........

     (defparameter *alist* (acons 1 "one" (acons 2 "two" '())))
     *alist* =>  ((1 . "one") (2 . "two"))
     (defparameter *list-copy* (copy-list *alist*))
     *list-copy* =>  ((1 . "one") (2 . "two"))
     (defparameter *alist-copy* (copy-alist *alist*))
     *alist-copy* =>  ((1 . "one") (2 . "two"))
     (setf (cdr (assoc 2 *alist-copy*)) "deux") =>  "deux"
     *alist-copy* =>  ((1 . "one") (2 . "deux"))
     *alist* =>  ((1 . "one") (2 . "two"))
     (setf (cdr (assoc 1 *list-copy*)) "uno") =>  "uno"
     *list-copy* =>  ((1 . "uno") (2 . "two"))
     *alist* =>  ((1 . "uno") (2 . "two"))

See Also::
..........

*note copy-list::


File: gcl.info,  Node: pairlis,  Next: rassoc,  Prev: copy-alist,  Up: Conses Dictionary

14.2.38 pairlis [Function]
--------------------------

'pairlis' keys data &optional alist => new-alist

Arguments and Values::
......................

keys--a proper list.

   data--a proper list.

   alist--an association list.  The default is the empty list.

   new-alist--an association list.

Description::
.............

Returns an association list that associates elements of keys to
corresponding elements of data.  The consequences are undefined if keys
and data are not of the same length.

   If alist is supplied, pairlis returns a modified alist with the new
pairs prepended to it.  The new pairs may appear in the resulting
association list in either forward or backward order.  The result of

      (pairlis '(one two) '(1 2) '((three . 3) (four . 19)))

   might be

      ((one . 1) (two . 2) (three . 3) (four . 19))

   or

      ((two . 2) (one . 1) (three . 3) (four . 19))

Examples::
..........

      (setq keys '(1 2 3)
             data '("one" "two" "three")
             alist '((4 . "four"))) =>  ((4 . "four"))
      (pairlis keys data) =>  ((3 . "three") (2 . "two") (1 . "one"))
      (pairlis keys data alist)
     =>  ((3 . "three") (2 . "two") (1 . "one") (4 . "four"))
      alist =>  ((4 . "four"))

Exceptional Situations::
........................

Should be prepared to signal an error of type type-error if keys and
data are not proper lists.

See Also::
..........

*note acons::


File: gcl.info,  Node: rassoc,  Next: get-properties,  Prev: pairlis,  Up: Conses Dictionary

14.2.39 rassoc, rassoc-if, rassoc-if-not [Function]
---------------------------------------------------

'rassoc' item alist &key key test test-not => entry

   'rassoc-if' predicate alist &key key => entry

   'rassoc-if-not' predicate alist &key key => entry

Arguments and Values::
......................

item--an object.

   alist--an association list.

   predicate--a designator for a function of one argument that returns a
generalized boolean.

   test--a designator for a function of two arguments that returns a
generalized boolean.

   test-not--a designator for a function of two arguments that returns a
generalized boolean.

   key--a designator for a function of one argument, or nil.

   entry--a cons that is an element of the alist, or nil.

Description::
.............

rassoc, rassoc-if, and rassoc-if-not return the first cons whose cdr
satisfies the test.  If no such cons is found, nil is returned.

   If nil appears in alist in place of a pair, it is ignored.

Examples::
..........

      (setq alist '((1 . "one") (2 . "two") (3 . 3)))
     =>  ((1 . "one") (2 . "two") (3 . 3))
      (rassoc 3 alist) =>  (3 . 3)
      (rassoc "two" alist) =>  NIL
      (rassoc "two" alist :test 'equal) =>  (2 . "two")
      (rassoc 1 alist :key #'(lambda (x) (if (numberp x) (/ x 3)))) =>  (3 . 3)
      (rassoc 'a '((a . b) (b . c) (c . a) (z . a))) =>  (C . A)
      (rassoc-if #'stringp alist) =>  (1 . "one")
      (rassoc-if-not #'vectorp alist) =>  (3 . 3)

See Also::
..........

*note assoc:: ,

   *note Traversal Rules and Side Effects::

Notes::
.......

The :test-not parameter is deprecated.

   The function rassoc-if-not is deprecated.

   It is possible to rplaca the result of rassoc, provided that it is
not nil, in order to "update" alist.

   The expressions

      (rassoc item list :test fn)

   and

      (find item list :test fn :key #'cdr)

   are equivalent in meaning, except when the item is nil and nil
appears in place of a pair in the alist.  See the function assoc.


File: gcl.info,  Node: get-properties,  Next: getf,  Prev: rassoc,  Up: Conses Dictionary

14.2.40 get-properties [Function]
---------------------------------

'get-properties' plist indicator-list => indicator, value, tail

Arguments and Values::
......................

plist--a property list.

   indicator-list--a proper list (of indicators).

   indicator--an object that is an element of indicator-list.

   value--an object.

   tail--a list.

Description::
.............

get-properties is used to look up any of several property list entries
all at once.

   It searches the plist for the first entry whose indicator is
identical to one of the objects in indicator-list.  If such an entry is
found, the indicator and value returned are the property indicator and
its associated property value, and the tail returned is the tail of the
plist that begins with the found entry (i.e., whose car is the
indicator).  If no such entry is found, the indicator, value, and tail
are all nil.

Examples::
..........

      (setq x '()) =>  NIL
      (setq *indicator-list* '(prop1 prop2)) =>  (PROP1 PROP2)
      (getf x 'prop1) =>  NIL
      (setf (getf x 'prop1) 'val1) =>  VAL1
      (eq (getf x 'prop1) 'val1) =>  true
      (get-properties x *indicator-list*) =>  PROP1, VAL1, (PROP1 VAL1)
      x =>  (PROP1 VAL1)

See Also::
..........

*note get:: , *note getf::


File: gcl.info,  Node: getf,  Next: remf,  Prev: get-properties,  Up: Conses Dictionary

14.2.41 getf [Accessor]
-----------------------

'getf' plist indicator &optional default => value

   (setf (' getf' place indicator &optional default) new-value)

Arguments and Values::
......................

plist--a property list.

   place--a place, the value of which is a property list.

   indicator--an object.

   default--an object.  The default is nil.

   value--an object.

   new-value--an object.

Description::
.............

getf finds a property on the plist whose property indicator is identical
to indicator, and returns its corresponding property value.

   If there are multiple properties_1 with that property indicator, getf
uses the first such property.

   If there is no property with that property indicator, default is
returned.

   setf of getf may be used to associate a new object with an existing
indicator in the property list held by place, or to create a new
assocation if none exists.

   If there are multiple properties_1 with that property indicator, setf
of getf associates the new-value with the first such property.

   When a getf form is used as a setf place, any default which is
supplied is evaluated according to normal left-to-right evaluation
rules, but its value is ignored.

   setf of getf is permitted to either write the value of place itself,
or modify of any part, car or cdr, of the list structure held by place.

Examples::
..........

      (setq x '()) =>  NIL
      (getf x 'prop1) =>  NIL
      (getf x 'prop1 7) =>  7
      (getf x 'prop1) =>  NIL
      (setf (getf x 'prop1) 'val1) =>  VAL1
      (eq (getf x 'prop1) 'val1) =>  true
      (getf x 'prop1) =>  VAL1
      (getf x 'prop1 7) =>  VAL1
      x =>  (PROP1 VAL1)

     ;; Examples of implementation variation permitted.
      (setq foo (list 'a 'b 'c 'd 'e 'f)) =>  (A B C D E F)
      (setq bar (cddr foo)) =>  (C D E F)
      (remf foo 'c) =>  true
      foo =>  (A B E F)
      bar
     =>  (C D E F)
     OR=> (C)
     OR=> (NIL)
     OR=> (C NIL)
     OR=> (C D)

See Also::
..........

*note get:: , *note get-properties:: , *note setf:: , *note Function
Call Forms as Places::

Notes::
.......

There is no way (using getf) to distinguish an absent property from one
whose value is default; but see get-properties.

   Note that while supplying a default argument to getf in a setf
situation is sometimes not very interesting, it is still important
because some macros, such as push and incf, require a place argument
which data is both read from and written to.  In such a context, if a
default argument is to be supplied for the read situation, it must be
syntactically valid for the write situation as well.  For example,

      (let ((plist '()))
        (incf (getf plist 'count 0))
        plist) =>  (COUNT 1)


File: gcl.info,  Node: remf,  Next: intersection,  Prev: getf,  Up: Conses Dictionary

14.2.42 remf [Macro]
--------------------

'remf' place indicator => generalized-boolean

Arguments and Values::
......................

place--a place.

   indicator--an object.

   generalized-boolean--a generalized boolean.

Description::
.............

remf removes from the property list stored in place a property_1 with a
property indicator identical to indicator.

   If there are multiple properties_1 with the identical key, remf only
removes the first such property.

   remf returns false if no such property was found, or true if a
property was found.

   The property indicator and the corresponding property value are
removed in an undefined order by destructively splicing the property
list.

   remf is permitted to either setf place or to setf any part, car or
cdr, of the list structure held by that place.

   For information about the evaluation of subforms of place, see *note
Evaluation of Subforms to Places::.

Examples::
..........

      (setq x (cons () ())) =>  (NIL)
      (setf (getf (car x) 'prop1) 'val1) =>  VAL1
      (remf (car x) 'prop1) =>  true
      (remf (car x) 'prop1) =>  false

Side Effects::
..............

The property list stored in place is modified.

See Also::
..........

*note remprop:: , *note getf::


File: gcl.info,  Node: intersection,  Next: adjoin,  Prev: remf,  Up: Conses Dictionary

14.2.43 intersection, nintersection [Function]
----------------------------------------------

'intersection' list-1 list-2 &key key test test-not => result-list

   'nintersection' list-1 list-2 &key key test test-not => result-list

Arguments and Values::
......................

list-1--a proper list.

   list-2--a proper list.

   test--a designator for a function of two arguments that returns a
generalized boolean.

   test-not--a designator for a function of two arguments that returns a
generalized boolean.

   key--a designator for a function of one argument, or nil.

   result-list--a list.

Description::
.............

intersection and nintersection return a list that contains every element
that occurs in both list-1 and list-2.

   nintersection is the destructive version of intersection.  It
performs the same operation, but may destroy list-1 using its cells to
construct the result.

   list-2 is not destroyed.

   The intersection operation is described as follows.  For all possible
ordered pairs consisting of one element from list-1 and one element from
list-2, :test or :test-not are used to determine whether they satisfy
the test.  The first argument to the :test or :test-not function is an
element of list-1; the second argument is an element of list-2.  If
:test or :test-not is not supplied, eql is used.  It is an error if
:test and :test-not are supplied in the same function call.

   If :key is supplied (and not nil), it is used to extract the part to
be tested from the list element.  The argument to the :key function is
an element of either list-1 or list-2; the :key function typically
returns part of the supplied element.  If :key is not supplied or nil,
the list-1 and list-2 elements are used.

   For every pair that satifies the test, exactly one of the two
elements of the pair will be put in the result.  No element from either
list appears in the result that does not satisfy the test for an element
from the other list.  If one of the lists contains duplicate elements,
there may be duplication in the result.

   There is no guarantee that the order of elements in the result will
reflect the ordering of the arguments in any particular way.  The result
list may share cells with, or be eq to, either list-1 or list-2 if
appropriate.

Examples::
..........

      (setq list1 (list 1 1 2 3 4 a b c "A" "B" "C" "d")
            list2 (list 1 4 5 b c d "a" "B" "c" "D"))
       =>  (1 4 5 B C D "a" "B" "c" "D")
      (intersection list1 list2) =>  (C B 4 1 1)
      (intersection list1 list2 :test 'equal) =>  ("B" C B 4 1 1)
      (intersection list1 list2 :test #'equalp) =>  ("d" "C" "B" "A" C B 4 1 1)
      (nintersection list1 list2) =>  (1 1 4 B C)
      list1 =>  implementation-dependent ;e.g., (1 1 4 B C)
      list2 =>  implementation-dependent ;e.g., (1 4 5 B C D "a" "B" "c" "D")
      (setq list1 (copy-list '((1 . 2) (2 . 3) (3 . 4) (4 . 5))))
     =>  ((1 . 2) (2 . 3) (3 . 4) (4 . 5))
      (setq list2 (copy-list '((1 . 3) (2 . 4) (3 . 6) (4 . 8))))
     =>  ((1 . 3) (2 . 4) (3 . 6) (4 . 8))
      (nintersection list1 list2 :key #'cdr) =>  ((2 . 3) (3 . 4))
      list1 =>  implementation-dependent ;e.g., ((1 . 2) (2 . 3) (3 . 4))
      list2 =>  implementation-dependent ;e.g., ((1 . 3) (2 . 4) (3 . 6) (4 . 8))

Side Effects::
..............

nintersection can modify list-1,

   but not list-2.

Exceptional Situations::
........................

Should be prepared to signal an error of type type-error if list-1 and
list-2 are not proper lists.

See Also::
..........

*note union:: ,

   *note Compiler Terminology::,

   *note Traversal Rules and Side Effects::

Notes::
.......

The :test-not parameter is deprecated.

   Since the nintersection side effect is not required, it should not be
used in for-effect-only positions in portable code.


File: gcl.info,  Node: adjoin,  Next: pushnew,  Prev: intersection,  Up: Conses Dictionary

14.2.44 adjoin [Function]
-------------------------

'adjoin' item list &key key test test-not => new-list

Arguments and Values::
......................

item--an object.

   list--a proper list.

   test--a designator for a function of two arguments that returns a
generalized boolean.

   test-not--a designator for a function of two arguments that returns a
generalized boolean.

   key--a designator for a function of one argument, or nil.

   new-list--a list.

Description::
.............

Tests whether item is the same as an existing element of list.  If the
item is not an existing element, adjoin adds it to list (as if by cons)
and returns the resulting list; otherwise, nothing is added and the
original list is returned.

   The test, test-not, and key affect how it is determined whether item
is the same as an element of list.  For details, see *note Satisfying a
Two-Argument Test::.\ifvmode\else\endgraf \ifdim \prevdepth>-1000pt
\NIS\parskip \normalparskip\relax\fi

Examples::
..........

      (setq slist '()) =>  NIL
      (adjoin 'a slist) =>  (A)
      slist =>  NIL
      (setq slist (adjoin '(test-item 1) slist)) =>  ((TEST-ITEM 1))
      (adjoin '(test-item 1) slist) =>  ((TEST-ITEM 1) (TEST-ITEM 1))
      (adjoin '(test-item 1) slist :test 'equal) =>  ((TEST-ITEM 1))
      (adjoin '(new-test-item 1) slist :key #'cadr) =>  ((TEST-ITEM 1))
      (adjoin '(new-test-item 1) slist) =>  ((NEW-TEST-ITEM 1) (TEST-ITEM 1))

Exceptional Situations::
........................

Should be prepared to signal an error of type type-error if list is not
a proper list.

See Also::
..........

*note pushnew:: ,

   *note Traversal Rules and Side Effects::

Notes::
.......

The :test-not parameter is deprecated.

      (adjoin item list :key fn)
        == (if (member (fn item) list :key fn) list (cons item list))


File: gcl.info,  Node: pushnew,  Next: set-difference,  Prev: adjoin,  Up: Conses Dictionary

14.2.45 pushnew [Macro]
-----------------------

'pushnew' item place &key key test test-not
=> new-place-value

Arguments and Values::
......................

item--an object.

   place--a place, the value of which is a proper list.

   test--a designator for a function of two arguments that returns a
generalized boolean.

   test-not--a designator for a function of two arguments that returns a
generalized boolean.

   key--a designator for a function of one argument, or nil.

   new-place-value--a list (the new value of place).

Description::
.............

pushnew tests whether item is the same as any existing element of the
list stored in place.  If item is not, it is prepended to the list, and
the new list is stored in place.

   pushnew returns the new list that is stored in place.

   Whether or not item is already a member of the list that is in place
is determined by comparisons using :test or :test-not.  The first
argument to the :test or :test-not function is item; the second argument
is an element of the list in place as returned by the :key function (if
supplied).

   If :key is supplied, it is used to extract the part to be tested from
both item and the list element, as for adjoin.

   The argument to the :key function is an element of the list stored in
place.  The :key function typically returns part part of the element of
the list.  If :key is not supplied or nil, the list element is used.

   For information about the evaluation of subforms of place, see *note
Evaluation of Subforms to Places::.

   It is implementation-dependent whether or not pushnew actually
executes the storing form for its place in the situation where the item
is already a member of the list held by place.

Examples::
..........

      (setq x '(a (b c) d)) =>  (A (B C) D)
      (pushnew 5 (cadr x)) =>  (5 B C)
      x =>  (A (5 B C) D)
      (pushnew 'b (cadr x)) =>  (5 B C)
      x =>  (A (5 B C) D)
      (setq lst '((1) (1 2) (1 2 3))) =>  ((1) (1 2) (1 2 3))
      (pushnew '(2) lst) =>  ((2) (1) (1 2) (1 2 3))
      (pushnew '(1) lst) =>  ((1) (2) (1) (1 2) (1 2 3))
      (pushnew '(1) lst :test 'equal) =>  ((1) (2) (1) (1 2) (1 2 3))
      (pushnew '(1) lst :key #'car) =>  ((1) (2) (1) (1 2) (1 2 3))

Side Effects::
..............

The contents of place may be modified.

See Also::
..........

*note push:: , *note adjoin:: , *note Generalized Reference::

Notes::
.......

The effect of
      (pushnew item place :test p)

   is roughly equivalent to
      (setf place (adjoin item place :test p))

   except that the subforms of place are evaluated only once, and item
is evaluated before place.


File: gcl.info,  Node: set-difference,  Next: set-exclusive-or,  Prev: pushnew,  Up: Conses Dictionary

14.2.46 set-difference, nset-difference [Function]
--------------------------------------------------

'set-difference' list-1 list-2 &key key test test-not => result-list

   'nset-difference' list-1 list-2 &key key test test-not => result-list

Arguments and Values::
......................

list-1--a proper list.

   list-2--a proper list.

   test--a designator for a function of two arguments that returns a
generalized boolean.

   test-not--a designator for a function of two arguments that returns a
generalized boolean.

   key--a designator for a function of one argument, or nil.

   result-list--a list.

Description::
.............

set-difference returns a list of elements of list-1 that do not appear
in list-2.

   nset-difference is the destructive version of set-difference.  It may
destroy list-1.

   For all possible ordered pairs consisting of one element from list-1
and one element from list-2, the :test or :test-not function is used to
determine whether they satisfy the test.  The first argument to the
:test or :test-not function is the part of an element of list-1 that is
returned by the :key function (if supplied); the second argument is the
part of an element of list-2 that is returned by the :key function (if
supplied).

   If :key is supplied, its argument is a list-1 or list-2 element.  The
:key function typically returns part of the supplied element.  If :key
is not supplied, the list-1 or list-2 element is used.

   An element of list-1 appears in the result if and only if it does not
match any element of list-2.

   There is no guarantee that the order of elements in the result will
reflect the ordering of the arguments in any particular way.  The result
list may share cells with, or be eq to, either of list-1 or list-2, if
appropriate.

Examples::
..........

      (setq lst1 (list "A" "b" "C" "d")
            lst2 (list "a" "B" "C" "d")) =>  ("a" "B" "C" "d")
      (set-difference lst1 lst2) =>  ("d" "C" "b" "A")
      (set-difference lst1 lst2 :test 'equal) =>  ("b" "A")
      (set-difference lst1 lst2 :test #'equalp) =>  NIL
      (nset-difference lst1 lst2 :test #'string=) =>  ("A" "b")
      (setq lst1 '(("a" . "b") ("c" . "d") ("e" . "f")))
     =>  (("a" . "b") ("c" . "d") ("e" . "f"))
      (setq lst2 '(("c" . "a") ("e" . "b") ("d" . "a")))
     =>  (("c" . "a") ("e" . "b") ("d" . "a"))
      (nset-difference lst1 lst2 :test #'string= :key #'cdr)
     =>  (("c" . "d") ("e" . "f"))
      lst1 =>  (("a" . "b") ("c" . "d") ("e" . "f"))
      lst2 =>  (("c" . "a") ("e" . "b") ("d" . "a"))

     ;; Remove all flavor names that contain "c" or "w".
      (set-difference '("strawberry" "chocolate" "banana"
                       "lemon" "pistachio" "rhubarb")
               '(#\c #\w)
               :test #'(lambda (s c) (find c s)))
     =>  ("banana" "rhubarb" "lemon")    ;One possible ordering.

Side Effects::
..............

nset-difference may destroy list-1.

Exceptional Situations::
........................

Should be prepared to signal an error of type type-error if list-1 and
list-2 are not proper lists.

See Also::
..........

*note Compiler Terminology::,

   *note Traversal Rules and Side Effects::

Notes::
.......

The :test-not parameter is deprecated.


File: gcl.info,  Node: set-exclusive-or,  Next: subsetp,  Prev: set-difference,  Up: Conses Dictionary

14.2.47 set-exclusive-or, nset-exclusive-or [Function]
------------------------------------------------------

'set-exclusive-or' list-1 list-2 &key key test test-not => result-list

   'nset-exclusive-or' list-1 list-2 &key key test test-not =>
result-list

Arguments and Values::
......................

list-1--a proper list.

   list-2--a proper list.

   test--a designator for a function of two arguments that returns a
generalized boolean.

   test-not--a designator for a function of two arguments that returns a
generalized boolean.

   key--a designator for a function of one argument, or nil.

   result-list--a list.

Description::
.............

set-exclusive-or returns a list of elements that appear in exactly one
of list-1 and list-2.

   nset-exclusive-or is the destructive version of set-exclusive-or.

   For all possible ordered pairs consisting of one element from list-1
and one element from list-2, the :test or :test-not function is used to
determine whether they satisfy the test.

   If :key is supplied, it is used to extract the part to be tested from
the list-1 or list-2 element.  The first argument to the :test or
:test-not function is the part of an element of list-1 extracted by the
:key function (if supplied); the second argument is the part of an
element of list-2 extracted by the :key function (if supplied).  If :key
is not supplied or nil, the list-1 or list-2 element is used.

   The result contains precisely those elements of list-1 and list-2
that appear in no matching pair.

   The result list of set-exclusive-or might share storage with one of
list-1 or list-2.

Examples::
..........

      (setq lst1 (list 1 "a" "b")
            lst2 (list 1 "A" "b")) =>  (1 "A" "b")
      (set-exclusive-or lst1 lst2) =>  ("b" "A" "b" "a")
      (set-exclusive-or lst1 lst2 :test #'equal) =>  ("A" "a")
      (set-exclusive-or lst1 lst2 :test 'equalp) =>  NIL
      (nset-exclusive-or lst1 lst2) =>  ("a" "b" "A" "b")
      (setq lst1 (list (("a" . "b") ("c" . "d") ("e" . "f"))))
     =>  (("a" . "b") ("c" . "d") ("e" . "f"))
      (setq lst2 (list (("c" . "a") ("e" . "b") ("d" . "a"))))
     =>  (("c" . "a") ("e" . "b") ("d" . "a"))
      (nset-exclusive-or lst1 lst2 :test #'string= :key #'cdr)
     =>  (("c" . "d") ("e" . "f") ("c" . "a") ("d" . "a"))
      lst1 =>  (("a" . "b") ("c" . "d") ("e" . "f"))
      lst2 =>  (("c" . "a") ("d" . "a"))

Side Effects::
..............

nset-exclusive-or is permitted to modify any part, car or cdr, of the
list structure of list-1 or list-2.

Exceptional Situations::
........................

Should be prepared to signal an error of type type-error if list-1 and
list-2 are not proper lists.

See Also::
..........

*note Compiler Terminology::,

   *note Traversal Rules and Side Effects::

Notes::
.......

The :test-not parameter is deprecated.

   Since the nset-exclusive-or side effect is not required, it should
not be used in for-effect-only positions in portable code.


File: gcl.info,  Node: subsetp,  Next: union,  Prev: set-exclusive-or,  Up: Conses Dictionary

14.2.48 subsetp [Function]
--------------------------

'subsetp' list-1 list-2 &key key test test-not => generalized-boolean

Arguments and Values::
......................

list-1--a proper list.

   list-2--a proper list.

   test--a designator for a function of two arguments that returns a
generalized boolean.

   test-not--a designator for a function of two arguments that returns a
generalized boolean.

   key--a designator for a function of one argument, or nil.

   generalized-boolean--a generalized boolean.

Description::
.............

subsetp returns true if every element of list-1 matches some element of
list-2, and false otherwise.

   Whether a list element is the same as another list element is
determined by the functions specified by the keyword arguments.  The
first argument to the :test or :test-not function is typically part of
an element of list-1 extracted by the :key function; the second argument
is typically part of an element of list-2 extracted by the :key
function.

   The argument to the :key function is an element of either list-1 or
list-2; the return value is part of the element of the supplied list
element.  If :key is not supplied or nil, the list-1 or list-2 element
itself is supplied to the :test or :test-not function.

Examples::
..........

      (setq cosmos '(1 "a" (1 2))) =>  (1 "a" (1 2))
      (subsetp '(1) cosmos) =>  true
      (subsetp '((1 2)) cosmos) =>  false
      (subsetp '((1 2)) cosmos :test 'equal) =>  true
      (subsetp '(1 "A") cosmos :test #'equalp) =>  true
      (subsetp '((1) (2)) '((1) (2))) =>  false
      (subsetp '((1) (2)) '((1) (2)) :key #'car) =>  true

Exceptional Situations::
........................

Should be prepared to signal an error of type type-error if list-1 and
list-2 are not proper lists.

See Also::
..........

*note Traversal Rules and Side Effects::

Notes::
.......

The :test-not parameter is deprecated.


File: gcl.info,  Node: union,  Prev: subsetp,  Up: Conses Dictionary

14.2.49 union, nunion [Function]
--------------------------------

'union' list-1 list-2 &key key test test-not => result-list

   'nunion' list-1 list-2 &key key test test-not => result-list

Arguments and Values::
......................

list-1--a proper list.

   list-2--a proper list.

   test--a designator for a function of two arguments that returns a
generalized boolean.

   test-not--a designator for a function of two arguments that returns a
generalized boolean.

   key--a designator for a function of one argument, or nil.

   result-list--a list.

Description::
.............

union and nunion return a list that contains every element that occurs
in either list-1 or list-2.

   For all possible ordered pairs consisting of one element from list-1
and one element from list-2, :test or :test-not is used to determine
whether they satisfy the test.  The first argument to the :test or
:test-not function is the part of the element of list-1 extracted by the
:key function (if supplied); the second argument is the part of the
element of list-2 extracted by the :key function (if supplied).

   The argument to the :key function is an element of list-1 or list-2;
the return value is part of the supplied element.  If :key is not
supplied or nil, the element of list-1 or list-2 itself is supplied to
the :test or :test-not function.

   For every matching pair, one of the two elements of the pair will be
in the result.  Any element from either list-1 or list-2 that matches no
element of the other will appear in the result.

   If there is a duplication between list-1 and list-2, only one of the
duplicate instances will be in the result.  If either list-1 or list-2
has duplicate entries within it, the redundant entries might or might
not appear in the result.

   The order of elements in the result do not have to reflect the
ordering of list-1 or list-2 in any way.  The result list may be eq to
either list-1 or list-2 if appropriate.

Examples::
..........

      (union '(a b c) '(f a d))
     =>  (A B C F D)
     OR=> (B C F A D)
     OR=> (D F A B C)
      (union '((x 5) (y 6)) '((z 2) (x 4)) :key #'car)
     =>  ((X 5) (Y 6) (Z 2))
     OR=> ((X 4) (Y 6) (Z 2))

      (setq lst1 (list 1 2 '(1 2) "a" "b")
            lst2 (list 2 3 '(2 3) "B" "C"))
     =>  (2 3 (2 3) "B" "C")
      (nunion lst1 lst2)
     =>  (1 (1 2) "a" "b" 2 3 (2 3) "B" "C")
     OR=> (1 2 (1 2) "a" "b" "C" "B" (2 3) 3)

Side Effects::
..............

nunion is permitted to modify any part, car or cdr, of the list
structure of list-1 or list-2.

Exceptional Situations::
........................

Should be prepared to signal an error of type type-error if list-1 and
list-2 are not proper lists.

See Also::
..........

*note intersection:: ,

   *note Compiler Terminology::,

   *note Traversal Rules and Side Effects::

Notes::
.......

The :test-not parameter is deprecated.

   Since the nunion side effect is not required, it should not be used
in for-effect-only positions in portable code.


File: gcl.info,  Node: Arrays,  Next: Strings,  Prev: Conses,  Up: Top

15 Arrays
*********

* Menu:

* Array Concepts::
* Arrays Dictionary::


File: gcl.info,  Node: Array Concepts,  Next: Arrays Dictionary,  Prev: Arrays,  Up: Arrays

15.1 Array Concepts
===================

* Menu:

* Array Elements::
* Specialized Arrays::


File: gcl.info,  Node: Array Elements,  Next: Specialized Arrays,  Prev: Array Concepts,  Up: Array Concepts

15.1.1 Array Elements
---------------------

An array contains a set of objects called elements that can be
referenced individually according to a rectilinear coordinate system.

* Menu:

* Array Indices::
* Array Dimensions::
* Implementation Limits on Individual Array Dimensions::
* Array Rank::
* Vectors::
* Fill Pointers::
* Multidimensional Arrays::
* Storage Layout for Multidimensional Arrays::
* Implementation Limits on Array Rank::


File: gcl.info,  Node: Array Indices,  Next: Array Dimensions,  Prev: Array Elements,  Up: Array Elements

15.1.1.1 Array Indices
......................

An array element is referred to by a (possibly empty) series of indices.
The length of the series must equal the rank of the array.

   Each index must be a non-negative fixnum

   less than the corresponding array dimension.  Array indexing is
zero-origin.


File: gcl.info,  Node: Array Dimensions,  Next: Implementation Limits on Individual Array Dimensions,  Prev: Array Indices,  Up: Array Elements

15.1.1.2 Array Dimensions
.........................

An axis of an array is called a dimension .

   Each dimension is a non-negative

   fixnum;

   if any dimension of an array is zero, the array has no elements.  It
is permissible for a dimension to be zero, in which case the array has
no elements, and any attempt to access an element is an error.  However,
other properties of the array, such as the dimensions themselves, may be
used.


File: gcl.info,  Node: Implementation Limits on Individual Array Dimensions,  Next: Array Rank,  Prev: Array Dimensions,  Up: Array Elements

15.1.1.3 Implementation Limits on Individual Array Dimensions
.............................................................

An implementation may impose a limit on dimensions of an array, but
there is a minimum requirement on that limit.  See the variable
array-dimension-limit.


File: gcl.info,  Node: Array Rank,  Next: Vectors,  Prev: Implementation Limits on Individual Array Dimensions,  Up: Array Elements

15.1.1.4 Array Rank
...................

An array can have any number of dimensions (including zero).  The number
of dimensions is called the rank .

   If the rank of an array is zero then the array is said to have no
dimensions, and the product of the dimensions (see array-total-size) is
then 1; a zero-rank array therefore has a single element.


File: gcl.info,  Node: Vectors,  Next: Fill Pointers,  Prev: Array Rank,  Up: Array Elements

15.1.1.5 Vectors
................

An array of rank one (i.e., a one-dimensional array) is called a vector
.


File: gcl.info,  Node: Fill Pointers,  Next: Multidimensional Arrays,  Prev: Vectors,  Up: Array Elements

15.1.1.6 Fill Pointers
......................

A fill pointer is a non-negative integer no larger than the total number
of elements in a vector.  Not all vectors have fill pointers.  See the
functions make-array and adjust-array.

   An element of a vector is said to be active if it has an index that
is greater than or equal to zero, but less than the fill pointer (if
any).  For an array that has no fill pointer, all elements are
considered active.

   Only vectors may have fill pointers; multidimensional arrays may not.
A multidimensional array that is displaced to a vector that has a fill
pointer can be created.


File: gcl.info,  Node: Multidimensional Arrays,  Next: Storage Layout for Multidimensional Arrays,  Prev: Fill Pointers,  Up: Array Elements

15.1.1.7 Multidimensional Arrays
................................


File: gcl.info,  Node: Storage Layout for Multidimensional Arrays,  Next: Implementation Limits on Array Rank,  Prev: Multidimensional Arrays,  Up: Array Elements

15.1.1.8 Storage Layout for Multidimensional Arrays
...................................................

Multidimensional arrays store their components in row-major order; that
is, internally a multidimensional array is stored as a one-dimensional
array, with the multidimensional index sets ordered lexicographically,
last index varying fastest.


File: gcl.info,  Node: Implementation Limits on Array Rank,  Prev: Storage Layout for Multidimensional Arrays,  Up: Array Elements

15.1.1.9 Implementation Limits on Array Rank
............................................

An implementation may impose a limit on the rank of an array, but there
is a minimum requirement on that limit.  See the variable
array-rank-limit.


File: gcl.info,  Node: Specialized Arrays,  Prev: Array Elements,  Up: Array Concepts

15.1.2 Specialized Arrays
-------------------------

An array can be a general array, meaning each element may be any object,
or it may be a specialized array, meaning that each element must be of a
restricted type.

   The phrasing "an array specialized to type <<type>>" is sometimes
used to emphasize the element type of an array.  This phrasing is
tolerated even when the <<type>> is t, even though an array specialized
to type t is a general array, not a specialized array.

   Figure 15-1 lists some defined names that are applicable to array
creation, access, and information operations.

 adjust-array             array-in-bounds-p      svref                       
 adjustable-array-p       array-rank             upgraded-array-element-type 
 aref                     array-rank-limit       upgraded-complex-part-type  
 array-dimension          array-row-major-index  vector                      
 array-dimension-limit    array-total-size       vector-pop                  
 array-dimensions         array-total-size-limit vector-push                 
 array-element-type       fill-pointer           vector-push-extend          
 array-has-fill-pointer-p make-array                                         

           Figure 15-1: General Purpose Array-Related Defined Names          


* Menu:

* Array Upgrading::
* Required Kinds of Specialized Arrays::


File: gcl.info,  Node: Array Upgrading,  Next: Required Kinds of Specialized Arrays,  Prev: Specialized Arrays,  Up: Specialized Arrays

15.1.2.1 Array Upgrading
........................

The upgraded array element type of a type T_1 is a type T_2 that is a
supertype of T_1 and that is used instead of T_1 whenever T_1 is used as
an array element type for object creation or type discrimination.

   During creation of an array, the element type that was requested is
called the expressed array element type .  The upgraded array element
type of the expressed array element type becomes the actual array
element type of the array that is created.

   Type upgrading implies a movement upwards in the type hierarchy
lattice.  A type is always a subtype of its upgraded array element type.
Also, if a type T_x is a subtype of another type T_y, then the upgraded
array element type of T_x must be a subtype of the upgraded array
element type of T_y.  Two disjoint types can be upgraded to the same
type.

   The upgraded array element type T_2 of a type T_1 is a function only
of T_1 itself; that is, it is independent of any other property of the
array for which T_2 will be used, such as rank, adjustability, fill
pointers, or displacement.  The function upgraded-array-element-type can
be used by conforming programs to predict how the implementation will
upgrade a given type.


File: gcl.info,  Node: Required Kinds of Specialized Arrays,  Prev: Array Upgrading,  Up: Specialized Arrays

15.1.2.2 Required Kinds of Specialized Arrays
.............................................

Vectors whose elements are restricted to type

   character or a subtype of character

   are called strings .  Strings are of type string.  Figure 15-2 lists
some defined names related to strings.

   Strings are specialized arrays and might logically have been included
in this chapter.  However, for purposes of readability most information
about strings does not appear in this chapter; see instead *note
Strings::.

  char                string-equal         string-upcase  
  make-string         string-greaterp      string/=       
  nstring-capitalize  string-left-trim     string<        
  nstring-downcase    string-lessp         string<=       
  nstring-upcase      string-not-equal     string=        
  schar               string-not-greaterp  string>        
  string              string-not-lessp     string>=       
  string-capitalize   string-right-trim                   
  string-downcase     string-trim                         

      Figure 15-2: Operators that Manipulate Strings     


   Vectors whose elements are restricted to type bit are called bit
vectors .  Bit vectors are of type bit-vector.  Figure 15-3 lists some
defined names for operations on bit arrays.

  bit        bit-ior   bit-orc2  
  bit-and    bit-nand  bit-xor   
  bit-andc1  bit-nor   sbit      
  bit-andc2  bit-not             
  bit-eqv    bit-orc1            

  Figure 15-3: Operators that Manipulate Bit Arrays



File: gcl.info,  Node: Arrays Dictionary,  Prev: Array Concepts,  Up: Arrays

15.2 Arrays Dictionary
======================

* Menu:

* array::
* simple-array::
* vector (System Class)::
* simple-vector::
* bit-vector::
* simple-bit-vector::
* make-array::
* adjust-array::
* adjustable-array-p::
* aref::
* array-dimension::
* array-dimensions::
* array-element-type::
* array-has-fill-pointer-p::
* array-displacement::
* array-in-bounds-p::
* array-rank::
* array-row-major-index::
* array-total-size::
* arrayp::
* fill-pointer::
* row-major-aref::
* upgraded-array-element-type::
* array-dimension-limit::
* array-rank-limit::
* array-total-size-limit::
* simple-vector-p::
* svref::
* vector::
* vector-pop::
* vector-push::
* vectorp::
* bit (Array)::
* bit-and::
* bit-vector-p::
* simple-bit-vector-p::


File: gcl.info,  Node: array,  Next: simple-array,  Prev: Arrays Dictionary,  Up: Arrays Dictionary

15.2.1 array [System Class]
---------------------------

Class Precedence List::
.......................

array, t

Description::
.............

An array contains objects arranged according to a Cartesian coordinate
system.  An array provides mappings from a set of

   fixnums

   \left{i_0,i_1,\dots,i_{r-1}\right} to corresponding elements of the
array, where 0 \le i_j < d_j, r is the rank of the array, and d_j is the
size of dimension j of the array.

   When an array is created, the program requesting its creation may
declare that all elements are of a particular type, called the expressed
array element type.  The implementation is permitted to upgrade this
type in order to produce the actual array element type, which is the
element type for the array is actually specialized.  See the function
upgraded-array-element-type.

Compound Type Specifier Kind::
..............................

Specializing.

Compound Type Specifier Syntax::
................................

('array'{[{element-type | *} [dimension-spec]]})

   dimension-spec ::=rank | * | ({dimension | *}*)

Compound Type Specifier Arguments::
...................................

dimension--a valid array dimension.

   element-type--a type specifier.

   rank--a non-negative fixnum.

Compound Type Specifier Description::
.....................................

This denotes the set of arrays whose element type, rank, and dimensions
match any given element-type, rank, and dimensions.  Specifically:

   If element-type is the symbol *, arrays are not excluded on the basis
of their element type.  Otherwise, only those arrays are included whose
actual array element type

   is the result of upgrading element-type; see *note Array Upgrading::.

   If the dimension-spec is a rank, the set includes only those arrays
having that rank.  If the dimension-spec is a list of dimensions, the
set includes only those arrays having a rank given by the length of the
dimensions, and having the indicated dimensions; in this case, * matches
any value for the corresponding dimension.  If the dimension-spec is the
symbol *, the set is not restricted on the basis of rank or dimension.

See Also::
..........

*print-array*, *note aref:: , *note make-array:: , vector, *note
Sharpsign A::, *note Printing Other Arrays::

Notes::
.......

Note that the type (array t) is a proper subtype of the type (array *).
The reason is that the type (array t) is the set of arrays that can hold
any object (the elements are of type t, which includes all objects).  On
the other hand, the type (array *) is the set of all arrays whatsoever,
including for example arrays that can hold only characters.  The type
(array character) is not a subtype of the type (array t); the two sets
are disjoint because the type (array character) is not the set of all
arrays that can hold characters, but rather the set of arrays that are
specialized to hold precisely characters and no other objects.


File: gcl.info,  Node: simple-array,  Next: vector (System Class),  Prev: array,  Up: Arrays Dictionary

15.2.2 simple-array [Type]
--------------------------

Supertypes::
............

simple-array, array, t

Description::
.............

The type of an array that is not displaced to another array, has no fill
pointer, and is not expressly adjustable is a subtype of type
simple-array.  The concept of a simple array exists to allow the
implementation to use a specialized representation and to allow the user
to declare that certain values will always be simple arrays.

   The types simple-vector, simple-string, and simple-bit-vector are
disjoint subtypes of type simple-array, for they respectively mean
(simple-array t (*)), the union of all (simple-array c (*)) for any c
being a subtype of type character, and (simple-array bit (*)).

Compound Type Specifier Kind::
..............................

Specializing.

Compound Type Specifier Syntax::
................................

('simple-array'{[{element-type | *} [dimension-spec]]})

   dimension-spec ::=rank | * | ({dimension | *}*)

Compound Type Specifier Arguments::
...................................

dimension--a valid array dimension.

   element-type--a type specifier.

   rank--a non-negative fixnum.

Compound Type Specifier Description::
.....................................

This compound type specifier is treated exactly as the corresponding
compound type specifier for type array would be treated, except that the
set is further constrained to include only simple arrays.

Notes::
.......

It is implementation-dependent whether displaced arrays, vectors with
fill pointers, or arrays that are actually adjustable are simple arrays.

   (simple-array *) refers to all simple arrays regardless of element
type, (simple-array type-specifier) refers only to those simple arrays
that can result from giving type-specifier as the :element-type argument
to make-array.


File: gcl.info,  Node: vector (System Class),  Next: simple-vector,  Prev: simple-array,  Up: Arrays Dictionary

15.2.3 vector [System Class]
----------------------------

Class Precedence List::
.......................

vector, array, sequence, t

Description::
.............

Any one-dimensional array is a vector.

   The type vector is a subtype of type array; for all types x, (vector
x) is the same as (array x (*)).

   The type (vector t), the type string, and the type bit-vector are
disjoint subtypes of type vector.

Compound Type Specifier Kind::
..............................

Specializing.

Compound Type Specifier Syntax::
................................

('vector'{[{element-type | *} [{size | *}]]})

Compound Type Specifier Arguments::
...................................

size--a non-negative fixnum.

   element-type--a type specifier.

Compound Type Specifier Description::
.....................................

This denotes the set of specialized vectors whose element type and
dimension match the specified values.  Specifically:

   If element-type is the symbol *, vectors are not excluded on the
basis of their element type.  Otherwise, only those vectors are included
whose actual array element type

   is the result of upgrading element-type; see *note Array Upgrading::.

   If a size is specified, the set includes only those vectors whose
only dimension is size.  If the symbol * is specified instead of a size,
the set is not restricted on the basis of dimension.

See Also::
..........

*note Required Kinds of Specialized Arrays::, *note Sharpsign
Left-Parenthesis::, *note Printing Other Vectors::, *note Sharpsign A::

Notes::
.......

The type (vector e s) is equivalent to the type (array e (s)).

   The type (vector bit) has the name bit-vector.

   The union of all types (vector C), where C is any subtype of
character, has the name string.

   (vector *) refers to all vectors regardless of element type, (vector
type-specifier) refers only to those vectors that can result from giving
type-specifier as the :element-type argument to make-array.


File: gcl.info,  Node: simple-vector,  Next: bit-vector,  Prev: vector (System Class),  Up: Arrays Dictionary

15.2.4 simple-vector [Type]
---------------------------

Supertypes::
............

simple-vector, vector, simple-array, array, sequence, t

Description::
.............

The type of a vector that is not displaced to another array, has no fill
pointer, is not expressly adjustable and is able to hold elements of any
type is a subtype of type simple-vector.

   The type simple-vector is a subtype of type vector, and is a subtype
of type (vector t).

Compound Type Specifier Kind::
..............................

Specializing.

Compound Type Specifier Syntax::
................................

('simple-vector'{[size]})

Compound Type Specifier Arguments::
...................................

size--a non-negative fixnum, or the symbol *.  The default is the symbol
*.

Compound Type Specifier Description::
.....................................

This is the same as (simple-array t (size)).


File: gcl.info,  Node: bit-vector,  Next: simple-bit-vector,  Prev: simple-vector,  Up: Arrays Dictionary

15.2.5 bit-vector [System Class]
--------------------------------

Class Precedence List::
.......................

bit-vector, vector, array, sequence, t

Description::
.............

A bit vector is a vector the element type of which is bit.

   The type bit-vector is a subtype of type vector, for bit-vector means
(vector bit).

Compound Type Specifier Kind::
..............................

Abbreviating.

Compound Type Specifier Syntax::
................................

('bit-vector'{[size]})

Compound Type Specifier Arguments::
...................................

size--a non-negative fixnum, or the symbol *.

Compound Type Specifier Description::
.....................................

This denotes the same type as the type (array bit (size)); that is, the
set of bit vectors of size size.

See Also::
..........

*note Sharpsign Asterisk::, *note Printing Bit Vectors::, *note Required
Kinds of Specialized Arrays::


File: gcl.info,  Node: simple-bit-vector,  Next: make-array,  Prev: bit-vector,  Up: Arrays Dictionary

15.2.6 simple-bit-vector [Type]
-------------------------------

Supertypes::
............

simple-bit-vector, bit-vector, vector, simple-array, array, sequence, t

Description::
.............

The type of a bit vector that is not displaced to another array, has no
fill pointer, and is not expressly adjustable is a subtype of type
simple-bit-vector.

Compound Type Specifier Kind::
..............................

Abbreviating.

Compound Type Specifier Syntax::
................................

('simple-bit-vector'{[size]})

Compound Type Specifier Arguments::
...................................

size--a non-negative fixnum, or the symbol *.  The default is the symbol
*.

Compound Type Specifier Description::
.....................................

This denotes the same type as the type (simple-array bit (size)); that
is, the set of simple bit vectors of size size.


File: gcl.info,  Node: make-array,  Next: adjust-array,  Prev: simple-bit-vector,  Up: Arrays Dictionary

15.2.7 make-array [Function]
----------------------------

'make-array' dimensions &key element-type initial-element
initial-contents adjustable fill-pointer displaced-to
displaced-index-offset
=> new-array

Arguments and Values::
......................

dimensions--a designator for a list of valid array dimensions.

   element-type--a type specifier.  The default is t.

   initial-element--an object.

   initial-contents--an object.

   adjustable--a generalized boolean.  The default is nil.

   fill-pointer--a valid fill pointer for the array to be created, or t
or nil.  The default is nil.

   displaced-to--an array or nil.  The default is nil.  This option must
not be supplied if either initial-element or initial-contents is
supplied.

   displaced-index-offset--a valid array row-major index for
displaced-to.  The default is 0.  This option must not be supplied
unless a non-nil displaced-to is supplied.

   new-array--an array.

Description::
.............

Creates and returns an array constructed of the most specialized type
that can accommodate elements of type given by element-type.  If
dimensions is nil then a zero-dimensional array is created.

   Dimensions represents the dimensionality of the new array.

   element-type indicates the type of the elements intended to be stored
in the new-array.  The new-array can actually store any objects of the
type which results from upgrading element-type; see *note Array
Upgrading::.

   If initial-element is supplied, it is used to initialize each element
of new-array.  If initial-element is supplied, it must be of the type
given by element-type.  initial-element cannot be supplied if either the
:initial-contents option is supplied or displaced-to is non-nil.  If
initial-element is not supplied,

   the consequences of later reading an uninitialized element of
new-array are undefined

   unless either initial-contents is supplied or displaced-to is
non-nil.

   initial-contents is used to initialize the contents of array.  For
example:

      (make-array '(4 2 3) :initial-contents
                  '(((a b c) (1 2 3))
                   ((d e f) (3 1 2))
                   ((g h i) (2 3 1))
                   ((j k l) (0 0 0))))

   initial-contents is composed of a nested structure of sequences.  The
numbers of levels in the structure must equal the rank of array.  Each
leaf of the nested structure must be of the type given by element-type.
If array is zero-dimensional, then initial-contents specifies the single
element.  Otherwise, initial-contents must be a sequence whose length is
equal to the first dimension; each element must be a nested structure
for an array whose dimensions are the remaining dimensions, and so on.
Initial-contents cannot be supplied if either initial-element is
supplied or displaced-to is non-nil.  If initial-contents is not
supplied,

   the consequences of later reading an uninitialized element of
new-array are undefined

   unless either initial-element is supplied or displaced-to is non-nil.

   If adjustable is non-nil, the array is expressly adjustable (and so
actually adjustable); otherwise, the array is not expressly adjustable
(and it is implementation-dependent whether the array is actually
adjustable).

   If fill-pointer is non-nil, the array must be one-dimensional; that
is, the array must be a vector.  If fill-pointer is t, the length of the
vector is used to initialize the fill pointer.  If fill-pointer is an
integer, it becomes the initial fill pointer for the vector.

   If displaced-to is non-nil, make-array will create a displaced array
and displaced-to is the target of that displaced array.  In that case,
the consequences are undefined if the actual array element type of
displaced-to is not type equivalent to the actual array element type of
the array being created.  If displaced-to is nil, the array is not a
displaced array.

   The displaced-index-offset is made to be the index offset of the
array.  When an array A is given as the :displaced-to argument to
make-array when creating array B, then array B is said to be displaced
to array A. The total number of elements in an array, called the total
size of the array, is calculated as the product of all the dimensions.
It is required that the total size of A be no smaller than the sum of
the total size of B plus the offset n supplied by the
displaced-index-offset.  The effect of displacing is that array B does
not have any elements of its own, but instead maps accesses to itself
into accesses to array A. The mapping treats both arrays as if they were
one-dimensional by taking the elements in row-major order, and then maps
an access to element k of array B to an access to element k+n of array
A.

   If make-array is called with adjustable, fill-pointer, and
displaced-to each nil, then the result is a simple array.

   If make-array is called with one or more of adjustable, fill-pointer,
or displaced-to being true, whether the resulting array is a simple
array is implementation-dependent.

   When an array A is given as the :displaced-to argument to make-array
when creating array B, then array B is said to be displaced to array A.
The total number of elements in an array, called the total size of the
array, is calculated as the product of all the dimensions.  The
consequences are unspecified if the total size of A is smaller than the
sum of the total size of B plus the offset n supplied by the
displaced-index-offset.  The effect of displacing is that array B does
not have any elements of its own, but instead maps accesses to itself
into accesses to array A. The mapping treats both arrays as if they were
one-dimensional by taking the elements in row-major order, and then maps
an access to element k of array B to an access to element k+n of array
A.

Examples::
..........


      (make-array 5) ;; Creates a one-dimensional array of five elements.
      (make-array '(3 4) :element-type '(mod 16)) ;; Creates a
                     ;;two-dimensional array, 3 by 4, with four-bit elements.
      (make-array 5 :element-type 'single-float) ;; Creates an array of single-floats.

      (make-array nil :initial-element nil) =>  #0ANIL
      (make-array 4 :initial-element nil) =>  #(NIL NIL NIL NIL)
      (make-array '(2 4)
                   :element-type '(unsigned-byte 2)
                   :initial-contents '((0 1 2 3) (3 2 1 0)))
     =>  #2A((0 1 2 3) (3 2 1 0))
      (make-array 6
                   :element-type 'character
                   :initial-element #\a
                   :fill-pointer 3) =>  "aaa"

   The following is an example of making a displaced array.

      (setq a (make-array '(4 3)))
     =>  #<ARRAY 4x3 simple 32546632>
      (dotimes (i 4)
        (dotimes (j 3)
          (setf (aref a i j) (list i 'x j '= (* i j)))))
     =>  NIL
      (setq b (make-array 8 :displaced-to a
                            :displaced-index-offset 2))
     =>  #<ARRAY 8 indirect 32550757>
      (dotimes (i 8)
        (print (list i (aref b i))))
      |>  (0 (0 X 2 = 0))
      |>  (1 (1 X 0 = 0))
      |>  (2 (1 X 1 = 1))
      |>  (3 (1 X 2 = 2))
      |>  (4 (2 X 0 = 0))
      |>  (5 (2 X 1 = 2))
      |>  (6 (2 X 2 = 4))
      |>  (7 (3 X 0 = 0))
     =>  NIL

   The last example depends on the fact that arrays are, in effect,
stored in row-major order.

      (setq a1 (make-array 50))
     =>  #<ARRAY 50 simple 32562043>
      (setq b1 (make-array 20 :displaced-to a1 :displaced-index-offset 10))
     =>  #<ARRAY 20 indirect 32563346>
      (length b1) =>  20

      (setq a2 (make-array 50 :fill-pointer 10))
     =>  #<ARRAY 50 fill-pointer 10 46100216>
      (setq b2 (make-array 20 :displaced-to a2 :displaced-index-offset 10))
     =>  #<ARRAY 20 indirect 46104010>
      (length a2) =>  10
      (length b2) =>  20

      (setq a3 (make-array 50 :fill-pointer 10))
     =>  #<ARRAY 50 fill-pointer 10 46105663>
      (setq b3 (make-array 20 :displaced-to a3 :displaced-index-offset 10
                              :fill-pointer 5))
     =>  #<ARRAY 20 indirect, fill-pointer 5 46107432>
      (length a3) =>  10
      (length b3) =>  5

See Also::
..........

*note adjustable-array-p:: , *note aref:: , *note arrayp:: , *note
array-element-type:: , *note array-rank-limit:: , *note
array-dimension-limit:: , *note fill-pointer:: , *note
upgraded-array-element-type::

Notes::
.......

There is no specified way to create an array for which
adjustable-array-p definitely returns false.  There is no specified way
to create an array that is not a simple array.


File: gcl.info,  Node: adjust-array,  Next: adjustable-array-p,  Prev: make-array,  Up: Arrays Dictionary

15.2.8 adjust-array [Function]
------------------------------

'adjust-array' array new-dimensions &key element-type initial-element
initial-contents fill-pointer displaced-to displaced-index-offset
=> adjusted-array

Arguments and Values::
......................

array--an array.

   new-dimensions--a valid array dimension or a list of valid array
dimensions.

   element-type--a type specifier.

   initial-element--an object.  Initial-element must not be supplied if
either initial-contents or displaced-to is supplied.

   initial-contents--an object.  If array has rank greater than zero,
then initial-contents is composed of nested sequences, the depth of
which must equal the rank of array.  Otherwise, array is
zero-dimensional and initial-contents supplies the single element.
initial-contents must not be supplied if either initial-element or
displaced-to is given.

   fill-pointer--a valid fill pointer for the array to be created, or t,
or nil.  The default is nil.

   displaced-to--an array or nil.  initial-elements and initial-contents
must not be supplied if displaced-to is supplied.

   displaced-index-offset--an object of type (fixnum 0 n) where n is
(array-total-size displaced-to).  displaced-index-offset may be supplied
only if displaced-to is supplied.

   adjusted-array--an array.

Description::
.............

adjust-array changes the dimensions or elements of array.  The result is
an array of the same type and rank as array, that is either the modified
array, or a newly created array to which array can be displaced, and
that has the given new-dimensions.

   New-dimensions specify the size of each dimension of array.

   Element-type specifies the type of the elements of the resulting
array.  If element-type is supplied, the consequences are unspecified if
the upgraded array element type of element-type is not the same as the
actual array element type of array.

   If initial-contents is supplied, it is treated as for make-array.  In
this case none of the original contents of array appears in the
resulting array.

   If fill-pointer is an integer, it becomes the fill pointer for the
resulting array.  If fill-pointer is the symbol t, it indicates that the
size of the resulting array should be used as the fill pointer.  If
fill-pointer is nil, it indicates that the fill pointer should be left
as it is.

   If displaced-to non-nil, a displaced array is created.  The resulting
array shares its contents with the array given by displaced-to.  The
resulting array cannot contain more elements than the array it is
displaced to.  If displaced-to is not supplied or nil, the resulting
array is not a displaced array.  If array A is created displaced to
array B and subsequently array B is given to adjust-array, array A will
still be displaced to array B. Although array might be a displaced
array, the resulting array is not a displaced array unless displaced-to
is supplied and not nil.

   The interaction between adjust-array and displaced arrays is as
follows given three arrays, A, B, and~C:

A is not displaced before or after the call
           (adjust-array A ...)

     The dimensions of A are altered, and the contents rearranged as
     appropriate.  Additional elements of A are taken from
     initial-element.  The use of initial-contents causes all old
     contents to be discarded.

A is not displaced before, but is displaced to
     C after the call
           (adjust-array A ... :displaced-to C)

     None of the original contents of A appears in A afterwards; A now
     contains the contents of C, without any rearrangement of C.

A is displaced to B
     before the call, and is displaced to C after the call
           (adjust-array A ... :displaced-to B)
           (adjust-array A ... :displaced-to C)

     B and C might be the same.  The contents of B do not appear in A
     afterward unless such contents also happen to be in C If
     displaced-index-offset is not supplied in the adjust-array call, it
     defaults to zero; the old offset into B is not retained.

A is displaced to B before the call, but not displaced
     afterward.
           (adjust-array A ... :displaced-to B)
           (adjust-array A ... :displaced-to nil)

     A gets a new "data region," and contents of B are copied into it as
     appropriate to maintain the existing old contents; additional
     elements of A are taken from initial-element if supplied.  However,
     the use of initial-contents causes all old contents to be
     discarded.

   If displaced-index-offset is supplied, it specifies the offset of the
resulting array from the beginning of the array that it is displaced to.
If displaced-index-offset is not supplied, the offset is~0.  The size of
the resulting array plus the offset value cannot exceed the size of the
array that it is displaced to.

   If only new-dimensions and an initial-element argument are supplied,
those elements of array that are still in bounds appear in the resulting
array.  The elements of the resulting array that are not in the bounds
of array are initialized to initial-element; if initial-element is not
provided,

   the consequences of later reading any such new element of new-array
before it has been initialized are undefined.

   If initial-contents or displaced-to is supplied, then none of the
original contents of array appears in the new array.

   The consequences are unspecified if array is adjusted to a size
smaller than its fill pointer without supplying the fill-pointer
argument so that its fill-pointer is properly adjusted in the process.

   If A is displaced to B, the consequences are unspecified if B is
adjusted in such a way that it no longer has enough elements to satisfy
A.

   If adjust-array is applied to an array that is actually adjustable,
the array returned is identical to array.  If the array returned by
adjust-array is distinct from array, then the argument array is
unchanged.

   Note that if an array A is displaced to another array B, and B is
displaced to another array C, and B is altered by adjust-array, A must
now refer to the adjust contents of B. This means that an implementation
cannot collapse the chain to make A refer to C directly and forget that
the chain of reference passes through B. However, caching techniques are
permitted as long as they preserve the semantics specified here.

Examples::
..........

      (adjustable-array-p
       (setq ada (adjust-array
                   (make-array '(2 3)
                               :adjustable t
                               :initial-contents '((a b c) (1 2 3)))
                   '(4 6)))) =>  T
      (array-dimensions ada) =>  (4 6)
      (aref ada 1 1) =>  2
      (setq beta (make-array '(2 3) :adjustable t))
     =>  #2A((NIL NIL NIL) (NIL NIL NIL))
      (adjust-array beta '(4 6) :displaced-to ada)
     =>  #2A((A B C NIL NIL NIL)
            (1 2 3 NIL NIL NIL)
            (NIL NIL NIL NIL NIL NIL)
            (NIL NIL NIL NIL NIL NIL))
      (array-dimensions beta) =>  (4 6)
      (aref beta 1 1) =>  2

   Suppose that the 4-by-4 array in m looks like this:

     #2A(( alpha     beta      gamma     delta )
         ( epsilon   zeta      eta       theta )
         ( iota      kappa     lambda    mu    )
         ( nu        xi        omicron   pi    ))

   Then the result of

      (adjust-array m '(3 5) :initial-element 'baz)

   is a 3-by-5 array with contents

     #2A(( alpha     beta      gamma     delta     baz )
         ( epsilon   zeta      eta       theta     baz )
         ( iota      kappa     lambda    mu        baz ))

Exceptional Situations::
........................

An error of type error is signaled if fill-pointer is supplied and
non-nil but array has no fill pointer.

See Also::
..........

*note adjustable-array-p:: , *note make-array:: , *note
array-dimension-limit:: , *note array-total-size-limit:: , array


File: gcl.info,  Node: adjustable-array-p,  Next: aref,  Prev: adjust-array,  Up: Arrays Dictionary

15.2.9 adjustable-array-p [Function]
------------------------------------

'adjustable-array-p' array => generalized-boolean

Arguments and Values::
......................

array--an array.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if and only if adjust-array could return a value which is
identical to array when given that array as its first argument.

Examples::
..........

      (adjustable-array-p
        (make-array 5
                    :element-type 'character
                    :adjustable t
                    :fill-pointer 3)) =>  true
      (adjustable-array-p (make-array 4)) =>  implementation-dependent

Exceptional Situations::
........................

Should signal an error of type type-error if its argument is not an
array.

See Also::
..........

*note adjust-array:: , *note make-array::


File: gcl.info,  Node: aref,  Next: array-dimension,  Prev: adjustable-array-p,  Up: Arrays Dictionary

15.2.10 aref [Accessor]
-----------------------

'aref' array &rest subscripts => element

   (setf (' aref' array &rest subscripts) new-element)

Arguments and Values::
......................

array--an array.

   subscripts--a list of valid array indices for the array.

   element, new-element--an object.

Description::
.............

Accesses the array element specified by the subscripts.  If no
subscripts are supplied and array is zero rank, aref accesses the sole
element of array.

   aref ignores fill pointers.  It is permissible to use aref to access
any array element, whether active or not.

Examples::
..........

If the variable foo names a 3-by-5 array, then the first index could be
0, 1, or 2, and then second index could be 0, 1, 2, 3, or 4.  The array
elements can be referred to by using the function aref; for example,
(aref foo 2 1) refers to element (2, 1) of the array.

      (aref (setq alpha (make-array 4)) 3) =>  implementation-dependent
      (setf (aref alpha 3) 'sirens) =>  SIRENS
      (aref alpha 3) =>  SIRENS
      (aref (setq beta (make-array '(2 4)
                         :element-type '(unsigned-byte 2)
                         :initial-contents '((0 1 2 3) (3 2 1 0))))
             1 2) =>  1
      (setq gamma '(0 2))
      (apply #'aref beta gamma) =>  2
      (setf (apply #'aref beta gamma) 3) =>  3
      (apply #'aref beta gamma) =>  3
      (aref beta 0 2) =>  3

See Also::
..........

*note bit (Array):: , *note char:: , *note elt:: , *note
row-major-aref:: , *note svref:: ,

   *note Compiler Terminology::


File: gcl.info,  Node: array-dimension,  Next: array-dimensions,  Prev: aref,  Up: Arrays Dictionary

15.2.11 array-dimension [Function]
----------------------------------

'array-dimension' array axis-number => dimension

Arguments and Values::
......................

array--an array.

   axis-number--an integer greater than or equal to zero and less than
the rank of the array.

   dimension--a non-negative integer.

Description::
.............

array-dimension returns the axis-number dimension_1 of array.  (Any fill
pointer is ignored.)

Examples::
..........

      (array-dimension (make-array 4) 0) =>  4
      (array-dimension (make-array '(2 3)) 1) =>  3

Affected By::
.............

None.

See Also::
..........

*note array-dimensions:: , *note length::

Notes::
.......

      (array-dimension array n) == (nth n (array-dimensions array))


File: gcl.info,  Node: array-dimensions,  Next: array-element-type,  Prev: array-dimension,  Up: Arrays Dictionary

15.2.12 array-dimensions [Function]
-----------------------------------

'array-dimensions' array => dimensions

Arguments and Values::
......................

array--an array.

   dimensions--a list of integers.

Description::
.............

Returns a list of the dimensions of array.  (If array is a vector with a
fill pointer, that fill pointer is ignored.)

Examples::
..........

      (array-dimensions (make-array 4)) =>  (4)
      (array-dimensions (make-array '(2 3))) =>  (2 3)
      (array-dimensions (make-array 4 :fill-pointer 2)) =>  (4)

Exceptional Situations::
........................

Should signal an error of type type-error if its argument is not an
array.

See Also::
..........

*note array-dimension::


File: gcl.info,  Node: array-element-type,  Next: array-has-fill-pointer-p,  Prev: array-dimensions,  Up: Arrays Dictionary

15.2.13 array-element-type [Function]
-------------------------------------

'array-element-type' array => typespec

Arguments and Values::
......................

array--an array.

   typespec--a type specifier.

Description::
.............

Returns a type specifier which represents the actual array element type
of the array, which is the set of objects that such an array can hold.
(Because of array upgrading, this type specifier can in some cases
denote a supertype of the expressed array element type of the array.)

Examples::
..........

      (array-element-type (make-array 4)) =>  T
      (array-element-type (make-array 12 :element-type '(unsigned-byte 8)))
     =>  implementation-dependent
      (array-element-type (make-array 12 :element-type '(unsigned-byte 5)))
     =>  implementation-dependent

      (array-element-type (make-array 5 :element-type '(mod 5)))

   could be (mod 5), (mod 8), fixnum, t, or any other type of which (mod
5) is a subtype.

Affected By::
.............

The implementation.

Exceptional Situations::
........................

Should signal an error of type type-error if its argument is not an
array.

See Also::
..........

array, *note make-array:: , *note subtypep:: , *note
upgraded-array-element-type::


File: gcl.info,  Node: array-has-fill-pointer-p,  Next: array-displacement,  Prev: array-element-type,  Up: Arrays Dictionary

15.2.14 array-has-fill-pointer-p [Function]
-------------------------------------------

'array-has-fill-pointer-p' array => generalized-boolean

Arguments and Values::
......................

array--an array.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if array has a fill pointer; otherwise returns false.

Examples::
..........

      (array-has-fill-pointer-p (make-array 4)) =>  implementation-dependent
      (array-has-fill-pointer-p (make-array '(2 3))) =>  false
      (array-has-fill-pointer-p
        (make-array 8
                    :fill-pointer 2
                    :initial-element 'filler)) =>  true

Exceptional Situations::
........................

Should signal an error of type type-error if its argument is not an
array.

See Also::
..........

*note make-array:: , *note fill-pointer::

Notes::
.......

Since arrays of rank other than one cannot have a fill pointer,
array-has-fill-pointer-p always returns nil when its argument is such an
array.


File: gcl.info,  Node: array-displacement,  Next: array-in-bounds-p,  Prev: array-has-fill-pointer-p,  Up: Arrays Dictionary

15.2.15 array-displacement [Function]
-------------------------------------

'array-displacement' array => displaced-to, displaced-index-offset

Arguments and Values::
......................

array--an array.

   displaced-to--an array or nil.

   displaced-index-offset--a non-negative fixnum.

Description::
.............

If the array is a displaced array, returns the values of the
:displaced-to and :displaced-index-offset options for the array (see the
functions make-array and adjust-array).  If the array is not a displaced
array, nil and 0 are returned.

   If array-displacement is called on an array for which a non-nil
object was provided as the :displaced-to argument to make-array or
adjust-array, it must return that object as its first value.  It is
implementation-dependent whether array-displacement returns a non-nil
primary value for any other array.

Examples::
..........

      (setq a1 (make-array 5)) =>  #<ARRAY 5 simple 46115576>
      (setq a2 (make-array 4 :displaced-to a1
                             :displaced-index-offset 1))
     =>  #<ARRAY 4 indirect 46117134>
      (array-displacement a2)
     =>  #<ARRAY 5 simple 46115576>, 1
      (setq a3 (make-array 2 :displaced-to a2
                             :displaced-index-offset 2))
     =>  #<ARRAY 2 indirect 46122527>
      (array-displacement a3)
     =>  #<ARRAY 4 indirect 46117134>, 2

Exceptional Situations::
........................

Should signal an error of type type-error if array is not an array.

See Also::
..........

*note make-array::


File: gcl.info,  Node: array-in-bounds-p,  Next: array-rank,  Prev: array-displacement,  Up: Arrays Dictionary

15.2.16 array-in-bounds-p [Function]
------------------------------------

'array-in-bounds-p' array &rest subscripts => generalized-boolean

Arguments and Values::
......................

array--an array.

   subscripts--a list of integers of length equal to the rank of the
array.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if the subscripts are all in bounds for array; otherwise
returns false.  (If array is a vector with a fill pointer, that fill
pointer is ignored.)

Examples::
..........

      (setq a (make-array '(7 11) :element-type 'string-char))
      (array-in-bounds-p a 0  0) =>  true
      (array-in-bounds-p a 6 10) =>  true
      (array-in-bounds-p a 0 -1) =>  false
      (array-in-bounds-p a 0 11) =>  false
      (array-in-bounds-p a 7  0) =>  false

See Also::
..........

*note array-dimensions::

Notes::
.......

      (array-in-bounds-p array subscripts)
      == (and (not (some #'minusp (list subscripts)))
              (every #'< (list subscripts) (array-dimensions array)))


File: gcl.info,  Node: array-rank,  Next: array-row-major-index,  Prev: array-in-bounds-p,  Up: Arrays Dictionary

15.2.17 array-rank [Function]
-----------------------------

'array-rank' array => rank

Arguments and Values::
......................

array--an array.

   rank--a non-negative integer.

Description::
.............

Returns the number of dimensions of array.

Examples::
..........

      (array-rank (make-array '())) =>  0
      (array-rank (make-array 4)) =>  1
      (array-rank (make-array '(4))) =>  1
      (array-rank (make-array '(2 3))) =>  2

Exceptional Situations::
........................

Should signal an error of type type-error if its argument is not an
array.

See Also::
..........

*note array-rank-limit:: , *note make-array::


File: gcl.info,  Node: array-row-major-index,  Next: array-total-size,  Prev: array-rank,  Up: Arrays Dictionary

15.2.18 array-row-major-index [Function]
----------------------------------------

'array-row-major-index' array &rest subscripts => index

Arguments and Values::
......................

array--an array.

   subscripts--a list of valid array indices for the array.

   index--a valid array row-major index for the array.

Description::
.............

Computes the position according to the row-major ordering of array for
the element that is specified by subscripts, and returns the offset of
the element in the computed position from the beginning of array.

   For a one-dimensional array, the result of array-row-major-index
equals subscript.

   array-row-major-index ignores fill pointers.

Examples::
..........

      (setq a (make-array '(4 7) :element-type '(unsigned-byte 8)))
      (array-row-major-index a 1 2) =>  9
      (array-row-major-index
         (make-array '(2 3 4)
                     :element-type '(unsigned-byte 8)
                     :displaced-to a
                     :displaced-index-offset 4)
         0 2 1) =>  9

Notes::
.......

A possible definition of array-row-major-index, with no error-checking,
is

      (defun array-row-major-index (a &rest subscripts)
        (apply #'+ (maplist #'(lambda (x y)
                                 (* (car x) (apply #'* (cdr y))))
                            subscripts
                            (array-dimensions a))))


File: gcl.info,  Node: array-total-size,  Next: arrayp,  Prev: array-row-major-index,  Up: Arrays Dictionary

15.2.19 array-total-size [Function]
-----------------------------------

'array-total-size' array => size

Arguments and Values::
......................

array--an array.

   size--a non-negative integer.

Description::
.............

Returns the array total size of the array.

Examples::
..........

      (array-total-size (make-array 4)) =>  4
      (array-total-size (make-array 4 :fill-pointer 2)) =>  4
      (array-total-size (make-array 0)) =>  0
      (array-total-size (make-array '(4 2))) =>  8
      (array-total-size (make-array '(4 0))) =>  0
      (array-total-size (make-array '())) =>  1

Exceptional Situations::
........................

Should signal an error of type type-error if its argument is not an
array.

See Also::
..........

*note make-array:: , *note array-dimensions::

Notes::
.......

If the array is a vector with a fill pointer, the fill pointer is
ignored when calculating the array total size.

   Since the product of no arguments is one, the array total size of a
zero-dimensional array is one.

      (array-total-size x)
         == (apply #'* (array-dimensions x))
         == (reduce #'* (array-dimensions x))


File: gcl.info,  Node: arrayp,  Next: fill-pointer,  Prev: array-total-size,  Up: Arrays Dictionary

15.2.20 arrayp [Function]
-------------------------

'arrayp' object => generalized-boolean

Arguments and Values::
......................

object--an object.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if object is of type array; otherwise, returns false.

Examples::
..........

      (arrayp (make-array '(2 3 4) :adjustable t)) =>  true
      (arrayp (make-array 6)) =>  true
      (arrayp #*1011) =>  true
      (arrayp "hi") =>  true
      (arrayp 'hi) =>  false
      (arrayp 12) =>  false

See Also::
..........

*note typep::

Notes::
.......

      (arrayp object) == (typep object 'array)


File: gcl.info,  Node: fill-pointer,  Next: row-major-aref,  Prev: arrayp,  Up: Arrays Dictionary

15.2.21 fill-pointer [Accessor]
-------------------------------

'fill-pointer' vector => fill-pointer

   (setf (' fill-pointer' vector) new-fill-pointer)

Arguments and Values::
......................

vector--a vector with a fill pointer.

   fill-pointer, new-fill-pointer--a valid fill pointer for the vector.

Description::
.............

Accesses the fill pointer of vector.

Examples::
..........

      (setq a (make-array 8 :fill-pointer 4)) =>  #(NIL NIL NIL NIL)
      (fill-pointer a) =>  4
      (dotimes (i (length a)) (setf (aref a i) (* i i))) =>  NIL
      a =>  #(0 1 4 9)
      (setf (fill-pointer a) 3) =>  3
      (fill-pointer a) =>  3
      a =>  #(0 1 4)
      (setf (fill-pointer a) 8) =>  8
      a =>  #(0 1 4 9 NIL NIL NIL NIL)

Exceptional Situations::
........................

Should signal an error of type type-error if vector is not a vector with
a fill pointer.

See Also::
..........

*note make-array:: , *note length::

Notes::
.......

There is no operator that will remove a vector's fill pointer.


File: gcl.info,  Node: row-major-aref,  Next: upgraded-array-element-type,  Prev: fill-pointer,  Up: Arrays Dictionary

15.2.22 row-major-aref [Accessor]
---------------------------------

'row-major-aref' array index => element

   (setf (' row-major-aref' array index) new-element)

Arguments and Values::
......................

array--an array.

   index--a valid array row-major index for the array.

   element, new-element--an object.

Description::
.............

Considers array as a vector by viewing its elements in row-major order,
and returns the element of that vector which is referred to by the given
index.

   row-major-aref is valid for use with setf.

See Also::
..........

*note aref:: , *note array-row-major-index::

Notes::
.......

      (row-major-aref array index) ==
        (aref (make-array (array-total-size array)
                          :displaced-to array
                          :element-type (array-element-type array))
              index)

      (aref array i1 i2 ...) ==
          (row-major-aref array (array-row-major-index array i1 i2))


File: gcl.info,  Node: upgraded-array-element-type,  Next: array-dimension-limit,  Prev: row-major-aref,  Up: Arrays Dictionary

15.2.23 upgraded-array-element-type [Function]
----------------------------------------------

'upgraded-array-element-type' typespec &optional environment =>
upgraded-typespec

Arguments and Values::
......................

typespec--a type specifier.

   environment--an environment object.  The default is nil, denoting the
null lexical environment and the current global environment.

   upgraded-typespec--a type specifier.

Description::
.............

Returns the element type of the most specialized array representation
capable of holding items of the type denoted by typespec.

   The typespec is a subtype of (and possibly type equivalent to) the
upgraded-typespec.

   If typespec is bit, the result is type equivalent to bit.

   If typespec is base-char, the result is type equivalent to base-char.

   If typespec is character, the result is type equivalent to character.

   The purpose of upgraded-array-element-type is to reveal how an
implementation does its upgrading.

   The environment is used to expand any derived type specifiers that
are mentioned in the typespec.

See Also::
..........

*note array-element-type:: , *note make-array::

Notes::
.......

Except for storage allocation consequences and dealing correctly with
the optional environment argument, upgraded-array-element-type could be
defined as:

      (defun upgraded-array-element-type (type &optional environment)
        (array-element-type (make-array 0 :element-type type)))


File: gcl.info,  Node: array-dimension-limit,  Next: array-rank-limit,  Prev: upgraded-array-element-type,  Up: Arrays Dictionary

15.2.24 array-dimension-limit [Constant Variable]
-------------------------------------------------

Constant Value::
................

A positive

   fixnum,

   the exact magnitude of which is implementation-dependent, but which
is not less than 1024.

Description::
.............

The upper exclusive bound on each individual dimension of an array.

See Also::
..........

*note make-array::


File: gcl.info,  Node: array-rank-limit,  Next: array-total-size-limit,  Prev: array-dimension-limit,  Up: Arrays Dictionary

15.2.25 array-rank-limit [Constant Variable]
--------------------------------------------

Constant Value::
................

A positive

   fixnum,

   the exact magnitude of which is implementation-dependent, but which
is not less than 8.

Description::
.............

The upper exclusive bound on the rank of an array.

See Also::
..........

*note make-array::


File: gcl.info,  Node: array-total-size-limit,  Next: simple-vector-p,  Prev: array-rank-limit,  Up: Arrays Dictionary

15.2.26 array-total-size-limit [Constant Variable]
--------------------------------------------------

Constant Value::
................

A positive

   fixnum,

   the exact magnitude of which is implementation-dependent, but which
is not less than 1024.

Description::
.............

The upper exclusive bound on the array total size of an array.

   The actual limit on the array total size imposed by the
implementation might vary according the element type of the array; in
this case, the value of array-total-size-limit will be the smallest of
these possible limits.

See Also::
..........

*note make-array:: , *note array-element-type::


File: gcl.info,  Node: simple-vector-p,  Next: svref,  Prev: array-total-size-limit,  Up: Arrays Dictionary

15.2.27 simple-vector-p [Function]
----------------------------------

'simple-vector-p' object => generalized-boolean

Arguments and Values::
......................

object--an object.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if object is of type simple-vector; otherwise, returns
false..

Examples::
..........

      (simple-vector-p (make-array 6)) =>  true
      (simple-vector-p "aaaaaa") =>  false
      (simple-vector-p (make-array 6 :fill-pointer t)) =>  false

See Also::
..........

simple-vector

Notes::
.......

      (simple-vector-p object) == (typep object 'simple-vector)


File: gcl.info,  Node: svref,  Next: vector,  Prev: simple-vector-p,  Up: Arrays Dictionary

15.2.28 svref [Accessor]
------------------------

'svref' simple-vector index => element

   (setf (' svref' simple-vector index) new-element)

Arguments and Values::
......................

simple-vector--a simple vector.

   index--a valid array index for the simple-vector.

   element, new-element--an object (whose type is a subtype of the array
element type of the simple-vector).

Description::
.............

Accesses the element of simple-vector specified by index.

Examples::
..........

      (simple-vector-p (setq v (vector 1 2 'sirens))) =>  true
      (svref v 0) =>  1
      (svref v 2) =>  SIRENS
      (setf (svref v 1) 'newcomer) =>  NEWCOMER
      v =>  #(1 NEWCOMER SIRENS)

See Also::
..........

*note aref:: , sbit, schar, *note vector:: ,

   *note Compiler Terminology::

Notes::
.......

svref is identical to aref except that it requires its first argument to
be a simple vector.

      (svref v i) == (aref (the simple-vector v) i)


File: gcl.info,  Node: vector,  Next: vector-pop,  Prev: svref,  Up: Arrays Dictionary

15.2.29 vector [Function]
-------------------------

'vector' &rest objects => vector

Arguments and Values::
......................

object--an object.

   vector--a vector of type (vector t *).

Description::
.............

Creates a fresh simple general vector whose size corresponds to the
number of objects.

   The vector is initialized to contain the objects.

Examples::
..........

      (arrayp (setq v (vector 1 2 'sirens))) =>  true
      (vectorp v) =>  true
      (simple-vector-p v) =>  true
      (length v) =>  3

See Also::
..........

*note make-array::

Notes::
.......

vector is analogous to list.

      (vector a_1 a_2 ... a_n)
       == (make-array (list n) :element-type t
                               :initial-contents
                                 (list a_1 a_2 ... a_n))


File: gcl.info,  Node: vector-pop,  Next: vector-push,  Prev: vector,  Up: Arrays Dictionary

15.2.30 vector-pop [Function]
-----------------------------

'vector-pop' vector => element

Arguments and Values::
......................

vector--a vector with a fill pointer.

   element--an object.

Description::
.............

Decreases the fill pointer of vector by one, and retrieves the element
of vector that is designated by the new fill pointer.

Examples::
..........

      (vector-push (setq fable (list 'fable))
                   (setq fa (make-array 8
                                        :fill-pointer 2
                                        :initial-element 'sisyphus))) =>  2
      (fill-pointer fa) =>  3
      (eq (vector-pop fa) fable) =>  true
      (vector-pop fa) =>  SISYPHUS
      (fill-pointer fa) =>  1

Side Effects::
..............

The fill pointer is decreased by one.

Affected By::
.............

The value of the fill pointer.

Exceptional Situations::
........................

An error of type type-error is signaled if vector does not have a fill
pointer.

   If the fill pointer is zero, vector-pop signals an error of type
error.

See Also::
..........

*note vector-push:: , vector-push-extend, *note fill-pointer::


File: gcl.info,  Node: vector-push,  Next: vectorp,  Prev: vector-pop,  Up: Arrays Dictionary

15.2.31 vector-push, vector-push-extend [Function]
--------------------------------------------------

'vector-push' new-element vector => new-index-p

   'vector-push-extend' new-element vector &optional extension =>
new-index

Arguments and Values::
......................

new-element--an object.

   vector--a vector with a fill pointer.

   extension--a positive integer.  The default is
implementation-dependent.

   new-index-p--a valid array index for vector, or nil.

   new-index--a valid array index for vector.

Description::
.............

vector-push and vector-push-extend store new-element in vector.
vector-push attempts to store new-element in the element of vector
designated by the fill pointer, and to increase the fill pointer by one.
If the (>= (fill-pointer vector) (array-dimension vector 0)), neither
vector nor its fill pointer are affected.  Otherwise, the store and
increment take place and vector-push returns the former value of the
fill pointer which is one less than the one it leaves in vector.

   vector-push-extend is just like vector-push except that if the fill
pointer gets too large, vector is extended using adjust-array so that it
can contain more elements.  Extension is the minimum number of elements
to be added to vector if it must be extended.

   vector-push and vector-push-extend return the index of new-element in
vector.  If (>= (fill-pointer vector) (array-dimension vector 0)),
vector-push returns nil.

Examples::
..........

      (vector-push (setq fable (list 'fable))
                   (setq fa (make-array 8
                                        :fill-pointer 2
                                        :initial-element 'first-one))) =>  2
      (fill-pointer fa) =>  3
      (eq (aref fa 2) fable) =>  true
      (vector-push-extend #\X
                         (setq aa
                               (make-array 5
                                           :element-type 'character
                                           :adjustable t
                                           :fill-pointer 3))) =>  3
      (fill-pointer aa) =>  4
      (vector-push-extend #\Y aa 4) =>  4
      (array-total-size aa) =>  at least 5
      (vector-push-extend #\Z aa 4) =>  5
      (array-total-size aa) =>  9 ;(or more)

Affected By::
.............

The value of the fill pointer.

   How vector was created.

Exceptional Situations::
........................

An error of type error is signaled by vector-push-extend if it tries to
extend vector and vector is not actually adjustable.

   An error of type error is signaled if vector does not have a fill
pointer.

See Also::
..........

*note adjustable-array-p:: , *note fill-pointer:: , *note vector-pop::


File: gcl.info,  Node: vectorp,  Next: bit (Array),  Prev: vector-push,  Up: Arrays Dictionary

15.2.32 vectorp [Function]
--------------------------

'vectorp' object => generalized-boolean

Arguments and Values::
......................

object--an object.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if object is of type vector; otherwise, returns false.

Examples::
..........

      (vectorp "aaaaaa") =>  true
      (vectorp (make-array 6 :fill-pointer t)) =>  true
      (vectorp (make-array '(2 3 4))) =>  false
      (vectorp #*11) =>  true
      (vectorp #b11) =>  false

Notes::
.......

      (vectorp object) == (typep object 'vector)


File: gcl.info,  Node: bit (Array),  Next: bit-and,  Prev: vectorp,  Up: Arrays Dictionary

15.2.33 bit, sbit [Accessor]
----------------------------

'bit' bit-array &rest subscripts => bit

   'sbit' bit-array &rest subscripts => bit

   (setf ('bit' bit-array &rest subscripts) new-bit)
(setf ('sbit' bit-array &rest subscripts) new-bit)

Arguments and Values::
......................

bit-array--for bit, a bit array; for sbit, a simple bit array.

   subscripts--a list of valid array indices for the bit-array.

   bit--a bit.

Description::
.............

bit and sbit access the bit-array element specified by subscripts.

   These functions ignore the fill pointer when accessing elements.

Examples::
..........

      (bit (setq ba (make-array 8
                                 :element-type 'bit
                                 :initial-element 1))
            3) =>  1
      (setf (bit ba 3) 0) =>  0
      (bit ba 3) =>  0
      (sbit ba 5) =>  1
      (setf (sbit ba 5) 1) =>  1
      (sbit ba 5) =>  1

See Also::
..........

*note aref:: ,

   *note Compiler Terminology::

Notes::
.......

bit and sbit are like aref except that they require arrays to be a bit
array and a simple bit array, respectively.

   bit and sbit, unlike char and schar, allow the first argument to be
an array of any rank.


File: gcl.info,  Node: bit-and,  Next: bit-vector-p,  Prev: bit (Array),  Up: Arrays Dictionary

15.2.34 bit-and, bit-andc1, bit-andc2, bit-eqv,
-----------------------------------------------

bit-ior, bit-nand, bit-nor, bit-not, bit-orc1, bit-orc2, bit-xor
----------------------------------------------------------------

                                                             [Function]

   'bit-and' bit-array1 bit-array2 &optional opt-arg =>
resulting-bit-array

   'bit-andc1' bit-array1 bit-array2 &optional opt-arg =>
resulting-bit-array

   'bit-andc2' bit-array1 bit-array2 &optional opt-arg =>
resulting-bit-array

   'bit-eqv' bit-array1 bit-array2 &optional opt-arg =>
resulting-bit-array

   'bit-ior' bit-array1 bit-array2 &optional opt-arg =>
resulting-bit-array

   'bit-nand' bit-array1 bit-array2 &optional opt-arg =>
resulting-bit-array

   'bit-nor' bit-array1 bit-array2 &optional opt-arg =>
resulting-bit-array

   'bit-orc1' bit-array1 bit-array2 &optional opt-arg =>
resulting-bit-array

   'bit-orc2' bit-array1 bit-array2 &optional opt-arg =>
resulting-bit-array

   'bit-xor' bit-array1 bit-array2 &optional opt-arg =>
resulting-bit-array

   'bit-not' bit-array &optional opt-arg => resulting-bit-array

Arguments and Values::
......................

bit-array, bit-array1, bit-array2--a bit array.

   Opt-arg--a bit array, or t, or nil.  The default is nil.

   Bit-array, bit-array1, bit-array2, and opt-arg (if an array) must all
be of the same rank and dimensions.

   resulting-bit-array--a bit array.

Description::
.............

These functions perform bit-wise logical operations on bit-array1 and
bit-array2 and return an array of matching rank and dimensions, such
that any given bit of the result is produced by operating on
corresponding bits from each of the arguments.

   In the case of bit-not, an array of rank and dimensions matching
bit-array is returned that contains a copy of bit-array with all the
bits inverted.

   If opt-arg is of type (array bit) the contents of the result are
destructively placed into opt-arg.  If opt-arg is the symbol t,
bit-array or bit-array1 is replaced with the result; if opt-arg is nil
or omitted, a new array is created to contain the result.

   Figure 15-4 indicates the logical operation performed by each of the
functions.

   2
Function                                                   Operation                                   
_______________________________________________________________________________________________________
                                                           
bit-and                                                    and                                         
bit-eqv                                                    equivalence (exclusive nor)                 
bit-not                                                    complement                                  
bit-ior                                                    inclusive or                                
bit-xor                                                    exclusive or                                
bit-nand                                                   complement of bit-array1 and bit-array2     
bit-nor                                                    complement of bit-array1 or bit-array2      
bit-andc1                                                  and complement of bit-array1 with bit-array2
bit-andc2                                                  and bit-array1 with complement of bit-array2
bit-orc1                                                   or complement of bit-array1 with bit-array2 
bit-orc2                                                   or bit-array1 with complement of bit-array2 
  Figure 15-3: Bit-wise Logical Operations on Bit Arrays 

Examples::
..........

      (bit-and (setq ba #*11101010) #*01101011) =>  #*01101010
      (bit-and #*1100 #*1010) =>  #*1000
      (bit-andc1 #*1100 #*1010) =>  #*0010
      (setq rba (bit-andc2 ba #*00110011 t)) =>  #*11001000
      (eq rba ba) =>  true
      (bit-not (setq ba #*11101010)) =>  #*00010101
      (setq rba (bit-not ba
                          (setq tba (make-array 8
                                                :element-type 'bit))))
     =>  #*00010101
      (equal rba tba) =>  true
      (bit-xor #*1100 #*1010) =>  #*0110

See Also::
..........

lognot, *note logand::


File: gcl.info,  Node: bit-vector-p,  Next: simple-bit-vector-p,  Prev: bit-and,  Up: Arrays Dictionary

15.2.35 bit-vector-p [Function]
-------------------------------

'bit-vector-p' object => generalized-boolean

Arguments and Values::
......................

object--an object.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if object is of type bit-vector; otherwise, returns false.

Examples::
..........

      (bit-vector-p (make-array 6
                                :element-type 'bit
                                :fill-pointer t)) =>  true
      (bit-vector-p #*) =>  true
      (bit-vector-p (make-array 6)) =>  false

See Also::
..........

*note typep::

Notes::
.......

      (bit-vector-p object) == (typep object 'bit-vector)


File: gcl.info,  Node: simple-bit-vector-p,  Prev: bit-vector-p,  Up: Arrays Dictionary

15.2.36 simple-bit-vector-p [Function]
--------------------------------------

'simple-bit-vector-p' object => generalized-boolean

Arguments and Values::
......................

object--an object.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if object is of type simple-bit-vector; otherwise, returns
false.

Examples::
..........

      (simple-bit-vector-p (make-array 6)) =>  false
      (simple-bit-vector-p #*) =>  true

See Also::
..........

*note simple-vector-p::

Notes::
.......

      (simple-bit-vector-p object) == (typep object 'simple-bit-vector)


File: gcl.info,  Node: Strings,  Next: Sequences,  Prev: Arrays,  Up: Top

16 Strings
**********

* Menu:

* String Concepts::
* Strings Dictionary::


File: gcl.info,  Node: String Concepts,  Next: Strings Dictionary,  Prev: Strings,  Up: Strings

16.1 String Concepts
====================

* Menu:

* Implications of Strings Being Arrays::
* Subtypes of STRING::


File: gcl.info,  Node: Implications of Strings Being Arrays,  Next: Subtypes of STRING,  Prev: String Concepts,  Up: String Concepts

16.1.1 Implications of Strings Being Arrays
-------------------------------------------

Since all strings are arrays, all rules which apply generally to arrays
also apply to strings.  See *note Array Concepts::.

   For example, strings can have fill pointers, and strings are also
subject to the rules of element type upgrading that apply to arrays.


File: gcl.info,  Node: Subtypes of STRING,  Prev: Implications of Strings Being Arrays,  Up: String Concepts

16.1.2 Subtypes of STRING
-------------------------

All functions that operate on strings will operate on subtypes of string
as well.

   However, the consequences are undefined if a character is inserted
into a string for which the element type of the string does not include
that character.


File: gcl.info,  Node: Strings Dictionary,  Prev: String Concepts,  Up: Strings

16.2 Strings Dictionary
=======================

* Menu:

* string (System Class)::
* base-string::
* simple-string::
* simple-base-string::
* simple-string-p::
* char::
* string::
* string-upcase::
* string-trim::
* string=::
* stringp::
* make-string::


File: gcl.info,  Node: string (System Class),  Next: base-string,  Prev: Strings Dictionary,  Up: Strings Dictionary

16.2.1 string [System Class]
----------------------------

Class Precedence List::
.......................

string, vector, array, sequence, t

Description::
.............

A string is a specialized vector whose elements are of type character or
a subtype of type character.  When used as a type specifier for object
creation, string means (vector character).

Compound Type Specifier Kind::
..............................

Abbreviating.

Compound Type Specifier Syntax::
................................

('string'{[size]})

Compound Type Specifier Arguments::
...................................

size--a non-negative fixnum, or the symbol *.

Compound Type Specifier Description::
.....................................

This denotes the union of all types (array c (size)) for all subtypes c
of character; that is, the set of strings of size size.

See Also::
..........

*note String Concepts::, *note Double-Quote::, *note Printing Strings::


File: gcl.info,  Node: base-string,  Next: simple-string,  Prev: string (System Class),  Up: Strings Dictionary

16.2.2 base-string [Type]
-------------------------

Supertypes::
............

base-string, string, vector, array, sequence, t

Description::
.............

The type base-string is equivalent to

   (vector base-char).

   The base string representation is the most efficient string
representation that can hold an arbitrary sequence of standard
characters.

Compound Type Specifier Kind::
..............................

Abbreviating.

Compound Type Specifier Syntax::
................................

('base-string'{[size]})

Compound Type Specifier Arguments::
...................................

size--a non-negative fixnum, or the symbol *.

Compound Type Specifier Description::
.....................................

This is equivalent to the type (vector base-char size); that is, the set
of base strings of size size.


File: gcl.info,  Node: simple-string,  Next: simple-base-string,  Prev: base-string,  Up: Strings Dictionary

16.2.3 simple-string [Type]
---------------------------

Supertypes::
............

simple-string, string, vector, simple-array, array, sequence, t

Description::
.............

A simple string is a specialized one-dimensional simple array whose
elements are of type character or a subtype of type character.  When
used as a type specifier for object creation, simple-string means
(simple-array character (size)).

Compound Type Specifier Kind::
..............................

Abbreviating.

Compound Type Specifier Syntax::
................................

('simple-string'{[size]})

Compound Type Specifier Arguments::
...................................

size--a non-negative fixnum, or the symbol *.

Compound Type Specifier Description::
.....................................

This denotes the union of all types (simple-array c (size)) for all
subtypes c of character; that is, the set of simple strings of size
size.


File: gcl.info,  Node: simple-base-string,  Next: simple-string-p,  Prev: simple-string,  Up: Strings Dictionary

16.2.4 simple-base-string [Type]
--------------------------------

Supertypes::
............

simple-base-string, base-string, simple-string, string, vector,
simple-array, array, sequence, t

Description::
.............

The type simple-base-string is equivalent to

   (simple-array base-char (*)).

Compound Type Specifier Kind::
..............................

Abbreviating.

Compound Type Specifier Syntax::
................................

('simple-base-string'{[size]})

Compound Type Specifier Arguments::
...................................

size--a non-negative fixnum, or the symbol *.

Compound Type Specifier Description::
.....................................

This is equivalent to the type (simple-array base-char (size)); that is,
the set of simple base strings of size size.


File: gcl.info,  Node: simple-string-p,  Next: char,  Prev: simple-base-string,  Up: Strings Dictionary

16.2.5 simple-string-p [Function]
---------------------------------

'simple-string-p' object => generalized-boolean

Arguments and Values::
......................

object--an object.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if object is of type simple-string; otherwise, returns
false.

Examples::
..........

      (simple-string-p "aaaaaa") =>  true
      (simple-string-p (make-array 6
                                   :element-type 'character
                                   :fill-pointer t)) =>  false

Notes::
.......

      (simple-string-p object) == (typep object 'simple-string)


File: gcl.info,  Node: char,  Next: string,  Prev: simple-string-p,  Up: Strings Dictionary

16.2.6 char, schar [Accessor]
-----------------------------

'char' string index => character

   'schar' string index => character

   (setf ('char' string index) new-character)
(setf ('schar' string index) new-character)

Arguments and Values::
......................

string--for char, a string; for schar, a simple string.

   index--a valid array index for the string.

   character, new-character--a character.

Description::
.............

char and schar access the element of string specified by index.

   char ignores fill pointers when accessing elements.

Examples::
..........

      (setq my-simple-string (make-string 6 :initial-element #\A)) =>  "AAAAAA"
      (schar my-simple-string 4) =>  #\A
      (setf (schar my-simple-string 4) #\B) =>  #\B
      my-simple-string =>  "AAAABA"
      (setq my-filled-string
            (make-array 6 :element-type 'character
                          :fill-pointer 5
                          :initial-contents my-simple-string))
     =>  "AAAAB"
      (char my-filled-string 4) =>  #\B
      (char my-filled-string 5) =>  #\A
      (setf (char my-filled-string 3) #\C) =>  #\C
      (setf (char my-filled-string 5) #\D) =>  #\D
      (setf (fill-pointer my-filled-string) 6) =>  6
      my-filled-string =>  "AAACBD"

See Also::
..........

*note aref:: , *note elt:: ,

   *note Compiler Terminology::

Notes::
.......

      (char s j) == (aref (the string s) j)


File: gcl.info,  Node: string,  Next: string-upcase,  Prev: char,  Up: Strings Dictionary

16.2.7 string [Function]
------------------------

'string' x => string

Arguments and Values::
......................

x--a string, a symbol, or a character.

   string--a string.

Description::
.............

Returns a string described by x; specifically:

*
     If x is a string, it is returned.
*
     If x is a symbol, its name is returned.
*

     If x is a character,

     then a string containing that one character is returned.
*

     string might perform additional, implementation-defined
     conversions.

Examples::
..........

      (string "already a string") =>  "already a string"
      (string 'elm) =>  "ELM"
      (string #\c) =>  "c"

Exceptional Situations::
........................

In the case where a conversion is defined neither by this specification
nor by the implementation, an error of type type-error is signaled.

See Also::
..........

*note coerce:: , string (type).

Notes::
.......

coerce can be used to convert a sequence of characters to a string.

   prin1-to-string, princ-to-string, write-to-string, or format (with a
first argument of nil) can be used to get a string representation of a
number or any other object.


File: gcl.info,  Node: string-upcase,  Next: string-trim,  Prev: string,  Up: Strings Dictionary

16.2.8 string-upcase, string-downcase, string-capitalize,
---------------------------------------------------------

nstring-upcase, nstring-downcase, nstring-capitalize
----------------------------------------------------

                                                             [Function]

   'string-upcase' string &key start end => cased-string

   'string-downcase' string &key start end => cased-string

   'string-capitalize' string &key start end => cased-string

   'nstring-upcase' string &key start end => string

   'nstring-downcase' string &key start end => string

   'nstring-capitalize' string &key start end => string

Arguments and Values::
......................

string--a string designator.  For nstring-upcase, nstring-downcase, and
nstring-capitalize, the string designator must be a string.

   start, end--bounding index designators of string.  The defaults for
start and end are 0 and nil, respectively.

   cased-string--a string.

Description::
.............

string-upcase, string-downcase, string-capitalize, nstring-upcase,
nstring-downcase, nstring-capitalize change the case of the subsequence
of string bounded by start and end as follows:

string-upcase
     string-upcase returns a string just like string with all lowercase
     characters replaced by the corresponding uppercase characters.
     More precisely, each character of the result string is produced by
     applying the function char-upcase to the corresponding character of
     string.

string-downcase
     string-downcase is like string-upcase except that all uppercase
     characters are replaced by the corresponding lowercase characters
     (using char-downcase).

string-capitalize
     string-capitalize produces a copy of string such that, for every
     word in the copy, the first character of the "word," if it has
     case, is uppercase and any other characters with case in the word
     are lowercase.  For the purposes of string-capitalize, a "word" is
     defined to be a consecutive subsequence consisting of alphanumeric
     characters, delimited at each end either by a non-alphanumeric
     character or by an end of the string.

nstring-upcase, nstring-downcase, nstring-capitalize
     nstring-upcase, nstring-downcase, and nstring-capitalize are
     identical to string-upcase, string-downcase, and string-capitalize
     respectively except that they modify string.

   For string-upcase, string-downcase, and string-capitalize, string is
not modified.  However, if no characters in string require conversion,
the result may be either string or a copy of it, at the implementation's
discretion.

Examples::
..........

      (string-upcase "abcde") =>  "ABCDE"
      (string-upcase "Dr. Livingston, I presume?")
     =>  "DR. LIVINGSTON, I PRESUME?"
      (string-upcase "Dr. Livingston, I presume?" :start 6 :end 10)
     =>  "Dr. LiVINGston, I presume?"
      (string-downcase "Dr. Livingston, I presume?")
     =>  "dr. livingston, i presume?"

      (string-capitalize "elm 13c arthur;fig don't") =>  "Elm 13c Arthur;Fig Don'T"
      (string-capitalize " hello ") =>  " Hello "
      (string-capitalize "occlUDeD cASEmenTs FOreSTAll iNADVertent DEFenestraTION")
     =>   "Occluded Casements Forestall Inadvertent Defenestration"
      (string-capitalize 'kludgy-hash-search) =>  "Kludgy-Hash-Search"
      (string-capitalize "DON'T!") =>  "Don'T!"    ;not "Don't!"
      (string-capitalize "pipe 13a, foo16c") =>  "Pipe 13a, Foo16c"

      (setq str (copy-seq "0123ABCD890a")) =>  "0123ABCD890a"
      (nstring-downcase str :start 5 :end 7) =>  "0123AbcD890a"
      str =>  "0123AbcD890a"

Side Effects::
..............

nstring-upcase, nstring-downcase, and nstring-capitalize modify string
as appropriate rather than constructing a new string.

See Also::
..........

*note char-upcase:: , char-downcase

Notes::
.......

The result is always of the same length as string.


File: gcl.info,  Node: string-trim,  Next: string=,  Prev: string-upcase,  Up: Strings Dictionary

16.2.9 string-trim, string-left-trim, string-right-trim [Function]
------------------------------------------------------------------

'string-trim' character-bag string => trimmed-string

   'string-left-trim' character-bag string => trimmed-string

   'string-right-trim' character-bag string => trimmed-string

Arguments and Values::
......................

character-bag--a sequence containing characters.

   string--a string designator.

   trimmed-string--a string.

Description::
.............

string-trim returns a substring of string, with all characters in
character-bag stripped off the beginning and end.  string-left-trim is
similar but strips characters off only the beginning; string-right-trim
strips off only the end.

   If no characters need to be trimmed from the string, then either
string itself or a copy of it may be returned, at the discretion of the
implementation.

   All of these functions observe the fill pointer.

Examples::
..........

      (string-trim "abc" "abcaakaaakabcaaa") =>  "kaaak"
      (string-trim '(#\Space #\Tab #\Newline) " garbanzo beans
             ") =>  "garbanzo beans"
      (string-trim " (*)" " ( *three (silly) words* ) ")
     =>  "three (silly) words"

      (string-left-trim "abc" "labcabcabc") =>  "labcabcabc"
      (string-left-trim " (*)" " ( *three (silly) words* ) ")
     =>  "three (silly) words* ) "

      (string-right-trim " (*)" " ( *three (silly) words* ) ")
     =>  " ( *three (silly) words"

Affected By::
.............

The implementation.


File: gcl.info,  Node: string=,  Next: stringp,  Prev: string-trim,  Up: Strings Dictionary

16.2.10 string=, string/=, string<, string>, string<=, string>=,
----------------------------------------------------------------

string-equal, string-not-equal, string-lessp,
---------------------------------------------

string-greaterp, string-not-greaterp, string-not-lessp
------------------------------------------------------

                                                             [Function]

   'string=' string1 string2 &key start1 end1 start2 end2 =>
generalized-boolean

   'string/=' string1 string2 &key start1 end1 start2 end2 =>
mismatch-index

   'string<' string1 string2 &key start1 end1 start2 end2 =>
mismatch-index

   'string>' string1 string2 &key start1 end1 start2 end2 =>
mismatch-index

   'string<=' string1 string2 &key start1 end1 start2 end2 =>
mismatch-index

   'string>=' string1 string2 &key start1 end1 start2 end2 =>
mismatch-index

   'string-equal' string1 string2 &key start1 end1 start2 end2 =>
generalized-boolean

   'string-not-equal' string1 string2 &key start1 end1 start2 end2 =>
mismatch-index

   'string-lessp' string1 string2 &key start1 end1 start2 end2 =>
mismatch-index

   'string-greaterp' string1 string2 &key start1 end1 start2 end2 =>
mismatch-index

   'string-not-greaterp' string1 string2 &key start1 end1 start2 end2 =>
mismatch-index

   'string-not-lessp' string1 string2 &key start1 end1 start2 end2 =>
mismatch-index

Arguments and Values::
......................

string1--a string designator.

   string2--a string designator.

   start1, end1--bounding index designators of string1.  The defaults
for start and end are 0 and nil, respectively.

   start2, end2--bounding index designators of string2.  The defaults
for start and end are 0 and nil, respectively.

   generalized-boolean--a generalized boolean.

   mismatch-index--a bounding index of string1, or nil.

Description::
.............

These functions perform lexicographic comparisons on string1 and
string2.  string= and string-equal are called equality functions; the
others are called inequality functions.  The comparison operations these
functions perform are restricted to the subsequence of string1 bounded
by start1 and end1 and to the subsequence of string2 bounded by start2
and end2.

   A string a is equal to a string b if it contains the same number of
characters, and the corresponding characters are the same under char= or
char-equal, as appropriate.

   A string a is less than a string b if in the first position in which
they differ the character of a is less than the corresponding character
of b according to char< or char-lessp as appropriate, or if string a is
a proper prefix of string b (of shorter length and matching in all the
characters of a).

   The equality functions return a generalized boolean that is true if
the strings are equal, or false otherwise.

   The inequality functions return a mismatch-index that is true if the
strings are not equal, or false otherwise.  When the mismatch-index is
true, it is an integer representing the first character position at
which the two substrings differ, as an offset from the beginning of
string1.

   The comparison has one of the following results:

string=
     string= is true if the supplied substrings are of the same length
     and contain the same characters in corresponding positions;
     otherwise it is false.

string/=
     string/= is true if the supplied substrings are different;
     otherwise it is false.

string-equal
     string-equal is just like string= except that differences in case
     are ignored; two characters are considered to be the same if
     char-equal is true of them.

string<
     string< is true if substring1 is less than substring2; otherwise it
     is false.

string>
     string> is true if substring1 is greater than substring2; otherwise
     it is false.

string-lessp, string-greaterp
     string-lessp and string-greaterp are exactly like string< and
     string>, respectively, except that distinctions between uppercase
     and lowercase letters are ignored.  It is as if char-lessp were
     used instead of char< for comparing characters.

string<=
     string<= is true if substring1 is less than or equal to substring2;
     otherwise it is false.

string>=
     string>= is true if substring1 is greater than or equal to
     substring2; otherwise it is false.

string-not-greaterp, string-not-lessp
     string-not-greaterp and string-not-lessp are exactly like string<=
     and string>=, respectively, except that distinctions between
     uppercase and lowercase letters are ignored.  It is as if
     char-lessp were used instead of char< for comparing characters.

Examples::
..........

      (string= "foo" "foo") =>  true
      (string= "foo" "Foo") =>  false
      (string= "foo" "bar") =>  false
      (string= "together" "frog" :start1 1 :end1 3 :start2 2) =>  true
      (string-equal "foo" "Foo") =>  true
      (string= "abcd" "01234abcd9012" :start2 5 :end2 9) =>  true
      (string< "aaaa" "aaab") =>  3
      (string>= "aaaaa" "aaaa") =>  4
      (string-not-greaterp "Abcde" "abcdE") =>  5
      (string-lessp "012AAAA789" "01aaab6" :start1 3 :end1 7
                                           :start2 2 :end2 6) =>  6
      (string-not-equal "AAAA" "aaaA") =>  false

See Also::
..........

*note char=::

Notes::
.......

equal calls string= if applied to two strings.


File: gcl.info,  Node: stringp,  Next: make-string,  Prev: string=,  Up: Strings Dictionary

16.2.11 stringp [Function]
--------------------------

'stringp' object => generalized-boolean

Arguments and Values::
......................

object--an object.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if object is of type string; otherwise, returns false.

Examples::
..........

      (stringp "aaaaaa") =>  true
      (stringp #\a) =>  false

See Also::
..........

*note typep:: , string (type)

Notes::
.......

      (stringp object) == (typep object 'string)


File: gcl.info,  Node: make-string,  Prev: stringp,  Up: Strings Dictionary

16.2.12 make-string [Function]
------------------------------

'make-string' size &key initial-element element-type => string

Arguments and Values::
......................

size--a valid array dimension.

   initial-element--a character.

   The default is implementation-dependent.

   element-type--a type specifier.  The default is character.

   string--a simple string.

Description::
.............

make-string returns a simple string of length size whose elements have
been initialized to initial-element.

   The element-type names the type of the elements of the string; a
string is constructed of the most specialized type that can accommodate
elements of the given type.

Examples::
..........

      (make-string 10 :initial-element #\5) =>  "5555555555"
      (length (make-string 10)) =>  10

Affected By::
.............

The implementation.


File: gcl.info,  Node: Sequences,  Next: Hash Tables,  Prev: Strings,  Up: Top

17 Sequences
************

* Menu:

* Sequence Concepts::
* Rules about Test Functions::
* Sequences Dictionary::


File: gcl.info,  Node: Sequence Concepts,  Next: Rules about Test Functions,  Prev: Sequences,  Up: Sequences

17.1 Sequence Concepts
======================

A sequence is an ordered collection of elements, implemented as either a
vector or a list.

   Sequences can be created by the function make-sequence, as well as
other functions that create objects of types that are subtypes of
sequence (e.g., list, make-list, mapcar, and vector).

   A sequence function is a function defined by this specification or
added as an extension by the implementation that operates on one or more
sequences.  Whenever a sequence function must construct and return a new
vector, it always returns a simple vector.  Similarly, any strings
constructed will be simple strings.

  concatenate        length              remove             
  copy-seq           map                 remove-duplicates  
  count              map-into            remove-if          
  count-if           merge               remove-if-not      
  count-if-not       mismatch            replace            
  delete             notany              reverse            
  delete-duplicates  notevery            search             
  delete-if          nreverse            some               
  delete-if-not      nsubstitute         sort               
  elt                nsubstitute-if      stable-sort        
  every              nsubstitute-if-not  subseq             
  fill               position            substitute         
  find               position-if         substitute-if      
  find-if            position-if-not     substitute-if-not  
  find-if-not        reduce                                 

        Figure 17-1: Standardized Sequence Functions       


* Menu:

* General Restrictions on Parameters that must be Sequences::


File: gcl.info,  Node: General Restrictions on Parameters that must be Sequences,  Prev: Sequence Concepts,  Up: Sequence Concepts

17.1.1 General Restrictions on Parameters that must be Sequences
----------------------------------------------------------------

In general, lists (including association lists and property lists) that
are treated as sequences must be proper lists.


File: gcl.info,  Node: Rules about Test Functions,  Next: Sequences Dictionary,  Prev: Sequence Concepts,  Up: Sequences

17.2 Rules about Test Functions
===============================

* Menu:

* Satisfying a Two-Argument Test::
* Satisfying a One-Argument Test::


File: gcl.info,  Node: Satisfying a Two-Argument Test,  Next: Satisfying a One-Argument Test,  Prev: Rules about Test Functions,  Up: Rules about Test Functions

17.2.1 Satisfying a Two-Argument Test
-------------------------------------

When an object O is being considered iteratively against each element
E_i of a sequence S by an operator F listed in Figure 17-2, it is
sometimes useful to control the way in which the presence of O is tested
in S is tested by F. This control is offered on the basis of a function
designated with either a :test or :test-not argument.

  adjoin           nset-exclusive-or  search            
  assoc            nsublis            set-difference    
  count            nsubst             set-exclusive-or  
  delete           nsubstitute        sublis            
  find             nunion             subsetp           
  intersection     position           subst             
  member           pushnew            substitute        
  mismatch         rassoc             tree-equal        
  nintersection    remove             union             
  nset-difference  remove-duplicates                    

  Figure 17-2: Operators that have Two-Argument Tests to be Satisfied


   The object O might not be compared directly to E_i.  If a :key
argument is provided, it is a designator for a function of one argument
to be called with each E_i as an argument, and yielding an object Z_i to
be used for comparison.  (If there is no :key argument, Z_i is E_i.)

   The function designated by the :key argument is never called on O
itself.  However, if the function operates on multiple sequences (e.g.,
as happens in set-difference), O will be the result of calling the :key
function on an element of the other sequence.

   A :test argument, if supplied to F, is a designator for a function of
two arguments, O and Z_i.  An E_i is said (or, sometimes, an O and an
E_i are said) to satisfy the test

   if this :test function returns a generalized boolean representing
true.

   A :test-not argument, if supplied to F, is designator for a function
of two arguments, O and Z_i.  An E_i is said (or, sometimes, an O and an
E_i are said) to satisfy the test

   if this :test-not function returns a generalized boolean representing
false.

   If neither a :test nor a :test-not argument is supplied, it is as if
a :test argument of #'eql was supplied.

   The consequences are unspecified if both a :test and a :test-not
argument are supplied in the same call to F.

* Menu:

* Examples of Satisfying a Two-Argument Test::


File: gcl.info,  Node: Examples of Satisfying a Two-Argument Test,  Prev: Satisfying a Two-Argument Test,  Up: Satisfying a Two-Argument Test

17.2.1.1 Examples of Satisfying a Two-Argument Test
...................................................

      (remove "FOO" '(foo bar "FOO" "BAR" "foo" "bar") :test #'equal)
     =>  (foo bar "BAR" "foo" "bar")
      (remove "FOO" '(foo bar "FOO" "BAR" "foo" "bar") :test #'equalp)
     =>  (foo bar "BAR" "bar")
      (remove "FOO" '(foo bar "FOO" "BAR" "foo" "bar") :test #'string-equal)
     =>  (bar "BAR" "bar")
      (remove "FOO" '(foo bar "FOO" "BAR" "foo" "bar") :test #'string=)
     =>  (BAR "BAR" "foo" "bar")

      (remove 1 '(1 1.0 #C(1.0 0.0) 2 2.0 #C(2.0 0.0)) :test-not #'eql)
     =>  (1)
      (remove 1 '(1 1.0 #C(1.0 0.0) 2 2.0 #C(2.0 0.0)) :test-not #'=)
     =>  (1 1.0 #C(1.0 0.0))
      (remove 1 '(1 1.0 #C(1.0 0.0) 2 2.0 #C(2.0 0.0)) :test (complement #'=))
     =>  (1 1.0 #C(1.0 0.0))

      (count 1 '((one 1) (uno 1) (two 2) (dos 2)) :key #'cadr) =>  2

      (count 2.0 '(1 2 3) :test #'eql :key #'float) =>  1

      (count "FOO" (list (make-pathname :name "FOO" :type "X")
                         (make-pathname :name "FOO" :type "Y"))
             :key #'pathname-name
             :test #'equal)
     =>  2


File: gcl.info,  Node: Satisfying a One-Argument Test,  Prev: Satisfying a Two-Argument Test,  Up: Rules about Test Functions

17.2.2 Satisfying a One-Argument Test
-------------------------------------

When using one of the functions in Figure 17-3, the elements E of a
sequence S are filtered not on the basis of the presence or absence of
an object O under a two argument predicate, as with the functions
described in *note Satisfying a Two-Argument Test::, but rather on the
basis of a one argument predicate.

  assoc-if       member-if           rassoc-if          
  assoc-if-not   member-if-not       rassoc-if-not      
  count-if       nsubst-if           remove-if          
  count-if-not   nsubst-if-not       remove-if-not      
  delete-if      nsubstitute-if      subst-if           
  delete-if-not  nsubstitute-if-not  subst-if-not       
  find-if        position-if         substitute-if      
  find-if-not    position-if-not     substitute-if-not  

  Figure 17-3: Operators that have One-Argument Tests to be Satisfied


   The element E_i might not be considered directly.  If a :key argument
is provided, it is a designator for a function of one argument to be
called with each E_i as an argument, and yielding an object Z_i to be
used for comparison.  (If there is no :key argument, Z_i is E_i.)

   Functions defined in this specification and having a name that ends
in "-if" accept a first argument that is a designator for a function of
one argument, Z_i.  An E_i is said to satisfy the test if this :test
function returns a generalized boolean representing true.

   Functions defined in this specification and having a name that ends
in "-if-not" accept a first argument that is a designator for a function
of one argument, Z_i.  An E_i is said to satisfy the test if this :test
function returns a generalized boolean representing false.

* Menu:

* Examples of Satisfying a One-Argument Test::


File: gcl.info,  Node: Examples of Satisfying a One-Argument Test,  Prev: Satisfying a One-Argument Test,  Up: Satisfying a One-Argument Test

17.2.2.1 Examples of Satisfying a One-Argument Test
...................................................

      (count-if #'zerop '(1 #C(0.0 0.0) 0 0.0d0 0.0s0 3)) =>  4

      (remove-if-not #'symbolp '(0 1 2 3 4 5 6 7 8 9 A B C D E F))
     =>  (A B C D E F)
      (remove-if (complement #'symbolp) '(0 1 2 3 4 5 6 7 8 9 A B C D E F))
     =>  (A B C D E F)

      (count-if #'zerop '("foo" "" "bar" "" "" "baz" "quux") :key #'length)
     =>  3


File: gcl.info,  Node: Sequences Dictionary,  Prev: Rules about Test Functions,  Up: Sequences

17.3 Sequences Dictionary
=========================

* Menu:

* sequence::
* copy-seq::
* elt::
* fill::
* make-sequence::
* subseq::
* map::
* map-into::
* reduce::
* count::
* length::
* reverse::
* sort::
* find::
* position::
* search::
* mismatch::
* replace::
* substitute::
* concatenate::
* merge::
* remove::
* remove-duplicates::


File: gcl.info,  Node: sequence,  Next: copy-seq,  Prev: Sequences Dictionary,  Up: Sequences Dictionary

17.3.1 sequence [System Class]
------------------------------

Class Precedence List::
.......................

sequence, t

Description::
.............

Sequences are ordered collections of objects, called the elements of the
sequence.

   The types vector and the type list are disjoint subtypes of type
sequence, but are not necessarily an exhaustive partition of sequence.

   When viewing a vector as a sequence, only the active elements of that
vector are considered elements of the sequence; that is, sequence
operations respect the fill pointer when given sequences represented as
vectors.


File: gcl.info,  Node: copy-seq,  Next: elt,  Prev: sequence,  Up: Sequences Dictionary

17.3.2 copy-seq [Function]
--------------------------

'copy-seq' sequence => copied-sequence

Arguments and Values::
......................

sequence--a proper sequence.

   copied-sequence--a proper sequence.

Description::
.............

Creates a copy of sequence.  The elements of the new sequence are the
same as the corresponding elements of the given sequence.

   If sequence is a vector, the result is a fresh simple array of rank
one that has the same actual array element type as sequence.  If
sequence is a list, the result is a fresh list.

Examples::
..........

      (setq str "a string") =>  "a string"
      (equalp str (copy-seq str)) =>  true
      (eql str (copy-seq str)) =>  false

Exceptional Situations::
........................

Should be prepared to signal an error of type type-error if sequence is
not a proper sequence.

See Also::
..........

*note copy-list::

Notes::
.......

From a functional standpoint,
      (copy-seq x) == (subseq x 0)

   However, the programmer intent is typically very different in these
two cases.


File: gcl.info,  Node: elt,  Next: fill,  Prev: copy-seq,  Up: Sequences Dictionary

17.3.3 elt [Accessor]
---------------------

'elt' sequence index => object

   (setf (' elt' sequence index) new-object)

Arguments and Values::
......................

sequence--a proper sequence.

   index--a valid sequence index for sequence.

   object--an object.

   new-object--an object.

Description::
.............

Accesses the element of sequence specified by index.

Examples::
..........

      (setq str (copy-seq "0123456789")) =>  "0123456789"
      (elt str 6) =>  #\6
      (setf (elt str 0) #\#) =>  #\#
      str =>  "#123456789"

Exceptional Situations::
........................

Should be prepared to signal an error of type type-error if sequence is
not a proper sequence.  Should signal an error of type type-error if
index is not a valid sequence index for sequence.

See Also::
..........

*note aref:: , *note nth:: ,

   *note Compiler Terminology::

Notes::
.......

aref may be used to access vector elements that are beyond the vector's
fill pointer.


File: gcl.info,  Node: fill,  Next: make-sequence,  Prev: elt,  Up: Sequences Dictionary

17.3.4 fill [Function]
----------------------

'fill' sequence item &key start end => sequence

Arguments and Values::
......................

sequence--a proper sequence.

   item--a sequence.

   start, end--bounding index designators of sequence.  The defaults for
start and end are 0 and nil, respectively.

Description::
.............

Replaces the elements of sequence bounded by start and end with item.

Examples::
..........

      (fill (list 0 1 2 3 4 5) '(444)) =>  ((444) (444) (444) (444) (444) (444))
      (fill (copy-seq "01234") #\e :start 3) =>  "012ee"
      (setq x (vector 'a 'b 'c 'd 'e)) =>  #(A B C D E)
      (fill x 'z :start 1 :end 3) =>  #(A Z Z D E)
      x =>  #(A Z Z D E)
      (fill x 'p) =>  #(P P P P P)
      x =>  #(P P P P P)

Side Effects::
..............

Sequence is destructively modified.

Exceptional Situations::
........................

Should be prepared to signal an error of type type-error if sequence is
not a proper sequence.  Should signal an error of type type-error if
start is not a non-negative integer.  Should signal an error of type
type-error if end is not a non-negative integer or nil.

See Also::
..........

*note replace:: , nsubstitute

Notes::
.......

(fill sequence item) == (nsubstitute-if item (constantly t) sequence)


File: gcl.info,  Node: make-sequence,  Next: subseq,  Prev: fill,  Up: Sequences Dictionary

17.3.5 make-sequence [Function]
-------------------------------

'make-sequence' result-type size &key initial-element => sequence

Arguments and Values::
......................

result-type--a sequence type specifier.

   size--a non-negative integer.

   initial-element--an object.  The default is implementation-dependent.

   sequence--a proper sequence.

Description::
.............

Returns a sequence of the type result-type and of length size, each of
the elements of which has been initialized to initial-element.

   If the result-type is a subtype of list, the result will be a list.

   If the result-type is a subtype of vector, then if the implementation
can determine the element type specified for the result-type, the
element type of the resulting array is the result of upgrading that
element type; or, if the implementation can determine that the element
type is unspecified (or *), the element type of the resulting array is
t; otherwise, an error is signaled.

Examples::
..........

      (make-sequence 'list 0) =>  ()
      (make-sequence 'string 26 :initial-element #\.)
     =>  ".........................."
      (make-sequence '(vector double-float) 2
                     :initial-element 1d0)
     =>  #(1.0d0 1.0d0)

      (make-sequence '(vector * 2) 3) should signal an error
      (make-sequence '(vector * 4) 3) should signal an error

Affected By::
.............

The implementation.

Exceptional Situations::
........................

The consequences are unspecified if initial-element is not an object
which can be stored in the resulting sequence.

   An error of type type-error must be signaled if the result-type is
neither a recognizable subtype of list, nor a recognizable subtype of
vector.

   An error of type type-error should be signaled if result-type
specifies the number of elements and size is different from that number.

See Also::
..........

*note make-array:: , *note make-list::

Notes::
.......

      (make-sequence 'string 5) == (make-string 5)


File: gcl.info,  Node: subseq,  Next: map,  Prev: make-sequence,  Up: Sequences Dictionary

17.3.6 subseq [Accessor]
------------------------

'subseq' sequence start &optional end => subsequence

   (setf (' subseq' sequence start &optional end) new-subsequence)

Arguments and Values::
......................

sequence--a proper sequence.

   start, end--bounding index designators of sequence.  The default for
end is nil.

   subsequence--a proper sequence.

   new-subsequence--a proper sequence.

Description::
.............

subseq creates a sequence that is a copy of the subsequence of sequence
bounded by start and end.

   Start specifies an offset into the original sequence and marks the
beginning position of the subsequence.  end marks the position following
the last element of the subsequence.

   subseq always allocates a new sequence for a result; it never shares
storage with an old sequence.  The result subsequence is always of the
same type as sequence.

   If sequence is a vector, the result is a fresh simple array of rank
one that has the same actual array element type as sequence.  If
sequence is a list, the result is a fresh list.

   setf may be used with subseq to destructively replace elements of a
subsequence with elements taken from a sequence of new values.  If the
subsequence and the new sequence are not of equal length, the shorter
length determines the number of elements that are replaced.  The
remaining elements at the end of the longer sequence are not modified in
the operation.

Examples::
..........

      (setq str "012345") =>  "012345"
      (subseq str 2) =>  "2345"
      (subseq str 3 5) =>  "34"
      (setf (subseq str 4) "abc") =>  "abc"
      str =>  "0123ab"
      (setf (subseq str 0 2) "A") =>  "A"
      str =>  "A123ab"

Exceptional Situations::
........................

Should be prepared to signal an error of type type-error if sequence is
not a proper sequence.  Should be prepared to signal an error of type
type-error if new-subsequence is not a proper sequence.

See Also::
..........

*note replace::


File: gcl.info,  Node: map,  Next: map-into,  Prev: subseq,  Up: Sequences Dictionary

17.3.7 map [Function]
---------------------

'map' result-type function &rest sequences^+ => result

Arguments and Values::
......................

result-type - a sequence type specifier, or nil.

   function--a function designator.  function must take as many
arguments as there are sequences.

   sequence--a proper sequence.

   result--if result-type is a type specifier other than nil, then a
sequence of the type it denotes; otherwise (if the result-type is nil),
nil.

Description::
.............

Applies function to successive sets of arguments in which one argument
is obtained from each sequence.  The function is called first on all the
elements with index 0, then on all those with index 1, and so on.  The
result-type specifies the type of the resulting sequence.

   map returns nil if result-type is nil.  Otherwise, map returns a
sequence such that element j is the result of applying function to
element j of each of the sequences.  The result sequence is as long as
the shortest of the sequences.  The consequences are undefined if the
result of applying function to the successive elements of the sequences
cannot be contained in a sequence of the type given by result-type.

   If the result-type is a subtype of list, the result will be a list.

   If the result-type is a subtype of vector, then if the implementation
can determine the element type specified for the result-type, the
element type of the resulting array is the result of upgrading that
element type; or, if the implementation can determine that the element
type is unspecified (or *), the element type of the resulting array is
t; otherwise, an error is signaled.

Examples::
..........

      (map 'string #'(lambda (x y)
                       (char "01234567890ABCDEF" (mod (+ x y) 16)))
            '(1 2 3 4)
            '(10 9 8 7)) =>  "AAAA"
      (setq seq '("lower" "UPPER" "" "123")) =>  ("lower" "UPPER" "" "123")
      (map nil #'nstring-upcase seq) =>  NIL
      seq =>  ("LOWER" "UPPER" "" "123")
      (map 'list #'- '(1 2 3 4)) =>  (-1 -2 -3 -4)
      (map 'string
           #'(lambda (x) (if (oddp x) #\1 #\0))
           '(1 2 3 4)) =>  "1010"

      (map '(vector * 4) #'cons "abc" "de") should signal an error

Exceptional Situations::
........................

An error of type type-error must be signaled if the result-type is not a
recognizable subtype of list, not a recognizable subtype of vector, and
not nil.

   Should be prepared to signal an error of type type-error if any
sequence is not a proper sequence.

   An error of type type-error should be signaled if result-type
specifies the number of elements and the minimum length of the sequences
is different from that number.

See Also::
..........

*note Traversal Rules and Side Effects::


File: gcl.info,  Node: map-into,  Next: reduce,  Prev: map,  Up: Sequences Dictionary

17.3.8 map-into [Function]
--------------------------

'map-into' result-sequence function &rest sequences => result-sequence

Arguments and Values::
......................

result-sequence--a proper sequence.

   function--a designator for a function of as many arguments as there
are sequences.

   sequence--a proper sequence.

Description::
.............

Destructively modifies result-sequence to contain the results of
applying function to each element in the argument sequences in turn.

   result-sequence and each element of sequences can each be either a
list or a vector.  If result-sequence and each element of sequences are
not all the same length, the iteration terminates when the shortest
sequence (of any of the sequences or the result-sequence) is exhausted.
If result-sequence is a vector with a fill pointer, the fill pointer is
ignored when deciding how many iterations to perform, and afterwards the
fill pointer is set to the number of times function was applied.  If
result-sequence is longer than the shortest element of sequences, extra
elements at the end of result-sequence are left unchanged.  If
result-sequence is nil, map-into immediately returns nil, since nil is a
sequence of length zero.

   If function has side effects, it can count on being called first on
all of the elements with index 0, then on all of those numbered 1, and
so on.

Examples::
..........

      (setq a (list 1 2 3 4) b (list 10 10 10 10)) =>  (10 10 10 10)
      (map-into a #'+ a b) =>  (11 12 13 14)
      a =>  (11 12 13 14)
      b =>  (10 10 10 10)
      (setq k '(one two three)) =>  (ONE TWO THREE)
      (map-into a #'cons k a) =>  ((ONE . 11) (TWO . 12) (THREE . 13) 14)
      (map-into a #'gensym) =>  (#:G9090 #:G9091 #:G9092 #:G9093)
      a =>  (#:G9090 #:G9091 #:G9092 #:G9093)

Exceptional Situations::
........................

Should be prepared to signal an error of type type-error if
result-sequence is not a proper sequence.  Should be prepared to signal
an error of type type-error if sequence is not a proper sequence.

Notes::
.......

map-into differs from map in that it modifies an existing sequence
rather than creating a new one.  In addition, map-into can be called
with only two arguments, while map requires at least three arguments.

   map-into could be defined by:

      (defun map-into (result-sequence function &rest sequences)
        (loop for index below (apply #'min
                                     (length result-sequence)
                                     (mapcar #'length sequences))
              do (setf (elt result-sequence index)
                       (apply function
                              (mapcar #'(lambda (seq) (elt seq index))
                                      sequences))))
        result-sequence)

