LISP: BACKQUOTE
C: Lbackquote
min args: 0
max args: -1
[F][SSCL]
SYNOPSIS:
backquote form
DESCRIPTION:
The backquote function is an internal function called backquote, not to be confused with the backquote syntax. (See entries for ` , ,@ and ,.).
The backquote characters are expanded into pseudo-functions in the scanner. After each iteration of the reader, the car of the list produced (if a list) is checked for the symbol backquote. If this is present, this function is called on the form to transform it as in Steele. Note that although the functions backquote, comma, comma-atsign,comma-dot and hashsign have actual bodies at some point in the reader, they are filtered out before the evaluator.
Hence it is an error to really call them at the top level. In this way we handle the detection of comma at the top level, etc.
LISP: BASE-STRING
min args:
max args:
[Typespec][CLTL2 4]
SYNOPSIS:
base-string [size]
DESCRIPTION:
This is the type specifier which indicates the set of data objects which are strings of the indicated size which can contain objects of type base-character:
base-string == (vector base-character size)
The size argument may be * or explicitly unspecified.
NOTES:
In this implementation base-character is equivalent to character, so this is equivalent to the string type specifier.
This is a new type specifier introduced by ANSI.
LISP: BIGNUM
[Typespec][CLTL 4]
SYNOPSIS:
bignum
DESCRIPTION:
This is the type specifier for the range of integers which (in this implementation) are too big to fit in a 32 bit signed twos complement number. Currently these numbers are stored in 256 byte buffers. bignum is a subtype of integer.
NOTES:
CLTL2 specifies that bignum and fixnum represent an exhaustive partition of integer. Star Sapphire has three separate size of integer; fixnums, which are 16 bits; 'true' integers, which are 32 bits; and bignums, which are everything else.
LISP: BIT
C: Lbit
min args: 1
max args: -1
[F][CLTL 17]
SYNOPSIS:
bit bit-array &rest subscripts
DESCRIPTION:
bit
allows access to an element of a bit array. The bit-array argument must be either a bit vector or an array with :element-type bit. The subscripts arguments are used as an index in the bit-array argument, retrieving the specified bit. The result will therefore always be 0 or 1. Fill pointers are ignored in the case of one dimensional bit arrays.Setf
may be used with bit to destructively replace a bit-array element with a new value. This is done through the set-bit function. The setf method for bit can be set up if the defsetf macro is loaded by one of the following invocations:(defsetf bit set-bit)
or, more generally,
(defsetf bit aset)
Bit
is essentially identical to aref except for the requirement that the first argument be a bit array. Using bit may make code more readable in certain circumstances.Bit
, unlike char, allows the first argument to be an array of any rank.SEE ALSO:
sbit, set-bit.
LISP: BIT (typespec)
[Typespec][CLTL 4]
SYNOPSIS:
bit
DESCRIPTION:
This is the type specifier symbol which represents the integers 1 and 0. Essentially:
bit == (integer 0 1)
This typespec is primarily used to define sequence types which have a specialized representation as bit fields, i.e. bit-vectors.
EXAMPLES:
(typep 3 'bit) => nil
(typep 0 'bit) => t
(make-array 10 :element-type 'bit) => #*0000000000
LISP: BIT-AND
C: Lbitand
min args: 2
max args: 3
[F][CLTL 17]
SYNOPSIS:
bit-and bit-array1 bit-array-2 &optional result-bit-array
DESCRIPTION:
bit-and
and the rest of the bit operation functions perform bit-wise logical operations on bit-arrays.All of the arguments to these functions must be bit-arrays of the same rank and dimensions. The result is a bit-array of matching rank and dimensions. Any given bit of the result is produced by operating on corresponding bits from each of the arguments. If the third argument is nil or omitted, a new array is created to contain the result. If the third argument is a bit-array, the result is overwritten into that array. If the third argument is t, the result is overwritten into the first array.
The following table gives the 'truth table' for each operation. This specifies the result for a given bit given the values of the bits in bit-array1 and bit-array2.
Operation Name |
|||||||||||
bit-array1 |
0 |
0 |
1 |
1 |
|||||||
bit-array2 |
0 |
1 |
0 |
1 |
|||||||
bit-and |
0 |
0 |
0 |
1 |
and |
||||||
bit-ior |
0 |
1 |
1 |
1 |
inclusive or |
Operation Name |
|||||
bit-xor |
0 |
1 |
1 |
0 |
exclusive or |
||||||
bit-eqv |
1 |
0 |
0 |
1 |
equivalence (exclusive nor) |
||||||
bit-nand |
1 |
1 |
1 |
0 |
not-and |
||||||
bit-nor |
1 |
0 |
0 |
0 |
not-or |
||||||
bit-andc1 |
0 |
1 |
0 |
0 |
and complement of argument1 with argument2 |
||||||
bit-andc2 |
0 |
0 |
1 |
0 |
and argument1 with complement of argument2 |
||||||
bit-orc1 |
1 |
1 |
0 |
1 |
or complement of argument1 with argument2 |
||||||
bit-orc2 |
1 |
0 |
1 |
1 |
or argument1 with complement of argument2 |
SEE ALSO:
bit-ior, bit-xor, bit-eqv, bit-nand, bit-nor, bit-andc1, bit-andc2, bit-orc1, bit-orc2
LISP: BIT-ANDC1
C: Lbit1andc
min args: 2
max args: 3
[F][CLTL 17]
SYNOPSIS:
bit-andc1 bit-array1 bit-array2 &optional result-bit-array
DESCRIPTION:
See bit-and.
SEE ALSO
bit-and, bit-ior, bit-xor, bit-eqv, bit-nand, bit-nor, bit-andc2, bit-orc1, bit-orc2
LISP: BIT-ANDC2
C: Lbit2andc
min args: 2
max args: 3
[F][CLTL 17]
SYNOPSIS:
bit-andc2 bit-array1 bit-array2 &optional result-bit-array
DESCRIPTION:
See bit-and.
SEE ALSO:
bit-and, bit-ior, bit-xor, bit-eqv, bit-nand, bit-nor, bit-andc1, bit-orc1, bit-orc2
LISP: BIT-EQV
C: Lbiteqv
min args: 2
max args: 3
[F][CLTL 17]
SYNOPSIS:
bit-eqv bit-array1 bit-array-2 &optional result-bit-array
DESCRIPTION:
See bit-and.
SEE ALSO:
bit-and, bit-ior, bit-xor, bit-nand, bit-nor, bit-andc1, bit-andc2, bit-orc1, bit-orc2
LISP: BIT-IOR
C: Lbitior
min args: 2
max args: 3
[F][CLTL 17]
SYNOPSIS:
bit-ior bit-array1 bit-array-2 &optional result-bit-array
DESCRIPTION:
See bit-and.
SEE ALSO:
bit-and, bit-xor, bit-eqv, bit-nand, bit-nor, bit-andc1, bit-andc2, bit-orc1, bit-orc2
LISP: BIT-NAND
C: Lbitnand
min args: 2
max args: 3
[F][CLTL 17]
SYNOPSIS:
bit-nand bit-array1 bit-array2 &optional result-bit-array
DESCRIPTION:
See bit-and.
SEE ALSO:
bit-and, bit-ior, bit-xor, bit-eqv, bit-nor, bit-andc1, bit-andc2, bit-orc1, bit-orc2
LISP: BIT-NOR
C: Lbitnor
min args: 2
max args: 3
[F][CLTL 17]
SYNOPSIS:
bit-nor bit-array1 bit-array2 &optional result-bit-array
DESCRIPTION:
See bit-and.
SEE ALSO:
bit-and, bit-ior, bit-xor, bit-eqv, bit-nand, bit-andc1, bit-andc2, bit-orc1, bit-orc2
LISP: BIT-NOT
C: Lbitnot
min args: 1
max args: 2
[F][CLTL 17]
SYNOPSIS:
bit-not bit-array &optional result-bit-array
DESCRIPTION:
The bit-array argument must be an array of bits. The return value is a bit-array with the same rank and dimensions as the original with all bit values inverted.
If the second argument is nil or not present, a new array is allocated for the result. If the second argument is a bit-array, the result is overwritten into that array. If the second argument is t, the result is overwritten into the first array argument.
SEE ALSO:
lognot, bit-and, bit-ior, bit-xor, bit-eqv, bit-nand, bit-nor, bit-andc1, bit-andc2, bit-orc1, bit-orc2
LISP: BIT-ORC1
C: Lbit1orc
min args: 2
max args: 3
[F][CLTL 17]
SYNOPSIS:
bit-orc1 bit-array1 bit-array2 &optional result-bit-array
DESCRIPTION:
See bit-and
SEE ALSO:
bit-and, bit-ior, bit-xor, bit-eqv, bit-nand, bit-nor, bit-andc1, bit-andc2, bit-orc2
LISP: BIT-ORC2
C: Lbit2orc
min args: 2
max args: 3
[F][CLTL 17]
SYNOPSIS:
bit-orc2 bit-array1 bit-array2 &optional result-bit-array
DESCRIPTION:
See bit-and
SEE ALSO:
bit-and, bit-ior, bit-xor, bit-eqv, bit-nand, bit-nor, bit-andc1, bit-andc2, bit-orc1
LISP: BIT-VECTOR
min args: 0
max args: 1
[Typespec][CLTL 6]
SYNOPSIS:
bit-vector [size]
bit-vector
DESCRIPTION:
This is the type specifier which represents bit-vectors. Bit-vectors are one dimensional arrays which are specialized to contain only the numbers 1 and 0.
The symbol can be used by itself or as the car of a type specifier list.
When used in a type specifier list, an optional size for the bit vector can be specified. The size can be unspecified either by omission or '*'.
EXAMPLES:
typep #*101010 'bit-vector) => t
(typep "foo" 'bit-vector) => nil
(typep #*101010 '(bit-vector 6)) => t
(typep #*101010 '(bit-vector 100)) => nil
(typep #*101010 '(bit-vector *)) => t
(typep #*101010 '(bit-vector)) => t
LISP: BIT-VECTOR-P
C: Lbit_vector_p
min args: 1
max args: 1
[F][CLTL 6]
SYNOPSIS:
bit-vector-p object
DESCRIPTION:
bit-vector-p
returns t if its argument is a bit-vector, otherwise nil.
LISP: BIT-XOR
C: Lbitxor
min args: 2
max args: 3
[F][CLTL 17]
SYNOPSIS:
bit-xor bit-array1 bit-array-2 &optional result-bit-array
DESCRIPTION:
See bit-and
SEE ALSO:
bit-and, bit-ior, bit-eqv, bit-nand, bit-nor, bit-andc1, bit-andc2, bit-orc1, bit-orc2
LISP: BLOCK
C: SFCBlock, EBlock
[S][CLTL 7]
SYNOPSIS:
block name {form}*
DESCRIPTION:
The block construct evaluates each form sequentially.
If, during the evaluation of the block, a return or return-from form is evaluated, the results of that form are returned as the value of the block.
Otherwise, the return value from block is the value of the last form.
The name, which must be a symbol, is not evaluated (and hence it is a mistake to quote it). This name is visible only within the block; in other words, it is lexically scoped. The name is used by return or return-from to specify which block to return from. Because name is lexically scoped, only return and return-from forms textually enclosed in the block can use that name and return from a given block.
A simple example follows. Note that all of the if forms are at the same level.
(block my-block
(if (eql today 'sunday)
(return-from my-block "back to work tomorrow"))
(if (eql today 'saturday)
(return-from my-block "middle of the weekend"))
"waiting for the weekend")
(This could probably be done more clearly with a cond statement; the point here is just to illustrate block and return-from).
Another example which illustrates nested blocks:
(block foo
(block bar
(print 'hello)
(if (= x 0)
(return-from foo 3))
(if (= x 1)
(return-from bar 4))
(print 'world)) ; normal exit from bar
(print 'there)) ; normal exit from foo
If x is 0, this form will print hello and return 3.
If x is 1, this form will print hello there and return there.
Otherwise, the form will print hello world there and return there.
A block is like a progn, except that progn does not permit the use of return or return-from and has no name.
Certain forms, including defun and defmacro establish implicit blocks. This means that a block with the same name as the function or macro is automatically inserted at some time after the form is read around the entire body of the defun or defmacro.
Thus return-from name can be used to return from a function named name:
( defun times 3x)
if (numberp x)
(return-from times3 (* 3 x)))
; the following clause is not the else clause in the 'if'.
(format t "hey - ~s isn't a number??!~%" x))
NOTES:
This form roughly corresponds to the a block in other programming languages; however, the fact that it is named distinguishes LISP. For instance, in C a set of wavy brackets creates a similar context for sequential evaluation; however, only the outermost block (those surrounding a function body) can be returned from.
The name has dynamic extent and thus a given block can only be exited once, either by returning from it or by reaching the end of the list of forms.
Depending on the situation, a return in Common LISP may not be simple. A return can break up catchers if necessary to get to a particular block. It is possible for a "closure" created by a function or lambda-expression to refer to a block name as long as the name is lexically apparent.
LISP: BOOLE
C: Boole
min args: 3
max args: 3
[F][CLTL 12]
SYNOPSIS:
boole op integer1 integer2 [F]
boole-clr [C]
boole-set [C]
boole-1 [C]
boole-2 [C]
boole-c1 [C]
boole-c2 [C]
boole-and [C]
boole-ior [C]
boole-xor [C]
boole-eqv [C]
boole-nand [C]
boole-nor [C]
boole-andc1 [C]
boole-andc2 [C]
boole-orc1 [C]
boole-orc2 [C]
DESCRIPTION:
The boole function performs a given bit operation on two integers. The first argument is the operation which is specified using the value of one of the constants listed above. The operation is performed on the second and third values, which must be integers, and the result is returned.
The truth table of each bit operation is as follows:
Operation Performed |
|||||
integer1 |
0 |
0 |
1 |
1 |
|
integer2 |
0 |
1 |
0 |
1 |
|
boole-cir |
0 |
0 |
0 |
0 |
always 0 |
boole-set |
1 |
1 |
1 |
1 |
always 1 |
boole-1 |
0 |
0 |
1 |
1 |
integer1 |
boole-2 |
0 |
1 |
0 |
1 |
nteger2 |
boole-c1 |
1 |
1 |
0 |
0 |
complement of integer1 |
boole-c2 |
1 |
0 |
1 |
0 |
complement of integer2 |
boole-and |
0 |
0 |
0 |
1 |
and |
boole-ior |
0 |
1 |
1 |
1 |
inclusive or |
boole-xor |
0 |
1 |
1 |
0 |
exclusive or |
boole-eqv |
1 |
0 |
0 |
1 |
equivalence (exclusive nor) |
boole-nand |
1 |
1 |
1 |
0 |
not-and |
boole-nor |
1 |
0 |
0 |
0 |
not-or |
boole-andc1 |
0 |
1 |
0 |
0 |
and complement of integer1 with integer2 |
boole-andc2 |
0 |
0 |
1 |
0 |
and integer1 with complement of integer2 |
boole-orc1 |
1 |
1 |
0 |
1 |
or complement of integer1 with integer2 |
boole-orc2 |
1 |
0 |
1 |
1 |
or integer1 with complement of integer2 |
boole
can therefore compute all sixteen logical functions on two arguments. In general,(boole boole-and x y) == (logand x y)
and so on. The reason that boole is useful is that the operation to be performed can be efficiently specified at runtime.
NOTES:
The various boole constants are defined as follows in init0.lsp. To use these, include the needed definitions in your own code:
(defconstant boole-clr 0)
(defconstant boole-set #xF)
(defconstant boole-1 3)
(defconstant boole-2 5)
(defconstant boole-c1 #xC)
(defconstant boole-c2 #xA)
(defconstant boole-and 1)
(defconstant boole-ior 7)
(defconstant boole-xor 6)
(defconstant boole-eqv 9)
(defconstant boole-nand #xE)
(defconstant boole-nor 8)
(defconstant boole-andc1 4)
(defconstant boole-andc2 2)
(defconstant boole-orc1 #xD
(defconstant boole-orc2 #xB)
LISP: BOTH-CASE-P
C: LBoCCharP
min args: 1
max args: 1
[F][CLTL 13]
SYNOPSIS:
both-case-p char
DESCRIPTION:
The char argument must be a character object.
both-case-p
returns t if the char argument is in the range #\A through #\Z or #\a through #\z. Otherwise it returns nil.If a character is either uppercase or lower-case, it is necessarily alphabetic (and therefore is graphic).
EXAMPLE:
(both-case-p #\?) => nil
(both-case-p #\x) => t
LISP: BOUNDP
C: LSymPBd
min args: 1
max args: 1
[F][CLTL 7]
SYNOPSIS:
boundp symbol
DESCRIPTION:
boundp
returns t, If symbol has a value, otherwise nil.An error is raised if symbol is not a global symbol.
Thus the symbol cannot be a lexical variable such as a function or lambda list parameter, or a name defined by let, unless that name was declared special.
EXAMPLE:
(setq x 15)
(boundp 'x) =>(makunbound 'x)
(boundp 'x) => nil
SEE ALSO:
set
and makunbound.
LISP: BREAK
C: Lbreak
min args: 0
max args: 0
[F][CLTL 24]
SYNOPSIS:
break &optional format-str &rest [format args...]
DESCRIPTION:
The break function enters the debugger immediately. If the optional format string and arguments are provided, a message will be printed when the break form is executed.
By inserting a call like this
(break)
in a LISP form, the debugger can be invoked at that point in the control flow of the form.
This allows you to 'set a breakpoint': to let your program execute up to a specific point and then drop into the debugger. Any number of breakpoints can be set.
A useful technique is to set a conditional breakpoint. Suppose you are interested in entering the debugger at a particular point in your program whenever the variable x exceeds 5000. The following code will do this:
(if (> x 5000)
(break))
Another useful technique is inserting a break into a progn where a form would otherwise be found.
This code example sets a breakpoint when factorial is at the base case:
(defun factorial(n)
(if (zerop n)
(progn (break) 1)
(* n (factorial (1- n)))))
Progn
returns 1 after (break) exits, which allows normal resumption of evaluation.
LISP: BUTLAST
C: Lbutlast
min args: 1
max args: 2
[F][CLTL 15]
SYNOPSIS:
butlast list &optional n
DESCRIPTION:
butlast
creates and returns a list with the same elements as its list argument, except for the last n elements. n defaults to 1. The argument is not destroyed. If the list has fewer than n elements, then the empty list is returned. For example:(butlast '(a b c d)) => (a b c)
(butlast '((a b) (c d))) => ((a b))
(butlast '(a)) => ()
(butlast nil) => ()
NOTES:
The name is from the phrase "all elements but the last."
LISP: BYE
C: Bye
min args: 0
max args: 0
[F][SSCL]
SYNOPSIS:
bye
DESCRIPTION:
The bye function exits LISP as if the user typed Ctrl-Z or an end of file was encountered in batch mode.