Star Sapphire Common LISP Home

Download Star Saphire
Index

LISP: FBOUNDP

C: LSymPFBd

min args: 1

max args: 1

[F][CLTL 7]

SYNOPSIS:

fboundp symbol

DESCRIPTION:

Fboundp returns t if the symbol has a global function definition, otherwise nil.

The argument symbol must be a global variable; otherwise an error is raised. Thus the symbol cannot be a let not otherwise declared special.

Note that fboundp is likewise true when the symbol names a special form or macro. The macro-function and special-form-p functions may be used to distinguish these cases.

NOTES:

In the current version of Star Sapphire Common LISP, all function definitions are global. In other versions of Common LISP with the flet, labels, and progv facilities this function may return false if a symbol has a local function definition but no global definition. This will not produce any incompatibilities with code written using this version of LISP which is ported elsewhere, but may create problems with code being ported to Star Sapphire.

See also:

symbol-function and fmakunbound.

 

LISP: FCEILING

C: Lfceiling

min args: 1

max args: 2

[F][CLTL 12]

SYNOPSIS:

fceiling number &optional divisor

DESCRIPTION:

This function is just like ceiling except that the result (the first result of two) is always a floating-point number rather than an integer. It is roughly as if fceiling gave its arguments to ceiling, and then applied float to the first result before passing them both back. In practice, however, fceiling may be implemented much more efficiently. Similar remarks apply to the other three functions. If the first argument is a floating-point number, and the second argument is not a floating-point number of longer format, then the first result will be a floating-point number of the same type as the first argument.

 

LISP: FFLOOR

C: Lffloor

min args: 1

max args: 2

[F][CLTL 12]

SYNOPSIS:

ffloor number &optional divisor

DESCRIPTION:

This function is just like floor except that the result (the first result of two) is always a floating-point number rather than an integer. It is roughly as if ffloor gave its arguments to floor, and then applied float to the first result before passing them both back. In practice, however, ffloor may be implemented much more efficiently. Similar remarks apply to the other three functions. If the first argument is a floating-point number, and the second argument is not a floating-point number of longer format, then the first result will be a floating-point number of the same type as the first argument.

 

LISP: FIFTH

C: Lfifth

min args: 1

max args: 1

[F][CLTL 15]

SYNOPSIS:

fifth list

DESCRIPTION:

See first.

 

LISP: FILE-AUTHOR

min args: 1

max args: 1

[F][CLTL]

SYNOPSIS:

file-author file

DESCRIPTION:

The specification states that this should return nil if the file author cannot be determined. Since this is not applicable under DOS, this function is defined (in init0.lsp) as always returning nil.

 

LISP: FILE-LENGTH

C: Lfile_length

min args: 1

max args: 1

[F][CLTL]

SYNOPSIS:

file-length stream

DESCRIPTION:

The stream must be a stream which is associated with a file via open. The length of the file is returned or nil if the file length cannot be ascertained.

 

LISP: FILE-POSITION

C: Lfile_position

min args: 1

max args: 2

[F][CLTL]

SYNOPSIS:

file-position stream &optional position

DESCRIPTION:

With one argument, a currently open stream, file-position returns the current position in the file as a non-negative integer. If the file does not exist or the file position is not ascertainable, nil is returned.

With two arguments, the second argument can be a non-negative, non-bignum integer or one of the keywords :start or :end. If the position argument is a number, it specifies the position in the file from the start of the file.

For convenience, :start or :end can be specified as the second argument (these keywords take no argument) to set the file pointer to the start or end of the file respectively.

In the two argument case, t is returned if the position was set and an error raised if it could be not.

The file position is the next place at which reading or writing will occur (assuming that the file is open for this kind of interaction).

EXAMPLES:

; report the file position in 'my-file'

(format t

"so far, we have read ~s bytes from my-file ~%"

(file-position my-file))

(file-position my-file :start) ; 'rewind' file to start

(file-position my-file 0) ; does same as previous

(file-position my-file 33) ; set to the 33rd byte in the file

NOTE:

Text files map each newline to two characters; file-position will add two for each newline in this case. To make file-position count one character for each newline, open the file using :external-format :binary.

SEE ALSO:

open, with-open-file

 

LISP: FILE-WRITE-DATE

C: Lfile_write_date

min args: 1

max args: 1

[F][CLTL]

SYNOPSIS:

file-write-date file

DESCRIPTION:

The file argument can either be an open stream object or a file name (in this implementation a string or a symbol). The return value is the Universal Time at which the file was last written to, or nil if this cannot be determined.

 

LISP: FILL

C: Lfill

min args: 2

max args: -1

[F][CLTL 14]

SYNOPSIS:

fill sequence item &key :start :end

DESCRIPTION:

The sequence is destructively modified by replacing each element of the sub-sequence specified by the :start and :end parameters with the item. The item may be any LISP object but must be a suitable element for the sequence. The item is stored into all specified components of the sequence, beginning at the one specified by the :start index (which defaults to zero), up to but not including the one specified by the :end index (which defaults to the length of the sequence). fill returns the modified sequence. For example:

(setq x (vector 'a 'b 'c 'd 'e)) => #(a b c d e)

(fill x 'z :start 1 :end 3) => #(a z z d e)

and now x => #(a z z d e)

(fill x 'p) => #(p p p p p)

and now x => #(p p p p p)

 

LISP: FILL-POINTER

C: LFillPointer

min args: 1

max args: 1

[F][CLTL 17]

SYNOPSIS:

fill-pointer vector

DESCRIPTION:

The fill pointer of vector is returned. It is an error if vector does not have a fill pointer.

setf may be used with fill-pointer to change the fill pointer of a vector. The fill pointer of a vector must always be an integer between zero and the size of the vector (inclusive).

 

LISP: FIND

C: Lfind

min args: 2

max args: -1

[F][CLTL 14]

SYNOPSIS:

find item sequence &key :from-end :test :test-not :start :end :key

DESCRIPTION:

Find searches a sequence to locate one or more elements satisfying some test.

If :start and :end keyword arguments are given, only the specified subsequence of sequence is searched.

If a non-nil :from-end keyword argument is specified, then the result is the rightmost element satisfying the test.

 

LISP: FIND-ALL-SYMBOLS

C: FindAllSymbols

min args: 1

max args: 1

[F][CLTL]

SYNOPSIS:

find-all-symbols string-or-symbol

DESCRIPTION:

find-all-symbols searches every package in the Lisp system to find every symbol whose print name is the specified string. A list of all such symbols found is returned. This search is case-sensitive. If the argument is a symbol, its print name supplies the string to be searched for.

 

LISP: FIND-DOCUMENTATION

C: FIND_DOCUMENTATION

min args: 1

max args: 1

[F][SSCL]

SYNOPSIS:

find-documentation

DESCRIPTION:

This is a function internal to the defstruct and defmacro implementation which locates documentation strings in forms. It is not intended to be called directly by users.

 

LISP: FIND-IF

C: Lfindif

min args: 2

max args: -1

[F][CLTL 14]

SYNOPSIS:

find-if test sequence &key :from-end :start :end :key.

DESCRIPTION:

See find.

 

LISP: FIND-IF-NOT

C: Lfindifn

min args: 2

max args: -1

[F][CLTL 14]

SYNOPSIS:

find-if-not test sequence &key :from-end :start :end :key

DESCRIPTION:

See find.

 

LISP: FIND-PACKAGE

C: LFindPackage

min args: 1

max args: 1

[F][CLTL]

SYNOPSIS:

find-package name

DESCRIPTION:

The name must be a string that is the name or nickname for a package. This argument may also be a symbol, in which case the symbol's print name with that name or nickname is returned; if no such package exists, find-package returns nil. The matching of names observes case (as in string=). Find-package accepts a package statement in which case the package is simply returned.

 

LISP: FIND-SYMBOL

C: LFindSym

min args: 1

max args: 2

[F][CLTL]

SYNOPSIS:

find-symbol string &optional package

DESCRIPTION:

This is identical to intern, but never creates a new symbol. If a symbol with the specified name is found in the specified package, directly or by inheritance, the symbol found is returned as the first value and the second value is as specified for intern. If the symbol is not accessible in the specified package, both values are nil.

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

 

LISP: FINISH-OUTPUT

C: L_FinOut

min args: 0

max args: 1

[F][CLTL 22]

SYNOPSIS:

finish-output &optional output-stream

DESCRIPTION:

Some streams may be implemented in an asynchronous or buffered manner. The function finish-output attempts to ensure that all output sent to output-stream has reached its destination, and only then returns nil.

 

LISP: FIRST

C: Lfirst

min args: 1

max args: 1

[F][CLTL 15]

SYNOPSIS:

first list

DESCRIPTION:

The functions first-tenth are sometimes convenient for accessing particular elements of list. first is the same as car, second is the same as cadr, third is the same as caddr, and so on. Note that the ordinal numbering used here is one-origin, as opposed to the zero-origin numbering used by nth:

(fifth x) == (nth 4 x)

setf may be used with each of these functions to store into the indicated position of a list.

 

LISP: FIXNUM

[Typespec][CLTL 4]

SYNOPSIS:

fixnum

DESCRIPTION:

This is the type specifier symbol for fixnums, small integers which are implemented by being stored directly into virtual addresses.

In this implementation, fixnums take the values -32766..32766.

EXAMPLES:

(typep 3 'fixnum) => t

(typep 3000000 'fixnum) => nil

SEE ALSO:

bignum

 

LISP: FLOAT

C: Lfloat

min args: 1

max args: 2

[F][CLTL 12]

SYNOPSIS:

float number &optional other

DESCRIPTION:

This converts any non-complex number to a floating-point number. With no second argument, if number is already a floating-point number, then number is returned; otherwise a float is produced. If the argument other is provided, then it must be a floating-point number, and number is converted to the same format as other.

NOTES:

There is only one floating point format in Star Sapphire Common LISP, so the second argument, although supported, has no effect.

SEE ALSO:

float (typespec)

 

LISP: FLOAT (typespec)

[Typespec][CLTL 4]

SYNOPSIS:

float [[low] high]

float

DESCRIPTION:

This is the type specifier symbol which indicates the set of floating point numbers.

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.

EXAMPLES:

(typep 3.14159 'float) => t

(typep "skunk" 'float) => nil

(typep 0.1 '(float (0.1)) => nil

(typep 0.1 '(float 0.1) => t

(typep 45.443 '(float 23.0 *)) => t

(typep 45.443 '(float * 23.0)) => nil

(typep -45.443 '(float * 23.0)) => t

NOTES:

In this implementaion, there is only one size of floating point number. Hence the specifiers double-float, single-float, long-float and short-float are completely equivalent to this specifier.

 

LISP: FLOATP

C: Lfloatp

min args: 1

max args: 2

[F][CLTL 6]

SYNOPSIS:

floatp object

DESCRIPTION:

floatp is true if its argument is a floating-point number, and otherwise is false.

(floatp x) == (typep x 'float)

 

LISP: FLOOR

C: Lfloor

min args: 1

max args: 2

[F][CLTL 12]

SYNOPSIS:

floor number &optional divisor

DESCRIPTION:

floor converts its argument by truncating toward negative infinity; that is, the result is the largest integer that is not larger than the argument.

In the simple one-argument case, floor 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: FMAKUNBOUND

C: LSymFMUB

min args: 1

max args: 1

[F][CLTL 7]

SYNOPSIS:

fmakunbound symbol

DESCRIPTION:

fmakunbound causes symbol to have no functional definition, regardless of whether it had one.

(defun foo (x) (+ x 1))

(foo 4) => 5

(fmakunbound 'foo)

(foo 4) => causes an error

Both functions return symbol as the result value.

NOTES:

Using fmakunbound on the symbol referencing a built-in function may cause strange behavior.

 

LISP: FORCE-OUTPUT

C: L_FrcOut

min args: 0

max args: 1

[F][CLTL 22]

SYNOPSIS:

force-output &optional output-stream

DESCRIPTION:

Some streams may be implemented in an asynchronous or buffered manner. Force-output initiates the emptying of any internal buffers but returns nil without waiting for completion or acknowledgement.

NOTES:

In the PC environment force-output has exactly the same effect as finish-output, that is, it does not return until the associated buffer is completely flushed.

LISP: FORMAT

C: L_Format

min args: 2

max args: -1

[F][CLTL 22]

SYNOPSIS:

format destination control-string &rest arguments

DESCRIPTION:

Format is used to produce very general formatted output, in much the same way that printf does in the C language. The facility has many specialized features and allows fine control over the positioning of output. However format is still grasped easily by beginners whose output needs have exceeded the capabilities of the simple print, princ, pprint, prin1 and terpri functions.

Format uses 'directives' to control the printing of its arguments. Directives are preceded by tildes (~).

Refer to the following entries for detailed descriptions of each format directive:

~A ascii

~S ascii

~D decimal

~B binary

~O octal

~X hex

~P plural

~C character

~F floating point

~E exponential floating point

~G general floating point

~$ dollars floating point

~% newline

~<newline> ignore newline

~& fresh line

~| page

~~ tilde

~T tabulate

~* skip

NOTE:

Star Sapphire does not yet implement all format directives specified by ANSI Common LISP; however, the directives that have been implemented are complete (except for some options pertaining to ~R).

Destination

The output is sent to destination.

Destination can be one of the following:

t

the output is the stream *standard-output*

nil

a new string is generated containing the output

a string

the output is appended to the string

a stream

the output is sent to that stream

The first two situations are the most commonly seen.

The value returned by format in the case of a destination of t or a stream is nil; as a side effect the output is sent to the respective stream. In the case of a destination of nil or a string, the return value is the string created or altered.

One minor difference between Star Sapphire and ANSI Common LISP is that the specification states that with a string argument, the string must have a fill pointer. In Star Sapphire, a string destination is not required to have a fill pointer; output is always appended to the string.

CONTROL STRING

The control-string consists of format directives preceeded by a tilde (~), which are replaced in the output by their respective argument printed in some fashion. All other characters are passed through to the output as-is.

For instance, the ~D directive prints an integer. If the value of x is 5:

(format nil "The answer is ~D." x)

returns the string

"The answer is 5."

Most directives consume an argument from the &rest arguments. It is an error if no argument remains for a directive requiring an argument, but it is not an error if one or more arguments remain unprocessed by a directive. Other directives do not consume any arguments, but insert control characters or explicitly skip arguments. For example, ~% inserts a line break in the output.

For instance:

(format t "~s~%~s" 'foo 'bar)

sends the following output to *standard-output*:

FOO

BARNIL

Where nil is the return value from the function.

A string after the tilde specifies what kind of formatting is desired.

A format directive consists of minimally a tilde (~), and a single character indicating what kind of directive this is. The alphabetic case of the directive character is ignored;~s and ~S are identical.

In the full form, a format directive includes optional prefix parameters and modifiers, ending with the same single character.

Prefix parameters are separated by commas and occur in a fixed order. If all successive prefix parameters from a given position are omitted, then those commas optionally need not be written. No spaces may occur between separate prefix parameters (unless a space character is being specifed).

The number, allowable parameters, and meaning of prefix parameters vary depending on the directive. The most complicated are the floating point directives ~e, ~f, and ~g, which can have up to seven separate prefix parameters.

In general prefix parameters are either omitted, numeric arguments, characters, V, v, or #.

Numeric arguments are positive integers.

Character parameters are the actual character preceeded by a single quote; for instance space is represented as ,' , if followed by a comma; the letter x would be represented by 'x.

The V (or v) parameter replaces a prefix parameter to a directive by taking an argument from the format argument list for use as a parameter to the driective. Normally the argument will be an integer or character object. If the argument is nil, the V parameter is treated as if was omitted. This allows runtime control over, for instance, the width of an output field.

The character # in a parameter list represents the number of arguments remaining to be processed.

The modifiers are : and @. These can occur in either order but are traditionally written in that order. The modifiers are the last element in a format directive, just before the directive character.

Here is a simple example. The ~d directive prints an integer in base 10. If one optional prefix argument is specified, the integer is printed in a field of that width:

(format nil ">>>~6d<<<" -54) => ">>> -54<<<

If a second prefix is given to ~d, it must be a character which is used to pad the field:

(format nil ">>>~6,'0d<<<" 54) => ">>>000054<<<

EXAMPLES:

Here are some relatively simple examples to give you the general flavor of how format is used.

(format nil "foo") => "foo"

(setq x 5)

(format nil "The answer is ~D." x) => "The answer is 5."

(setq y "elephant")

(format nil "Look at the ~A!" y) => "Look at the elephant!"

(setq n 3)

(format nil "~D item~:P found." n) => "3 items found."

 

LISP: ~A

(Ascii)

[FORMAT DIRECTIVE][CLTL]

SYNOPSIS:

mincol

minimum pad width (0 default)

colinc

column increment (1 default)

minpad

number of columns (0 default)

padchar

character to pad with (space default)

:

print top level nil as ()

@

pad on left (default right)

DESCRIPTION:

This format directive prints its argument with *print-escape* bound to nil (as if by princ). Basically this inserts the printed representation of an arbitrary LISP object into the output.

The string is padded with at least minpad copies of padchar; padding characters are inserted colinc characters at a time until the total width is at least mincol.

If arg is a string, its characters will be output verbatim. If arg is nil, it will be printed as nil; the colon modifier (~:A) will cause an arg of nil to be printed as (), but if arg is a composite structure, such as a list or vector, any contained ocurrences of nil will still be printed as nil.

~mincolA inserts spaces on the right, if necessary. to make the width at least mincol columns. The @ modifier causes the spaces to be inserted on the left rather than the right.

The full form of ~A is:

~mincol, colinc, minpad, padcharA

which allows full control of the padding. The string is padded on the right (or on the left if the @ is specified). Characters are then inserted colinc characters at a time until the total width is at least mincol. The defaults are 0 for mincol and minpad, 1 for colinc, and the space character for padchar.

 

LISP: ~S

Ascii

[FORMAT DIRECTIVE][CLTL]

SYNOPSIS:

mincol

minimum pad width (0 default)

colinc

column increment (1 default)

minpad

number of columns (0 default)

padchar

character to pad with (space default)

:

print top level nil as ()

@

pad on left (default right)

DESCRIPTION:

~S is a format directive which prints just like ~A, but with *print-escape* bound to t (as if by prin1).

 

LISP: ~D

Decimal

[FORMAT DIRECTIVE][CLTL]

SYNOPSIS:

mincol

minimum pad width (0 default)

padchar

character to pad with (space default)

commachar

comm character (',' default)

commainterval

digit comma grouping [ANSI] (3 default)

:

print commas between groups of commainterval digits

@

always print sign

DESCRIPTION:

~D is a format directive which prints an integer argument in base 10.

If the argument is not an integer it is printed as if by ~A in decimal base.

~D never puts a decimal point after the number.

~mincolD uses a column width of mincol; spaces are inserted on the left if the number requires fewer than mincol columns for its digits and sign. If the number doesn't fit in mincol columns, additional columns are used as needed.

~mincol, padcharD uses padchar as the pad character instead of space.

If arg is not an integer, it is printed in ~A format and decimal base.

The @ modifier causes the number's sign to be printed always; the default is to print it only if the number is negative.

The : modifier causes commas to be printed between groups of digits; commachar may be used to change the character used as the comma. comma-interval must be an integer and defaults to 3. When the : modifier is given to any of these directives, the commachar is printed between groups of comma-interval digits.

Thus, the most general form of ~D is

~mincol, padchar, commachar, comma-intervalD.

~D binds *print-escape* to false, *print-radix* to false, *print-base* to 10, and *print-readably* to false.

 

LISP: ~B

Binary

[FORMAT DIRECTIVE][CLTL]

SYNOPSIS:

mincol

minimum pad width (0 default)

padchar

character to pad with (space default)

commachar

comm character (',' default)

commainterval

digit comma grouping [ANSI] (3 default)

:

print commas between groups of commainterval digits

@

always print sign

DESCRIPTION:

This format directive is just like ~D with *print-base* bound to 2.

 

LISP: ~O

Octal

[FORMAT DIRECTIVE][CLTL]

SYNOPSIS:

mincol

minimum pad width (0 default)

padchar

character to pad with (space default)

commachar

comm character (',' default)

commainterval

digit comma grouping [ANSI] (3 default)

:

print commas between groups of commainterval digits

@

always print sign

DESCRIPTION:

This format directive is just like ~D with *print-base* bound to 8.

 

LISP: ~X

HeX

[FORMAT DIRECTIVE][CLTL]

SYNOPSIS:

mincol

minimum pad width (0 default)

padchar

character to pad with (space default)

commachar

comm character (',' default)

commainterval

digit comma grouping [ANSI] (3 default)

:

print commas between groups of commainterval digits

@

always print sign

DESCRIPTION:

This format directive is just like ~D with *print-base* bound to 16.

 

LISP: ~R

Radix

[FORMAT DIRECTIVE][CLTL]

SYNOPSIS:

n

print arg in base n

mincol

as for ~D

padchar

as for ~D

commachar

as for ~D

comma-interval

as for ~D

DESCRIPTION:

The ~R format directive prints an integer in an arbitary radix (number base). The n argument is required in this implementation. The ANSI Common LISP specification states that if n is missing, the number is printed as a cardinal number or in Roman numerals; this is not yet supported in Star Sapphire.

The modifier flags and any remaining parameters are used as for the ~D directive.

~D is the same as ~10R. The full form is:

~radix, mincol, padchar, commachar, comma-intervalR.

 

LISP: ~P

Plural

[FORMAT DIRECTIVE][CLTL]

SYNOPSIS:

:

prints a lowercase 's' if the last argument was not 1.

@

print 'y' if the argument is 1, or 'ies' if not.

:@

print 'y' if the last argument was 1, or 'ies' if not.

DESCRIPTION:

The ~P format directive outputs pluralization.

If arg is not eql to the integer 1, a lowercase s is printed; if arg is eql to 1, nothing is printed. If arg is a floating-point 1.0, the s is printed.

~:P does the same thing, after doing a ~:* to back up one argument; that is, it prints a lowercase s if the previous argument was not 1.

~@P prints y if the argument is 1, or ies if it is not.

~:@P does the same thing, but backs up first.

EXAMPLES:

(format nil "~D tr~ :@P/~D win~:P" 7 1) [outputs] "7 tries/1 win"

(format nil "~D tr~ :@P/~D win~:P" 1 0) [outputs] "1 try/0 wins"

(format nil "~D tr~ :@P/~D win~:P" 1 3) [outputs] "1 try/3 wins"

 

LISP: ~C

Character

[FORMAT DIRECTIVE][CLTL]

SYNOPSIS:

:

spell out character name

@

also print keyboard hint for unusual keys

:@

print in LISP reader-compatible format with #\ prefix

DESCRIPTION:

~C is the character format directive.

The next arg should be a character; it is printed according to the modifier flags.

~C prints the character as if by using write-char, if it is a simple character. Characters that are not simple are not necessarily printed as if by write-char, but are displayed in an implementation-defined, abbreviated format. For example,

(format nil "~C" #\A) [outputs] "A"

(format nil "~C" #\Space) [outputs] " "

~:C is the same as ~C for printing characters, but other characters are spelled out. The intent is that this is a pretty format for printing characters. For simple characters that are not printing, what is spelled out is the name of the character (see char-name). For characters that are not simple and not printing, what is spelled out is implementation-defined.

For example,

(format nil "~:C" #\A) [outputs] "A"

(format nil "~:C" #\Space) [outputs] "Space"

;; This next example assumes an

;; implementation-defined "Control" attribute.

(format nil "~:C" #\Control-Space)

[outputs] "Control-Space" [or] "c-Space"

~:@C prints what ~:C would, and then if the character requires unusual shift keys on the keyboard to type it, this fact is mentioned.

This is the format used for telling the user about a key he or she is expected to type, in prompts, for instance. This is an implementation dependent format.

~@C prints the character in a way the the Lisp reader can understand, using #\ syntax.

~@C binds *print-escape* to t.

 

LISP: ~F

floating point

[FORMAT DIRECTIVE][CLTL]

SYNOPSIS:

@

always print sign

d

digits after decimal point

k

scale factor

ovchr

overflow character

padchr

padding character

w

field width

DESCRIPTION:

~F is the fixed-format floating-point format directive. The next arg is printed as a float.

The full form is

~w,d,k,overflowchar,padcharF

The parameter w is the width of the field to be printed; d is the number of digits to print after the decimal point: k is a scale factor that defaults to zero.

Exactly w characters will be output. First, leading copies of the character padchar (which defaults to a space,) are printed, if necessary, to pad the field on the left.

If the arg is negative, then a minus sign is printed; if the arg is not negative, then a plus sign is printed if and only if the @ modifier was supplied.

Then a sequence of digits, containing a single embedded decimal point, is printed; this represents the magnitude of the value of arg times 10k, rounded to d fractional digits. When rounding up and rounding down would produce printed valuses equidistant from the scaled value of arg, then the implemenation is free to use either one. For example, printing the argument 6.375 using the format ~4,2F may correctly produce either 6.37 or 6.38. Leading zeros are not permitted, except that a single zero digit is output before the decimal point if the printed value is less that one, and this single zero digit is not output at all if w=d+1.

If it is impossible to print the value in the required format in a field of width w, then one of two actions is taken. If the parameter overflowchar is supplied, then w copies of that parameter are printed instead of the scaled value of arg. If the overflowchar parameter is omitted, then the scaled value is printed using more than w characters, as many more as may be needed.

If the w parameter is omitted, then the field is of variable width. In effect, a value is chosen for w in such a way that no leading pad characters need to be printed and exactly d characters will follow the decimal point. For example, the directive ~,2F will print exactly two digits after the decimal point and as many as necessary before the decimal point.

If the parameter d is omitted, then there is no constraint on the number of digits to appear after the decimal point. A value is chosen for d in such a way that as many digits as possible may be printed subject to the width constraint imposed by the parameter w and the constraint that no trailing zero digits may appear in the fraction, except that if the fraction to be printed is zero, then a single zero digit should appear after the decimal point if permitted by the width constraint.

If both w and d are omitted, then the effect is to print the value using ordinary free-format output. prin1 uses this format for any number whose magnitude is either zero or between 10-3 (inclusive) and 107 (exclusive).

If w is omitted, then if the magnitude of arg is so large (or, if d is also omitted, so small) that more than 100 digits would have to be printed, then an implementation is free, at its discretion, to print the number using exponential notation instead, as if by the directive ~E (with all parameters to ~E defaulted, not taking their values from the ~F directive). This implementation does not do this.

If arg is a rational number, then it is coerced to be a single float and then printed. Alternatively, an implementation is permitted to process a rational number by any other method that has essentially the same behavior but avoids loss of precision or overflow because of the coercion. If w and d are not supplied, and the number has no exact decimal representation, for example 1/3, some precision cutoff must be chosen by the implementation since only a finite number of digits may be printed.

If arg is a complex number or some non-numeric object, then it is printed using the format directive ~wD, thereby printing it in decimal radix and a minimum field width of w.

~F binds *print-escape* to false and *print-readably* to false.

 

LISP: ~E

exponential floating point

[FORMAT DIRECTIVE][CLTL]

SYNOPSIS:

w

field width

d

digits after decimal point

e

exponent digits

k

scale factor

ovchr

overflow character

padchr

padding character

expchr

exponenet character

@

always print sign

DESCRIPTION:

The ~E format directive prints the next argument as a float in exponential notation.

The full form is:

~w,d,e,k,overflowchar,padchar,exponentcharE.

The parameter w is the width of the field to be printed; d is the number of digits to print after the decimal point; e is the number of digits to use when printing the exponent; k is a scale factor that defaults to one (not zero).

Exactly w characters will be output. First, leading copies of the character padchar (which defaults to a space) are printed, if necessary, to pad the field on the left.

If the arg is negative, then a minus sign is printed; if the arg is not negative, then a plus sign is printed if and only if the @ modifier was supplied. Then a sequence of digits containing a single embedded decimal point is printed. The form of this sequence of digits depends on the scale factor k.

If k is zero, then d digits are printed after the decimal point, and a single zero digit appears before the decimal point if the total field width will permit it. If k is positive, then it must be strictly less than d+2; k significant digits are printed before the decimal point, and d-k+1 digits are printed after the decimal point. If k is negative, then it must be strictly greater that -d; a single zero digit appears before the decimal point if the total field width will permit it, and after the decimal point are printed first -k zeros and then d+k significant digits. The printed fraction must be properly rounded. When rounding up and rounding down, if the result would produce printed values equidistant from the scaled value of arg, then the implementation is free to use either one. Star Sapphire scales up.

For example, printing the argument 637.5 using the format ~8,2E may correctly produce either 6.37E+2 or 6.38E+2.

Following the digit sequence, the exponent is printed. First the character parameter exponentchar is printed; if this parameter is omitted, then the exponent marker that prin1 would use is printed, as determined from the type of the float and the current value of *read-default-float-format*. Next, either a plus sign or a minus sign is printed, followed by e digits representing the power of ten by which the printed fraction must be multiplied to properly represent the rounded value of arg.

If it is impossible to print the value in the required format in a field of width w, possibly beause k is too large or too small or because the exponent cannot be printed in e character positions, then one of two actions is taken.

If the parameter overflowchar is supplied, then w copies of that parameter are printed instead of the scaled value of arg.

If the overflowchar parameter is omitted, then the scaled value is printed using more than w characters, as many more as may be needed; if the problem is that d is too small for the supplied k or that e is too small, then a larger value is used for d or e as may be needed.

If the w parameter is omitted, then the field is of variable width. In effect a value is chosen for w in such a way that no leading pad characters need to be printed.

If the parameter d is omitted, then there is no constraint on the number of digits to appear. A value is chosen for d in such a way that as many digits as possible may be printed subject to the width constraint imposed by the parameter w, the constraint of the scale factor k, and the constraint that no trailing zero digits may appear in the fraction, except that if the fraction to be printed is zero then a single zero digit should appear after the decimal point.

If the parameter e is omitted, then the exponent is printed using the smallest number of digits necessary to represent its value.

If all of w, d, and e are omitted, then the effect is to print the value using ordinary free-format exponential-notation output: prin1 uses a similar format for any non-zero number whose magnitude is less than 10-3 or greater than or equal to 107.

The only difference is that the ~E directive always prints a plus or minus sign in front of the exponent, while prin1 omits the plus sign if the exponent is non-negative.

If arg is a rational number, then it is coerced to be a single float and then printed. Alternatively, an implementation is permitted to process a rational number by any other method that has esentially the same behavior but avoids loss of precision or overflow because of the coercion. If w and d are unsupplied and the number has no exact decimal representation, for example 1/3, some precision cutoff must be chosen by the implementation since only a finite number of digits may be printed.

If arg is a complex number or some non-numeric object, then it is printed using the format directive ~wD, thereby printing it in decimal radix and a minimum field width of w.

~E binds *print-escape* to false and *print-readably* to false.

 

LISP: ~G

general floating point

[FORMAT DIRECTIVE][CLTL]

SYNOPSIS:

w

width

d

digits after decimal point

e

exponent width

k

scale factor

ovflchr

overflow character

padchr

padding character

expchr

exponent character

@

always sign

Description:

~G is the general floating-point format directive. The next arg is printed as a float in either fixed-format or exponential notation as appropriate.

The full form is

~w,d,e,k,overflowchar,padchar,exponentcharG.

The format in which to print arg depends on the magnitude (absolute value) of the arg. Let n be an integer such that

10n-1 <= |arg| < 10n

Let ee equal e+2, or 4 if e is omitted. Let ww equal w-ee, or nil if w is omitted. If d is omitted, first let q be the number of digits needed to print arg with no loss of information and without leading or trailing zeros; then let d equal (max q (min n 7)). Let dd equal d-n.

If 0 <= dd <= d, then arg is printed as if by the format directives

~ww, dd,, overflowchar, padcharF~ee@T

Note that the scale factor k is not passed to the ~F directive. For all other values of dd, arg is printed as if by the format directive

~w, d, e, k, overflowchar, padchar, exponentcharE.

In either case, an @ modifier is supplied to the ~F or ~E directive if and only if one was supplied to the ~G directive.

~G binds *print-escape* to false and *print-readably* to false.

 

LISP: ~$

Dollars floating-point.

[FORMAT DIRECTIVE][CLTL]

SYNOPSIS:

d

digits after decimal point

n

minimum digits before decimal point

w

minimum width of field

padchr

padding character

@

always sign

:

sign before padding (default is after)

DESCRIPTION:

~$ is the dollars floating point format directive.

The next arg is printed as a float in fixed-format notation. Note that this does not print a currency symbol; rather it prints a floating point in a format that is typical for printing amounts of currency.

The full form is

~d, n, w, padchar$

The parameter d is the number of digits to print after the decimal point (default value 2); n is the minimum number of digits to print before the decimal point (default value 1); w is the minimum total width of the field to be printed (default value 0).

Fist padding and the sign are output. If the arg is negative, then a minus sign is printed; if the arg is not negative, then a plus sign is printed if and only if the @ modifier was supplied. If the : modifier is used, the sign appears before any padding, and otherwise after the padding.

If w is supplied and the number of other characters to be output is less than w, then enough copies of padchar (which defaults to a space) are output to make the total field width equal w. Then n digits are printed for the integer part of arg, with leading zeros if necessary; then a decimal point; then d digits of fraction, properly rounded.

If the magnitude of arg is so large that more than m digits would have to be printed, where m is the larger of w and 100, then an implementation is free, at its discretion, to print the number using exponential notation instead, as if by the directive

~w, q,,,,padcharE,

where w and padchar are present or omitted according to whether they were present or omitted in the ~$ directive, and where q=d+n-1, where d and n are the (possibly default) values given to the ~$ directive.

If arg is a rational number, then it is coerced to be a single float and then printed. Alternatively, an implementation is permitted to process a rational number by any other method that has essentially the same behavior but avoids loss of precision or overflow because of the coercion.

If arg is a complex number or some non-numeric object, then it is printed using the format directive ~wD, thereby printing it in decimal radix and a minimum field width of w.

~$ binds *print-escape* to false and *print-readably* to false.

 

LISP: ~%

output newline

[FORMAT DIRECTIVE][CLTL]

SYNOPSIS:

n

number of newlines to output

DESCRIPTION:

The ~% format directive outputs a newline. ~n% outputs n newlines.

You can also include newlines in format directives by inserting an actual newline in the string; however, ~% is typically used in format directives so that that line separation is explicit.

 

LISP ~<newline>

ignore newline

[FORMAT DIRECTIVE][CLTL]

SYNOPSIS:

:

newline ignored, leave whitespace

@

whitespace ignored, leave newline

DESCRIPTION:

~<newline> is the ‘ignore newline’ format directive.

Tilde immediately followed by an actual newline ignores the newline and any following non-newline whitespace characters.

With a :, the newline is ignored, but any following whitespace is left in place. With an @, the newline is left in place, but any following whitespace is ignored.

 

LISP: ~&

output fresh line

[FORMAT DIRECTIVE][CLTL]

SYNOPSIS:

n

number of newlines to output

DESCRIPTION:

Unless it can be determined that the output stream is already at the beginning of a line, the ~& format directive outputs a newline. ~n& calls fresh-line and then outputs n-1 newlines. ~0& (tilde zero ampersand) does nothing.

 

LISP: ~|

form feed

[FORMAT DIRECTIVE][CLTL]

SYNOPSIS:

n

number of form feeds to output

DESCRIPTION:

This format directive outputs a page separator character by outputting a CTRL-L character. ~n| (tilde n vertical-bar) does this n times.

 

LISP: ~~

tilde

[FORMAT DIRECTIVE][CLTL]

SYNOPSIS:

n

number of tildes to output

DESCRIPTION:

The ~~ format directive outputs a tilde.

~n~ outputs n tildes.

 

LISP: ~T

tabulate

[FORMAT DIRECTIVE][CLTL]

SYNOPSIS:

colnum

column

colinc

column width

:

tabulate relative to current position

@

relative tabulation

DESCRIPTION:

This format directive spaces over to a given column by putting spaces into the output stream. Note that to output an actual tab character (the ASCII character with the value 9) you can put the tab character in the format directive or use ~c with the argument #\tab.

~colnum, colincT will output sufficient spaces to move the cursor to column colnum. If the cursor is already at or beyond column colnum, it will output spaces to move it to column colnum+(k*colinc) for the smallest positive integer k possible, unless colinc is zero, in which case no spaces are output if the cursor is already at or beyond column colnum. colnum and colinc default to 1.

The Star Sapphire ~T algorithm deduces the current column position by noting that certain directives cause the column position to be reset to zero. The column is calculated using an internal stream count of the number of characters put on the given stream since creation of the stream.

The count is saved whenever a format invocation starts or a ~% or ~& is used and subtracted from the current count to get a logical column. Although this may not always correspond to the physical screen column, it at allows consistent output, regardless of the stream type.

~@T performs relative tabulation. ~colre, colinc@T outputs colrel spaces and then outputs the smallest non-negative number of additional spaces necessary to move the cursor to a column that is a multiple of colinc. For example, the directive ~3,8@T outputs three spaces and then moves the cursor to a "standard multiple-of-eight tab stop" if not at one already. If the current output column cannot be determined, however, then colinc is ignored, and exactly colrel spaces are output.

If the colon modifier is used with the ~T directive, the tabbing computation is done relative to the horizontal position where the section immediately containing the directive begins, rather than with respect to a horizontal position of zero. The default for both parameters in this case is 1.

 

LISP: ~*

ignore argument

[FORMAT DIRECTIVE][CLTL]

SYNOPSIS:

n

number to ignore

:

back up

@

absolute argument position

DESCRIPTION:

This format directive ignores the next arg. ~n* ignores the next n arguments.

~:* backs up in the list of arguments so that the argument last processed will be processed again. ~n:* backs up n arguments.

~n@* goes to the nth arg, where 0 means the first one; n defaults to 0, so ~@* goes back to the first arg. Directives after a ~n@* will take arguments in sequence beginning with the one gone to.

 

LISP: FOURTH

C: Lfourth

min args: 1

max args: 1

[F][CLTL 15]

SYNOPSIS:

fourth list

DESCRIPTION:

See first.

 

LISP: FRESH-LINE

C: FrshLn

min args: 0

max args: 1

[F][CLTL 22]

SYNOPSIS:

fresh-line &optional output-stream

DESCRIPTION:

fresh-line is similar to terpri but outputs a newline only if the stream is not already at the start of a line. (If for some reason this cannot be determined, then a newline is output anyway.) This guarantees that the stream will be on a "fresh line" while consuming as little vertical distance as possible. fresh-line returns t if a newline was output and nil otherwise.

 

LISP: FROUND

C: Lfround

min args: 1

max args: 2

[F][CLTL 12]

SYNOPSIS:

fround number &optional divisor

DESCRIPTION:

This function is just like round except that the result (the first result of two) is always a floating-point number rather than an integer. It is roughly as if fround gave its arguments to round, and then applied float to the first result before passing them both back.

 

LISP: FTRUNCATE

C: Lftruncate

min args: 1

max args: 2

[F][CLTL 12]

SYNOPSIS:

ftruncate number &optional divisor

DESCRIPTION:

This function is just like truncate except that the result (the first result of two) is always a floating-point number rather than an integer. It is roughly as if ftruncate gave its arguments to truncate, and then applied float to the first result before passing them both back.

 

LISP: FUNCALL

C: LFuncall

min args: 1

max args: -1

[F][CLTL 7]

SYNOPSIS:

funcall fn &rest arguments

DESCRIPTION:

(funcall fn al a2 ... an) applies the function fn to the arguments a1, a2, ..., an. fn may not be a special form nor a macro; this would not be meaningful. For example:

(cons 1 2) => (1 . 2)

(setq cons (symbol-function '+))

(funcall cons 1 2) => 3

The difference between funcall and an ordinary function call is that the function is obtained by ordinary LISP evaluation rather than by the special interpretation of the function position that normally occurs.

 

LISP: FUNCTION

C: SFCFunc, EFunction

[S][CLTL 7]

SYNOPSIS:

function fn

DESCRIPTION:

The function special form evaluates to an object which embodies the functional definition of its argument. The argument is not evaluated before function gets to it (i.e., does not otherwise need quoting).

In the simplest case, function is run with a simple symbol argument; this extracts the functional definition of the symbol. This can be used in any context where a function is needed, such as for the map functions:

(mapcar (function cons) '(x a b)'(d e f))

The function special form can also be used to explore one of the most interesting capabilities of LISP: closures. A closure, roughly, is an anonymous function which retains its internal state. A closure is returned when function is given a lambda expression as its argument.

Technically speaking, the sole argument fn of the function special form is interpreted as if it had appeared in the functional position of a functional invocation.

A standard macro-character abbreviation is defined for function. Any form f preceeded by #' (poundsign quote) is assumed to have

(function ...)

wrapped around it to make

(function f)

For instance, the example above could be written:

(mapcar #'cons '(x a b)'(d e f))

In any case, the return value from function can be used in its own right for application to arguments, just as if it were a lambda expression, or a meaningful symbol at the head of a list, previously defined using defun; the object which is the value of a function call can be stored in a variable for later use, etc.

This object is termed a functional object.

The value of function is always the functional interpretation of fn.

If fn is a symbol, the functional definition associated with that symbol is returned (see symbol-function).

If fn is a lambda-expression, then a lexical closure is returned.

A lexical closure is a function that, when invoked, will execute the body of the lambda-expression in such a way as to observe the rules of lexical scoping properly. For example:

(defun adder (x) (function (lambda (y) (+ x y))))

The result of (adder 3) is a function that will add 3 to its argument:

(setq add3 (adder 3))

(funcall add3 5) => 8

This works because function creates a closure of the inner lambda-expression that is able to refer to the value 3 of the variable x even after control has returned from the function adder.

More generally, a lexical closure in effect retains the ability to refer to lexically visible bindings, not just values. Consider this code:

(defun two-funs (x)

(list (function (lambda () x))

(function (lambda (y) (setq x y)))))

(setq funs (two-funs 6))

(funcall (car funs)) => 6

(funcall (cadr funs) 43) => 43

(funcall (car funs)) => 43

The function two-funs returns a list of two functions, each of which refers to the binding of the variable x created on entry to the function two-funs when it was called with argument 6. This binding has the value 6 initially, but setq can alter a binding. The lexical closure created for the first lambda-expression does not "snapshot" the value 6 for x when the closure is created. The second function can be used to alter the binding (to 43, in the example), and this altered value then becomes accessible to the first function.

In situations where a closure of a lambda-expression over the same set of bindings may be produced more than once, the various resulting closures may or may not be eq, at the discretion of the implementation. For example:

(let ((x 5) (funs '()))

(dotimes (j 10)

(push #'(lambda (z)

(if (null z) (setq x 0) (+ x z)))

funs))

funs)

The result of the above expression is a list of ten closures. Each logically requires only the binding of x. It is the same binding in each case, so the ten closures may or may not be the same identical (eq) object. On the other hand, the result of the expression

(let ((funs '()))

(dotimes (j 10)

(let ((x 5))

(push (function (lambda (z)

(if (null z) (setq x 0) (+ x z))))

funs)))

fns)

is also a list of ten closures. However, in this case no two of the closures may be eq, because each closure is over a distinct binding of x, and these bindings can be behaviorally distinguished because of the use of setq.

The question of distinguishable behavior is important; the result of the simpler expression

(let ((funs '()))

(dotimes (j 10)

(let ((x 5))

(push (function (lambda (z) (+ x z)))

funs)))

funs)

is a list of ten closures that may be pairwise eq. Although one might think that a different binding of x is involved for each closure (which is indeed the case), the bindings cannot be distinguished because their values are identical and immutable, there being no occurrence of setq on x. A compiler would therefore be justified in transforming the expression to

(let ((funs '()))

(dotimes (j 10)

(push (function (lambda (z) (+ 5 z)))

funs))

funs)

where clearly the closures may be the same after all. The general rule, then, is that the implementation is free to have two distinct evaluations of the same function form produce identical (eq) closures if it can prove that the two conceptually distinct resulting closures must in fact be behaviorally identical with respect to invocation. This is merely a permitted optimization; a perfectly valid implementation might simply cause every distinct evaluation of a function form to produce a new closure object not eq to any other.

Frequently a compiler can deduce that a closure in fact does not need to close over any variable bindings. For example, in the code fragment

(mapcar (function (lambda (x) (+ x 2))) y)

the function (lambda (x) (+ x 2)) contains no references to any outside entity. In this important special case, the same "closure" may be used as the value for all evaluations of the function special form. Indeed, this value need not be a closure object at all; it may be a simple compiled function containing no environment information. This example is simply a special case of the foregoing discussion and is included as a hint to implementators familiar with previous methods of implementing LISP. The distinction between closures and other kinds of functions is somewhat pointless, actually, as Common LISP defines no particular representation for closures and no way to distinguish between closures and non-closure functions. All that matters is that the rules of lexical scoping be obeyed.

 

LISP: FUNCTION (typespec)

[Typespec][CLTL 4]

SYNOPSIS:

function

DESCRIPTION:

This is the type specifier for functional objects. This is also used in declarations in a type specifier list format.

EXAMPLES

(typep #'car 'function) => t

(typep #'(lambda(x)(* x x)) 'function) => t

 

LISP: FUNCTIONP

C: Lfuncp

min args: 1

max args: 1

[F][CLTL 6]

SYNOPSIS:

functionp object

DESCRIPTION:

functionp returns t if object is suitable for applying to arguments, using for example the funcall or apply function. Otherwise functionp returns nil.

functionp is always true of symbols, lists whose car is the symbol lambda, any value returned by the function special form, and any values returned by the function compile when the first argument is nil.