Star Sapphire Common LISP Home

Download Star Saphire
Index

LISP: SBIT

C: Lsbit

min args: 1

max args: -1

[F][CLTL 17]

SYNOPSIS:

sbit simple-bit-array &rest subscripts

DESCRIPTION:

sbit is exactly like aref but requires a simple array of bits, that is, one of type (array bit). The result will always be 0 or 1.

Note that sbit, schar, allows the first argument to be an array of any rank.

setf may be used with sbit to destructively replace a bit-array element with a new value.

sbit is identical to aref except for the more specific type requirements on the first argument.

LISP: SCHAR

C: Lchar

min args: 2

max args: 2

[F][CLTL 18]

SYNOPSIS:

schar simple-string index

DESCRIPTION:

The argument must be a simple string.

The given index must be a non-negative integer less than the length of string, which must be a string. The character at position index of the string is returned as a character object. (This character will necessarily satisfy the predicate string-char-p.) As with all sequences in Common LISP, indexing is zero-origin. For example:

(char "Floob-Boober-Bab-Boober-Bubs" 0) => #/F

(char "Floob-Boober-Bab-Boober-Bubs" 1) => #/l

See aref and elt. In effect,

(char s j) == (aref (the string s) j)

setf may be used with schar to destructively replace a character within a string.

LISP: SECOND

C: Lsecond

min args: 1

max args: 1

[F][CLTL 15]

SYNOPSIS:

second list

DESCRIPTION:

See first.

LISP: SEQUENCE

[Typespec][CLTL 4]

SYNOPSIS:

sequence

DESCRIPTION:

This is the type specifier symbol for the set of all sequences. Sequences are defined to include vectors and lists; this means that the following types are considered to be sequences:

null (i.e., the object nil)

conses

vectors

bit vectors

strings

any one dimensional array

simple-vectors, simple-bit-vectors, simple-strings and

simple-arrays with one dimension

LISP: SET

C: LSymSet

min args: 2

max args: 2

[F][CLTL 7]

SYNOPSIS:

set symbol value

DESCRIPTION:

set allows alteration of the value of a dynamic (special) variable. set causes the dynamic variable named by symbol to take on value as its value. Only the value of the current dynamic binding is altered; if there are no bindings in effect, the most global value is altered. For example,

(set (if (eq a b) 'c 'd) 'foo)

will either set c to foo or set d to foo, depending on the outcome of the test (eq a b).

set returns value as its result.

set cannot alter the value of a local (lexically bound) variable. The special form setq is usually used for altering the values of variables (lexical or dynamic) in programs. set is particularly useful for implementing interpreters for languages embedded in LISP.

LISP: SET-BIT

C: Lsetbit

min args: 1

max args: -1

[F][SSCL]

SYNOPSIS:

set-bit array subscripts value

DESCRIPTION:

This Star Sapphire specific function sets the given bit array at the position specified by subscripts to value.

This is a setf method for bit. The function aset can also be used. The definition for the setf of bit can be found in init0.lsp:

(defsetf bit aset)

LISP: SET-CHAR-BIT

C: Lset_char_bit

min args: 3

max args: 3

[F][CLTL 13]

SYNOPSIS:

set-char-bit char name value

DESCRIPTION:

The bit with the given name (which in this implementation is either :meta or :control) in character char is set if value is non-nil and cleared if value is nil.

NOTES:

set-char-bit has been eliminated in ANSI Common LISP; it will probably not be supported in future Star Sapphire versions.

LISP: SET-DIFFERENCE

C: Lset_difference

min args: 2

max args: -1

[F][CLTL 15]

SYNOPSIS:

set-difference list1 list2 &key :test :test-not :key

DESCRIPTION:

set-difference returns a list of elements of list1 that do not appear in list2. This operation is not destructive.

There is no guarantee that the order of elements in the result will reflect the ordering of the arguments in any particular way. The implementation is therefore free to use any of a variety of strategies. The result list may share cells with, or be eq to, either of the arguments if appropriate.

In general, the test may be any predicate, and the set difference operation may be described as follows. For all possible ordered pairs consisting of one element from list1 and one element from list2, the test is used to determine whether they "match." An element of list1 appears in the result if and only if it does not match any element of list2. This is very general and permits interesting applications. For example, one can remove from a list of strings all those strings containing one of a given list of characters:

;; 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.

nset-difference is the destructive version of set-difference. This operation may destroy list1.

LISP: SET-DISPATCH-MACRO-CHARACTER

C: SetDMC

min args: 3

max args: 4

[F][CLTL 22]

SYNOPSIS:

set-dispatch-macro-character disp-char sub-char function

&optional readtable

DESCRIPTION:

Set-dispatch-macro-character causes function to be called when the disp-char followed by sub-char is read. The readtable defaults to the current readtable.

The arguments and return values for function are the same as for normal macro characters except that function getssub-char, not disp-char, as its second argument and also receives a third argument that is the non-negative integer whose decimal representation appeared between disp-char and sub-char, or nil if no decimal integer appeared there.

The sub-char may not be one of the ten decimal digits; they are always reserved for specifying an infix integer argument. Moreover, if sub-char is a lowercase character (as if by lower-case-p), its uppercase equivalent is used instead. (This is how the rule is enforced that the case of a dispatch sub-character doesn't matter.)

Set-dispatch-macro-character returns t.

An error is signaled if the specified disp-char is not in fact a dispatch character in the specified readtable. It is necessary to use make-dispatch-macro-character to set up the dispatch character before specifying its sub-characters.

SEE ALSO:

get-dispatch-macro-character, make-dispatch-macro-character

LISP: SET-DOCUMENTATION

C: Lsetdocumentation

min args: 3

max args: 3

[F][SSCL]

SYNOPSIS:

set-documentation symbol doc-type value

DESCRIPTION:

This is the Star Sapphire specific setf method for documentation.

The symbol documentation type doc-type is set to the given value, which should be a string.

The following defsetf must be run before this function can be used as a setf method or documentation is used in a setf form:

(defsetf documentation (s d) (v) `(set-documentation ,s ,d ,v))

This defsetf can be found in init0.lsp.

LISP: SET-ELT

C: Lset_elt

min args: 3

max args: 3

[F][SSCL]

SYNOPSIS:

set-elt sequence index item.

DESCRIPTION:

This is the setf method for elt. The sequence value at the offset index is set to item.

The following defsetf must be run before this function can be used as a setf method or elt is used in a setf form:

(defsetf elt set-elt)

This defsetf can be found in init0.lsp.

LISP: SET-EXCLUSIVE-OR

C: Lset_exclusive_or

min args: 2

max args: -1

[F][CLTL 15]

SYNOPSIS:

set-exclusive-or list1 list2 &key :test :test-not :key

DESCRIPTION:

set-exclusive-or returns a list of elements that appear in exactly one of list1 and list2. This operation is not destructive.

There is no guarantee that the order of elements in the result will reflect the ordering of the arguments in any particular way. The implementation is therefore free to use any of a variety of strategies. The result list may share cells with, or be eq to, either of the arguments if appropriate.

In general, the test may be any predicate, and the set-exclusive-or operation may be described as follows. For all possible ordered pairs consisting of one element from list1 and one element from list2, the test is used to determine whether they "match." The result contains precisely those elements of list1 and list2 that appear in no matching pair.

nset-exclusive-or is the destructive version of set-exclusive-or. Both lists may be destroyed in producing the result.

LISP: SET-FILL-POINTER

C: LSetFillPointer

min args: 2

max args: 2

[F][SSCL]

SYNOPSIS:

set-fill-pointer vector new-fill-pointer

DESCRIPTION:

The fill pointer of vector is set to new-fill-pointer. This is the setf method for fill-pointer. The new-fill-pointer argument must be a non-negative, non-bignum integer. The value of new-fill-pointer is returned.

The following defsetf must be run before this function can be used as a setf method or fill-pointer is used in a setf form:

(defsetf fill-pointer set-fill-pointer)

This defsetf can be found in init0.lsp.

LISP: SET-GC-LEVEL

C: Lset_gc_level

min args: 1

max args: 1

[F][SSCL]

SYNOPSIS:

set-gc-level nconses

DESCRIPTION:

This Star Sapphire specific function allows setting the internal garbage collection limit.

nconses argument is the number of conses to allocate before another sweep of cons space. If this is given a very large value (say 9000000), the garbage collector is effectively turned off.

LISP: SET-MACRO-CHARACTER

C: SetMC

min args: 2

max args: 4

[F][CLTL 22]

SYNOPSIS:

set-macro-character char function &optional non-terminating-p readtable

DESCRIPTION:

set-macro-character causes char to be a macro character that when seen by read causes function to be called. If non-terminating-p is not nil, (it defaults to nil), then it will be a non-terminating macro character: it may be embedded within extended tokens. Set-macro-character returns t.

The function is called with two arguments, stream and char. The stream is the input stream, and char is the macro character itself. In the simplest case, function may return a LISP object. This object is taken to be that whose printed representation was the macro character. For example:

(defun single-quote-reader (stream char)

(declare (ignore char))

(list 'quote (read stream t nil t)))

(set-macro-character #\' #'single-quote-reader)

(Note that t is specified for the recursive-p argument to read--see section 22.2.1). The function reads an object following the single-quote and returns a list of the symbol quote and that object. The char argument is ignored.

The function may choose instead to return 'zero' values (for example, by using (values) as the return expression). In this case, the macro character and whatever it may have read contribute nothing to the object being read. As an example, here is a plausible definition for the standard semicolon (comment) character:

(defun semicolon-reader (stream char)

(declare (ignore char))

;; First swallow the rest of the current input line.

;; End-of-file is acceptable for terminating the comment.

(do () ((char= (read-char stream nil #\Newline t) #\Newline)))

;; Return zero values.

(values))

(set-macro-character #\; #'semicolon-reader)

(Note that t is specified for the recursive-p argument to read-char; see section 22.2.1).

The function should not have any side effects other than on the stream. Because of backtracking and restarting of the read operation, front ends (such as editors and rubout handlers to the reader) may cause function to be called repeatedly during the reading of a single expression in which the macro character only appears once.

LISP: SET-MACRO-FUNCTION

C: LSymMSet

min args: 2

max args: 3

[F][SSCL]

SYNOPSIS:

set-macro-function symbol function

DESCRIPTION:

The macro-function for symbol is set to function. This is the Star Sapphire specific setf method for macro-function.

The following defsetf must be run before this function can be used as a setf method or macro-function is used in a setf form:

(defsetf macro-function (s) (v) `(progn (fset ,s (cons 'macro ,v)) ,v))

This defsetf can be found in init0.lsp.

LISP: SET-SBIT

C: Lsetsbit

min args: 1

max args: -1

[F][SSCL]

SYNOPSIS:

set-sbit array subscripts value

DESCRIPTION:

This function sets the given bit array at the position specified by subscripts to value.

This is the Star Sapphire specific setf method for sbit. The function aset can also be used. The definition for the setf of sbit can be found in init0.lsp:

(defsetf sbit aset)

LISP: SET-SLOT-VALUE

C: Lsetslot_value

min args: 3

max args: 3

[F][SSCL][CLOS]

SYNOPSIS:

set-slot-value object slot value

DESCRIPTION:

This is the Star Sapphire specific setf method for class slots. The slot in object is set to value.

.

This is made the setf method of slot-value in clos.lsp using a defsetf form. clos.lsp or its fastload version clos.fsl can optionally be loaded at startup if CLOS functionality is desired.

LISP: SET-SYMBOL-FUNCTION

C: LSymFSet

min args: 2

max args: 2

[F][SSCL]

SYNOPSIS:

set-symbol-function symbol function

DESCRIPTION:

The functional definition for symbol is set to function. This is the Star Sapphire specific setf method for symbol-function.

The following defsetf must be run before this function can be used as a setf method or symbol-function is used in a setf form:

(defsetf symbol-function fset)

This defsetf can be found in init0.lsp.

LISP: SET-SYMBOL-PLIST

C: Lset_symbol_plist

min args: 2

max args: 2

[F][SSCL]

SYNOPSIS:

set-symbol-plist symbol new-property-list

DESCRIPTION:

The property list for symbol is set to new-property-list. This is the Star Saphhire specific setf method for symbol-plist.

The following defsetf must be run before this function can be used as a setf method or symbol-plist is used in a setf form:

(defsetf symbol-plist set-symbol-plist)

This defsetf can be found in init0.lsp.

NOTES:

Replacing the property list of a symbol can lose important information which the system needs to maintain the consistency of the environment. Therefore caution should be exercised in the use of this function.

LISP: SET-SYNTAX-FROM-CHAR

C: SetSyntaxFromChar

min args: 2

max args: 4

[F][CLTL 22]

SYNOPSIS:

set-syntax-from-char to-char from-char &optional to-readtable from-readtable

DESCRIPTION:

This makes the syntax of to-char in to-readtable be the same as the syntax of from-char in from-readtable. The to-readtable defaults to the current readtable (the value of the global variable *readtable*), and from-readtable defaults to nil, meaning to use the syntaxes from the standard Lisp readtable.

To-char and from-char must each be a character.

Only attributes as shown in table 22-1 are copied; moreover, if a macro character is copied, the macro definition function is copied also. However, attributes as shown in table 22-3 are not copied; they are "hard-wired" into the extended-token parser. For example, if the definition of 'S' is copied to '*', then '*' will become a 'constituent' that is 'alphabetic' but cannot be used as an exponent indicator for short-format floating-point number syntax.

It works to copy a macro definition from a character such as " to another character; the standard definition for " looks for another character that is the same as the character that invoked it. It doesn't work to copy the definition of ( to {, for example; it can be done, but it lets one write lists in the form {a b c), not {a b c}, because the definition always looks for a closing parenthesis, not a closing brace. See the function read-delimited-list, which is useful in this connection.

Set-syntax-from-char returns t.

LISP: SET-TRACE-FILE

C: SetTrceFile

min args: 1

max args: 1

[F][SSCL]

SYNOPSIS:

set-trace-file &optional file-name

DESCRIPTION:

This function controls the destination file for output from the trace facility. Normally this is stdout.

With no arguments, the function resets the trace file to stdout. The current trace file is flushed, and subsequently closed. It is not closed if it is stdout or stderr.

With one symbol or string argument, this function opens the file with the given name and writes trace output to the file. Warning: No attempt is made to prompt the user if the file already exists.

NOTES:

This function has largely been superceeded by the dribble facility. Note that output to the trace file is in addition to any open dribble file.

We have retained this because it may be useful if you are doing some hairy trace and don't want the output to go to the screen (since output to a file may be faster).

LISP: SETF

C: N/A

min args: 2

max args: -1

[M][CLTL 7]

SYNOPSIS:

setf [place newvalue]*

DESCRIPTION:

(setf place newvalue) takes a form place that when evaluated accesses a data object in some location and "inverts" it to produce a corresponding form to update the location. A call to the setf macro therefore expands into an update form that stores the result of evaluating the form newvalue into the place referred to by the access-form.

If more than one place-newvalue pair is specified, the pairs are processed sequentially; that is,

(setf place1 newvalue1

place2 newvalue2)

...

placen newvaluen)

is precisely equivalent to

(progn (setf place1 newvalue1)

(setf place2 newvalue2)

...

(setf placen newvaluen))

For consistency, it is legal to write (setf), which simply returns nil. The form place may be any one of the following:

· The name of a variable (either lexical or dynamic).

· A function call form whose first element is the name of any one of the following functions:

aref

caaaar

caaadr

caaar

caadar

caaddr

caadr

caar

cadaar

cadadr

cadar

caddar

cadddr

caddr

cadr

car

cdaaar

cdaadr

cdaar

cdadar

cdaddr

cdadr

cdar

cddaar

cddadr

cddar

cdddar

cddddr

cdddr

cddr

cdr

eighth

elt

fifth

fill-pointer

first

fourth

get

getf

macro-function

ninth

nth

rest

second

seventh

sixth

svref

symbol-function

symbol-plist

symbol-value

tenth

third

· A function call form whose first element is the name of a selector function constructed by defstruct.

· A macro call, in which case setf expands the macro call and then analyzes the resulting form.

setf carefully arranges to preserve the usual left-to-right order in which the various subforms are evaluated.

The ultimate result of evaluating a setf form is the value of newvalue.

NOTES:

The implementation of setf was particularly difficult. The only way in which it can be done correctly is in LISP itself; hence, we have implemented setf in Common LISP; using it requires loading initsetf.fsl.

This file contains fastload definitions for the implementation macros, especially defsetf, without which setf is impossible.

In the product as shipped, initsetf.fsl is loaded in init.lsp. This also loads a few setf methods: specifically, those for aref, get, car and cdr.

Pre-written setf methods for all Common LISP forms which can be defined and used in a setf are provided in init0.lsp.

These definitions can be selectively loaded at startup by appending them to init.lsp. They can also be incorporated into specific source code modules which need them.

However, if you aren't using setf, you can comment out the load of initsetf.fsl and speed your startup time substantially.

LISP: SETF-EXPAND

C: SETF_EXPAND

min args: 1

max args: 1

[F][SSCL]

DESCRIPTION:

This is a routine which is internal to the setf facility.

LISP: SETF-EXPAND-1

C: SETF_EXPAND_1

min args: 2

max args: 2

[F][SSCL]

DESCRIPTION:

This is a routine which is internal to the setf facility.

LISP: SETQ

C: SFCSetq, ESetq

[S][CLTL 7]

SYNOPSIS:

setq {var form}*

DESCRIPTION:

The special form (setq var1 form1 var2 form2 ...) is the "simple variable assignment statement" of LISP. First form1 is evaluated and the result is stored in the variable var1, then form2 is evaluated and the result is var2, and so forth. The variables are represented as symbols, of course, and are interpreted as referring to static or dynamic instances according to the usual rules. Therefore setq may be used for assignment of both lexical and special variables. setq returns the last value assigned, that is, the result of the evaluation of its last argument. As a boundary case, the form (setq) is legal and returns nil. There must be an even number of argument forms. For example, in

(setq x (+ 3 2 1) y (cons x nil))

x is set to 6, y is set to (6), and the setq returns (6). Note that the first assignment is performed before the second form is evaluated, allowing that form to use the new value of x.

SEE ALSO:

The description of setf, the Common LISP "general assignment statement" that is capable of assigning to variables, array elements, and other locations.

LISP: SEVENTH

C: Lseventh

min args: 1

max args: 1

[F][CLTL 15]

SYNOPSIS:

seventh list

DESCRIPTION:

See first.

LISP: SHADOW

C: Shadow

min args: 1

max args: 2

[F][CLTL 11]

SYNOPSIS:

shadow symbols &optional package

DESCRIPTION:

The argument symbols should be a list of symbols, or possibly a single symbol. The print name of each symbol is extracted, and the specified package is searched for a symbol of that name. If such a symbol is present in this package (directly, not by inheritance), then nothing is done. Otherwise, a new symbol is created with this print name, and it is inserted in the package as an internal symbol. The symbol is also placed on the shadowing-symbols list of the package. shadow returns t.

shadow should be used with caution. It changes the state of the package system in such a way that the consistency rules do not hold across the change.

The package argument may be either a package object or a package name.

LISP: SHADOWING-IMPORT

C: ShadImport

min args: 1

max args: 2

[F][CLTL 11]

SYNOPSIS:

shadowing-import symbols &optional package

DESCRIPTION:

This is like import, but it does not signal an error even if the importation of a symbol would shadow some symbol already accessible in the package. In addition to being imported, the symbol is placed on the shadowing-symbols list of package. Shadowing-import returns t.

Shadowing-import should be used with caution. It changes the state of the package system in such a way that the consistency rules do not hold across the change.

The package argument may be either a package object or a package name.

LISP: SHORT-FLOAT

[Typespec][CLTL 4]

SYNOPSIS:

short-float [[low] high]

short-float

DESCRIPTION:

This is the type specifier symbol which indicates the set of short floating point numbers. Objects of this type are a subtype of the type float.

This specifier can occur either as a symbol or at the head of a type specifier list. In the latter case, optional low and high values can be specified. The low and high values can be specified as

· A floating point number, indicating an inclusive limit

· A list of exactly one floating point number, indicating an exclusive limit

or left unspecified either explicitly by writing * or by omission. If the limit is unspecified it is considered to be negative or positive infinity, for the low and high values respectively.

NOTES:

In this implementaion, there is only one size of floating point number, so use of short-float is equivalent to the use of float.

LISP: SHORT-SITE-NAME

min args: 0

max args: 0

[F][CLTL 25]

SYNOPSIS:

short-site-name

DESCRIPTION:

A string is returned that briefly identifies the physical location of the computer hardware.

SEE ALSO:

long-site-name

NOTES:

This function is defined in init0.lsp.

LISP: SIGNED-BYTE

[Typespec][CLTL 4]

SYNOPSIS:

signed-byte

signed-byte [nbits]

DESCRIPTION:

This type specifier is used either as a symbol or at the car of a type specifier list.

When used as a type specifier symbol, signed-byte simply means the same set of numbers as integer.

When used in a type specifier list can optionally indicate the set of two's complement integers which can be represented in a byte of nbits bits. This is equivalent to

'(integer (- (expt -2 (- nbits 1)))(- (expt 2 (- nbits 1)) 1))

nbits must be a non-negative integer.

nbits may be unspecified either by being written as * or by omission; in this case the type specifier list indicates all integers.

EXAMPLES:

(typep 2 '(signed-byte 8)) => t

(typep #x10 '(signed-byte 8)) => nil

(typep #x10 '(signed-byte 9)) => t

(typep 300 '(signed-byte *)) => t

(typep 402 '(signed-byte)) => t

(typep -1 'signed-byte) => t

SEE ALSO:

unsigned-byte

LISP: SIGNUM

min args: 1

max args: 1

[F][CLTL 12]

SYNOPSIS:

signum number

DESCRIPTION:

For a rational number, signum returns -1 if the number is negative, zero if it is zero, and 1 if it is positive. If number is floating-point then the floating point number of the same format with the same value -1.0, 0,0 or 1.0 is returned.

This function is defined in init0.lsp and must be included in your source before it is available.

LISP: SIMPLE-ARRAY

min args: 0

max args: 2

[Typespec]

SYNOPSIS:

simple-array [element-type [dimspec]]

simple-array

DESCRIPTION:

This type specifier can be used either by itself as a symbol or at the head of a type specifier list to indicate a simple array.

In this implemenation a simple array is one which does not have a fill pointer. All arrays which are written as data objects explicitly (such as #*10101, #2a((1 2)(3 5)), or "hello") are always simple. The only arrays which have fill pointers are those which are created by make-array with an explicit non-nil :fill-pointer argument.

When used at the car of a type specifier list, simple-array represents the set of simple arrays with elements of element-type and dimensions matching dimspec.

In this case either argument may be unspecified, either by omission or by being written *.

The element-type, if specified, must be a typespec.

The dimspec, if specified, may either be a non-negative integer or a list of non-negative integers. A single integer indicates a one-dimensional array of the given length. A list of integers specifies the length of each dimension. A given dimension may be written as unspecified using *.

SEE ALSO:

array

LISP: SIMPLE-BASE-STRING

min args:

max args:

[Typespec][CLTL2 4]

SYNOPSIS:

simple-base-string [size]

simple-base-string

DESCRIPTION:

This type specifier can be used either by itself or at the head of a type specifier list.

This is the type specifier which indicates the set of data objects which are simple strings of the indicated size which can contain objects of type base-character:

simple-base-string == (simple-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 simple-string type specifier.

This is a new type specifier introduced by ANSI.

LISP: SIMPLE-BIT-VECTOR

min args: 0

max args: 1

[Typespec][CLTL 4]

SYNOPSIS:

simple-bit-vector [size]

simple-bit-vector

DESCRIPTION:

This is the type specifier which represents simple-bit-vectors. Simple-bit-vectors are one dimensional arrays which are specialized to contain only the numbers 1 and 0 and have no fill pointer.

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 *.

SEE ALSO:

simple-array, bit-vector, simple-bit-vector-p

LISP: SIMPLE-BIT-VECTOR-P

C: Lsimple_bit_vector_p

min args: 1

max args: 1

[F][CLTL 6]

SYNOPSIS:

simple-bit-vector-p object

DESCRIPTION:

simple-bit-vector-p is true if its argument is a simple-bit-vector, and otherwise is false.

(simple-bit-vector-p x) == (typep x 'simple-bit-vector)

LISP: SIMPLE-STRING

min args: 0

max args: 1

[Typespec][CLTL 4]

SYNOPSIS:

simple-string [size]

simple-string

DESCRIPTION:

This is the type specifier which represents simple-strings. Simple-strings are one dimensional arrays which are specialized to contain only characters and have no fill pointer.

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 string can be specified. The size can be unspecified either by omission or *.

SEE ALSO:

simple-array, simple-string-p, string

LISP: SIMPLE-STRING-P

C: Lsimple_string_p

min args: 1

max args: 1

[F][CLTL 6]

SYNOPSIS:

simple-string-p object

DESCRIPTION:

simple-string-p is true if its argument is a simple string, and otherwise is false.

(simple-string-p x) == (typep x 'simple-string)

LISP: SIMPLE-VECTOR

min args: 0

max args: 1

[Typespec][CLTL 4]

SYNOPSIS:

simple-vector [size]

simple-vector

DESCRIPTION:

This is the type specifier which represents simple-vectors. Simple-vectors are one dimensional arrays which have no fill pointer.

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 vector can be specified. The size can be unspecified either by omission or *.

SEE ALSO:

simple-array, simple-vector-p, vector

LISP: SIMPLE-VECTOR-P

C: Lsimple_vector_p

min args: 1

max args: 1

[F][CLTL 6]

SYNOPSIS:

simple-vector-p object

DESCRIPTION:

simple-vector-p is true if its argument is a simple general vector, and otherwise is false.

(simple-vector-p x) == (typep x 'simple-vector)

LISP: SIN

C: Lsin

min args: 1

max args: 1

[F][CLTL 12]

SYNOPSIS:

sin radians

DESCRIPTION:

sin returns the sine of the argument. The argument is in radians.

LISP: SINGLE-FLOAT

[Typespec][CLTL 4]

SYNOPSIS:

single-float [[low] high]

single-float

DESCRIPTION:

This is the type specifier symbol which indicates the set of single precision floating point numbers. Objects of this type are a subtype This specifier can occur either as a symbol or at the head of a type specifier list. In the latter case, optional low and high values can be specified. The low and high values can be specified as

· A floating point number, indicating an inclusive limit

· A list of exactly one floating point number, indicating an exclusive limit

or left unspecified either explicitly by writing * or by omission. If the limit is unspecified it is considered to be negative or positive infinity, for the low and high values respectively.

NOTES:

In this implementaion, there is only one size of floating point number, so use of single-float is equivalent to the use of float.

LISP: SIXTH

C: Lsixth

min args: 1

max args: 1

[F][CLTL 15]

SYNOPSIS:

sixth list

DESCRIPTION:

See first.

LISP: SLOT-BOUNDP

C: Lslotboundp

min args: 2

max args: 2

[F][CLOS]

SYNOPSIS:

slot-boundp instance slot-name

DESCRIPTION:

The function slot-boundp tests whether a specific slot in an instance is bound. The arguments are the instance and the name of the slot. The function slot-boundp returns t if the slot-name in instance is bound, and nil otherwise.

LISP: SLOT-EXISTS-P

C: LSlotExistsP

min args: 2

max args: 2

[F][CLOS]

SYNOPSIS:

slot-exists-p object slot-name

DESCRIPTION:

The function slot-exists-p tests whether the specified object has a slot of the given name.

The object argument is any object; the slot-name argument is a symbol.

The function slot-exists-p returns t if the specified object has a slot named slot-name and nil otherwise.

LISP: SLOT-MAKUNBOUND

C: LSlotMUB

min args: 2

max args: 2

[F][CLOS]

SYNOPSIS:

slot-makunbound instance slot-name

DESCRIPTION:

The function slot-makunbound restores a slot in an instance to an unbound state. The arguments to slot-makunbound are the instance and the name of the slot. instance is returned as the result.

If no slot of the given name exists in instance, an error is raised.

LISP: SLOT-VALUE

C: Lslot_value

min args: 2

max args: 2

[F][CLOS]

SYNOPSIS:

slot-value object slot-name

DESCRIPTION:

The function slot-value returns the value contained in the slot named slot-name of the given object. If there is no slot with that name, or the slot is unbound, an error is raised.

The macro setf can be used with slot-value to change the value of a slot; to do so the following defsetf must be run:

(defsetf slot-value set-slot-value)

The arguments are the object and the name of the given slot. The result is the value contained in the given slot.

LISP: SOFTWARE-TYPE

min args: 0

max args: 0

[F][CLTL 25]

SYNOPSIS:

software-type

DESCRIPTION:

A string is returned that identifies the generic name of any relevant supporting software.

NOTES:

This function is defined in init0.lsp.

LISP: SOFTWARE-VERSION

min args: 0

max args: 0

[F][CLTL 25]

SYNOPSIS:

software-version

DESCRIPTION:

A string is returned that identifies the version of any relevant supporting software; this information should be of use to maintainers of the implementation.

NOTES:

This function is defined in init0.lsp.

LISP: SOME

C: Lsome

min args: 2

max args: -1

[F][CLTL 14]

SYNOPSIS:

some predicate sequence &rest more-sequences

DESCRIPTION:

This function is a predicate. The predicate must take as many arguments as there are sequences provided. The predicate is first applied to the elements with index 1, and so on, until a termination criterion is met or the end of the shortest of the sequences is reached.

If the predicate has side effects, it can count on being called first on all the elements numbered 0, then on all those numbered 1, and so on.

some returns as soon as any invocation of predicate returns a non-nil value. Thus, considered as a predicate, it is true if every invocation of predicate is true.

LISP: SORT

C: Lsort

min args: 2

max args: -1

[F][CLTL 14]

SYNOPSIS:

sort sequence predicate &key :key

DESCRIPTION:

The sequence is destructively sorted according to an order determined by the predicate. The predicate should take two arguments, and return non-nil if and only if the first argument is strictly less than the second (in some appropriate sense), then the predicate should return nil.

The sort function determines the relationship between two elements by giving keys extracted from the elements to the predicate. The :key argument, when applied to an element, should return the key for that element. The :key argument defaults to the identity function, thereby making the element itself be the key.

The :key function should not have any side effects. A useful example of a :key function would be a component selector function for a defstruct structure, used in sorting sequence of strucures.

(sort a p :key s) = (sort a #'(lambda (x y) (p (s x) (s y))))

While the above two expressions are equivalent, the first may be more efficient in some implementations for certain types or arguments. For example, an implementation may choose to apply s to each item just once, putting the resulting keys into a separate table, and then sort the parallel tables, as opposed to applying s to an item every time just before applying the predicate.

If the :key and predicate functions always return, then the sorting operation will always terminate, producing a sequence containing the same elements as the original sequence (that is, the result is a permutation of sequence). This is guaranteed even if the predicate does not really consistently represent a total order (in which case the elements will be scrambled in some unpredictable way, but no element will be lost). If the :key function consistently returns meaningful keys, and the predicate does reflect some total ordering criterion on those keys, then the elements of the result sequence will be properly sorted according to that ordering.

The sorting operation performed by sort is not guaranteed stable. Elements considered equal by the predicate may or may not stay in their original order. (The (predicate x y) and (funcall predicate y x) are both false.)

The sorting operation may be destructive in all cases. In the case of an array argument, this is accomplished by permuting the elements in place. In the case of a list, the list is destructively reordered in the same manner as for nreverse. Thus if the argument should not be destroyed, the user must sort a copy of the argument.

Should execution of the :key function or the predicate cause an error, the state of the list or array being sorted is undefined. However, if the error is corrected, the sort will, of course, proceed correctly.

An example:

(setq foovector (sort foovector #'string-lessp :key #'car))

If foovector contained these items before the sort

("Tokens" "The Lion Sleeps Tonight")

("Carpenters" "Close To You")

("Rolling Stones" "Brown Sugar")

("Beach Boys" "I Get Around")

("Mozart" "Eine Kleine Nachtmusik" (K 525))

("Beatles" "I Want to Hold Your Hand")

then after the sort foovector would contain

("Beach Boys" "I Get Around")

("Beatles" "I Want to Hold Your Hand")

("Carpenters" "Close to You")

("Mozart" "Eine Kleine Nachtmusik" (K 525))

("Rolling Stones" "Brown Sugar")

("Tokens" "The Lion Sleeps Tonight")

 

NOTES:

Note that since sorting requires many comparisons, and thus many calls to the predicate, sorting will be faster if the predicate is a runtime function rather than a defun.

Since the sort algorithm must access a given pair of elements to compare them, sorting sequences which are arrays will be considerably faster than sorting lists.

We used heapsort to implement sort because it gets performance equivalent to or better than the more usual quicksort. However, quicksort requires an auxiliary array. This would become a bottleneck due to being stored in virtual memory. Also heapsort does not thrash on worst case (already sorted) data.

The heapsort algorithm is from Numerical Methods in C, page 247.

 

LISP: SPECIAL-FORM-P

min args: 1

max args: 1

[F][CLTL 7]

SYNOPSIS:

special-form-p symbol

DESCRIPTION:

The function special-form-p takes a symbol. If the symbol globally names a special form, then a non-nil value is returned; otherwise nil is returned. A returned non-nil value is typically a function of implementation-dependent nature that can be used to interpret (evaluate) the special form.

 

LISP: SQRT

C: Lsqrt

min args: 1

max args: 1

[F][CLTL 12]

SYNOPSIS:

sqrt number

DESCRIPTION:

Returns the principal square root of number. The argument may be any non-negative, non-bignum number; the return value is a float.

(sqrt 9.0) => 3.0

 

LISP: STANDARD-CHAR

[Typespec][CLTL 4]

SYNOPSIS:

standard-char

DESCRIPTION:

This is a type specifier symbol which indicates the set of standard characters.

SEE ALSO:

standard character set.

 

LISP: STANDARD-CHAR-P

C: LStdCharP

min args: 1

max args: 1

[F][CLTL 13]

SYNOPSIS:

standard-char-p char

DESCRIPTION:

The argument char must be a character object. standard-char-p is true if the argument is a "standard character," that is, an object of type standard-char.

SEE ALSO:

standard character set.

 

LISP: *STANDARD-AUX*

[V][SSCL]

SYNOPSIS:

*standard-aux*

DESCRIPTION:

This Star Sapphire specific stream is opened at startup to access the C file stdaux which normally gets mapped to the DOS serial port device.

 

LISP: *STANDARD-INPUT*

[V][CLTL 21]

SYNOPSIS:

*standard-input*

DESCRIPTION:

In the normal LISP top-level loop, input is read from *standard-input* (that is, whatever stream is the value of the global variable *standard input*). Many input functions, including read and read-char, take a stream argument that defaults to *standard-input*.

 

LISP: *STANDARD-OUTPUT*

[V][CLTL 21]

SYNOPSIS:

*standard-output*

DESCRIPTION:

In the normal LISP top-level loop, output is sent to *standard-output* (that is, whatever stream is the value of the global variable *standard output*). Many output functions, including print and write-char, take a stream argument that defaults to *standard-output*.

 

LISP: STEP

C: L_Step

min args: 1

max args: 1

[F][CLTL 25]

SYNOPSIS:

step form

DESCRIPTION:

You can get a step by step view of what your LISP program is doing using the step command. The step command allows you to single step through execution of a form, as well as examine the contents and state of the LISP stack at any time.

You must give step a form to single-step. For example, try

LISP: (step '(factorial 20))

This will put you into the stepper. Every time you press enter, you will view another step of the evaluation of your form. This section assumes that you are in LISP and have entered this form. Due to the highly interactive nature of the stepper and the many features, the best way to learn is to experiment.

Most step options consist of one letter which you type. The option takes effect when you press return. The evaluation is 'frozen' for the duration of the stepper commands which allow you to examine the stack - the trace will not advance until you press return with no command again.

To get a list of stepper options, type a question mark and press enter at the stepper prompt. You will see a usage message:

step USAGE

<Enter> one step

b print brief backtrace

B print verbose backtrace

e E run editor

# print number of frames

l describe a lexical variable

L set a lexical variable

n[num] descend [num] functions (default 1)

N[num] descend [num] frames (default 1)

p[num] ascend [num] functions (default 1)

P[num] ascend [num] frames (default 1)

r R resume evaluation without stepper

s print bottom function

S > print bottom frame

t print top function

T < print top frame

v describe a global variable

V set a global variable

q Q x X quit stepper

! run system command

? print help

Note that when you are using step, you are not talking to LISP, but to a sub-system which only understands these one letter commands. Any unrecognized command will simply advance the trace by one step.

The first action you may wish to take is to determine how you got to a particular place in the evaluation. The most useful stepper command is backtrace. You can give the 'b' or 'B' commands to the stepper obtain a backtrace. Every function call preserves the address of the previous function. By walking down this chain of links, the stepper can print out the contents of the stack from top to bottom.

To simply get the names of the functions, use the 'b' command. The output will look like this:

1- <- FACTORIAL <- * <- FACTORIAL <- STEP <-

This indicates that you are currently calling the function -1, which was called from factorial, which was called from multiply, and so on down to the bottom of the stack, the step command.

To get a full listing of each frame from top to bottom, use the 'B' command:

==== 1- ====

1 argument 1 return value

argument 0: 4

value 0: 4

==== FACT ====

0 arguments 0 return values

==== * ====

0 arguments 0 return values

==== BLOCK ====

2 arguments 0 return values

argument 0: #<JMP_BUF 81e2 81e4 81e6 81e8 81ea 81ec 81ee 81f0 81f2 >

argument 1: FACT

==== FACT ====

1 argument 1 return value

argument 0: 5

value 0: #<0x15e6:0x5489>

==== STEP ====

1 argument 1 return value

argument 0: (FACT 5)

value 0: #<0x15d6:0x5489>

This produces a full listing of each 'stack frame'. A stack frame contains all the information about a given function call. This output gives a complete listing of this information.

First, the name of the function is given enclosed in ====== signs. Then the number of arguments (inputs) to each function, and the number of return values (outputs) are given. Note that at a given point in time, both of these can be zero, as all arguments to a function are evaluated before the function is called. In the meantime the stackframe will be empty. Then all of the arguments and return values are listed by number. Note that some of the return values at a given point in time may contain garbage since a return value has not been established yet or they contain physical pointers. Garbage values are printed out as #<C hex number:C hex number>.

Sometimes the backtrace will scroll past too quickly, or you want to look at a particular stack frame in isolation.

You can look at the stack snapshot one frame at a time using the 'N' and 'P' commands. 'P' moves down to previous frames, and 'N' moves up. To move to the top stack frame, you can type '< 'or T': to move to the bottom stack frame (which will be step) you can type '>' or 'S'.

The 'N' and 'P' commands take an optional numeric argument which is the number of stack frames to move up or down.

To just print the function name rather than the stack frame contents, use the lower case version of the command.

To invoke the editor inside the stepper, use the 'e' command. LISP will prompt you for the name of a file to edit.

You can view or change the value of any global variable using the 'v' and 'V' commands respectively. The 'l' and 'L' commands do the same thing for lexical variables.

In the first case you will be prompted for a symbol name; this is read in verbatim without any error checking, so be sure you type an actual symbol name. Press enter on an empty line to cancel the command.

In the second case you will be prompted for a frame and an offset; in both cases you must enter an unsigned integer (or an empty string to cancel). The frame is the number of lexical boundaries relative to the current frame; the offset is the offset in the given frame; see lexvar for a more detailed explanation.

The 'v', 'V', 'l', and 'L' commands will then print the current value of the variable you have specified.

If you have chosen the 'V' or 'L' commands, you will also be prompted for a value to set the variable to; this value is read without being evaluated. Again to cancel, press enter on an empty line.

To exit the stepper, you can resume the execution of the current form by typing 'r' or 'R'. If you want to stop altogether and return to the top level without finishing the execution of the current form, type 'x', 'X', 'q' or 'Q'. Ctrl-Break has the same effect.

NOTES:

Star Sapphire step is implemented as a function; the language specifies that step is a macro. Hence you must quote the arguments to this function whereas in other implementations you do not.

LISP: STREAM

[Typespec][CLTL 4]

SYNOPSIS:

stream

DESCRIPTION:

This is the type specifier symbol which represents the set of all stream objects.

 

LISP: STREAMP

C: Lstreamp

min args: 1

max args: 1

[F][CLTL 21]

SYNOPSIS:

streamp object

DESCRIPTION:

This is a predicate which is true if its argument, which can be any LISP object, is a stream object, and false otherwise.

 

LISP: STRING

C: Lstring

min args: 1

max args: 1

[F][CLTL 18]

SYNOPSIS:

string x

DESCRIPTION:

Most of the string functions effectively apply string to such of their arguments as are supposed to be strings. If x is a string, it is returned. If x is a symbol, its print name is returned. If x is a string character (a character of type string-char), then a string containing that one character is returned. In any other situation, an error is signaled.

To convert a sequence of characters to a string, use coerce. (Note that (coerce x 'string) will not succeed if x is a symbol. Conversely, string will not convert a list or other sequence to be a string.)

To get the string representation of a number or any other LISP object, use prin1-to-string, princ-to-string, or format.

See Also:

string (typespec)

 

LISP: STRING (typespec)

min args: 0

max args: 1

[Typespec][CLTL 4]

SYNOPSIS:

string [size]

string

DESCRIPTION:

This is the type specifier which represents strings. Strings are one dimensional arrays which are specialized to contain only characters.

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 string can be specified. The size can be unspecified either by omission or *.

SEE ALSO:

simple-array, simple-string-p, string

LISP: STRING-CAPITALIZE

C: Lcastring

min args: 1

max args: -1

[F][CLTL 18]

SYNOPSIS:

string-capitalize string &key :start :end

DESCRIPTION:

string-capitalize produces a copy of string such that, for every word in the copy, the first character of the word, if case-modifiable, is uppercase and any other case-modifiable characters in the word are lower-case. For the purposes of string-capitalize, a word is defined to be a consecutive subsequence consisting of alphanumeric characters or digits, delimited at each end either by a non-alphanumeric character or by an end of the string.

The keyword arguments :start and :end delimit the portion of the string to be affected. The result is always of the same length as string, however.

The argument is not destroyed. However, if no characters in the argument require conversion, the result may be either the argument or a copy of it, at the implementation's discretion.

For example:

(string-capitalize " hello ") => " Hello "

(string-capitalize

"occ1UDed 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"

LISP: STRING-CHAR-P

C: LStrCharP

min args: 1

max args: 1

[F][CLTL 13]

SYNOPSIS:

string-char-p char

DESCRIPTION:

The argument char must be a character object. string-char-p is true if char can be stored into a string, and otherwise is false. Any character that satisfies standard-char-p also satisfies string-char-p; others may also.

LISP: STRING-DOWNCASE

C: Ldnstring

min args: 1

max args: -1

[F][CLTL 18]

SYNOPSIS:

string-downcase string &key :start :end

DESCRIPTION:

string-downcase converts uppercase characters in string to lower-case characters.

The keyword arguments :start and :end delimit the portion of the string to be affected. The result is always of the same length as string, however.

The argument is not destroyed. However, if no characters in the argument require conversion, the result may be either the argument or a copy of it, at the implementation's discretion. For example:

(string-downcase "Dr. Livingston, I presume?")

=> "dr. livingston, i presume?"

LISP: STRING-EQUAL

C: Leqistring

min args: 2

max args: -1

[F][CLTL 18]

SYNOPSIS:

string-equal string1 string2 &key :start1 :end1 :start2 :end2

DESCRIPTION:

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. For example:

(string-equal "foo" "Foo")

is true

LISP: STRING-GREATERP

C: Lgtistring

min args: 2

max args: -1

[F][CLTL 18]

SYNOPSIS:

string-greaterp string1 string2 &key :start1 :end1 :start2 :end2

DESCRIPTION:

string-greaterp is just like string> except that differences in case are ignored.

LISP: STRING-LEFT-TRIM

C: Ll_string_trim

min args: 2

max args: 2

[F][CLTL 18]

SYNOPSIS:

string-left-trim character-bag string

DESCRIPTION:

This function returns a substring of its string argument, with all the characters in character-bag, which may be any sequence containing characters, stripped off the beginning. If no characters in character-bag are contained in the string, then the string is returned unmodified.

SEE ALSO:

string-right-trim, string-trim

LISP: STRING-LESSP

C: Lltistring

min args: 2

max args: -1

[F][CLTL 18]

SYNOPSIS:

string-lessp string1 string2 &key :start1 :end1 :start2 :end2

DESCRIPTION:

string-lessp is just like string< except that differences in case are ignored.

LISP: STRING-NOT-EQUAL

C: Lneistring

min args: 2

max args: -1

[F][CLTL 18]

SYNOPSIS:

string-not-equal string1 string2 &key :start1 :end1 :start2 :end2

DESCRIPTION:

string-not-equal is just like string\= except that differences in case are ignored.

LISP: STRING-NOT-GREATERP

C: Lleistring

min args: 2

max args: -1

[F][CLTL 18]

SYNOPSIS:

string-not-greaterp string1 string2 &key :start1 :end1 :start2 :end2

DESCRIPTION:

string-not-greaterp is just like string<= except that differences in case are ignored.

LISP: STRING-NOT-LESSP

C: Lgeistring

min args: 2

max args: -1

[F][CLTL 18]

SYNOPSIS:

string-not-lessp string1 string2 &key :start1 :end1 :start2 :end2

DESCRIPTION:

string-not-lessp is just like string>= except that differences in case are ignored.

LISP: STRING-RIGHT-TRIM

C: Lr_string_trim

min args: 2

max args: 2

[F][CLTL 18]

SYNOPSIS:

string-right-trim character-bag string

DESCRIPTION:

This function returns a substring of its string argument, with all the characters in character-bag, which may be any sequence containing characters, stripped off the end. If no characters in character-bag are contained in the string, then the string is returned unmodified.

SEE ALSO:

string-trim, string-left-trim

LISP: STRING-TO-LIST

C: Lstr2ls

min args: 1

max args: 1

[F][CLTL 18]

SYNOPSIS:

string-to-list string

DESCRIPTION:

This is a Star Sapphire specific function which takes a string argument and converts it into a list where each space separated substring becomes a symbol. The list is returned.

The intent of this function is to provide a rapid way to convert text typed by the user into lists.

This is done by copying the string into a buffer in physical memory surrounded by parentheses and then feeding that string to the reader. Space in this context is defined as any sequence of spaces, tabs or newlines. The symbols in the string are interned in the user package.

NOTES:

The maximum length of the string to parse is limited to 253 characters (256 less one character for a null character, two for the parends). Any additional characters will be silently flushed and not incorporated into the parsed list contents.

LISP: STRING-TRIM

C: Lstring_trim

min args: 2

max args: 2

[F][CLTL 18]

SYNOPSIS:

string-trim character-bag string

DESCRIPTION:

This function returns a substring of its string argument, with all the characters in character-bag, which may be any sequence containing characters, stripped off the beginning and end. If no characters in character-bag are contained in the string, then string is returned unmodified.

SEE ALSO:

string-right-trim, string-left-trim

LISP: STRING-UPCASE

C: Lupstring

min args: 1

max args: -1

[F][CLTL 18]

SYNOPSIS:

string-upcase string &key :start :end

DESCRIPTION:

string-upcase returns a string just like string with all lower-case 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 correspondent character of string.

The keyword arguments :start and :end delimit the portion of the string to be affected. The result is always of the same length as string, however.

The argument is not destroyed. However, if no characters in the argument require conversion, the result may be either the argument or a copy of it, at the implementation's discretion.

For example:

(string-upcase "Dr. Livingston, I presume?")

=> "DR. LIVINGSTON, I PRESUME?

LISP: STRING/=

C: Lnestring

min args: 2

max args: -1

[F][CLTL 18]

SYNOPSIS:

string/= string1 string2 &key :start1 :end1 :start2 :end2

DESCRIPTION:

See string=.

LISP: STRING<

C: Lltstring

min args: 2

max args: -1

[F][CLTL 18]

SYNOPSIS:

string< string1 string2 &key :start1 :end1 :start2 :end2

DESCRIPTION:

See string=.

LISP: STRING<=

C: Llestring

min args: 2

max args: -1

[F][CLTL 18]

SYNOPSIS:

string<= string1 string2 &key :start1 :end1 :start2 :end2

DESCRIPTION:

See string=.

 

LISP: STRING=

C: Leqstring

min args: 2

max args: -1

[F][CLTL 18]

SYNOPSIS:

string= string1 string2 &key :start1 :end1 :start2 :end2

DESCRIPTION:

The string comparison functions compare the two string arguments lexicographically, and the result is nil unless string1 is respectively less than, greater than, less or equal to, greater than or equal to, or not equal to string2. If the condition is satisfied, however, then the result is the index within the strings of the first character position at which the strings fail to match; put another way, the result is the length of the longest common prefix of the strings.

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 the function char<, or if string a is a proper prefix of string b (of shorter length and matching in all the characters of a). The keyword arguments :start1 and :start2 are places in the strings to start the comparison. The keyword arguments :end1 and :end2 are the places in the strings to stop comparing; comparison stops just before the position specified by a limit. The start arguments default to zero (beginning of string), and the "end arguments (if either omitted or nil) default to the lengths of the strings (end of string), so that by default the entirety of each string is examined. These arguments are provided so that substrings can be compared efficiently. The index returned in case of a mismatch is an index into string1.

 

LISP: STRING>

C: Lgtstring

min args: 2

max args: -1

[F][CLTL 18]

SYNOPSIS:

string> string1 string2 &key :start1 :end1 :start2 :end2

DESCRIPTION:

See string=.

 

LISP: STRING>=

C: Lgestring

min args: 2

max args: -1

[F][CLTL 18]

SYNOPSIS:

string>= string1 string2 &key :start1 :end1 :start2 :end2

DESCRIPTION:

See string=.

 

LISP: STRINGP

C: Lstringp

min args: 1

max args: 1

[F][CLTL 18]

SYNOPSIS:

stringp object

DESCRIPTION:

stringp is true if its argument is a string, and otherwise is false.

(stringp x) == (typep x 'string)

 

LISP: STRUCTURE-NAME

C: Lzname

min args: 1

max args: 1

[F][SSCL]

DESCRIPTION:

This is a function which is internal to the defstruct facility.

 

LISP: STRUCTURE-REF

C: Lzref

min args: 3

max args: 3

[F][SSCL]

DESCRIPTION:

This is a function which is internal to the defstruct facility.

 

LISP: STRUCTURE-SET

C: Lzset

min args: 4

max args: 4

[F][SSCL]

DESCRIPTION:

This is a function which is internal to the defstruct facility.

 

LISP: STRUCTUREP

C: Lzp

min args: 1

max args: 1

[F][SSCL]

DESCRIPTION:

This is a function which is internal to the defstruct facility.

 

LISP: SUBLIS

C: Lsublis

min args: 2

max args: -1

[F][CLTL 15]

SYNOPSIS:

sublis alist tree &key :test :test-not :key

DESCRIPTION:

sublis makes substitutions for objects in a tree (a structure of conses). The first argument to sublis is an association list. The second argument is the tree in which substitutions are to be made, as for subst. sublis looks at all subtrees and leaves of tree; if a subtree or leaf appears as a key in the association list (that is, the key and the subtree or leaf satisfy the test), it is replaced by the object it is associated with. This operation is non-destructive. In effect, sublis can perform several subst operations simultaneously. For example:

(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))

 

LISP: SUBSEQ

C: Lsubseq

min args: 2

max args: 3

[F][CLTL 14]

SYNOPSIS:

subseq sequence start &optional end

DESCRIPTION:

This returns the subsequence of sequence specified by start and end. 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 the argument sequence.

setf may be used with subseq to destructively replace a subsequence with a sequence of new values.

SEE ALSO

replace.

 

LISP: SUBSETP

C: Lsubsetp

min args: 2

max args: -1

[F][CLTL 15]

SYNOPSIS:

subsetp list1 list2 &key :test :test-not :key

DESCRIPTION:

subsetp is a predicate that is true if every element of list1 appears in ("matches" some element of) list2, and false otherwise.

 

LISP: SUBST

C: Lsubst

min args: 3

max args: -1

[F][CLTL 15]

SYNOPSIS:

subst new old tree &key :test :test-not :key

DESCRIPTION:

(subst new old tree) 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. It returns the modified copy of tree. The original tree is unchanged, but the result may share with parts of the argument tree.

Compatibility note: In MACLISP, subst is guaranteed not to share with the tree argument, and the idiom (subst nil nil x) was used to copy a tree x. In Common LISP, the function copy-tree should be used to copy a tree, as the subst idiom will not work.

For example:

(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))

This function is not destructive; that is, it does not change the car or cdr of any already existing list structure.

SEE ALSO:

substitute, which substitutes for top-level elements of a sequence.

 

LISP: SUBST-IF

C: Lif_subst

min args: 3

max args: -1

[F][CLTL 15]

SYNOPSIS:

subst-if new test tree &key :key

DESCRIPTION:

See subst

 

LISP: SUBST-IF-NOT

C: Lifn_subst

min args: 3

max args: -1

[F][CLTL 15]

SYNOPSIS:

subst-if-not new test tree &key :key

DESCRIPTION:

See subst.

 

LISP: SVREF

C: Lsvref

min args: 2

max args: 2

[F][CLTL 17]

SYNOPSIS:

svref simple-vector index

DESCRIPTION:

svref is identical to aref except that it requires its first argument to be a simple vector.

The first argument must be a simple general vector, that is, an object of type simple-vector. The element of the simple-vector specified by the integer index is returned. The index must be non-negative and less than the length of the vector.

setf may be used with svref to destructively replace a simple-vector element with a new value.

 

LISP: SVSET

C: Lsvset

min args: 3

max args: 3

[F][CLTL 17]

SYNOPSIS:

svset simple-vector index item

DESCRIPTION:

This is the setf method for svref. The item is set at index in simple-vector. The usual checking on the type of item 'and range of index' apply.

 

LISP: SYMBOL-FUNCTION

C: LSymFun

min args: 1

max args: 1

[F][CLTL 7]

SYNOPSIS:

symbol-function symbol

DESCRIPTION:

symbol-function returns the current global function definition named by symbol. An error is signalled if the symbol has no function definition; see fboundp. Note that the definition may be a function or may be an object representing a special form or marco. In the latter case, however, it is an error to attempt to invoke the object as a function. If it is desired to process macros, special forms, and functions equally well, as when writing an interpreter, it is best first to test the symbol with macro-function and special-form-p and then to invoke the functional value only if these two tests both yield false.

This function is particularly useful for implementing interpreters for languages embedded in LISP.

The global function definition of a symbol may be altered by using setf with symbol-function. Performing this operation causes symbol to have only the specified definition as its global function definition; any previous definition, whether as a macro or as a function, is lost. It is an error to attempt to redefine the name of a special form.

 

LISP: SYMBOL-NAME

C: Lsymbol_name

min args: 1

max args: 1

[F][CLTL 10]

SYNOPSIS:

symbol-name symbol

DESCRIPTION:

The symbol-name function returns the print name of its symbol argument.

For example:

(symbol-name 'iguana) => "IGUANA"

ANSI Common LISP forbids modifying a symbols' print name. Although this has not been implemented in Star Sapphire Common LISP, it is recommended as a practice. Modifying a symbol print name will definitely trash the package system and the internal hash tables in this or any other LISP implementation.

The best way to use this function is as follows:

(copy-seq (symbol-name 'helen-of-troy)) => "HELEN-OF-TROY"

Which creates a copy of the symbol print name. Then any desired modifications can safely be made on the result.

 

LISP: SYMBOL-PACKAGE

C: Lsymbol_package

min args: 1

max args: 1

[F][CLTL 10]

SYNOPSIS:

symbol-package sym

DESCRIPTION:

symbol-package returns the contents of the package cell of the symbol argument sym. The return value will be a package object or nil (if the symbol is uninterned).

 

LISP: SYMBOL-PLIST

C: Lsymbol_plist

min args: 1

max args: 1

[F][CLTL 10]

SYNOPSIS:

symbol-plist symbol

DESCRIPTION:

This returns the actual list that contains the property pairs of the symbol. The symbol is not modified. Although this operation in and of itself is innocuous, care must be taken with the result returned.

NOTES:

WARNING: setf may be used with symbol-plist to destructively replace the entire property list of a symbol. This will destroy important information that Star Sapphire LISP (as well as other implementations) stores in property lists; the system environment may become corrupted in subtle ways.

If symbol-plist is used with setf, care must be taken that the new property list is valid, in particular, that it is a list of even length.

Note that using get on the result of symbol-plist does not work. One must give the symbol itself to get or else use the function getf.

 

LISP: SYMBOL-VALUE

C: LSymVal

min args: 1

max args: 1

[F][CLTL 7]

SYNOPSIS:

symbol-value symbol

DESCRIPTION:

symbol-value returns the current value of the dynamic (special) variable named by symbol. An error occurs if the symbol has no value; see boundp and makunbound. Note that constant symbols are really variables that cannot be changed, and so symbol-value may be used to get the value of a named constant. In particular, symbol-value of a keyword will return that keyword.

symbol-value cannot access the value of a lexical variable.

This function is particularly useful for implementing interpreters for languages embedded in LISP. The corresponding assignment primitive is set; alternatively, symbol-value may be used with setf.

 

LISP: SYMBOL

[Typespec][CLTL 4]

SYNOPSIS:

symbol

DESCRIPTION:

This is a type specifier symbol which indicates the set of all symbol objects.

Note that nil is considered a symbol.

SEE ALSO:

symbolp

 

LISP: SYMBOLP

C: Lsymbolp

min args: 1

max args: 1

[F][CLTL 6]

SYNOPSIS:

symbolp object

DESCRIPTION:

symbolp is true if its argument is a symbol, and otherwise is false.

(symbolp x) == (typep x 'symbol)

 

LISP: SYSTEM

C: Los

min args: 1

max args: -1

[F][SSCL]

SYNOPSIS:

system dos-command &rest dos-commands

DESCRIPTION:

This command runs any number of system commands in sequence. The commands can be symbols or strings. The function always returns t.

If there is not enough memory to run the commands, the behavior of this function is unspecified; it may fail or the interpreter may run out of low memory.

NOTES:

This was called ‘OS’ in DOS Star Sapphire.

The #! command in Star Sapphire LISP is an interactive shell escape: However, #! does not work when embedded in loaded files. This function overcomes this limitation.

There should be some means of telling whether the command succeeded; no indication is given presently outside of any error messages that DOS prints (which are independent of the Star Sapphire I/O system and hence cannot be captured using dribble).