.c	Monday  June 6,1983  23:44  LQ+3D.21H.15M.33S.  -*- Bolio -*-

.chapter "Data Types"

This chapter provides a brief outline of some of the data types in
lan{nil}, their uses, and their printed representation.  Most of
these have sections of the manual devoted to them, in which more
detailed information is presented;  more comprehensive coverage of
what the lan{lisp} function 3read* accepts, and what the
3print* function produces, is in (syntax-section-page).

.section "Numbers"
.setq number-types-section-page section-page
The lan{nil} (and lan{common lisp}) hierarchy of numerical types
looks like this:
.lisp
number
    rational
        integer
	    fixnum
	    bignum
	ratio
    float
	short-float
	single-float
	double-float
	long-float
    complex
.end_lisp
Collectively, the non-complex numbers are referred to in lan{nil} as
the type 3non-complex-number*;  the term 3real* is not used
because of potential confusion with floating-point.
Note that there is no guarantee that the above types might not be
further subdivided or grouped for the convenience of the implementation.

.subsection "Rationals"

The term_i{integer} data type is intended to represent mathematical
integers.  There is no magnitude limit on them other than that imposed
by memory or addressing limitations.

In lan{nil}, those integers which can be fit in a 30 bit field in
twos-complement are term{fixnum}s, which are represented in such a
way that no storage is consumed.  For integers not in this range,
term{bignum}s are used.  Generic arithmetic functions automatically
choose the appropriate representation.

The printed representation of integers ordinarily uses decimal
notation, optionally preceeded by a sign character and optionally
followed by a decimal point.  The sharpsign reader macro
((sharpsign-macro-section-page)) may be used to input rational
numbers in other radices;  for instance,
.lisp
259		;1The integer 259*
259.		;1The integer 259*
#o403		;1 entered in octal*
#b100000011	;1 entered in binary*
.end_lisp

A term_i{ratio} is the type used to represent non-integer rational
numbers.  It consists logically of integer components which are its
term_i{numerator} and term_i{denominator} (which are accessible by
functions of the same names).
The external interface
is defined such that a ratio will always appear to be in reduced form
(whether or not it is), and the denominator will always be positive.
(lan{Common lisp} sez it can't be zero, infinity freaks.)  The
arithmetic routines which deal with rational numbers tranparently
convert between ratios, bignums, and fixnums as appropriate.  Ratios
are denoted separating the numerator and the denominatory by a
3/*:  thus, the ratio three-halves is 33/2*.

.subsection "Floating-point Numbers"
.c This doubles as the discussion on floating-point syntax,
.c apparently.
.setq floating-point-syntax-section-page section-page

lan{Common lisp} allows for four kinds of floating-point
representations, which must meet the following criteria:
.lisp
Format		Minimum Precision	Minimum Exponent Size
Short		     13 bits			7 bits
Single		     24 bits			8 bits
Double		     50 bits			8 bits
Long		     50 bits			8 bits
.end_lisp
lan{Nil} provides all of these formats, with the following specs:
.lisp
Type		    Precision		       Exponent
short-float	     19 bits			8 bits
single-float	     24 bits			8 bits
double-float	     56 bits			8 bits
long-float	    113 bits		       15 bits
.end_lisp
The 3long-float* type requires microcode support to avoid
software emulation.

Floating-point numbers in lan{nil} are syntactically distinguished
from integers in that they 2must* have a decimal point followed by at
least one digit.  (This is more rigid than the lan{common lisp}
specification.)  So, for instance, 310* and 310.* are both the
integer ten, but 310.0* is floating-point 10.
The various formats of floating-point number are syntactically
distinguished by the use of the character used in exponential
notation.  For example, 310.0d0* is double-float ten;
310.0s0* is short-float ten, 310.0l0* is long-float ten, and
310.0e0* is single-float ten.  When exponential notation is not
used, the type of float is determined by the user-modifiable variable
var_i{*read-default-float-format*}
((*read-default-float-format*-var)).  lan{Common lisp} specifies
that the default type of float is 3single-float*, both for readin
and the values of various irrational or trancendental mathematical
functions when they are given rational arguments (e.g., 3sqrt*).
However, in lan{nil}, the default is currently
3double-float*, because this lan{nil} release is the first to
supply any format 2other* than 3double-float*.  The default
2will* be changed in a future release.

.subsection "Complex Numbers"

Complex numbers in lan{nil} represent a point in the complex plane
in cartesian coordinates.  Their printed representation shows these
coordinates:
.lisp
#C(2realpart* 2imagparg*)
.end_lisp
The real and imaginary parts may be extracted with the
fun_i{realpart} and fun_i{imagpart} functions.

The real and imaginary components of complex numbers must both be
either rational numbers, or floating point numbers of the same
floating-point format.

Rational numbers and complex numbers with rational components
'cindex gaussian rational
'cindex gaussian integer
collectively constitute the 3gaussian-rational* lan{nil} data
type.  Many, but not all, rational number functions have been extended
to operate on gaussian rationals in lan{nil}, for instance
3numerator*, 3denominator*, and 3mod*.  In
order to provide what we call a 2seamless extension* of the
rational numbers to the complex plane, a gaussian rational with a zero
imaginary part is not of type 3complex*, but just the rational
number.  This interconversion may be compared with that which
interconverts between 3fixnum*s and 3bignum*s as necessary.
Gaussian rationals which have integer components (i.e., integers, and
complex numbers with integer components) are the lan{nil} type
3gaussian-integer*, which is of course a subtype of
3gaussian-rational*.  Certain integer functions in lan{nil} have
been extended to operate on gaussian integers;  these include
3gcd*, 3oddp*, and 3evenp*.  All gaussian rational and
gaussian integer extensions in lan{nil} are not defined by
lan{common lisp}, and should therefore be considered experimental
and potentially subject to change.  For this reason, feedback on their
usage and utility is desired in order that these extensions can be
evaluated.

Complex numbers with floating point components always have components
of the same floating-point format.  Such a number is always of type
3complex*, even if the imaginary part is zero.


.section "Characters"

lan{nil} provides a data type for representing characters.
Characters are the things one manipulates when doing "character I/O"
on streams.  They are the things one gets out of, and puts into,
strings.  Having a separate data type allows them to maintain their
identity within the lisp (as opposed to being an interpretation placed
on fixnums, for instance).  Chapter (character-chapter-number) is
devoted to this.

Characters in lan{nil} use 3#\* syntax for input and output, as
shown below.  Note that if the character after the 3#\* stands
alone, it is taken literally.  If it occurs after a prefix such as
"control-", then it will be treated like an ordinary token, so may
need to have a preceding backslash to inhibit case translation or just
to allow proper token parsing.
.lisp
#\a			;1Lowercase "a".*
#\A			;1Uppercase "a".*
#\Control-a		;1Uppercase "a", with the control bit.*
#\Meta-\a		;1Lowercase "a", with the meta bit.*
.end_lisp
Some characters have names, which may be used in place of the
character itself:
.lisp
#\Rubout		;1The "rubout" or "delete" character*
#\Hyper-Space		;1The "space" character with the hyper bit.*
.end_lisp

Only a subset of all possible characters are allowed to be contained
in strings.  These comprise the 3string-char* data type.  It
happens that in lan{nil} these are those characters which have no
font or bits attributes (both are 0).


.section "Symbols"

Symbols are what are used as names in lisp.  They can name functions,
and variables (the two uses of which are syntactically distinguishable
by the lan{lisp} evaluator).  Symbols have a term_i{name}, also
called the term_i{print name} or
term_i{pname}, which is a string containing the characters used in
the printed representation of the symbol.  A symbol also has a
term_i{property list} or term_i{plist} associated with it.  This
is a list of alternating "indicators" and "values", allowing one to
store unidirectional associations on the symbol.  A symbol also has
a term_i{package}, which points to the "name space" it is associated
with ((package-section-page)).

The symbol 3nil* is special.  It is used both to represent
term_i{boolean false}, and the term_i{empty list}.  Its alternate
printed representation is 3()*, the empty list.  It has the data
type 3null*, which is both a subtype of 3symbol* and a subtype
of 3list*, and is the only object of that type.  Its value is not
allowed to be changed.  Otherwise, it is treated the same as other
symbols (it has a property list etc.).

The symbol 3t* is used to represent term_i{boolean truth}.  Its
value is also not allowed to be changed.

Symbols are often used as keywords.  Because of the existence of
multiple namespaces (packages), this might present a problem because
two symbols read into different namespaces might not be the same.
This is solved by having special term_i{keyword symbols}, or just
term_i{keywords} for short.  A symbol which is typed in preceded by
a colon (and nothing else) is read into the namespace (package) for
keywords.  Thus, all symbols so designated are the same (they are
3eq*).  Keywords are self-evaluating, and their values are not
allowed to be modified.

Notationally, tokens which cannot be interpreted as anything else are
taken to be 2symbols*, except that tokens consisting entirely of
unslashified dots are supposed to cause a syntax error.  Thus,
31.0e+4* will read as a floating-point number, but 31.0e+4a*
will read as a symbol.  More complete details on input syntax are in
(syntax-section-page).


.section "Lists and Conses"
2some basic lisp here*



.section "Arrays"
Arrays in lan{nil} are a very general type.  One dimensional arrays
are the type 3vector*.  Arrays can be specialized as to the types
of elements they may contain.  A one dimensional array (a vector)
which can only contain "string characters" (see the 3string-char-p*
function, (string-char-p-fun)) is a term_i{string}.  A one
dimensional array which is allowed to hold only objects of type
3bit* (that is, the integers 30* or 31*) is a term_i{bit
vector}.  Arrays are discussed fully in (array-section-page).


.section "Structures"

lan{Nil} provides a term_i{structure} or term_i{record}
definition facility.  This is supplied by the 3defstruct*
function ((defstruct-page)), which is essentially the same one used
in both lan{maclisp} and lan{lispm}.  In lan{nil},
3defstruct*-defined objects are capable of being of their own type
(by use of the 3:extend* option to 3defstruct*)--that is,
3defstruct* provides a way for users to define their own types
distinguishable by 3typep*.  Additionally, such types interface to
the lan{nil} flavor system, which may be used to give them methods
for such things as how they should print and pretty-print.


.section "Functions"



.section "Randoms"

Internally used types.

.subsection "Minisubrs"
Pointers to special subroutines (not procedures).  Stripping off the
type bits results in the address of the subroutine, which is called
via lan{jsb}.  But argument-passing conventions vary.  This type is
expected to vanish someday.

.subsection "Modules"
A term_i{module}, as a type, is a logical unit of compiled
subroutines and the constants and datastructures they reference.  When
the compiler compiles a file, it produces a module.  When the
garbagecollector (haha) relocates things, it relocates the module as a
block.  The name 3module* should not be used for this purpose, so
it will probably be changed in a future release.

.subsection "Internal Markers"

The type 3si:internal-marker* is used for various things in
lan{nil}, none of which should ordinarily be visible to (or touched
by) the user.  Objects of this type are meant to be checked for by
things like the debugger and garbage-collector (to, for instance,
parse stack frames), and manipulating them out of context will confuse
these programs.

These objects print out as 3#!* followed by the name followed by
3!*.  For instance,
.lisp
#!AFM-3!		;1Stack marker for 3-arg function*
			; 1call frame*
#!PC-MARK!		;1Next slot on stack is a PC*
#!DOUBLE-FLOAT-MARK!	;1Next two stack entries are the*
			; 1representation of a double-float*
#!NULL-ARG!		;1Stack slot is for an argument which*
			; 1has not yet been computed, in a*
			; 1function call frame.*
.end_lisp

.subsection "Unused Types"
There are a number of unused type codes in lan{nil}.  Certain
internal routines, upon encountering them, bomb out to the lan{vms}
debugger because your lan{nil} is then undoubtedly losing its lunch.

