with-underlying-simple-vector

Arguments: (array simple-vector-var &optional displacement-var length-var explicit-end allow-nil) &body body

This macro returns the last values of the implict progn of the body of the macro.

The simple-vector-var and array arguments

Within the body of this macro, the simple-vector-var, which must be a symbol, and it is lexically or specially bound to the array's most primitive data vector, which will always be a simple-array of 1 dimension and the same element type as the array.

The array must be an array of any kind; it may itself be a simple-array, and it can be of any dimensionality.

The displacement-var argument

If displacement-var is supplied, it must be a symbol, and it is lexically or specially bound to the total displacement of the array onto its underlying data. If an array is displaced to another array which is also displaced, then the displacements are added together; the displacement-var will contain the sum of the displacements.

The length-var and explicit-end arguments

If length-var is supplied it must be a symbol, and it is lexically or specially bound to the sum of the total displacement of the array onto its underlying data and one of the following values:

• If explicit-end is supplied and non-nil, the value of explicit-end, or
• If array is a vector, the length of the vector (as would be returned by a call to length), or
• If array is multidimensional, the first (most significant) dimension of the array.

explicit-end supplies one of the values used in the computation of length-var, which overrides the macro's concept of the upper boundary of the array. This value is not checked against any real storage; care must be given when providing explicit-end that it does not overreach the bounds of the simple-vector-var.

More on displacement-var, length-var, and explicit-end arguments when array is a vector

If array is a vector, displacement-var, length-var, and explicit-end can be summarized as follows:

displacement-var and length-var are the real bounding index designators of simple-vector-var which correspond to the virtual bounding index designators 0 and explicit-end (which defaults to the length of array) of array.

The allow-nil argument

If allow-nil is supplied and non-nil, and if the array is nil then no initialization is done for the displacememt-var, if supplied, and the length-var, if supplied, gets the value most-positive-fixnum. The body code is still responsible for testing the simple-vector-var value for nil, but at least the with-underlying-simple-vector macro will not complain about a supplied array value of nil, if allow-nil is true.

Declarations for the variables can be made immediately following the argument list, and will be transferred to the final expanded form.

Example

The following code:

(deftype adim () '(mod #.array-dimension-limit))

(defun simple-write-string (string stream &optional (start 0) end)
  (declare (type adim start)
	   (optimize speed))
  (excl::with-underlying-simple-vector (string str disp len end t)
    (declare (type adim disp)
	     (type (simple-array character 1) str))
    (when string
      (do* ((i (+ start disp) (1+ i)))
	  ((>= i len))
	(declare (type adim i))
	(write-char (aref str i) stream))))
  string)

Results in the following output:

cl-user(2): (setq sstring "hello")
"hello"
cl-user(3): (setq string (make-array 3
                                     :element-type 'character
                                     :displaced-to sstring
                                     :displaced-index-offset 2))
"llo"
cl-user(4): (simple-write-string nil *standard-output*)
nil
cl-user(5): (simple-write-string sstring *standard-output*)
hello
"hello"
cl-user(6): (simple-write-string string *standard-output*)
llo
"llo"
cl-user(7): 

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.