Star Sapphire Common LISP Home

Download Star Saphire
Index

LISP: T

C: tsym

[C][CLTL 6]

SYNOPSIS:

t

DESCRIPTION:

The name t is a predefined constant in Common LISP.

t is a symbol like any other symbol. It appears to be treated as a variable when evaluated. However, it is not permitted to modify its value, as if it were defined by defconstant.

The value of t is always t.

LISP: T (typespec)

[Typespec][CLTL 4]

SYNOPSIS:

t

DESCRIPTION:

The type specifier t includes the set of all objects of any type whatsoever; it is the complement of the type specifier nil.

LISP: TAGBODY

C: SFCTagBdy, ETagBd

[S][CLTL 7]

SYNOPSIS:

tagbody {tag | statement}*

DESCRIPTION:

A tagbody creates a lexical scope for tags and their associated gos. The part of a tagbody after the variable is called the body. An item in the body may be a symbol or an integer, in which case it is called a tag, or an item in the body may be a list, in which case it is called a statement.

Each element of the body is processed from left to right. A tag is ignored; a statement is evaluated, and its results are discarded. If the end of the body is reached, the tagbody returns nil.

If (go tag) is evaluated, control jumps to the part of the body labelled with the tag.

The scope of the tags established by a tagbody is lexical, and the extent is dynamic. Once a tagbody construct has been exited, it is no longer legal to go to a tag in its body. It is permissible for a go to jump to a tagbody that is not the innermost tagbody construct containing that go; the tags established by a tagbody will only shadow other tags of like name.

The lexical scoping of the go targets named by tags is fully general and has consequences that may be surprising to users and implementors of other LISP systems. For example, the go in the following example actually does "work" in Common LISP as one might expect:

(tagbody

(catch 'stuff

(mapcar #'(lambda (x) (if (numberp x)

(hairyfun x)

(go lose)))

items))

(return)

lose

(error "I lost big!"))

Depending on the situation, a go in Common LISP does not necessarily correspond to a simple machine "jump" instruction! A go can break up catchers if necessary to get to the target. It is possible for a "closure" created by function for a lambda-expression to refer to a go target as long as the tag is lexically apparent. See Chapter 3 for an elaborate example of this.

LISP: TAILP

C: Ltailp

min args: 2

max args: 2

[F][CLTL 15]

SYNOPSIS:

tailp sublist list

DESCRIPTION:

This predicate is true if sublist is a sublist of list (i.e., one of the conses that makes up list); otherwise it is false. Another way to look at this is that tailp is true if (nthcdr n list) is sublist, for some value of n.

SEE ALSO:

ldiff.

LISP: TAN

C: Ltan

min args: 1

max args: 1

[F][CLTL 12]

SYNOPSIS:

tan radians

DESCRIPTION:

tan returns the tangent of the argument. The argument is in radians.

LISP: TENTH

C: Ltenth

min args: 1

max args: 1

[F][CLTL 12]

SYNOPSIS:

tenth list

DESCRIPTION:

See first.

LISP: TERPRI

C: Terpri

min args: 0

max args: 1

[F][CLTL 22]

SYNOPSIS:

terpri &optional output-stream

DESCRIPTION:

terpri outputs a newline to output-stream. It is identical in effect to

(write-char #\Newline output-stream)

terpri returns nil.

LISP: THE

C: SFCThe

[S][CLTL 9]

SYNOPSIS:

the value-type form

DESCRIPTION:

The form is evaluated; whatever it produces is returned by the the form. In addition, it is an error if what is produced by the form does not conform to the data type specified by value-type (which is not evaluated).

In effect, this declares that the user undertakes to guarantee that the value of the form will always be of the specified type.

EXAMPLES:

(the string (copy-seq x)) ;The result will be a string.

(the integer (+. x 3)) ;The result of + will be an integer.

(+ (the integer x) 3) ;The value of x will be an integer.

LISP: THIRD

C: Lthird

min args: 1

max args: 1

[F][CLTL 15]

SYNOPSIS:

third list

DESCRIPTION:

See first.

LISP: THROW

C: SFCThrow, EThrow

[S][CLTL 7]

SYNOPSIS:

throw tag result

DESCRIPTION:

The throw special form jumps to a currently active catch which has a matching tag. The throw defines the result that the catch will return.

First, the tag is evaluated. The tag produces an object called the throw tag. Note that the tag must be quoted if it is a symbol.

Then the result form is evaluated.

The most recent outstanding catch whose tag matches the throw tag is exited. A catch matches only if its catch tag is strictly eq to the throw tag.

All values returned by result are returned as the value(s) of the catch. Note that this allows multiple return values; if the result form returns zero values, catch will return zero values; if result returns three values, catch will likewise return three values. Note also that the result form is evaluated before the unwinding process commences. In the process: Dynamic variable bindings are undone back to the point of the catch. Any intervening unwind-protect cleanup code is run.

It is an error if there is no outstanding catcher whose tag is eq to the throw tag. If this is the case, no unwinding of the stack is performed. When the error is signalled, the dynamic variable bindings and outstanding catchers are unchanged from the time of throw.

For an example of throw, see catch.

LISP: TIME

C: LispTime

min args: 1

max args: 1

[M][CLTL 25]

SYNOPSIS:

time form

DESCRIPTION:

This evaluates form and returns what the form returns. As a side effect, the total time spent in evaluation (not reading, printing or compiling) is printed to standard output.

The time macro is specified in time.lsp. This file needs to be loaded in order to use the macro. Note that if you are not running on an AT class PC or higher, you will need to alter this macro slightly (see get-internal-run-time).

The windows specific version of this macro is in the file wintime.lsp.

LISP: TIME-OF-DAY

C: TOD

min args: 0

max args: 2

[F][SSCL]

SYNOPSIS:

time-of-day &optional universal-time date-format-string

DESCRIPTION:

With no arguments, this function simply returns a string which is the current time of day in a default, conventional human-readable format. This is a Star Sapphire specific function.

The default output string format looks like:

(time-of-day) => "Tue Oct 17 17:07:06 1989"

If a first argument is given and is not nil, it must be an integer, representing a universal time value. The argument in this case is decoded and converted into a string. This is particularly useful for applications like:

(time-of-day (file-write-date ...))

If the first argument is nil, the current time is used (as in the no-arguments case).

If there is a second argument it must be a string. The string specifies the date printing format. Tilde preceeded characters are called date-format specifiers and indicate a component of the date to print; the date-format specifiers are given in the table at the end of this entry. All other characters in the date-format string are printed verbatim.

For example:

(time-of-day nil

"today is ~A, ~B ~d ~Y; it is ~j days since New Years.")

=>

"today is Tuesday, October 17 1989, it is 290 days since New Years."

The date-format string can be used to print dates in various national formats (for instance British dates are written "~d/~m/~y", as opposed to the US "~m/~d/~y").

The return value can be assigned to a variable for later use, or printed using format, princ, and so on.

The date-format specifiers are described in the following table . Note that 'zero-based' means that the item is printed as an integer from 0 to max-1, and 'one-based' means that the item is printed as an integer from 1 to max.

~~ the character ~

~a abbreviated weekday name

~A full weekday name

~b abbreviated month name

~B full month name

~c date and time

~d two-digit one-based day of the month

~H two-digit zero-based hour in 24 hour format

~I two-digit one-based hour in 12 hour format

~j three-digit one-based day of the year

~m two-digit month as a decimal number

~M two-digit zero-based minute

~p AM or PM

~S two-digit zero-based second

~U two-digit zero-based week number in year where Sunday is the first day of the week

~w zero-based weekday number where Sunday is the first day of the week.

~W two-digit zero-based week number in year where Monday is the first day of the week

~x date in default format

~X time in default format

~y two digit year without century

~Y year with century

~Z Time-zone name, or no characters if time-zone not set

NOTES:

The format is simply the ANSI C strftime() format with all instances of '~' converted to '%'.

The time-zone defaults to EST: Use the DOS environment variable 'TZ' to set the time-zone (see Chapter 25).

BUGS:

The format string and its expansion must contain less than 256 characters. Universal times before 1970 do not work correctly.

LISP: TOP-LEVEL-PRINT

C: LG_TLP

min args: 1

max args: 1

[F][SSCL]

SYNOPSIS:

top-level-print value

DESCRIPTION:

This Star Sapphire function turns on or off the print function of the read-eval-print loop. If value is nil, printing will be turned off, and if value' is t, top level LISP printing will be turned on.

This is done by setting a flag in the LISP toplevel function.

Note that any printing by other means (such as explicit calls to princ or format, or any of the text functions) will occur normally.

This is provided for programs which perform screen or graphics output requiring complete control over program output to the screen.

LISP: TRACE

C: L_Trace

min args: 0

max args: -1

[F][CLTL 25]

SYNOPSIS:

trace &rest function-name

DESCRIPTION:

Invoking trace with one or more function-names (symbols) causes the functions named to be traced. Henceforth, whenever such a function is invoked, information about the call, the arguments passed, and the eventually returned values, if any, will be printed to standard output.

Invoking untrace with one or more function names will cause those functions not to be traced any more.

Tracing an already traced function, or untracing a function not currently being traced, should produce no harmful effects, but may produce a warning message.

Calling trace with no argument forms will return a list of functions currently being traced.

Calling untrace with no argument forms will cause all currently traced functions to be no longer traced.

SEE ALSO:

untrace, tracef, mtrace

NOTE:

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

LISP: TRACEF

C: Ltracef

min args: 0

max args: -1

[F][SSCL]

SYNOPSIS:

tracef &rest function-name

DESCRIPTION:

Essentially this Star Sapphire specific facility does exactly the same thing as trace except that the output from the trace will not list the arguments or values of the function being called. This is handy if all you want to know is which function is being entered or exited in the execution trace. Viewing or printing the arguments and values The alternative is to set *print-length* and *print-depth* to some minimal values while tracing is going on; however, tracef may be more convenient.

tracef has the same arguments and relationship with untrace as trace.

SEE ALSO:

trace, untrace, mtrace

LISP: TREE-EQUAL

C: Ltree_equal

min args: 2

max args: -1

[F][CLTL 15]

SYNOPSIS:

tree-equal x y &key :test :test-not

DESCRIPTION:

This is a predicate that is true if x and y are isomorphic trees with identical leaves, that is, if x and y are atoms that satisfy the test (by default ), or if they are both conses and their car's are tree-equal and their cdr's are tree-equal. Thus tree-equal recursively compares conses (but not any other objects that have components). See equal, which does recursively compare certain other structured objects, such as strings.

LISP: TRUNCATE

C: Ltruncate

min args: 1

max args: 2

[F][CLTL 12]

SYNOPSIS:

truncate number &optional divisor

DESCRIPTION:

truncate converts its argument by truncating toward zero; that is, the result is the integer of the same sign as the argument and which has the greatest integral magnitude not greater than that of the argument.

In the simple one-argument case, truncate 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 truncation 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: TYPE-OF

C: Type_Of

min args: 1

max args: 1

[F][CLTL 4]

SYNOPSIS:

type-of object

DESCRIPTION:

Type-of returns some type of which the object is a member. If the argument is a user-defined named structure created by defstruct, then type-of will return the type name of that structure.

SEE ALSO:

getltype

NOTES:

The result of this function is implementation-dependent.

It is usually better to use getltype primarily for debugging purposes. However, in a few situations portable code requires the use of getltype such as when the result is to be given to the map function. On the other hand, often the typep function or the typecase construct is more appropriate than type-of.

LISP: TYPECASE

C: SFCTCase, ETCase

[M][CLTL 7]

SYNOPSIS:

typecase keyform { ( type { form }* ) }*

DESCRIPTION:

A typecase form, similar to cond, does a linear search in a list of clauses to pick out a particular form to run.

This ability to switch on a type is unique to Common LISP, although it is quite similar in its action to case and switch in other languages. Computer languages insist that keys in a switch or case statement be of the same type.

Typecase is much like cond in terms of structure. Typecase behaves like cond by selecting a clause and then running all consequents of that clause. However, typecase differs in the method of selecting a clause. The syntax looks like this:

(typecase keyform

(type-1 consequent-1-1 consequent-1-2 ...)

(type-2 consequent-2-1 ...)

(type-3 consequent-3-1 ...)

...)

The decision is made, unlike cond, not on the basis of whether a particular form turns out to be true; but by comparing the type of the result of evaluating a particular form (the keyform) with the type specified at the head of each clause.

The result of evaluating the keyform is termed the key object.

The type that appears in at the head of each clause is a type specifier; it is not evaluated (and hence need not have a quote), but is a literal type specifier.

In contrast to case, typecase allows duplicate types in the clauses. The first applicable clause is selected.

Therefore it is important to note that the order of the clauses in a typecase is significant.

Just as for case, in place of a type, one may write one of the symbols t and otherwise. The Common LISP specification does not state whether, like case, this must be the last clause; anyway, Star Sapphire LISP does not enforce this requirement for typecase.

Just as with cond and case, the selected consequent is evaluated as an implicit progn, and the typecase form returns the result of the last form in the implicit progn.

Specifically, typecase returns what was returned by the last consequent (or nil if there are no consequents in that clause). If no clause is selected, typecase returns nil.

LISP: TYPEP

C: PType

min args: 2

max args: 2

[F][CLTL 6]

SYNOPSIS:

typep object typespec

DESCRIPTION:

The typep predicate is true if the object is of type type and is false otherwise. Note that an object can be "of" more than one type, since one type can include another. The typespec can be a type symbol or a list (see chapter 4).