LISP: CxR
C: Lcaar, Lcadr, Lcdar, Lcddr, Lcaaar, Lcaadr, Lcadar, Lcaddr, Lcdaar, Lcdadr, Lcddar, Lcdddr, Lcaaaar, Lcaaadr, Lcaadar, Lcaaddr, Lcadaar, Lcadadr, Lcaddar, Lcadddr, Lcdaaar, Lcdaadr, Lcdadar, Lcdaddr, Lcddaar, Lcddadr, Lcdddar, Lcddddr
min args: 1
max args: 1
[F][CLTL 15]
SYNOPSIS:
caar list
cadr list
cdar list
cddr list
caaar list
caadr list
cadar list
caddr list
cdaar list
cdadr list
cddar list
cdddr list
caaaar list
caaadr list
caadar list
caaddr list
cadaar list
cadadr list
caddar list
cadddr list
cdaaar list
cdaadr list
cdadar list
cdaddr list
cddaar list
cddadr list
cdddar list
cddddr list
DESCRIPTION:
The car and cdr functions extract the head and tail of cons structures. Since LISP programs and data are both represented as lists built up of cons structures, it is often useful to use a combination of several car and cdr function calls to extract a given piece of a list.
There are several list functions which are used for this purpose; the most numerous being the composite car and cdr functions. These functions are named by a function beginning with 'C' and ending in 'R'. The body of the name is two to four letters, 'A' and 'D'; each of which specifies a car or cdr function in the sequence. For instance (cadddr x) is the same as (car (cdr (cdr (cdr x)))); this extracts the head of the tail of the tail of the tail of the list x. A useful technique which employs these functions extracts the head of a specified composition of tails of a list. For instance, if you are analyzing defun forms,
(setq form '(defun foo(x y z)(* x y z)))
then the following will extract the argument list of the defun:
(caddr form) => (x y z)
Note that the order of operations specified by the 'A' and 'D' letters is the same as a parenthesized expression; hence the first one to get applied will be the last in the list. Begin by scanning the 'A' and 'D' letters backwards to understand the actual sequence of operations. Drawing box and arrow diagrams, as shown in any introductory LISP text, will also help with these operations.
In practice, use of the more obscure permutations of these functions should be frowned upon. Instead, defun or defmacro should be used to construct an alias:
(defun get-defun-arg-list(form)(caddr form))
This is in the interest both of readability and maintainability of code.
Any of these functions may be used to specify a place for setf. The defsetf calls are found in init0.lsp and need to be invoked once defsetf.fsl has been loaded to get a setf for a particular function. For instance, the defsetf for cadar is:
(defsetf cadar (x) (y) `(progn (rplaca (cdar ,x) ,y) ,y))
NOTES:
These functions' names are traditionally pronounced (by English speakers, at least) by interpolating the schwa ('uh' as in 'but') sound between any adjacent consonants otherwise not separated by the 'A' vowel. Note that schwa between D and R is pronounced 'der', as the final syllable in 'order'. The 'A' is pronounced in this case 'ah' as in 'bat'. These rules do not hold for car and cdr, which are pronounced like the synonym for automobile and 'coodr' respectively. Hence cadr is pronounced 'cah-der' and cddddr is pronounced 'cuh-duh-duh-der'.
LISP: CAAR
see CxR
LISP: CADR
see CxR
LISP: CDAR
see CxR
LISP: CDDR
see CxR
LISP: CAAAR
see CxR
LISP: CAADR
see CxR
LISP: CADAR
see CxR
LISP: CADDR
see CxR
LISP: CDAAR
see CxR
LISP: CDADR
see CxR
LISP: CDDAR
see CxR
LISP: CDDDR
see CxR
LISP: CAAAAR
see CxR
LISP: CAAADR
see CxR
LISP: CAADAR
see CxR
LISP: CAADDR
see CxR
LISP: CADAAR
see CxR
LISP: CADADR
see CxR
LISP: CADDAR
see CxR
LISP: CADDDR
see CxR
LISP: CDAAAR
see CxR
LISP: CDAADR
see CxR
LISP: CDADAR
see CxR
LISP: CDADDR
see CxR
LISP: CDDAAR
see CxR
LISP: CDDADR
see CxR
LISP: CDDDAR
see CxR
LISP: CDDDDR
see CxR
LISP: CALL-ARGUMENTS-LIMIT
C: N/A
[C][CLTL 7]
SYNOPSIS:
call-arguments-limit
DESCRIPTION:
The value of call-arguments-limit is a positive integer that is the upper exclusive bound on the number of arguments that may be passed to a function. In theory, this is one less than the largest positive fixnum. In practice, it is limited by available stack.
NOTES:
This constant is defined in init0.lsp. By default, it is not loaded at startup to reduce the time needed to initialize LISP. If needed, its definition can be added to init.lsp so that it will be initialized at startup; it can also be added to any file of LISP code.
SEE ALSO:
multiple-values-limit.
LISP: CAR
C: Lcar
min args: 1
max args: 1
[F][CLTL 15]
SYNOPSIS:
car list
DESCRIPTION:
The car function extracts the head cell from a list. The list can consist either of a cons or the empty list () (also known as nil). In other words, the argument must be one for which the predicate listp would return t. It is an error if the argument to car is not a cons or nil.
If the cons is the first cons of a list, then car returns the first element of the list. For example:
(car '(a b c)) => a
By definition, the car of () is ().
The car of a cons may be altered by using rplaca or setf. To use setf with car, defsetf.fsl must be loaded (see init.lsp). This automatically brings in the setf definition for car, which is:
(defsetf car (x) (y) `(progn (rplaca ,x ,y) ,y))
SEE ALSO:
first,
which is identical but slightly more readable.NOTES:
The name comes from an opcode on the antique IBM computer that LISP was first implemented on, mnenomic for 'Contents of Address Register'.
LISP: CASE
C: SFCCase, ECase
[M][CLTL 7]
SYNOPSIS:
case keyform { ( { ( {key}* ) | key } { form }* ) }*
DESCRIPTION:
A case form, similar to cond, does a linear search in a list of clauses to pick out a particular form to run.
This is very close in spirit to the case and switch constructs in other programming languages; however, Common LISP provides somewhat greater flexibility.
case
is much like cond in terms of structure. case behaves like cond by selecting a clause and then running all consequents of that clause. However, case differs in the method of selecting a clause.The syntax looks like this:
(case keyform
(keylist-1 consequent-1-1 ...)
(keylist-2 consequent-2-1 ...)
(keylist-3 consequent-3-1 consequent-3-2 ...)
...)
The decision is made, unlike cond, not on the basis of whether a particular form turns out to be true; but by comparing the result of evaluating a particular form (the keyform) with the result of evaluating a form at the head of each clause.
The result of evaluating the keyform is termed the key object.
The test used to determine which clause to run is eql. If the result of evaluating any of the forms in the keylist is eql to the key object, that consequent is selected.
The keys in the keylists are not evaluated (need not be have a quote). The Common LISP specification states that it is an error for the same key to appear in more than one clause. Therefore the order of the clauses does not affect the behavior of the case construct, with the exception of clauses which begin with t or otherwise.
The form at the head of a given clause, the keylist, can either be one conditional expression, or a list of such conditions. If there is only one conditional expression (a "singleton key") certain rules apply so there is no ambiguity in the interpretation of the clause:
A singleton key may not be nil (which could be confused with (), a list of no keys).
A singleton key may not be t, otherwise, or a cons.
In place of a keylist, one may write one of the symbols t and otherwise. A clause with one of these symbols always succeeds and must be the last clause (this is an exception to the order-independence of clauses).
Just as with cond, the selected consequent is evaluated as an implicit progn, and the case form returns the result of the last form in the implicit progn.
Specifically, case returns what was returned by the last consequent (or nil if there are no consequents in that clause). If no clause is selected, case returns nil.
NOTES:
Keyform values are typically constant values, such as characters, keywords, integers. However, any constant form is legal.
Star Sapphire does not presently require that keylist forms evaluate to constants. In other Common LISPs, particularly those which are compiled to native code, this may be enforced.
LISP: CATCH
C: SFCCatch, ECatch
[S][CLTL 7]
SYNOPSIS:
catch tag {form}*
DESCRIPTION:
The catch special form acts as a target for a throw.
First, the tag is evaluated to produce an object. The object will name the catch for the purposes of throw. This object may be any LISP object. The tag is used to match throws with catches. A catcher is thereby established with the object as the tag. Note that the tag must be quoted if it is a symbol.
The forms in the body of the catch are then evaluated as an implicit progn. If no throw is executed while the body of the implicit progn is being run, the results of the last form will be returned.
However, if during the evaluation of the forms a throw is executed, a non-local transfer back to this catcher occurs if the following conditions are met:
The tag of the throw must match (eq) the tag of the catch. Because the comparison is performed with eq, not eql, numbers and characters should not be used as catch tags; tags are traditionally symbols.
The catcher must be the most recent catcher established with the tag. It is an error if a throw occurs when there is no matching catch.
In the latter case, the evaluation of the forms is interrupted. The results specified by the throw are returned immediately from the catch expression.
Just before the results are returned, the catcher established by the catch expression is disestablished.
For example:
(catch 'dog ; this sets up a catcher named 'dog
(hairy-function)) ; hairy-function is defined somewhere else
;;; a big, complicated function in some other file
(defun hairy-function
:
:
(throw 'dog 'bone) ; this transfers to the dog catcher
; which will return bone.
:
:
)
For another example of catch and throw, see the advent code, which uses this mechanism to return from the endgame if the adventurer gets sufficiently irritated. In fact, the throw occurs in an entirely different file (aendgame.lsp) than the catcher (advent.lsp).
LISP: CDR
C: Lcdr
min args: 1
max args: 1
[F][CLTL 15]
SYNOPSIS:
cdr list
DESCRIPTION:
The cdr function extracts the tail cell from a list. The list can consist either of a cons or the empty list () (also known as nil). In other words, the argument must be one for which the predicate listp would return t. It is an error if the argument to cdr is not a cons or nil.
If the cons is the first cons of a list, then cdr returns the rest of the list. For example:
(cdr '(a b c)) => (b c)
By definition, the cdr of () is ().
The cdr of a cons may be altered by using rplaca or setf. To use setf with cdr, defsetf.fsl must be loaded (see init.lsp). This automatically brings in the setf definition for cdr, which is:
(defsetf cdr (x) (y) `(progn (rplacd ,x ,y) ,y))
SEE ALSO:
rest
, which is identical but slightly more readable.NOTES:
The name comes from an opcode on the antique IBM computer that LISP was first implemented on, mnenomic for 'Contents of Decrement Register'.
LISP: CEILING
C: Lceiling
min args: 1
max args: 2
[F][CLTL 12]
SYNOPSIS:
ceiling number &optional divisor
DESCRIPTION:
Ceiling
converts its argument by truncating toward positive infinity.Ceiling
can take one or two arguments. The first argument is the number to find the ceiling of. The second optional argument is an optional divisor to divide number by before performing the truncation. Both arguments must be numbers, or an error is raised.Ceiling
always returns two values. The first result is the smallest integer that is not smaller than the argument. The second result is the remainder and may be obtained using multiple-value-bind and related constructs.That is, if ceiling is given two arguments x and y and produces results q and r, then (q*y)+r=x.
The first result q is always an integer.
The remainder r is an integer if both arguments are integers, is rational if both arguments are rational, and is floating-point if either argument is floating-point.
In the one-argument case, ceiling converts its argument to be an integer. If the argument is already an integer, that integer is returned as the first return value. If the argument is a ratio or floating-point number, ceiling uses different algorithms for the conversion.
In the one-argument case the second return value, the remainder, is always a number of the same type as the argument.
If a second argument divisor is supplied, then the first return value is the truncation applied to the result of dividing the number by the divisor. The divisor may be any number. The one-argument case is exactly like the two-argument case where the second argument is 1. When only one argument is given, the two results are exact; the mathematical sum of the two results is always equal to the mathematical value of the argument.
SEE ALSO:
floor, truncate, round, ffloor, ftruncate, fround.
LISP: CHAR
C: Lchar
min args: 2
max args: 2
[F][CLTL 18]
SYNOPSIS:
char string index
DESCRIPTION:
The char function obtains the character at the position index in the string string. The index is, as usual for Common LISP, zero based.
The first argument must be a string. The index must be a non-negative integer less than the length of the string. setf may be used with char to destructively replace a given character within a string. This capability can be activated once defsetf.fsl is loaded by invoking defsetf as follows:
(defsetf char aset)
This definition, with the other setf methods, can be found in init0.lsp.
SEE ALSO:
schar, aref, elt.
LISP: CHAR-BIT
C: Lchar_bit
min args: 2
max args: 2
[F][CLTL 13]
SYNOPSIS:
char-bit char bit-name -> predicate
DESCRIPTION:
The char-bit function returns t if the bit named bit-name is set in the char argument, otherwise nil.
Supported bit names are :control and :meta. The :hyper and :super bit names specified in CLTL1 are not supported in this implementation and it is an error to give char-bit one of these names.
For instance:
(char-bit #\meta-control-p :meta) => T
NOTES:
This function, defined in CLTL1 has been eliminated in ANSI Common LISP; it will probably not be supported in future Star Sapphire versions.
SEE ALSO:
set-char-bit
LISP: CHAR-BITS
C: Lcharbits
min args: 1
max args: 1
[F][CLTL 13]
SYNOPSIS:
char-bits character -> integer
DESCRIPTION:
char-bits
returns the bits attribute of the character object; this will be a non-negative integer less than the normal value of the variable char-bits-limit.The character argument must be a character object.
NOTES:
This function, defined in CLTL1, has been eliminated in ANSI Common LISP; it will probably not be supported in future Star Sapphire versions.
LISP: CHAR-CODE
C: Lchar_code
min args: 1
max args: 1
[F][CLTL 13]
SYNOPSIS:
char-code character -> integer
DESCRIPTION:
If the numeric value of the character argument is less than 128, char-code will return that value; if that value is greater than or equal to 128, the value -128 is returned. Font bits are stripped from the value. The character argument must be a character object.
NOTES:
The following non-printing characters have special names:
char value |
Name |
#\control- |
#x8 |
Backspace |
#\control-h |
#x9 |
Tab |
#\control-i |
#xA |
Newline |
#\control-j |
#xC |
Page |
#\control-l |
#xD |
Return |
#\control-m |
#x1b |
Escape |
#\control-[ |
#x20 |
Space |
N/A |
#x7f |
Rubout |
N/A |
In Star Sapphire LISP, the ASCII character code is used for 'ordinary' characters in the range #\space to #\rubout (del); control- prefixed to a given character in the range #\@ to #\rubout subtracts 64 from the value; meta- characters are the equivalent character plus 128 and meta-control of a given character in the range #\@ to #\rubout adds 64 to its ASCII value. Furthermore, the case of character names with #\control- prefixes is ignored, so that #\control-x is the same character as #\control-X (numeric value 24).
The following chart explains how this works within given ranges.
character value |
char-code |
SSCL Name |
#x0 .. #x1F |
#x0 .. #x1F |
#\control-@..#\control-_ |
#x20 .. #x3F |
#x20 .. #x3F |
#\space .. #\? |
#x40 .. #x7F |
#x40 .. #x7F |
#\@ .. #\rubout |
#x80 .. #xBF |
#x0 .. #x3F |
#\meta-control-@..#\meta-control-rubout |
#xC0 .. #xFF |
#x40 .. #x7F |
#\meta-@..#\meta-rubout |
SEE ALSO:
Extended ASCII characters for a more comprehensive chart of this mapping.
EXAMPLES:
(char-code #\x) => 120
(char-code #\meta-A) => 65
(char-code #\m-c-~) => 62
(char-code #\control-@) => 0
LISP: CHAR-DOWNCASE
C: Lchar_dncase
min args: 1
max args: 1
[F][CLTL 13]
SYNOPSIS:
char downcase character
DESCRIPTION:
The character argument must be a character object. char-downcase converts the argument to a lowercase equivalent if it is an uppercase character.
NOTES:
Common LISP specifies that this function should preserve meta- and control- attributes, while converting the character code attribute if it is uppercase.
Star Sapphire LISP char-downcase only converts characters strictly in the range #\A .. #\Z to #\a .. #\z. All other characters will be returned as is.
EXAMPLE:
(char-upcase #\control-meta-X) => #\ctrl-meta-X.
The return value will have any font information stripped out. This effect can be considered a bug, although fonts are not supported in this implementation.
SEE ALSO:
char-upcase
LISP: CHAR-EQUAL
see: CHAR- Predicates
LISP: CHAR-GREATERP
see: CHAR- Predicates
LISP: CHAR-LESSP
see: CHAR- Predicates
LISP: CHAR-NOT-EQUAL
see: CHAR- Predicates
LISP: CHAR-NOT-GREATERP
see: CHAR- Predicates
LISP: CHAR-NOT-LESSP
see: CHAR- Predicates
LISP: CHAR- Predicates
C: Lchreqnc, Lchrgtnc, Lchrltnc, Lchrnenc, Lchrlenc, Lchrgenc
min args: 1
max args: -1
[F][CLTL 13]
SYNOPSIS:
char-equal character &rest more-characters -> predicate
char-greaterp character &rest more-characters -> predicate
char-lessp character &rest more-characters -> predicate
char-not-equal character &rest more-characters -> predicate
char-not-greaterp character &rest more-characters -> predicate
char-not-lessp character &rest more-characters -> predicate
DESCRIPTION:
These functions compare a sequence of one or more characters without regard to case. All of the arguments must be characters.
The return value is t if the given relation holds for all the arguments in the given sequence from left to right, and nil otherwise. Before the comparison the following Star Sapphire specific conversion occurs:
Any #\control- characters will have 64 added to their value; any #\meta-control- characters will have 64 subtracted from their value; and any #meta- characters will have 128 subtracted from their value. Following this, all characters in the range #\A to #\Z get mapped to #\a .. #\z, as per the specification.
SEE ALSO:
char-code
NOTES:
The implicit ordering on the converted arguments in Star Sapphire LISP is that of the ASCII code; however, code which relies on this ordering will not be portable.
EXAMPLES:
(char-equal #\A #\a) is true
(char= #\A #\a) is false
(char-equal #\A #\Control-A) is true
LISP: CHAR-FONT
C: Lchar_font
min args: 1
max args: 1
[F][CLTL 13]
SYNOPSIS:
char-font character -> integer
DESCRIPTION:
char-font
returns the font attribute of its character argument. The argument must be a character.NOTES:
This function has been eliminated in ANSI Common LISP; it will probably not be supported in future Star Sapphire versions.
LISP: CHAR-INT
C: Lchar_int
min args: 1
max args: 1
[F][CLTL 13]
SYNOPSIS:
char-int character -> integer
DESCRIPTION:
This function returns the raw numeric value of its character argument, which must be a character. This will be the ASCII code for characters less than 127; for others all bits will be preserved.
EXAMPLES:
assuming *print-base* is 16:
(char-int #\control-x) => #x18
(char-int #\x) => #x58
(char-int #\X) => #x78
(char-int #\m-c-x) => #xb8
(char-int #\meta-x) => #xf8
NOTE:
Since characters are represented immediately (right in the cons) this is the raw, actual value stored in the page-address field of the addr struct.
SEE ALSO:
char-code
LISP: CHAR-LIST-TO-STRING
C: Lclstos
min args: 0
max args: -1
[F][SSCL]
SYNOPSIS:
char-list-to-string list -> string
DESCRIPTION:
The char-list-to-string function takes as its only argument a list of characters. The return value is a new string which contains all of the characters in the list in sequence. The list must contain less than 256 characters. This function is non-standard but quite a bit faster than coerce.
This is a Star Sapphire specific function.
LISP: CHAR-NAME
C: Lchar_name
min args: 1
max args: 1
[F][CLTL 13]
SYNOPSIS:
char-name character -> string
DESCRIPTION:
The character argument to char-name is a character object. If the character has a 'simple' character name, the return value is a string which contains the printed representation of the character's name according to Common LISP conventions.
If not, the return value will be nil.
SEE ALSO:
char-code
NOTES:
In this implementation 'simple' means any character with a char-int value below 128. The same routine which prints the character ordinarily is called to do the conversion; however, if the character is meta- anything, nil is returned.
LISP: CHAR-UPCASE
C: Lchar_upcase
min args: 1
max args: 1
[F][CLTL 13]
SYNOPSIS:
char-upcase character -> character
DESCRIPTION:
The character argument must be a character object. char-upcase converts the argument to an uppercase equivalent if it is a lowercase character.
NOTES:
Common LISP specifies that this function should preserve meta- and control attributes, while converting the character code attribute if it is lowercase.
Star Sapphire LISP char-upcase only converts characters strictly in the range #\a .. #\z to #\A .. #\z. All other characters will be returned as is.
EXAMPLE:
(char-upcase #\control-meta-x) => #\control-meta-x.
NOTE:
The return value will have any font information stripped out. This effect can be considered a bug.
SEE ALSO:
char-downcase
LISP: CHAR=
See CHAR comparisons
LISP: CHAR/=
See CHAR comparisons
LISP: CHAR<
See CHAR comparisons
LISP: CHAR<=
See CHAR comparisons
LISP: CHAR>
See CHAR comparisons
LISP: CHAR>=
See CHAR comparisons
LISP: CHAR comparisons
C: Lchreq, Lchrne, Lchrlt, Lchrle, Lchrgt, Lchrge
min args: 1
max args: -1
[F][CLTL 13]
SYNOPSIS:
char= character &rest more-characters -> predicate
char/= character &rest more-characters -> predicate
char< character &rest more-characters-> predicate
char<= character &rest more-characters -> predicate
char> character &rest more-characters -> predicate
char>= character &rest more-characters -> predicate
DESCRIPTION:
These functions compare a sequence of one or more characters. All of the arguments must be characters. No conversion is performed on the characters before comparison.
The return value is t if the given relation holds for all the arguments in the given sequence from left to right, and nil otherwise.
NOTES:
The implicit ordering on the arguments to char=, etc. in Star Sapphire LISP is that of the ASCII code; however, code which relies on this ordering will not be portable.
For instance, while alphabetic characters of a given case must be properly ordered, code which relies on these characters being contiguous will not be portable to other implementations. Thus (char<= #\A x #\Z) is not a portable way of determining whether or not x is a upper-case letter. Hence a separate upper-case-p predicate is provided.
In any implementation of Common LISP, if (eq c1 c2) is true, then one may expect (char= c1 c2) to be true.
Moreover, because of the implementation of characters in Star Sapphire LISP as immediate objects (stored directly on the stack and in conses), (char= c1 c2) will likewise happen to imply (eq c1 c2). However, this may not be true in all implementations of Common LISP and code which relies on this will not be portable.
eql
and equal compare character objects in the same way that char= does. Use these instead if an equality test incorporating characters and possibly other types of objects is required.EXAMPLES:
(char= #\d #\d) is true.
(char= #\d #\x) is false.
(char= #\d #\D) is false.
(char= #\d #\d #\d #\d) is true.
(char= #\d #\d #\x #\d) is false.
(char= #\d #\y #\x #\c) is false.
(char= #\d #\c #\d) is false.
(char/= #\d #\d) is false.
(char/= #\d #\x) is true.
(char/= #\d #\D) is true.
(char/= #\d #\d #\d #\d) is false.
(char/= #\d #\d #\x #\d) is false.
(char/= #\d #\y #\x #\c) is true.
(char/= #\d #\c #\d) is false.
(char< #\d #\x) is true.
(char< #\d #\d) is false.
(char< #\a #\e #\y #\z) is true.
(char< #\a #\e #\e #\y) is false.
(char<= #\d #\x) is true.
(char<= #\d #\d) is true.
(char<= #\a #\e #\y #\z) is true.
(char<= #\a #\e #\e #\y) is true.
(char> #\e #\d) is true.
(char> #\d #\c #\b #\a) is true.
(char> #\d #\d #\c #\a) is false.
(char> #\e #\d #\b #\c #\a) is false.
(char> #\z #\A) may be true or false.
(char> #\Z #\a) may be true or false.
(char>= #\e #\d) is true.
(char>= #\d #\c #\b #\a) is true.
(char>= #\d #\d #\c #\a) is true.
(char>= #\e #\d #\b #\c #\a) is false.
LISP: CHARACTER (function)
C: Lcharacter
min args: 1
max args: 1
[F][CLTL 13]
SYNOPSIS:
character object
DESCRIPTION:
The character function coerces its argument to be a character. This implementation currently supports the following coercions:
If object is already a character, the selfsame object is returned.
If object is a string of length 1, the first character in the string is turned into a character object and returned.
If object is a symbol with a print name of length 1, the procedure in the previous sentence is followed for the print name of the symbol.
If object is a fixnum integer it is turned into a character by simply adding the proper typebits.
If none of these criteria are met, the error 'coercion failed' will be raised.
NOTES:
Fixnum arguments beyond the range 0...255 (including negative numbers), while not raising an error, will produce appropriate characters with non-zero font values; however, this is pretty useless since fonts are not otherwise supported.
LISP: CHARACTER (typespec)
[Typespec][CLTL 4]
SYNOPSIS:
character
DESCRIPTION:
This is the type specifier symbol which stands for the class of character objects.
LISP: CHARACTERP
C: Lcharacterp
min args: 1
max args: 1
[F][CLTL 6]
SYNOPSIS:
characterp object
DESCRIPTION:
characterp
returns t if its argument is a character object, else nil.LISP: CLASS-OF
C: LClassOf
min args: 1
max args: 1
[F][CLOS]
SYNOPSIS:
class-of object
DESCRIPTION:
The function class-of returns the class of which the given object is an instance. The argument to class-of may be any Common LISP object. The function class-of returns the class of which the argument is an instance.
LISP: CLASS-PRECEDENCE-OF
C: LPrecLsOf
min args: 1
max args: 1
[F][SSCL][CLOS]
SYNOPSIS:
class-precedence-of object
DESCRIPTION:
This Star Sapphire specific CLOS interface function returns the class precedence list of a given object as an instance of a class, including precedence lists for standard types which are initialized at startup.
LISP: CLEAR-INPUT
C: Lclearinput
min args: 0
max args: 1
[F][CLTL]
SYNOPSIS:
clear-input &optional input-stream
DESCRIPTION:
This function clears all input from the given stream. If no arguments are given *standard-input* is flushed, as well as LISPs internal terminal I/O.
clear-input
returns nil.NOTES:
If the stream is not an input stream it is flushed regardless. This function is useful to clear the input stream prior to a call to listen (q.v.).
LISP: CLOSE
C: L_Close
min args: 1
max args: 3
[F][CLTL 21]
SYNOPSIS:
close stream &key :abort
DESCRIPTION:
The close function closes a stream; the argument must be a stream object.
No further input/output operations may be performed on the argument after it is closed. However, certain inquiry operations may still be performed, and it is harmless to close an already closed stream.
If the :abort parameter is not nil (it defaults to nil), it indicates an abnormal termination of the use of the stream. An attempt is made to clean up any side effects of having created the stream in the first place. For example, if the stream performs output to a file that was newly created when the stream was created, then if possible the file is deleted and any previously existing file is not superseded.
NOTES:
The :abort parameter has no effect in the current version of Star Sapphire Common LISP. It is accepted for compatibility.
LISP: CLRHASH
C: Lclrhash
min args: 1
max args: 1
[F][CLTL 16]
SYNOPSIS:
clrhash hash-table
DESCRIPTION:
The clrhash function removes all entries from the hash-table. The return value is the cleared hash-table.
LISP: CODE-CHAR
C: Lcode_char
min args: 1
max args: 3
[F][CLTL 13]
SYNOPSIS:
code-char code &optional (bits 0) (font 0)
DESCRIPTION:
The code-char function attempts to construct a character object with code attribute code, bits attribute bits, and font attribute font.
For any integers c, b, and f, if (code-char c b f) is not nil then
(char-code (code-char c b f)) => c
(char-bits (code-char c b f)) => b
(char-font (code-char c b f)) => f
All three arguments must be non-negative fixnum integers.
If such a character object cannot be constructed, nil is returned.
NOTES:
ANSI Common LISP has eliminated the bits and font arguments to code-char; Star Sapphire LISP will do so in a future version.
SEE ALSO:
char-code
LISP: COERCE
C: Lcoerce
min args: 2
max args: 2
[F][CLTL 4]
SYNOPSIS:
coerce object result-type
DESCRIPTION:
The result-type parameter must be a type specifier. The object is converted if possible to an equivalent object of the specified type . If the object is already of the specified type, the selfsame object is returned.
The following coercions are supported.
· Any sequence type may be converted to any other sequence type, as long as the new sequence can contain all actual elements of the old sequence (it is an error if their type or number are incompatible with the new sequence). For instance:
(coerce '(#\a #\b #\c) 'string) => "abc"
(coerce #*101010 '(vector integer)) => #(1 0 1 0 1)
(coerce #(a b c) 'string)
=> error ; symbols cannot be incorporated as string elements
· Strings of length one, symbols with print names of length one, and integers may be converted to characters. In the case of strings and symbols, the sole character is returned as a character; in the case of the integer, the equivalent ASCII value is returned (integers out of the range of ASCII will get converted to equivalent high-bit characters).
· Any number can be converted to a floating point number of any type (although this implementation will always produce a object of type float).
· Any object can be converted to type t: this is the equivalent of the identity function.
* This implementation supports the following unspecified coercion. Any integer which is (typep '(mod 32)) can be converted to a bit vector which contains the same bits as the twos' complement value of the number. If the integer is mod 16, it will have 16 bits, and if it is mod 32, it will have 32 bits.
For instance:
(coerce 2 'bit-vector) => #*000000000000000010
If the conversion is not possible, then an error is raised. Note that (coerce x 'nil) always signals an error, since no object is of type nil.
LISP: COMMA
C: Lcomma
min args: 0
max args: -1
[F][SSCL]
SYNOPSIS:
comma form
DESCRIPTION:
This is an internal function used to implement backquote. Refer to the entry for , for information on the use of the comma macro character.
SEE ALSO:
backquote
LISP: COMMA-ATSIGN
C: Lcommaatsign
min args: 0
max args: -1
[F][SSCL]
SYNOPSIS:
comma-atsign form
DESCRIPTION:
This is an internal function used to implement backquote. Refer to the entry for ,@ for information on the use of the comma-atsign macro character.
SEE ALSO:
backquote
LISP: COMMA-DOT
C: Lcommadot
min args: 0
max args: -1
[F][SSCL]
SYNOPSIS:
comma-dot form
DESCRIPTION:
This is an internal function used to implement backquote. Refer to the entry for ,. for information on the use of the comma period macro character.
SEE ALSO
backquote
LISP: COMPILE
C: Lcompile
min args: 1
max args: 2
[F][CLTL 25]
SYNOPSIS:
compile form
DESCRIPTION:
The compile function runs the incremental compiler on its form argument, returning the compiled code.
Note that the compiled form may not be read back in, but in all other respects is a LISP form stored internally in the same format as all other LISP lists: Albeit with many unreadable objects embedded in it.
The incremental compiler is a program that may make code run faster by translating programs into an implementation-dependent form that can be executed more efficiently by the computer. Most of the time you can write programs without worrying about the compiler.
Star Sapphire has a read-compile-eval-print loop, as opposed to an interpreter, which has a read-eval-print loop at the top level. Technically, this is called an "incremental semi-compiler." The Star Sapphire compiler is sometimes referred to as the canonicalizer, as it translates forms into a 'canonical' representation.
The canonicalizer recursively descends an expression and
LISP: COMPILE-FILE
C: Lcompfile
min args: 1
max args: -1
[F][CLTL 25]
SYNOPSIS:
compile-file input-file &key :output-file
DESCRIPTION:
Produces a fastload file from LISP source.
The input-file argument must be a valid file name as a symbol or string. The file should be a LISP source file: its contents are compiled and written as a .fsl file with the same basename as the original. The output-file argument may be used to specify an output file with a different name than this. This function always returns the name of the output file. It is an error if the file with the .fsl extension cannot be created, due to exceeding 256 characters in length.
The resulting file can be loaded by load: load examines any binary file it receives to see if the fastload header is present. If the file is found to be a fastload file, it is loaded into memory.
NOTES:
One important thing to note when compiling macro, setf or defsetf definitions (basically anything which depends on macros) is that the definition has to have been loaded into the environment at the time that the fastload file is compiled, otherwise the compiled version will not expand the macros. You will then get messages such as "setf has no runtime definition." This is not a bug. Since setf is a macro it doesn't actually have an associated function, only an expansion which produces code.
The bottom line: Always make sure you have loaded the most current version of any macros used in your files before compiling them to fastloads.
Note, on the other hand, that defmacros compile into very efficient fastload files.
We strongly encourage you to use fastload files instead of save images, as the fastload files are position-independent.
LISP: COMPILE-FILE-0
C: _L0compfile
min args: 1
max args: 1
[F][SSCL]
SYNOPSIS:
compile-file-0 filename
DESCRIPTION:
This function returns a list consisting of the compiled code for each form in the file.
This is a LISP interface to the first pass of all Star Sapphire file compilers.
NOTES:
This is an internal function.
LISP: COMPILED-FUNCTION-P
C: Lcompiled_function_p
min args: 1
max args: 1
[F][CLTL 6]
SYNOPSIS:
compiled-function-p object
DESCRIPTION:
compiled-function-p
is true if its argument is any compiled code object, and otherwise is false.(compiled-function-p x) == (typep x 'compiled-function)
LISP: COMPILED-FUNCTION
[Typespec][CLTL 4]
SYNOPSIS:
compiled-function
DESCRIPTION:
This is the type specifier symbol which stands for the set of LISP compiled functional objects.
LISP: COMPLEXP
C: Lcomplexp
min args: 1
max args: 1
[F][CLTL 6]
SYNOPSIS:
complexp object
DESCRIPTION:
complexp
is true if its argument is a complex number, and otherwise is false.(complexp x) == (typep x 'complex)
LISP: COMPLEX
[Typespec]
SYNOPSIS:
complex [type]
complex
DESCRIPTION:
This is the type specifier which stands for the set of LISP complex numbers. It can occur either as a symbol or at the head of a type specifier list. If it is at the head of a type specifier list, a type can be specified for the real and imaginary parts of the number; this type can be left unspecified either through omission or explicitly via *.
LISP: CONCATENATE
C: concat
min args: 2
max args: -1
[F][CLTL 14]
SYNOPSIS:
concatenate result-type &rest sequences
DESCRIPTION:
The result is a new sequence that contains all the elements of all the sequences in order. All of the sequences are copied from; the result does not share any structure with any of the argument sequences (in this concatenate differs from append). The type of the result is specified by result-type, which must be a subtype of sequence, as for the function coerce. It must be possible for every element of the argument sequences to be an element of a sequence of type result-type.
If only one sequence argument is provided and it has the type specified by result-type, concatenate is required to copy the argument rather than simply returning it. If a copy is not required, but only possible type-conversion, then the coerce function may be appropriate.
LISP: COND
C: SFCCond, ECond
[M][CLTL 7]
SYNOPSIS:
cond { ( test {form}* ) }*
DESCRIPTION:
The cond macro corresponds to the if-then-else if-elseif..else syntax in other programming languages, which permits sequential testing of multiple conditions. These conditions do not need to be strictly disjoint; the conditions are simply evaluated until a matching clause is found, so the form can be thought of as performing a sucession of filtering actions. Hence:
(cond (p ...) if p then ...
(q ...) roughly else if q then ...
(r ...) corresponds else if r then ...
to ...
(t ...)) else ...
A cond form has zero or more clauses, each of which are lists of forms.
Each clause is comprised of a test, followed by zero or more consequent clauses. For example, the following demonstrates a sequence of legal cond clauses:
(cond (test-1 consequent-1-1 consequent-1-2 ...)
(test-2 consequent-2-1 ...)
(test-3)
...)
Each cond clause is evaluated in sequence; cond processes its clauses from left to right in order. For each clause, the test is evaluated.
If the result is nil, the evaluation advances to the next clause. The first time a clause with a test which evaluates to non-nil is encountered, that clause is selected. All other clauses will be ignored.
The consequents of the selected clause are treated as an implicit progn, i.e. they are evaluated in order from left to right. After evaluating the consequents of the selected clause, cond returns without trying any remaining clauses. The return values of a cond form are the results of evaluating the last of the selected consequents. If there were no consequents in the selected clause, then the single value of the test is returned: this will, of course, not be nil. If every test in a cond form produced nil, no clause will be selected. The value of the cond form in this case will be nil.
There are several conventions used when coding cond clauses which experienced LISP programmers follow.
If the intent is to select the last clause unconditionally if all others do not succeed, t is used for the test of the last clause.
It is considered good style to write the last clause
(t nil)
if the value of the cond form is significant.
As a corollary, avoid letting the last clause of a cond be a "singleton clause"; an explicit t should be provided.
Furthermore,
(cond...(x))
may behave differently from
(cond...(t x))
if evaluating after x the form might return multiple values. The first always returns a single value, whereas the second example returns whatever values x returns. However, as a matter of style it is preferable to obtain this behavior by writing:
(cond... (t (values x)))
using the values function explicitly to indicate that any values other than the first can be ignored.
LISP: CONJUGATE
C: Lconjugate
min args: 1
max args: 1
[F][CLTL 12]
SYNOPSIS:
conjugate number
DESCRIPTION:
This returns the complex conjugate of its argument, which must be a number; note that the conjugate of a non-complex number is itself.
LISP: CONS
C: Lcons
min args: 2
max args: 2
[F][CLTL 15]
SYNOPSIS:
cons x y
DESCRIPTION:
cons
is the primitive function to create a new cons whose car is x and whose cdr is y. For example:(cons 'a 'b) => (a . b)
(cons 'a (cons 'b (cons 'c '()))) => (a b c)
(cons 'a '(b c d)) = > (a b c d)
cons
may be thought of as creating a cons, or as adding a new element to the front of a list.See Also:
cons (typespec), consp
LISP: CONS (typespec)
[Typespec][CLTL 4]
SYNOPSIS:
cons
DESCRIPTION:
This is the type specifier symbol which indicates the set of LISP objects which are not atomic and not nil (i.e., all non-empty lists).
See Also:
cons
LISP: CONSP
C: Lconsp
min args: 1
max args: 1
[F][CLTL 6]
SYNOPSIS:
consp object
DESCRIPTION:
The predicate consp is true if its argument is a cons, and otherwise is false. Note that the empty list is not a cons, so:
(consp '()) == (consp 'nil) => nil.
(consp x) == (typep x 'cons) == (not (typep x 'atom))
LISP: CONSTANTP
C: ConstP
min args: 1
max args: 1
[F][CLTL 20]
SYNOPSIS:
constantp object
DESCRIPTION:
The constantp function returns t if the object, when evaluated, always evaluates to the same object; this includes self-evaluating objects such as numbers, characters, strings, bit-vectors and keywords, as well as nil, t and any symbol defined by defconstant and quoted lists. Otherwise constantp returns nil.
LISP: COPY-ALIST
C: Lcopy_alist
min args: 1
max args: 1
[F][CLTL 15]
SYNOPSIS:
copy-alist list
DESCRIPTION:
The copy-alist function is used to copy association lists.
The top level of list structure of list is copied, just as for copy-list. In addition, each element of the list argument that is a cons is replaced in the copy by a new cons with the same car and cdr.
LISP: COPY-LIST
C: Lcopy_list
min args: 1
max args: 1
[F][CLTL 15]
SYNOPSIS:
copy-list list
DESCRIPTION:
The copy-list function copies the top level of a list only. Thus any sublists in the copy will be shared with the original.
copy-list
can be thought of copying in the cdr direction but not in the car direction.If the list is dotted, the returned list will be too.
The copy-list function returns a list that is equal to list, but not eq.
SEE ALSO:
copy-seq, copy-tree
LISP: COPY-READTABLE
C: CpRT
min args: 0
max args: 2
[F][CLTL 22]
SYNOPSIS:
copy-readtable &optional from-readtable to-readtable
DESCRIPTION:
A copy is made of from-readtable, which defaults to the current readtable (the value of the global variable *readtable*). If from-readtable is nil, then a copy of a standard Common LISP readtable is made.
For example:
(setq *readtable* (copy-readtable nil))
will restore the input syntax to standard Common LISP syntax, even if the original readtable has been clobbered (assuming it is not so badly clobbered that you cannot type in the above expression!). On the other hand,
(setq *readtable* (copy-readtable))
will merely replace the current readtable with a copy of itself.
If to-readtable is unsupplied or nil, a fresh copy is made. Otherwise, to-readtable must be a readtable, which is destructively copied into.
LISP: COPY-SEQ
C: Lcopy_seq
min args: 1
max args: 1
[F][CLTL 14]
SYNOPSIS:
copy-seq sequence
DESCRIPTION:
The copy-seq function makes a copy of its argument, which must be a sequence.
The result is equalp but not eq to the original.
NOTE:
The following equivalence holds:
(copy-seq x) == (subseq x 0)
but using the copy-seq is more readable.
LISP: COPY-STRUCTURE
C: Lcpz
min args: 2
max args: 2
[F][SSCL]
DESCRIPTION:
This is a Star Sapphire Common LISP internal function which copies structures for the benefit of defstruct. Calls to this function occur only in defstruct generated code and need not be coded directly.
LISP: COPY-SYMBOL
C: Lcopy_symbol
min args: 1
max args: 2
[F][CLTL 10]
SYNOPSIS:
copy-symbol sym &optional copy-props
DESCRIPTION:
The copy-symbol function returns a new uninterned symbol with the same print name as its argument.
If copy-props is nil (the default), then the new symbol will be unbound and undefined, and its property list will be nil.
If copy-props is non-nil, then the property list of the new symbol will be a copy of sym's and the initial value and function definition of the new symbol will also be the same as those of sym.
LISP: COPY-TREE
C: Lcopy_tree
min args: 1
max args: 1
[F][CLTL 15]
SYNOPSIS:
copy-tree object
DESCRIPTION:
The copy-tree function is used to make complete copies of trees of conses.
All conses in the tree are copied recursively, stopping only when non-conses are encountered.
The argument object may be any LISP object. If it is not a cons, it is returned verbatim; otherwise the result is a new cons of the results of calling copy-tree on the car and cdr of the argument.
Circularities and the sharing of substructure are not preserved.
LISP: COS
C: Lcos
min args: 1
max args: 1
[F][CLTL 12]
SYNOPSIS:
cos radians
DESCRIPTION:
The cos function returns the cosine of the argument. The argument is considered to be expressed in radians.
LISP: COUNT
C: Lcnt
min args: 2
max args: -1
[F][CLTL 14]
SYNOPSIS:
count item sequence &key :from-end :test :test-not :start :end :key
DESCRIPTION:
The count function counts the number of items in sequence which satisfy the test. As usual, the test defaults to (eql item).
For instance:
(count 'down '(1 2 down 3 up 4 sideways down #\meta- x)) => 2
The result is always a non-negative integer, the number of elements in the specified subsequence of sequence satisfying the test.
The :from-end argument does not affect the result returned; it is accepted purely for compatibility with other sequence funtions.
SEE ALSO:
count-if and count-if-not
LISP: COUNT-IF
C: Lcntif
min args: 2
max args: -1
[F][CLTL 14]
SYNOPSIS:
count-if test sequence &key :from-end :start :end :key
DESCRIPTION:
See count.
LISP: COUNT-IF-NOT
C: Lcntifnot
min args: 2
max args: -1
[F][CLTL 14]
SYNOPSIS:
count-if-not test sequence &key :from-end :start :end :key
DESCRIPTION:
See count.
LISP: CURPOS
C: Lcurpos
min args: 2
max args: 2
[F][SSCL][DOS]
SYNOPSIS:
curpos row col
DESCRIPTION:
curpos
is a Star Sapphire specific function which moves the display page 0 cursor to row and col. The return value is always t.SEE ALSO:
cursor
LISP: CURSOR
C: Lcursor
min args: 1
max args: 5
[F][SSCL][DOS]
SYNOPSIS:
cursor message &optional row/start col/end &key :page
DESCRIPTION:
cursor
is a Star Sapphire specific function for controlling the IBM PC cursor position and shape.If message is :getpos, return the row and column of the cursor position as first and second values.
If message is :setpos, move the cursor to row and column and return t.
If message is :getsize return the start and end scan lines as the first and second values.
If message is :setsize set the start and end lines and return t The :page keyword specifies the display page to set or get on, which defaults to 0. This argument is permitted but ignored for :getsize and :setsize.
NOTES:
For the effect of various cursor sizes in specific display contexts, consult an IBM PC reference.