;;; -*- Mode:Text; Base:10.; Package:User;-*-
LOCATIVES                               



Introduction             29.1 The data type locative defines a Lisp object used as a pointer to a cell.
			Locatives are inherently a more low-level construct than most Lisp objects: they
			require some knowledge of the nature of the Lisp implementation.

			A cell is a machine word that can hold a (pointer to a) Lisp object. For example,
			a symbol has five cells: the print name cell, the value cell, the function cell,
			the property list cell, and the package cell. The value cell holds (a pointer to)
			the binding of the symbol, and so on. Also, an array leader of length n has n cells,
			and an art-q array of n elements has n cells. (Numeric arrays do not have cells
			in this sense.) A locative is an object that points to a cell; it lets you refer to a
			cell so that you can examine or alter its contents.
------------------------------------------------------------------------------------------------     

Functions That             29.2 The following functions, special forms, and macros return locatives.
Return Locatives              

               locf place                                                                                 Macro
			This macro takes a place form (a form that accesses a cell) and produces a
			corresponding form to create a locative pointer to that cell; in this sense, it is
			analogous to setf. Note the following equivalence:

			(locf a) <=> (variable-location a)

               value-cell-location symbol                                                            Function
			This function returns a locative pointer to the value cell of the symbol that is
			the value of symbol; symbol is evaluated. This is actually the internal value
			cell; there can also be an external value cell if the variable is closed over. 

               variable-location symbol                                                         Special Form
			This special form returns a locative pointer into the value cell of which the
			value of symbol is stored. This form does not evaluate its argument, so the name
			of the symbol must appear explicitly in the code.

			With ordinary special variables (nonconstants and nonsystem-defined
			variables), this form is equivalent to the following form: 

			(value-cell-location 'symbol)

			The compiler does not always store the values of variables in the value cell of
			symbols. The compiler handles variable-location by producing code that returns
			a locative to the cell where the value is actually being kept. For a local variable,
			this locative is a pointer into the function's stack frame. For a flavor instance
			variable, this locative is a pointer into the instance that is the value of self.

			In addition, if sym is a special variable that is closed over by a dynamic closure,
			the value returned is an external value cell, the same as the value of 
			locate-in-closure applied to the proper closure and sym. This cell always
			contains the value that is current only while inside the closure. 

               function-cell-location symbol                                                    Function
			This function returns a locative pointer to the function cell of symbol.

               property-cell-location symbol                                                          Function
			This function returns a locative pointer to the location of the property cell of 
			symbol. This locative pointer can be passed to get or putprop with the same
			results as if symbol itself had been passed. It is preferable to write the
			following:

			(locf (symbol-plist symbol))

               car-location cons                                                                Function
			This function returns a locative pointer to the cell containing the car of cons.
			The argument must be a cons.

			Note that there is no cdr-location function because of cdr-coding (see paragraph
			6.2, Cdr-Coding). Instead, the cons itself serves as a locative to its cdr. 

               aloc array &rest subscripts                                                        Function
			This function returns a locative pointer to the element cell of array selected by
			the subscripts. The subscripts must be fixnums, and their number must match
			the rank of array. Consider the following equivalence:

			(locf (aref some-array index)) <=> (aloc some-array index)

               ap-leader array i                                                                   Function
			The argument array should be an array with a leader, and i should be a fixnum.
			This function returns a locative pointer to the ith element of the leader of array.
			Note the following equivalence:

			(ap-leader array index) <=> (locf (array-leader array index))
------------------------------------------------------------------------------------------------     

Functions                 29.3 The following functions operate on locatives.
That Operate              
on Locatives                  

               locativep objectFunction
			This function returns true if object is a locative; otherwise, it returns nil.

               contents locative                                                                Function
			The function contents returns the contents of the cell to which the locative
			points. To modify the contents of the cell, use setf with contents: 

			(setf (contents loc) newvalue)

               location-boundp locative                                                               Function
			This function returns t if the cell to which locative points contains anything
			except a void marker.

			The void marker is a special data type, dtp-null, which is stored in cells to
			indicate that their value is missing. For example, an unbound variable actually
			has a void marker in the value cell. Note the following equivalence: 

			(location-boundp (locf-x)) <=> (variable-boundp x)

               location-makunbound locative &optional pointer                                          Function
			This function stores an empty marker into the cell to which locative points.
			This cell consists of a data-type field dtp-null and a pointer copied from pointer
			.

			The pointer field of the void marker is used to tell the error handler which
			variable was unbound. In the case of a symbol's value cell or function cell, it
			should point to the symbol header. In the case of a flavor method, it should
			point to the beginning of the block of data that holds the definition, which is a
			word containing the method's function spec.

			If the second argument is not specified, then the place at which the void marker
			points is not defined.
------------------------------------------------------------------------------------------------     

Mixing Locatives           29.4 The functions car and cdr can be given a locative and return the
With Lists                   contents of the cell at which the locative points. These two functions are
			equivalent to contents when the argument is a locative.

			Similarly, the functions rplaca and rplacd can be used to store an object into the
			cell at which a locative points. The following three forms are equivalent:

               (rplaca locative y) <=> (rplacd locative y) <=> (setf (contents locative) y)

			If you are just using locatives, you should use contents rather than car or cdr.
			But you can also mix locatives and conses. For example, the same variable may
			usefully sometimes have a locative as its value and sometimes a cons. In such a
			case, it is useful that car and cdr work on locatives, and it also matters which
			one you use. Pick the one that is proper for the case of a cons.

			For example, the following function conses up a list by adding onto the end of
			the list.

			(defun simplified-version-of-mapcar (fcn lst)
			          (do* ((lst lst (cdr lst))
			                (result nil)
			                (loc (locf result)))
			               ((null lst) result)
			           (setf (cdr loc)
			                 (setq loc (cons (funcall fcn (car lst)) nil)))))

			The first time through the loop, loc points to nil. In subsequent iterations of
			the loop, loc points to the last cons cell in the list. Each time through the loop,
			the current value of loc is first saved as the place argument for the form (setf
			(cdr loc) ...); then loc is changed to point to a new cons cell whose cdr is nil.
			The last action performed by the loop is the actual setf operation. In the general
			case, it replaces the cdr of the old last cons cell (pointed to by loc when the loop
			started) to point to the new cons cell, which is now being pointed to by loc.
			Note that the first time through the loop, the form (setf (cdr loc) ...) is actually
			setting the value of the variable result to the initial cons cell; once set, the
			value of result never changes because it is pointing to the first cons cell.

			In this example, cdr is used rather than contents because the normal case is
			that the argument is a list.
