Star Sapphire Common LISP Home

Download Star Saphire
Index

LISP: RANDOM

C: Lrandom

min args: 1

max args: 2

[F][CLTL 12]

SYNOPSIS:

random number &optional state

DESCRIPTION:

(random n) accepts a positive number n and returns a number of the same kind between zero (inclusive) and n (exclusive). The number n may be an integer or a floating-point number. An approximately uniform choice distribution is used. If n is an integer, each of the possible results occurs with (approximate) probability 1/n. (The qualifier "approximate" is used because of implementation considerations; in practice, the deviation from uniformity should be quite small.)

The argument state must be an object of type random-state; it defaults to the value of the variable *random-state*. This object is used to maintain the state of the pseudo-random-number generator and is altered as a side effect of the random operation.

 

LISP: RANDOM-STATE

[Typespec][CLTL 4]

SYNOPSIS:

random-state

DESCRIPTION:

This is the type specifier symbol which indicates the set of all random-state objects.

SEE ALSO:

random-state-p and random.

 

LISP: RANDOM-STATE-P

C: Lrandom_state_p

min args: 1

max args: 1

[F][CLTL 12]

SYNOPSIS:

random-state-p object

DESCRIPTION:

random-state-p is true if its argument is a random-state object, and otherwise is false.

(random-state-p x) == (typep x 'random-state)

 

LISP: RASSOC

C: Lrassoc

min args: 2

max args: -1

[F][CLTL 15]

SYNOPSIS:

rassoc item a-list &key :test-not :key

DESCRIPTION:

rassoc is the reverse form of assoc; it searches for a pair whose cdr satisfies the test, rather than the car. If the a-list is considered to be a mapping, then rassoc treats the a-list as representing the inverse mapping. For example:

(rassoc 'a '((a . b) (b . c) (c . a) (z . a))) => (c . a)

The expressions

(rassoc item list: test fn)

and

(find item list :test fn :key #'cdr)

are equivalent in meaning, except when the item is nil and nil appears in place of a pair in the a-list. See the discussion of the function assoc.

 

LISP: RASSOC-IF

C: Lif_rassoc

min args: 2

max args: -1

[F][CLTL 15]

SYNOPSIS:

rassoc-if prediate a-list

DESCRIPTION:

See rassoc.

 

LISP: RASSOC-IF-NOT

C: Lifn_rassoc

min args: 2

max args: -1

[F][CLTL 15]

SYNOPSIS:

rassoc-if-not predicate a-list

DESCRIPTION:

See rassoc.

 

LISP: RATIO

[Typepec][CLTL 4]

SYNOPSIS:

ratio

DESCRIPTION:

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

 

LISP: RATIONAL

[Typepec][CLTL 4]

SYNOPSIS:

rational

DESCRIPTION:

This is the type specifier symbol which indicates the set of all rational numbers.

SEE ALSO:

rationalp

 

LISP: RATIONALP

C: Lrationalp

min args: 1

max args: 1

[F][CLTL 6]

SYNOPSIS:

rationalp object

DESCRIPTION:

rationalp is true if its argument is a rational number (a ratio or an integer), and otherwise is false.

(rationalp x) == (typep x 'rational)

 

LISP: READ

C: L_Read

min args: 0

max args: 3

[F][CLTL 22]

SYNOPSIS:

read &optional input-stream eof-error-p eof-value

DESCRIPTION:

read reads in the printed representation of a LISP object from input-stream, builds a corresponding LISP object, and returns the object.

 

LISP: READ-FROM-STRING

C: L_Read

min args: 1

max args: -1

[F][CLTL 22]

SYNOPSIS:

read-from-string string &optional eof-error-p eof-value

&key :start :end :preserve-whitespace

DESCRIPTION:

read-from-string reads in the printed representation of a LISP object from string, builds a corresponding LISP object, and returns the object.

The :start and :end keywords allow definition of a substring to read from. The start and end default to the entire string.

The :preserve-whitespace keyword, if provided and not nil, indicates that the read should preserve whitespace (see read-preserving-whitespace). It defaults to nil.

The function returns two values: The object read and the index of the first character in the string not read.

 

LISP: READTABLE

[Typespec][CLTL 4]

SYNOPSIS:

readtable

DESCRIPTION:

This is the type specifier which specifies the class of all readtable objects.

 

LISP: *READTABLE*

[V][CLTL 22]

SYNOPSIS:

*readtable*

DESCRIPTION:

The value of *readtable* is the current readtable. The initial value of this is a readtable set up for standard Common LISP syntax. You can bind this variable to temporarily change the readtable being used.

To program the reader for a different syntax, a set of functions are provided for manipulating readtables. Normally, you should begin with a copy of the standard Common LISP readtable and then customize the individual characters within that copy.

 

LISP: READTABLEP

C: Lreadtablep

min args: 1

max args: 1

[F][CLTL 22]

SYNOPSIS:

readtablep

DESCRIPTION:

This is the type predicate which is true if its argument is a readtable object and false otherwise.

 

LISP: READ-CHAR

C: L_RdCh

min args: 0

max args: 3

[F][CLTL 22]

SYNOPSIS:

read-char &optional input-stream eof-error-p eof-value recursive-p

DESCRIPTION:

read-char inputs one character from input-stream and returns it as a character object.

The corresponding output function is write-char.

 

LISP: READ-DELIMITED-LIST

C: RdDelLs

min args: 1

max args: 3

[F][CLTL]

SYNOPSIS:

read-delimited-list char &optional input-stream recursive-p

DESCRIPTION:

This reads objects from stream until the next character after an object's representation (ignoring whitespace characters and comments) is char. (The char should not have whitespace syntax in the current readtable.) A list of the objects read is returned.

To be more precise, read-delimited-list looks ahead at each step for the next non-whitespace character and peeks at it as if with peek-char. If it is char, then the character is consumed and the list of objects is returned. If it is a constituent or escape character, then read is used to read an object, which is added to the end of the list. If it is a macro character, the associated macro function is called; if the function returns a value, that value is added to the list. The peek-ahead process is then repeated.

This function is particularly useful for defining new macro characters. Usually it is desirable for the terminating character char to be a terminating macro character so that it may be used to delimit tokens; however, read-delimited-list makes no attempt to alter the syntax specified for char by the current readtable. The user must make any necessary changes to the readtable syntax explicitly.

EXAMPLE:

Suppose you wanted #{a b c ... z} to be read as a list of all pairs of the elements a,b,c ... z; for example:

#{p q z a} reads as ((p q) (p z) (p a) (q z) (q a) (z a))

This can be done by specifying a macro-character definition for #{ that does two things: Read in all the items up to the {, and construct the pairs. Read-delimited-list performs the first task.

Note that the mapcon allows the mapped function to examine the items of the list after the current one, and that mapcon uses nconc, which is all right because mapcar will produce fresh lists.

(defun |#{-reader| (stream char arg)

(declare (ignore char arg))

(mapcon #'(lambda (x)

(mapcar #'(lambda (y) (list (car x) y)) (cdr x)))

(read-delimited-list #\} stream t)))

(set-dispatch-macro-character #\# #\{ #'|#{-reader|)

(set-macro-character #\} (get-macro-character #\) nil))

(Note that t is specified for the recursive-p'argument.)

It is necessary here to give a definition to the character } as well as to prevent it from being a constituent. If the line

(set-macro-character #\} (get-macro-character #\) nil))

shown above were not included, then the } in

#{p q z a}

would be considered a constituent character, part of the symbol named a}. One could correct for this by putting a space before the }, but it is better simply to use the call to set-macro-character.

Giving } the same definition as the standard definition of the character ) has the twin benefit of making it terminate tokens for use with read-delimited-list and also making it illegal for use in any other context (that is, attempting to read a stray } will signal an error).

Note that read-delimited-list does not take an eof-error-p (or eof-value argument. The reason is that it is always an error to hit end-of-file during the operation of read-delimited-list.

 

LISP: READ-LINE

C: L_RdLn

min args: 0

max args: 3

[F][CLTL 22]

SYNOPSIS:

read-line &optional input-stream eof-error-p eof-value

DESCRIPTION:

read-line reads in a line of text terminated by a newline. It

returns the line as a character string (without the newline character). This function is usually used to get a line of input from the user. A second returned value is a flag that is false if the line was terminated normally, or true if end-of-file terminated the (non-empty) line. If end-of-file is encountered immediately (that is, appears to terminate an empty line), then end-of-file processing is controlled in the usual way by the eof-error-p, and eof-value arguments.

The corresponding output function is write-line.

 

LISP: READ-PRESERVING-WHITESPACE

C: RdPresWS

min args: 0

max args: 4

[F][CLTL]

SYNOPSIS:

read-preserving-whitespace &optional in-stream eof-error-p eof-value recursive-p

DESCRIPTION:

Certain printed representations given to read, notably those of symbols and numbers, require a delimiting character after them. (Lists do not, because the close parenthesis marks the end of the list). Normally read will throw away the delimiting character if it is a whitespace character; but read will preserve the character (essentially, using unread-char) if it is syntactically meaningful, because it may be the start of the next expression.

The function read-preserving-whitespace is provided for some specialized situations where it is desirable to determine precisely what character terminated the extended token.

On the other hand, there are times when whitespace should be discarded. If a command interpreter takes single-character commands, but occasionally reads a LISP object, then if the whitespace after a symbol is not discarded it might be interpreted as a command some time later after the symbol has been read.

Note that read-preserving-whitespace behaves exactly like read when the recursive-p argument is not nil. The distinction is established only by calls with recursive-p equal to nil or omitted.

 

LISP: REAL

[Typespec][CLTL2 4]

SYNOPSIS:

real [low [high]]

real

DESCRIPTION:

This is the type specifier symbol which indicates the set of real numbers. Real numbers are specified to include all non-complex numbers; since complex numbers are not implemented in this version, this is equivalent to the set of all Star Sapphire numbers of any type whatsoever.

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.

NOTE:

This type was introduced into Common LISP by ANSI and was not present in CLTL1.

 

LISP: REDUCE

C: Lreduce

min args: 2

max args: -1

[F][CLTL 14]

SYNOPSIS:

reduce function sequence &key :from-end :start :end :initial-value

DESCRIPTION:

The reduce function combines all the elements of a sequence using a binary operation; for example, using + one can add up all the elements.

The specified subsequence of the sequence is combined or "reduced" using the function, which must accept two arguments. The reduction is left-associative, unless the :from-end argument is true (it defaults to nil), in which case it is right-associative. If an :initial-value argument is given, it is logically placed before the subsequence (after it if :from-end is true) and included in the reduction operation.

If the specified subsequence contains exactly one element and no :initial-value is given, then the :initial-value is returned and the function is not called.

If the specified subsequence is empty and no :initial-value is given, then the function is called with zero arguments, and reduce returns whatever the function does. (This is the only case where the function is called with other than two arguments.)

(reduce #'+ '(1 2 3 4 ) => 10

(reduce #'- '(1 2 3 4)) = (- (- (- 1 2) 3) 4) => -8

(reduce #'- '(1 2 3 4) :from-end t) ;Alternating sum.

= (- 1 (- 2 (- 3 4))) => -2

(reduce #'+ '()) => 0

(reduce #'+ '(3)) => 3

(reduce #'+ '(foo)) => foo

(reduce #'list '(1 2 3 4)) => (((1 2) 3) 4)

(reduce #'list '(1 2 3 4) :from-end t) => (1 (2 (3 4)))

(reduce #'list '(1 2 3 4) :initial-value 'foo)

=> ((((foo 1) 2) 3) 4)

(reduce #'list '(1 2 3 4)

:from-end t :initial-value 'foo)

=> (1 (2 (3 (4 foo))))

If the function produces side-effects, the order of the calls to the function can be correctly predicted from the reduction ordering demonstrated above.

The name reduce for this function is borrowed from APL.

 

LISP: REM

C: Lremainder

min args: 2

max args: 2

[F][CLTL 12]

SYNOPSIS:

rem number divisor

DESCRIPTION:

Rem performs the operation truncate on its arguments and returns the second result of truncate as its only result.

Rem is therefore the usual remainder function when applied to two integer arguments. In general, however, the arguments may be integers or floating-point numbers.

(rem 13 4) => 1

(rem -13 4) => -1

(rem 13 -4) => 1

(rem -13 -4) => -1

(rem 13.4 1) => 0.4

(rem -13.4 1) -0.=> 4

 

LISP: REMF

min args: 2

max args: 2

[M][CLTL 7]

SYNOPSIS:

remf plist indicator

DESCRIPTION:

The remf macro removes the property with an indicator eq to indicator from the given plist. Both property indicator and corresponding value are removed. This is done by destructively splicing the property list.

Remprop returns nil if no such property was found for removal, in which case the property-list is unmodified. A non-nil value is returned if a property was removed.

The form plist may be any generalized variable acceptable to setf.

SEE ALSO:

remprop.

NOTES:

Star Sapphire LISP remf is defined in the file init0.lsp; it can be incorporated into your startup sequence if desired by copying its code into init.lsp. However, as it takes a while to load, it may be better to incorporate the code for remf or code which loads a fastload image of the code for remf specifically into whatever module needs it.

LISP: REMOVE

C: Lremv

min args: 2

max args: -1

[F][CLTL 14]

SYNOPSIS:

remove item sequence &key :from-end :test :test-not :start :end :count :key

DESCRIPTION:

The result is a sequence of the same kind as the argument sequence that has the same elements except that those in the subsequence delimited by :start and :end and satisfying the test (see above) have been removed. This is a non-destructive operation; the result is a copy of the input sequence, save that some elements are not copied. Elements not removed occur in the same order in the result that they did in the argument.

The :count argument, if supplied, limits the number of elements removed; if more than :count elements satisfy the test, then of these elements only the leftmost are removed, as many as specified by :count.

A non-nil :from-end specification matters only when the :count argument is provided; in that case only the rightmost :count elements satisfying the test are removed. For example:

(remove 4 '(1 2 4 1 3 4 5)) => (1 2 1 3 5)

(remove 4 '(1 2 4 1 3 4 5) :count 1) => (1 2 1 3 4 5)

(remove 4 '( 2 4 1 3 4 5 ) :count 1 :from-end t)

=> (1 2 4 1 3 5)

(remove 3 '(1 2 4 1 3 4 5) :test #'>) => (4 3 4 5)

(remove-if #'oddp '(1 2 4 1 3 4 5)) => (2 4 4)

(remove-if #'evenp '(1 2 4 1 3 4 5) :count 1 :from-end t)

=> (1 2 4 1 3 5)

The result of remove may share with the argument sequence; a list result may share a tail with an input list, and the result may be eq to the input sequence if no elements need to be removed.

LISP: REMOVE-IF

C: Lremvif

min args: 2

max args: -1

[F][CLTL 14]

SYNOPSIS:

remove-if test sequence &key :from-end :start :end :count :key

DESCRIPTION:

See remove.

LISP: REMOVE-IF-NOT

C: Lremvifn

min args: 2

max args: -1

[F][CLTL 14]

SYNOPSIS:

remove-if-not test sequence &key :from-end :start :end :count :key

DESCRIPTION:

See remove.

LISP: REMPROP

C: Lremprop

min args: 2

max args: 2

[F][CLTL 10]

SYNOPSIS:

remprop symbol indicator

DESCRIPTION:

The remprop function removes the property with an indicator eq to indicator from the given symbol. Both property indicator and corresponding value are removed. This is done by destructively splicing the property list. remprop returns nil if no such property was found for removal, in which case the symbol property-list is unmodified. A non-nil value is returned if a property was removed.

For example, if the property list of 'rogue' is initially

(health 4 hit-points 6 armor chain-mail)

then the call

(remprop 'rogue 'armor)

returns a non-nil value after altering the rogue's property list to be

(health 4 hit-points 6)

Specifically:

(remprop x y) == (remf (symbol-plist x) y)

NOTES:

Implementation note:

In Star Sapphire Common LISP, remprop returns T if a property is removed; code which relies on a T return specifically may not be portable.

LISP: RENAME-FILE

C: Lrename_file

min args: 2

max args: 2

[F][CLTL]

SYNOPSIS:

rename-file file new-name

DESCRIPTION:

The file 'ile is renamed as new-name'. The file argument must be a legal file name (a string or a symbol in this implementation).

On success, three values are returned. The first is the new name of the file. The second is specified as the truename of the original file; in this implementation this is the same as the first argument. The third return value is specified as the truename of the file after it was renamed; in this implementation this is simply the renamed file's name.

On failure, an error is raised.

EXAMPLE:

(rename-file 'src 'tgt)

TGT

SRC

TGT

LISP: RENAME-PACKAGE

C: LRenPkg

min args: 2

max args: 3

[F][CLTL]

SYNOPSIS:

rename-package package new-name &optional new-nicknames

DESCRIPTION:

The old name and all of the old nicknames of package are eliminated and are replaced by new-name and new-nicknames. The new-name argument is a string or symbol; the new-nicknames argument, which defaults to nil, is a list of strings or symbols.

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

Rename-package returns package.

LISP: REPLACE

C: Lreplace

min args: 2

max args: -1

[F][CLTL 14]

SYNOPSIS:

replace sequence1 sequence2 &key :start1 :end1 :start2 :end2

DESCRIPTION:

The sequence sequence1 is destructively modified by copying successive elements into it from sequence2. The elements of sequence2 must be of a type that may be stored into sequence1. The subsequence of sequence2 specified by :start2 and :end2 is copied into the subsequence of sequence1 specified by :start1 and :end1. (The arguments :start1 and :start2 default to zero. The arguments :end1 and :end2 default to nil, meaning the end of the appropriate sequence.) If these subsequences are not of the same length, then the shorter length determines how many elements are copied; the extra elements near the end of the longer subsequence are not involved in the operation. The number of elements copied may be expressed as:

(min (- end1 start1) (- end2 start2))

The value returned by replace is the modified sequence1.

If sequence1 and sequence2 are the same (eq) object and the region being modified overlaps the region being copied from, then it is as if the entire source region were copied to another place and only then copied back into the target region. However, if sequence1 and sequence2 are not the same, but the region being modified overlaps the region being copied from (perhaps because of shared list structure or displaced arrays), then after the replace operation the subsequence of sequence1 being modified will have unpredictable contents.

LISP: REST

C: Lcdr

min args: 1

max args: 1

[F][CLTL 15]

SYNOPSIS:

rest list

DESCRIPTION:

rest means the same as cdr but mnemonically complements first. setf may be used with rest to replace the cdr of a list with a new value.

LISP: RETURN

C: SFCRets, ERet

[M][CLTL 7]

SYNOPSIS:

return [result]

DESCRIPTION:

(return form) is identical in meaning to (return-from nil form); it returns from a block named nil. Blocks established implicitly by iteration constructs such as do are named nil, so that return will exit property from such a construct.

LISP: RETURN-FROM

C: SFCRets, ERet

[S][CLTL 7]

SYNOPSIS:

return-from name [result]

DESCRIPTION:

return-from is used to return from a block or from such constructs as do and prog that implicitly establish a block. The name is not evaluated and must be a symbol. A block construct with the same name must lexically enclose the occurrence of return-from; whatever the evaluation of result produces is immediately returned from the block. (If the result form is omitted, it defaults to nil. As a matter of style, this form ought to be used to indicate that the particular value returned doesn't matter.)

The return-from form itself never returns and cannot have a value; it causes results to be returned from a block construct. If the evaluation of result produces multiple values, those multiple values are returned by the construct exited.

LISP: REVAPPEND

C: Lrevappend

min args: 2

max args: 2

[F][CLTL 15]

SYNOPSIS:

revappend x y

DESCRIPTION:

(revappend x y) is exactly the same as (append (reverse x) y) except that it is potentially more efficient. Both x and y should be lists. The argument x is copied, not destroyed. Compare this with nreconc, which destroys its first argument.

LISP: REVERSE

C: Lreverse

min args: 1

max args: 1

[F][CLTL 14]

SYNOPSIS:

reverse sequence

DESCRIPTION:

The result is a new sequence of the same kind as sequence, containing the same elements but in reverse order. The argument is not modified.

SEE ALSO:

nreverse

LISP: ROOM

C: Room

min args: 0

max args: 1

[F][CLTL 25]

SYNOPSIS:

room &optional x

DESCRIPTION:

room prints, to the stream in the variable *standard-output*, information about the state of internal storage and its management.

(room nil) prints out a minimal amount of information. (room t) prints out a maximal amount of information. Simply (room) prints out an intermediate amount of information that is likely to be useful.

LISP: ROUND

C: Lround

min args: 1

max args: 2

[F][CLTL 12]

SYNOPSIS:

round number &optional divisor

DESCRIPTION:

round converts its argument by rounding to the nearest integer; if number is exactly halfway between two integers (that is, of the form integer +0.5), then it is rounded to the one that is even (divisible by two).

In the simple one-argument case, round converts its argument number to be an integer. If the argument is already an integer, it is returned directly. If the argument is a ratio or floating-point number, the functions use different algorithms for the conversion.

If a second argument divisor is supplied, then the result is the appropriate type of rounding or trancation applied to the result of dividing the number by the divisor. For example, (floor 5 2) == (floor (/ 5 2)) but is potentially more efficient. The divisor may be any number. The one-argument case is exactly like the two-argument case where the second argument is 1.

Each of the functions actually returns two values, whether given one or two arguments. The second result is the remainder and may be obtained using multiple-value-bind and related constructs. If any of these functions 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. One consequence is that in the one-argument case the remainder is always a number of the same type as the argument.

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.

LISP: RPLACA

C: Lrplaca

min args: 2

max args: 2

[F][CLTL 15]

SYNOPSIS:

rplaca x y

DESCRIPTION:

The functions rplaca and rplacd may be used to make alterations in already existing list structure, that is, to change the car or cdr of an existing cons. One may also use setf in conjunction with car and cdr.

The structure is not copied but is destructively altered; hence caution should be exercised when using these functions, as strange side effects can occur if portions of list structure become shared. The nconc, nreverse, nreconc, and nbutlast functions, already described, have the same property, as do certain of the generic sequence functions such as delete. However, they are normally not used for this side effect; raather, the list-structure modification is purely for efficiency, and compatible non-modifying functions are provided.

(rplaca x y) changes the car of x to y and returns (the modified) x. x

must be a cons, but y may be any LISP object. For example:

(setq g '(a b c))

(rplaca (cdr g) 'd) => (d c)

Now g => (a d c)

SEE ALSO:

rplacd

LISP: RPLACD

C: Lrplacd

min args: 2

max args: 2

[F][CLTL 15]

SYNOPSIS:

rplacd x y

DESCRIPTION:

(rplacd x y) changes the cdr of x to y and returns (the modified) x. x must be a cons, but y may be any LISP object. For example:

(setq x '(a b c))

(rplacd x 'd) => (a . d)

Now x => (a . d)

SEE ALSO:

rplaca

LISP: RUN

C: RunEdFile

min args: 0

max args: 1

[F][SSCL]

SYNOPSIS:

run &optional file-name

DESCRIPTION:

The run function loads the last file edited as if by (load :verbose t).

The run function loads the file name determined by examining the system call invoked by the last ed invocation and stripping off the name of the editor. This is not a standard Common LISP function, but is provided for convenience. ed will also use the name from the last run invocation, if you have not called ed previously in the session.

Suppose you had typed:

LISP: (ed 'hanoi.lsp)

You could also type

LISP: (load 'hanoi.lsp :verbose t)

for the identical effect but the run function requires less typing. Also note that ed has no knowledge of the name of last file loaded.

If a file-name argument is supplied it must be a string or symbol. The argument is taken to be a file name. This then becomes the next file edited by ed and succesive ed/run invocations until reset.

NOTE:

This function is not supported in the beta. It will be supported in the release. This documentation is left here as a placeholder.