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.

Within the body of this macro, the simple-vector-var, which must be a symbol, is a lexical variable given the value of 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.

If displacement-var is supplied, it must be a symbol, and it is lexically 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.

If length-var is supplied it must be a symbol, and it is lexically bound to the length of the array. If explicit-end is supplied or is not nil, then length-var gets this value, otherwise it gets the value that would have been returned by a call to length (note that length would normally result in an error if the array is not one dimension; instead the length-var gets the value of the first (most significant) dimension of the array; the dimensions are not added and multiplied to calculate the total array size. Finally, if displacement-var is given, the total displacement is added to the length in length-var.

explicit-end supplies a value for the length-var, in case more accurate calculations of the length are required and the extra time for these calculations are acceptable.

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-2007, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 8.1. This page was not revised from the 8.0 page.
Created 2007.7.19.