@node Arrays, Strings, Conses, Top @chapter Arrays @menu * Array Concepts:: * Arrays Dictionary:: @end menu @node Array Concepts, Arrays Dictionary, Arrays, Arrays @section Array Concepts @c including concept-arrays @menu * Array Elements:: * Specialized Arrays:: @end menu @node Array Elements, Specialized Arrays, Array Concepts, Array Concepts @subsection Array Elements An @i{array} contains a set of @i{objects} called @i{elements} that can be referenced individually according to a rectilinear coordinate system. @menu * Array Indices:: * Array Dimensions:: * Implementation Limits on Individual Array Dimensions:: * Array Rank:: * Vectors:: * Fill Pointers:: * Multidimensional Arrays:: * Storage Layout for Multidimensional Arrays:: * Implementation Limits on Array Rank:: @end menu @node Array Indices, Array Dimensions, Array Elements, Array Elements @subsubsection Array Indices An @i{array} @i{element} is referred to by a (possibly empty) series of indices. The length of the series must equal the @i{rank} of the @i{array}. Each index must be a non-negative @i{fixnum} less than the corresponding @i{array} @i{dimension}. @i{Array} indexing is zero-origin. @node Array Dimensions, Implementation Limits on Individual Array Dimensions, Array Indices, Array Elements @subsubsection Array Dimensions An axis of an @i{array} is called a @i{dimension} @IGindex{dimension} . Each @i{dimension} is a non-negative @i{fixnum}; if any dimension of an @i{array} is zero, the @i{array} has no elements. It is permissible for a @i{dimension} to be zero, in which case the @i{array} has no elements, and any attempt to @i{access} an @i{element} is an error. However, other properties of the @i{array}, such as the @i{dimensions} themselves, may be used. @node Implementation Limits on Individual Array Dimensions, Array Rank, Array Dimensions, Array Elements @subsubsection Implementation Limits on Individual Array Dimensions An @i{implementation} may impose a limit on @i{dimensions} of an @i{array}, but there is a minimum requirement on that limit. See the @i{variable} @b{array-dimension-limit}. @node Array Rank, Vectors, Implementation Limits on Individual Array Dimensions, Array Elements @subsubsection Array Rank An @i{array} can have any number of @i{dimensions} (including zero). The number of @i{dimensions} is called the @i{rank} @IGindex{rank} . If the rank of an @i{array} is zero then the @i{array} is said to have no @i{dimensions}, and the product of the dimensions (see @b{array-total-size}) is then 1; a zero-rank @i{array} therefore has a single element. @node Vectors, Fill Pointers, Array Rank, Array Elements @subsubsection Vectors An @i{array} of @i{rank} one (@i{i.e.}, a one-dimensional @i{array}) is called a @i{vector} @IGindex{vector} . @node Fill Pointers, Multidimensional Arrays, Vectors, Array Elements @subsubsection Fill Pointers A @i{fill pointer} @IGindex{fill pointer} is a non-negative @i{integer} no larger than the total number of @i{elements} in a @i{vector}. Not all @i{vectors} have @i{fill pointers}. See the @i{functions} @b{make-array} and @b{adjust-array}. An @i{element} of a @i{vector} is said to be @i{active} @IGindex{active} if it has an index that is greater than or equal to zero, but less than the @i{fill pointer} (if any). For an @i{array} that has no @i{fill pointer}, all @i{elements} are considered @i{active}. Only @i{vectors} may have @i{fill pointers}; multidimensional @i{arrays} may not. A multidimensional @i{array} that is displaced to a @i{vector} that has a @i{fill pointer} can be created. @node Multidimensional Arrays, Storage Layout for Multidimensional Arrays, Fill Pointers, Array Elements @subsubsection Multidimensional Arrays @node Storage Layout for Multidimensional Arrays, Implementation Limits on Array Rank, Multidimensional Arrays, Array Elements @subsubsection Storage Layout for Multidimensional Arrays Multidimensional @i{arrays} store their components in row-major order; that is, internally a multidimensional @i{array} is stored as a one-dimensional @i{array}, with the multidimensional index sets ordered lexicographically, last index varying fastest. @node Implementation Limits on Array Rank, , Storage Layout for Multidimensional Arrays, Array Elements @subsubsection Implementation Limits on Array Rank An @i{implementation} may impose a limit on the @i{rank} of an @i{array}, but there is a minimum requirement on that limit. See the @i{variable} @b{array-rank-limit}. @node Specialized Arrays, , Array Elements, Array Concepts @subsection Specialized Arrays An @i{array} can be a @i{general} @i{array}, meaning each @i{element} may be any @i{object}, or it may be a @i{specialized} @i{array}, meaning that each @i{element} must be of a restricted @i{type}. The phrasing ``an @i{array} @i{specialized} to @i{type} <<@i{type}>>'' is sometimes used to emphasize the @i{element type} of an @i{array}. This phrasing is tolerated even when the <<@i{type}>> is @b{t}, even though an @i{array} @i{specialized} to @i{type} @i{t} is a @i{general} @i{array}, not a @i{specialized} @i{array}. Figure 15--1 lists some @i{defined names} that are applicable to @i{array} creation, @i{access}, and information operations. @group @noindent @w{ adjust-array array-in-bounds-p svref } @w{ adjustable-array-p array-rank upgraded-array-element-type } @w{ aref array-rank-limit upgraded-complex-part-type } @w{ array-dimension array-row-major-index vector } @w{ array-dimension-limit array-total-size vector-pop } @w{ array-dimensions array-total-size-limit vector-push } @w{ array-element-type fill-pointer vector-push-extend } @w{ array-has-fill-pointer-p make-array } @noindent @w{ Figure 15--1: General Purpose Array-Related Defined Names } @end group @menu * Array Upgrading:: * Required Kinds of Specialized Arrays:: @end menu @node Array Upgrading, Required Kinds of Specialized Arrays, Specialized Arrays, Specialized Arrays @subsubsection Array Upgrading The @i{upgraded array element type} @IGindex{upgraded array element type} of a @i{type} T_1 is a @i{type} T_2 that is a @i{supertype} of T_1 and that is used instead of T_1 whenever T_1 is used as an @i{array element type} for object creation or type discrimination. During creation of an @i{array}, the @i{element type} that was requested is called the @i{expressed array element type} @IGindex{expressed array element type} . The @i{upgraded array element type} of the @i{expressed array element type} becomes the @i{actual array element type} @IGindex{actual array element type} of the @i{array} that is created. @i{Type} @i{upgrading} implies a movement upwards in the type hierarchy lattice. A @i{type} is always a @i{subtype} of its @i{upgraded array element type}. Also, if a @i{type} T_x is a @i{subtype} of another @i{type} T_y, then the @i{upgraded array element type} of T_x must be a @i{subtype} of the @i{upgraded array element type} of T_y. Two @i{disjoint} @i{types} can be @i{upgraded} to the same @i{type}. The @i{upgraded array element type} T_2 of a @i{type} T_1 is a function only of T_1 itself; that is, it is independent of any other property of the @i{array} for which T_2 will be used, such as @i{rank}, @i{adjustability}, @i{fill pointers}, or displacement. The @i{function} @b{upgraded-array-element-type} can be used by @i{conforming programs} to predict how the @i{implementation} will @i{upgrade} a given @i{type}. @node Required Kinds of Specialized Arrays, , Array Upgrading, Specialized Arrays @subsubsection Required Kinds of Specialized Arrays @i{Vectors} whose @i{elements} are restricted to @i{type} @b{character} or a @i{subtype} of @b{character} are called @i{strings} @IGindex{string} . @i{Strings} are of @i{type} @b{string}. Figure 15--2 lists some @i{defined names} related to @i{strings}. @i{Strings} are @i{specialized} @i{arrays} and might logically have been included in this chapter. However, for purposes of readability most information about @i{strings} does not appear in this chapter; see instead @ref{Strings}. @group @noindent @w{ char string-equal string-upcase } @w{ make-string string-greaterp string@t{/=} } @w{ nstring-capitalize string-left-trim string@t{<} } @w{ nstring-downcase string-lessp string@t{<=} } @w{ nstring-upcase string-not-equal string@t{=} } @w{ schar string-not-greaterp string@t{>} } @w{ string string-not-lessp string@t{>=} } @w{ string-capitalize string-right-trim } @w{ string-downcase string-trim } @noindent @w{ Figure 15--2: Operators that Manipulate Strings } @end group @i{Vectors} whose @i{elements} are restricted to @i{type} @b{bit} are called @i{bit vectors} @IGindex{bit vector} . @i{Bit vectors} are of @i{type} @b{bit-vector}. Figure 15--3 lists some @i{defined names} for operations on @i{bit arrays}. @group @noindent @w{ bit bit-ior bit-orc2 } @w{ bit-and bit-nand bit-xor } @w{ bit-andc1 bit-nor sbit } @w{ bit-andc2 bit-not } @w{ bit-eqv bit-orc1 } @noindent @w{ Figure 15--3: Operators that Manipulate Bit Arrays} @end group @c end of including concept-arrays @node Arrays Dictionary, , Array Concepts, Arrays @section Arrays Dictionary @c including dict-arrays @menu * array:: * simple-array:: * vector (System Class):: * simple-vector:: * bit-vector:: * simple-bit-vector:: * make-array:: * adjust-array:: * adjustable-array-p:: * aref:: * array-dimension:: * array-dimensions:: * array-element-type:: * array-has-fill-pointer-p:: * array-displacement:: * array-in-bounds-p:: * array-rank:: * array-row-major-index:: * array-total-size:: * arrayp:: * fill-pointer:: * row-major-aref:: * upgraded-array-element-type:: * array-dimension-limit:: * array-rank-limit:: * array-total-size-limit:: * simple-vector-p:: * svref:: * vector:: * vector-pop:: * vector-push:: * vectorp:: * bit:: * bit-and:: * bit-vector-p:: * simple-bit-vector-p:: @end menu @node array, simple-array, Arrays Dictionary, Arrays Dictionary @subsection array [System Class] @subsubheading Class Precedence List:: @b{array}, @b{t} @subsubheading Description:: An @i{array} contains @i{objects} arranged according to a Cartesian coordinate system. An @i{array} provides mappings from a set of @i{fixnums} \left@{i_0,i_1,\dots,i_@{r-1@}\right@} to corresponding @i{elements} of the @i{array}, where 0 \le i_j < d_j, r is the rank of the array, and d_j is the size of @i{dimension} j of the array. When an @i{array} is created, the program requesting its creation may declare that all @i{elements} are of a particular @i{type}, called the @i{expressed array element type}. The implementation is permitted to @i{upgrade} this type in order to produce the @i{actual array element type}, which is the @i{element type} for the @i{array} is actually @i{specialized}. See the @i{function} @b{upgraded-array-element-type}. @subsubheading Compound Type Specifier Kind:: Specializing. @subsubheading Compound Type Specifier Syntax:: (@code{array}@{@i{@t{[}@{element-type | @b{*}@} @r{[}dimension-spec@r{]}@t{]}}@}) @w{@i{dimension-spec} ::=rank | @b{*} | @r{(}@{dimension | @b{*}@}{*}@r{)}} @subsubheading Compound Type Specifier Arguments:: @i{dimension}---a @i{valid array dimension}. @i{element-type}---a @i{type specifier}. @i{rank}---a non-negative @i{fixnum}. @subsubheading Compound Type Specifier Description:: This denotes the set of @i{arrays} whose @i{element type}, @i{rank}, and @i{dimensions} match any given @i{element-type}, @i{rank}, and @i{dimensions}. Specifically: If @i{element-type} is the @i{symbol} @b{*}, @i{arrays} are not excluded on the basis of their @i{element type}. Otherwise, only those @i{arrays} are included whose @i{actual array element type} is the result of @i{upgrading} @i{element-type}; see @ref{Array Upgrading}. If the @i{dimension-spec} is a @i{rank}, the set includes only those @i{arrays} having that @i{rank}. If the @i{dimension-spec} is a @i{list} of @i{dimensions}, the set includes only those @i{arrays} having a @i{rank} given by the @i{length} of the @i{dimensions}, and having the indicated @i{dimensions}; in this case, @b{*} matches any value for the corresponding @i{dimension}. If the @i{dimension-spec} is the @i{symbol} @b{*}, the set is not restricted on the basis of @i{rank} or @i{dimension}. @subsubheading See Also:: @b{*print-array*}, @ref{aref} , @ref{make-array} , @b{vector}, @ref{Sharpsign A}, @ref{Printing Other Arrays} @subsubheading Notes:: Note that the type @t{(array t)} is a proper @i{subtype} of the type @t{(array *)}. The reason is that the type @t{(array t)} is the set of @i{arrays} that can hold any @i{object} (the @i{elements} are of @i{type} @b{t}, which includes all @i{objects}). On the other hand, the type @t{(array *)} is the set of all @i{arrays} whatsoever, including for example @i{arrays} that can hold only @i{characters}. The type @t{(array character)} is not a @i{subtype} of the type @t{(array t)}; the two sets are @i{disjoint} because the type @t{(array character)} is not the set of all @i{arrays} that can hold @i{characters}, but rather the set of @i{arrays} that are specialized to hold precisely @i{characters} and no other @i{objects}. @node simple-array, vector (System Class), array, Arrays Dictionary @subsection simple-array [Type] @subsubheading Supertypes:: @b{simple-array}, @b{array}, @b{t} @subsubheading Description:: The @i{type} of an @i{array} that is not displaced to another @i{array}, has no @i{fill pointer}, and is not @i{expressly adjustable} is a @i{subtype} of @i{type} @b{simple-array}. The concept of a @i{simple array} exists to allow the implementation to use a specialized representation and to allow the user to declare that certain values will always be @i{simple arrays}. The @i{types} @b{simple-vector}, @b{simple-string}, and @b{simple-bit-vector} are @i{disjoint} @i{subtypes} of @i{type} @b{simple-array}, for they respectively mean @t{(simple-array t (*))}, the union of all @t{(simple-array @i{c} (*))} for any @i{c} being a @i{subtype} of @i{type} @b{character}, and @t{(simple-array bit (*))}. @subsubheading Compound Type Specifier Kind:: Specializing. @subsubheading Compound Type Specifier Syntax:: (@code{simple-array}@{@i{@t{[}@{element-type | @b{*}@} @r{[}dimension-spec@r{]}@t{]}}@}) @w{@i{dimension-spec} ::=rank | @b{*} | @r{(}@{dimension | @b{*}@}{*}@r{)}} @subsubheading Compound Type Specifier Arguments:: @i{dimension}---a @i{valid array dimension}. @i{element-type}---a @i{type specifier}. @i{rank}---a non-negative @i{fixnum}. @subsubheading Compound Type Specifier Description:: This @i{compound type specifier} is treated exactly as the corresponding @i{compound type specifier} for @i{type} @b{array} would be treated, except that the set is further constrained to include only @i{simple arrays}. @subsubheading Notes:: It is @i{implementation-dependent} whether @i{displaced arrays}, @i{vectors} with @i{fill pointers}, or arrays that are @i{actually adjustable} are @i{simple arrays}. @t{(simple-array *)} refers to all @i{simple arrays} regardless of element type, @t{(simple-array @i{type-specifier})} refers only to those @i{simple arrays} that can result from giving @i{type-specifier} as the @t{:element-type} argument to @b{make-array}. @node vector (System Class), simple-vector, simple-array, Arrays Dictionary @subsection vector [System Class] @subsubheading Class Precedence List:: @b{vector}, @b{array}, @b{sequence}, @b{t} @subsubheading Description:: Any one-dimensional @i{array} is a @i{vector}. The @i{type} @b{vector} is a @i{subtype} of @i{type} @b{array}; for all @i{types} @t{x}, @t{(vector x)} is the same as @t{(array x (*))}. The @i{type} @t{(vector t)}, the @i{type} @b{string}, and the @i{type} @b{bit-vector} are @i{disjoint} @i{subtypes} of @i{type} @b{vector}. @subsubheading Compound Type Specifier Kind:: Specializing. @subsubheading Compound Type Specifier Syntax:: (@code{vector}@{@i{@t{[}@{element-type | @b{*}@} @r{[}@{size | @b{*}@}{]}@t{]}}@}) @subsubheading Compound Type Specifier Arguments:: @i{size}---a non-negative @i{fixnum}. @i{element-type}---a @i{type specifier}. @subsubheading Compound Type Specifier Description:: This denotes the set of specialized @i{vectors} whose @i{element type} and @i{dimension} match the specified values. Specifically: If @i{element-type} is the @i{symbol} @b{*}, @i{vectors} are not excluded on the basis of their @i{element type}. Otherwise, only those @i{vectors} are included whose @i{actual array element type} is the result of @i{upgrading} @i{element-type}; see @ref{Array Upgrading}. If a @i{size} is specified, the set includes only those @i{vectors} whose only @i{dimension} is @i{size}. If the @i{symbol} @b{*} is specified instead of a @i{size}, the set is not restricted on the basis of @i{dimension}. @subsubheading See Also:: @ref{Required Kinds of Specialized Arrays}, @ref{Sharpsign Left-Parenthesis}, @ref{Printing Other Vectors}, @ref{Sharpsign A} @subsubheading Notes:: The @i{type} @t{(vector @i{e} @i{s})} is equivalent to the @i{type} @t{(array @i{e} (@i{s}))}. The type @t{(vector bit)} has the name @b{bit-vector}. The union of all @i{types} @t{(vector C)}, where C is any @i{subtype} of @b{character}, has the name @b{string}. @t{(vector *)} refers to all @i{vectors} regardless of element type, @t{(vector @i{type-specifier})} refers only to those @i{vectors} that can result from giving @i{type-specifier} as the @t{:element-type} argument to @b{make-array}. @node simple-vector, bit-vector, vector (System Class), Arrays Dictionary @subsection simple-vector [Type] @subsubheading Supertypes:: @b{simple-vector}, @b{vector}, @b{simple-array}, @b{array}, @b{sequence}, @b{t} @subsubheading Description:: The @i{type} of a @i{vector} that is not displaced to another @i{array}, has no @i{fill pointer}, is not @i{expressly adjustable} and is able to hold elements of any @i{type} is a @i{subtype} of @i{type} @b{simple-vector}. The @i{type} @b{simple-vector} is a @i{subtype} of @i{type} @b{vector}, and is a @i{subtype} of @i{type} @t{(vector t)}. @subsubheading Compound Type Specifier Kind:: Specializing. @subsubheading Compound Type Specifier Syntax:: (@code{simple-vector}@{@i{@t{[}size@t{]}}@}) @subsubheading Compound Type Specifier Arguments:: @i{size}---a non-negative @i{fixnum}, or the @i{symbol} @b{*}. The default is the @i{symbol} @b{*}. @subsubheading Compound Type Specifier Description:: This is the same as @t{(simple-array t (@i{size}))}. @node bit-vector, simple-bit-vector, simple-vector, Arrays Dictionary @subsection bit-vector [System Class] @subsubheading Class Precedence List:: @b{bit-vector}, @b{vector}, @b{array}, @b{sequence}, @b{t} @subsubheading Description:: A @i{bit vector} is a @i{vector} the @i{element type} of which is @i{bit}. The @i{type} @b{bit-vector} is a @i{subtype} of @i{type} @b{vector}, for @b{bit-vector} means @t{(vector bit)}. @subsubheading Compound Type Specifier Kind:: Abbreviating. @subsubheading Compound Type Specifier Syntax:: (@code{bit-vector}@{@i{@t{[}size@t{]}}@}) @subsubheading Compound Type Specifier Arguments:: @i{size}---a non-negative @i{fixnum}, or the @i{symbol} @b{*}. @subsubheading Compound Type Specifier Description:: This denotes the same @i{type} as the @i{type} @t{(array bit (@i{size}))}; that is, the set of @i{bit vectors} of size @i{size}. @subsubheading See Also:: @ref{Sharpsign Asterisk}, @ref{Printing Bit Vectors}, @ref{Required Kinds of Specialized Arrays} @node simple-bit-vector, make-array, bit-vector, Arrays Dictionary @subsection simple-bit-vector [Type] @subsubheading Supertypes:: @b{simple-bit-vector}, @b{bit-vector}, @b{vector}, @b{simple-array}, @b{array}, @b{sequence}, @b{t} @subsubheading Description:: The @i{type} of a @i{bit vector} that is not displaced to another @i{array}, has no @i{fill pointer}, and is not @i{expressly adjustable} is a @i{subtype} of @i{type} @b{simple-bit-vector}. @subsubheading Compound Type Specifier Kind:: Abbreviating. @subsubheading Compound Type Specifier Syntax:: (@code{simple-bit-vector}@{@i{@t{[}size@t{]}}@}) @subsubheading Compound Type Specifier Arguments:: @i{size}---a non-negative @i{fixnum}, or the @i{symbol} @b{*}. The default is the @i{symbol} @b{*}. @subsubheading Compound Type Specifier Description:: This denotes the same type as the @i{type} @t{(simple-array bit (@i{size}))}; that is, the set of @i{simple bit vectors} of size @i{size}. @node make-array, adjust-array, simple-bit-vector, Arrays Dictionary @subsection make-array [Function] @code{make-array} @i{dimensions {&key} element-type initial-element initial-contents adjustable fill-pointer displaced-to displaced-index-offset}@* @result{} @i{new-array} @subsubheading Arguments and Values:: @i{dimensions}---a @i{designator} for a @i{list} of @i{valid array dimensions}. @i{element-type}---a @i{type specifier}. The default is @b{t}. @i{initial-element}---an @i{object}. @i{initial-contents}---an @i{object}. @i{adjustable}---a @i{generalized boolean}. The default is @b{nil}. @i{fill-pointer}---a @i{valid fill pointer} for the @i{array} to be created, or @b{t} or @b{nil}. The default is @b{nil}. @i{displaced-to}---an @i{array} or @b{nil}. The default is @b{nil}. This option must not be supplied if either @i{initial-element} or @i{initial-contents} is supplied. @i{displaced-index-offset}---a @i{valid array row-major index} for @i{displaced-to}. The default is @t{0}. This option must not be supplied unless a @i{non-nil} @i{displaced-to} is supplied. @i{new-array}---an @i{array}. @subsubheading Description:: Creates and returns an @i{array} constructed of the most @i{specialized} @i{type} that can accommodate elements of @i{type} given by @i{element-type}. If @i{dimensions} is @b{nil} then a zero-dimensional @i{array} is created. @i{Dimensions} represents the dimensionality of the new @i{array}. @i{element-type} indicates the @i{type} of the elements intended to be stored in the @i{new-array}. The @i{new-array} can actually store any @i{objects} of the @i{type} which results from @i{upgrading} @i{element-type}; see @ref{Array Upgrading}. If @i{initial-element} is supplied, it is used to initialize each @i{element} of @i{new-array}. If @i{initial-element} is supplied, it must be of the @i{type} given by @i{element-type}. @i{initial-element} cannot be supplied if either the @t{:initial-contents} option is supplied or @i{displaced-to} is @i{non-nil}. If @i{initial-element} is not supplied, the consequences of later reading an uninitialized @i{element} of @i{new-array} are undefined unless either @i{initial-contents} is supplied or @i{displaced-to} is @i{non-nil}. @i{initial-contents} is used to initialize the contents of @i{array}. For example: @example (make-array '(4 2 3) :initial-contents '(((a b c) (1 2 3)) ((d e f) (3 1 2)) ((g h i) (2 3 1)) ((j k l) (0 0 0)))) @end example @i{initial-contents} is composed of a nested structure of @i{sequences}. The numbers of levels in the structure must equal the rank of @i{array}. Each leaf of the nested structure must be of the @i{type} given by @i{element-type}. If @i{array} is zero-dimensional, then @i{initial-contents} specifies the single @i{element}. Otherwise, @i{initial-contents} must be a @i{sequence} whose length is equal to the first dimension; each element must be a nested structure for an @i{array} whose dimensions are the remaining dimensions, and so on. @i{Initial-contents} cannot be supplied if either @i{initial-element} is supplied or @i{displaced-to} is @i{non-nil}. If @i{initial-contents} is not supplied, the consequences of later reading an uninitialized @i{element} of @i{new-array} are undefined unless either @i{initial-element} is supplied or @i{displaced-to} is @i{non-nil}. If @i{adjustable} is @i{non-nil}, the array is @i{expressly adjustable} (and so @i{actually adjustable}); otherwise, the array is not @i{expressly adjustable} (and it is @i{implementation-dependent} whether the array is @i{actually adjustable}). If @i{fill-pointer} is @i{non-nil}, the @i{array} must be one-dimensional; that is, the @i{array} must be a @i{vector}. If @i{fill-pointer} is @b{t}, the length of the @i{vector} is used to initialize the @i{fill pointer}. If @i{fill-pointer} is an @i{integer}, it becomes the initial @i{fill pointer} for the @i{vector}. If @i{displaced-to} is @i{non-nil}, @b{make-array} will create a @i{displaced array} and @i{displaced-to} is the @i{target} of that @i{displaced array}. In that case, the consequences are undefined if the @i{actual array element type} of @i{displaced-to} is not @i{type equivalent} to the @i{actual array element type} of the @i{array} being created. If @i{displaced-to} is @b{nil}, the @i{array} is not a @i{displaced array}. The @i{displaced-index-offset} is made to be the index offset of the @i{array}. When an array A is given as the @t{:displaced-to} @i{argument} to @b{make-array} when creating array B, then array B is said to be displaced to array A. The total number of elements in an @i{array}, called the total size of the @i{array}, is calculated as the product of all the dimensions. It is required that the total size of A be no smaller than the sum of the total size of B plus the offset @t{n} supplied by the @i{displaced-index-offset}. The effect of displacing is that array B does not have any elements of its own, but instead maps @i{accesses} to itself into @i{accesses} to array A. The mapping treats both @i{arrays} as if they were one-dimensional by taking the elements in row-major order, and then maps an @i{access} to element @t{k} of array B to an @i{access} to element @t{k}+@t{n} of array A. If @b{make-array} is called with @i{adjustable}, @i{fill-pointer}, and @i{displaced-to} each @b{nil}, then the result is a @i{simple array}. If @b{make-array} is called with one or more of @i{adjustable}, @i{fill-pointer}, or @i{displaced-to} being @i{true}, whether the resulting @i{array} is a @i{simple array} is @i{implementation-dependent}. When an array A is given as the @t{:displaced-to} @i{argument} to @b{make-array} when creating array B, then array B is said to be displaced to array A. The total number of elements in an @i{array}, called the total size of the @i{array}, is calculated as the product of all the dimensions. The consequences are unspecified if the total size of A is smaller than the sum of the total size of B plus the offset @t{n} supplied by the @i{displaced-index-offset}. The effect of displacing is that array B does not have any elements of its own, but instead maps @i{accesses} to itself into @i{accesses} to array A. The mapping treats both @i{arrays} as if they were one-dimensional by taking the elements in row-major order, and then maps an @i{access} to element @t{k} of array B to an @i{access} to @i{element} @t{k}+@t{n} of array A. @subsubheading Examples:: @example (make-array 5) ;; Creates a one-dimensional array of five elements. (make-array '(3 4) :element-type '(mod 16)) ;; Creates a ;;two-dimensional array, 3 by 4, with four-bit elements. (make-array 5 :element-type 'single-float) ;; Creates an array of single-floats. @end example @example (make-array nil :initial-element nil) @result{} #0ANIL (make-array 4 :initial-element nil) @result{} #(NIL NIL NIL NIL) (make-array '(2 4) :element-type '(unsigned-byte 2) :initial-contents '((0 1 2 3) (3 2 1 0))) @result{} #2A((0 1 2 3) (3 2 1 0)) (make-array 6 :element-type 'character :initial-element #\a :fill-pointer 3) @result{} "aaa" @end example The following is an example of making a @i{displaced array}. @example (setq a (make-array '(4 3))) @result{} # (dotimes (i 4) (dotimes (j 3) (setf (aref a i j) (list i 'x j '= (* i j))))) @result{} NIL (setq b (make-array 8 :displaced-to a :displaced-index-offset 2)) @result{} # (dotimes (i 8) (print (list i (aref b i)))) @t{ |> } (0 (0 X 2 = 0)) @t{ |> } (1 (1 X 0 = 0)) @t{ |> } (2 (1 X 1 = 1)) @t{ |> } (3 (1 X 2 = 2)) @t{ |> } (4 (2 X 0 = 0)) @t{ |> } (5 (2 X 1 = 2)) @t{ |> } (6 (2 X 2 = 4)) @t{ |> } (7 (3 X 0 = 0)) @result{} NIL @end example The last example depends on the fact that @i{arrays} are, in effect, stored in row-major order. @example (setq a1 (make-array 50)) @result{} # (setq b1 (make-array 20 :displaced-to a1 :displaced-index-offset 10)) @result{} # (length b1) @result{} 20 (setq a2 (make-array 50 :fill-pointer 10)) @result{} # (setq b2 (make-array 20 :displaced-to a2 :displaced-index-offset 10)) @result{} # (length a2) @result{} 10 (length b2) @result{} 20 (setq a3 (make-array 50 :fill-pointer 10)) @result{} # (setq b3 (make-array 20 :displaced-to a3 :displaced-index-offset 10 :fill-pointer 5)) @result{} # (length a3) @result{} 10 (length b3) @result{} 5 @end example @subsubheading See Also:: @ref{adjustable-array-p} , @ref{aref} , @ref{arrayp} , @ref{array-element-type} , @ref{array-rank-limit} , @ref{array-dimension-limit} , @ref{fill-pointer} , @ref{upgraded-array-element-type} @subsubheading Notes:: There is no specified way to create an @i{array} for which @b{adjustable-array-p} definitely returns @i{false}. There is no specified way to create an @i{array} that is not a @i{simple array}. @node adjust-array, adjustable-array-p, make-array, Arrays Dictionary @subsection adjust-array [Function] @code{adjust-array} @i{array new-dimensions {&key} element-type initial-element initial-contents fill-pointer displaced-to displaced-index-offset}@* @result{} @i{adjusted-array} @subsubheading Arguments and Values:: @i{array}---an @i{array}. @i{new-dimensions}---a @i{valid array dimension} or a @i{list} of @i{valid array dimensions}. @i{element-type}---a @i{type specifier}. @i{initial-element}---an @i{object}. @i{Initial-element} must not be supplied if either @i{initial-contents} or @i{displaced-to} is supplied. @i{initial-contents}---an @i{object}. If @i{array} has rank greater than zero, then @i{initial-contents} is composed of nested @i{sequences}, the depth of which must equal the rank of @i{array}. Otherwise, @i{array} is zero-dimensional and @i{initial-contents} supplies the single element. @i{initial-contents} must not be supplied if either @i{initial-element} or @i{displaced-to} is given. @i{fill-pointer}---a @i{valid fill pointer} for the @i{array} to be created, or @b{t}, or @b{nil}. The default is @b{nil}. @i{displaced-to}---an @i{array} or @b{nil}. @i{initial-elements} and @i{initial-contents} must not be supplied if @i{displaced-to} is supplied. @i{displaced-index-offset}---an @i{object} of @i{type} @t{(fixnum 0 @i{n})} where @i{n} is @t{(array-total-size @i{displaced-to})}. @i{displaced-index-offset} may be supplied only if @i{displaced-to} is supplied. @i{adjusted-array}---an @i{array}. @subsubheading Description:: @b{adjust-array} changes the dimensions or elements of @i{array}. The result is an @i{array} of the same @i{type} and rank as @i{array}, that is either the modified @i{array}, or a newly created @i{array} to which @i{array} can be displaced, and that has the given @i{new-dimensions}. @i{New-dimensions} specify the size of each @i{dimension} of @i{array}. @i{Element-type} specifies the @i{type} of the @i{elements} of the resulting @i{array}. If @i{element-type} is supplied, the consequences are unspecified if the @i{upgraded array element type} of @i{element-type} is not the same as the @i{actual array element type} of @i{array}. If @i{initial-contents} is supplied, it is treated as for @b{make-array}. In this case none of the original contents of @i{array} appears in the resulting @i{array}. If @i{fill-pointer} is an @i{integer}, it becomes the @i{fill pointer} for the resulting @i{array}. If @i{fill-pointer} is the symbol @b{t}, it indicates that the size of the resulting @i{array} should be used as the @i{fill pointer}. If @i{fill-pointer} is @b{nil}, it indicates that the @i{fill pointer} should be left as it is. If @i{displaced-to} @i{non-nil}, a @i{displaced array} is created. The resulting @i{array} shares its contents with the @i{array} given by @i{displaced-to}. The resulting @i{array} cannot contain more elements than the @i{array} it is displaced to. If @i{displaced-to} is not supplied or @b{nil}, the resulting @i{array} is not a @i{displaced array}. If array A is created displaced to array B and subsequently array B is given to @b{adjust-array}, array A will still be displaced to array B. Although @i{array} might be a @i{displaced array}, the resulting @i{array} is not a @i{displaced array} unless @i{displaced-to} is supplied and not @b{nil}. The interaction between @b{adjust-array} and displaced @i{arrays} is as follows given three @i{arrays}, @t{A}, @t{B}, and~@t{C}: @table @asis @item @t{A} is not displaced before or after the call @example (adjust-array A ...) @end example The dimensions of @t{A} are altered, and the contents rearranged as appropriate. Additional elements of @t{A} are taken from @i{initial-element}. The use of @i{initial-contents} causes all old contents to be discarded. @item @t{A} is not displaced before, but is displaced to @t{C} after the call @example (adjust-array A ... :displaced-to C) @end example None of the original contents of @t{A} appears in @t{A} afterwards; @t{A} now contains the contents of @t{C}, without any rearrangement of @t{C}. @item @t{A} is displaced to @t{B} before the call, and is displaced to @t{C} after the call @example (adjust-array A ... :displaced-to B) (adjust-array A ... :displaced-to C) @end example @t{B} and @t{C} might be the same. The contents of @t{B} do not appear in @t{A} afterward unless such contents also happen to be in @t{C} If @i{displaced-index-offset} is not supplied in the @b{adjust-array} call, it defaults to zero; the old offset into @t{B} is not retained. @item @t{A} is displaced to @t{B} before the call, but not displaced afterward. @example (adjust-array A ... :displaced-to B) (adjust-array A ... :displaced-to nil) @end example @t{A} gets a new ``data region,'' and contents of @t{B} are copied into it as appropriate to maintain the existing old contents; additional elements of @t{A} are taken from @i{initial-element} if supplied. However, the use of @i{initial-contents} causes all old contents to be discarded. @end table If @i{displaced-index-offset} is supplied, it specifies the offset of the resulting @i{array} from the beginning of the @i{array} that it is displaced to. If @i{displaced-index-offset} is not supplied, the offset is~0. The size of the resulting @i{array} plus the offset value cannot exceed the size of the @i{array} that it is displaced to. If only @i{new-dimensions} and an @i{initial-element} argument are supplied, those elements of @i{array} that are still in bounds appear in the resulting @i{array}. The elements of the resulting @i{array} that are not in the bounds of @i{array} are initialized to @i{initial-element}; if @i{initial-element} is not provided, the consequences of later reading any such new @i{element} of @i{new-array} before it has been initialized are undefined. If @i{initial-contents} or @i{displaced-to} is supplied, then none of the original contents of @i{array} appears in the new @i{array}. The consequences are unspecified if @i{array} is adjusted to a size smaller than its @i{fill pointer} without supplying the @i{fill-pointer} argument so that its @i{fill-pointer} is properly adjusted in the process. If @t{A} is displaced to @t{B}, the consequences are unspecified if @t{B} is adjusted in such a way that it no longer has enough elements to satisfy @t{A}. If @b{adjust-array} is applied to an @i{array} that is @i{actually adjustable}, the @i{array} returned is @i{identical} to @i{array}. If the @i{array} returned by @b{adjust-array} is @i{distinct} from @i{array}, then the argument @i{array} is unchanged. Note that if an @i{array} A is displaced to another @i{array} B, and B is displaced to another @i{array} C, and B is altered by @b{adjust-array}, A must now refer to the adjust contents of B. This means that an implementation cannot collapse the chain to make A refer to C directly and forget that the chain of reference passes through B. However, caching techniques are permitted as long as they preserve the semantics specified here. @subsubheading Examples:: @example (adjustable-array-p (setq ada (adjust-array (make-array '(2 3) :adjustable t :initial-contents '((a b c) (1 2 3))) '(4 6)))) @result{} T (array-dimensions ada) @result{} (4 6) (aref ada 1 1) @result{} 2 (setq beta (make-array '(2 3) :adjustable t)) @result{} #2A((NIL NIL NIL) (NIL NIL NIL)) (adjust-array beta '(4 6) :displaced-to ada) @result{} #2A((A B C NIL NIL NIL) (1 2 3 NIL NIL NIL) (NIL NIL NIL NIL NIL NIL) (NIL NIL NIL NIL NIL NIL)) (array-dimensions beta) @result{} (4 6) (aref beta 1 1) @result{} 2 @end example Suppose that the 4-by-4 array in @t{m} looks like this: @example #2A(( alpha beta gamma delta ) ( epsilon zeta eta theta ) ( iota kappa lambda mu ) ( nu xi omicron pi )) @end example Then the result of @example (adjust-array m '(3 5) :initial-element 'baz) @end example is a 3-by-5 array with contents @example #2A(( alpha beta gamma delta baz ) ( epsilon zeta eta theta baz ) ( iota kappa lambda mu baz )) @end example @subsubheading Exceptional Situations:: An error of @i{type} @b{error} is signaled if @i{fill-pointer} is supplied and @i{non-nil} but @i{array} has no @i{fill pointer}. @subsubheading See Also:: @ref{adjustable-array-p} , @ref{make-array} , @ref{array-dimension-limit} , @ref{array-total-size-limit} , @b{array} @node adjustable-array-p, aref, adjust-array, Arrays Dictionary @subsection adjustable-array-p [Function] @code{adjustable-array-p} @i{array} @result{} @i{generalized-boolean} @subsubheading Arguments and Values:: @i{array}---an @i{array}. @i{generalized-boolean}---a @i{generalized boolean}. @subsubheading Description:: Returns true if and only if @b{adjust-array} could return a @i{value} which is @i{identical} to @i{array} when given that @i{array} as its first @i{argument}. @subsubheading Examples:: @example (adjustable-array-p (make-array 5 :element-type 'character :adjustable t :fill-pointer 3)) @result{} @i{true} (adjustable-array-p (make-array 4)) @result{} @i{implementation-dependent} @end example @subsubheading Exceptional Situations:: Should signal an error of @i{type} @b{type-error} if its argument is not an @i{array}. @subsubheading See Also:: @ref{adjust-array} , @ref{make-array} @node aref, array-dimension, adjustable-array-p, Arrays Dictionary @subsection aref [Accessor] @code{aref} @i{array {&rest} subscripts} @result{} @i{element} (setf (@code{ aref} @i{array {&rest} subscripts}) new-element)@* @subsubheading Arguments and Values:: @i{array}---an @i{array}. @i{subscripts}---a @i{list} of @i{valid array indices} for the @i{array}. @i{element}, @i{new-element}---an @i{object}. @subsubheading Description:: @i{Accesses} the @i{array} @i{element} specified by the @i{subscripts}. If no @i{subscripts} are supplied and @i{array} is zero rank, @b{aref} @i{accesses} the sole element of @i{array}. @b{aref} ignores @i{fill pointers}. It is permissible to use @b{aref} to @i{access} any @i{array} @i{element}, whether @i{active} or not. @subsubheading Examples:: If the variable @t{foo} names a 3-by-5 array, then the first index could be 0, 1, or 2, and then second index could be 0, 1, 2, 3, or 4. The array elements can be referred to by using the @i{function} @b{aref}; for example, @t{(aref foo 2 1)} refers to element (2, 1) of the array. @example (aref (setq alpha (make-array 4)) 3) @result{} @i{implementation-dependent} (setf (aref alpha 3) 'sirens) @result{} SIRENS (aref alpha 3) @result{} SIRENS (aref (setq beta (make-array '(2 4) :element-type '(unsigned-byte 2) :initial-contents '((0 1 2 3) (3 2 1 0)))) 1 2) @result{} 1 (setq gamma '(0 2)) (apply #'aref beta gamma) @result{} 2 (setf (apply #'aref beta gamma) 3) @result{} 3 (apply #'aref beta gamma) @result{} 3 (aref beta 0 2) @result{} 3 @end example @subsubheading See Also:: @ref{bit} , @ref{char; schar} , @ref{elt} , @ref{row-major-aref} , @ref{svref} , @ref{Compiler Terminology} @node array-dimension, array-dimensions, aref, Arrays Dictionary @subsection array-dimension [Function] @code{array-dimension} @i{array axis-number} @result{} @i{dimension} @subsubheading Arguments and Values:: @i{array}---an @i{array}. @i{axis-number}---an @i{integer} greater than or equal to zero and less than the @i{rank} of the @i{array}. @i{dimension}---a non-negative @i{integer}. @subsubheading Description:: @b{array-dimension} returns the @i{axis-number} @i{dimension}_1 of @i{array}. (Any @i{fill pointer} is ignored.) @subsubheading Examples:: @example (array-dimension (make-array 4) 0) @result{} 4 (array-dimension (make-array '(2 3)) 1) @result{} 3 @end example @subsubheading Affected By:: None. @subsubheading See Also:: @ref{array-dimensions} , @ref{length} @subsubheading Notes:: @example (array-dimension array n) @equiv{} (nth n (array-dimensions array)) @end example @node array-dimensions, array-element-type, array-dimension, Arrays Dictionary @subsection array-dimensions [Function] @code{array-dimensions} @i{array} @result{} @i{dimensions} @subsubheading Arguments and Values:: @i{array}---an @i{array}. @i{dimensions}---a @i{list} of @i{integers}. @subsubheading Description:: Returns a @i{list} of the @i{dimensions} of @i{array}. (If @i{array} is a @i{vector} with a @i{fill pointer}, that @i{fill pointer} is ignored.) @subsubheading Examples:: @example (array-dimensions (make-array 4)) @result{} (4) (array-dimensions (make-array '(2 3))) @result{} (2 3) (array-dimensions (make-array 4 :fill-pointer 2)) @result{} (4) @end example @subsubheading Exceptional Situations:: Should signal an error of @i{type} @b{type-error} if its argument is not an @i{array}. @subsubheading See Also:: @ref{array-dimension} @node array-element-type, array-has-fill-pointer-p, array-dimensions, Arrays Dictionary @subsection array-element-type [Function] @code{array-element-type} @i{array} @result{} @i{typespec} @subsubheading Arguments and Values:: @i{array}---an @i{array}. @i{typespec}---a @i{type specifier}. @subsubheading Description:: Returns a @i{type specifier} which represents the @i{actual array element type} of the array, which is the set of @i{objects} that such an @i{array} can hold. (Because of @i{array} @i{upgrading}, this @i{type specifier} can in some cases denote a @i{supertype} of the @i{expressed array element type} of the @i{array}.) @subsubheading Examples:: @example (array-element-type (make-array 4)) @result{} T (array-element-type (make-array 12 :element-type '(unsigned-byte 8))) @result{} @i{implementation-dependent} (array-element-type (make-array 12 :element-type '(unsigned-byte 5))) @result{} @i{implementation-dependent} @end example @example (array-element-type (make-array 5 :element-type '(mod 5))) @end example could be @t{(mod 5)}, @t{(mod 8)}, @t{fixnum}, @t{t}, or any other type of which @t{(mod 5)} is a @i{subtype}. @subsubheading Affected By:: The @i{implementation}. @subsubheading Exceptional Situations:: Should signal an error of @i{type} @b{type-error} if its argument is not an @i{array}. @subsubheading See Also:: @b{array}, @ref{make-array} , @ref{subtypep} , @ref{upgraded-array-element-type} @node array-has-fill-pointer-p, array-displacement, array-element-type, Arrays Dictionary @subsection array-has-fill-pointer-p [Function] @code{array-has-fill-pointer-p} @i{array} @result{} @i{generalized-boolean} @subsubheading Arguments and Values:: @i{array}---an @i{array}. @i{generalized-boolean}---a @i{generalized boolean}. @subsubheading Description:: Returns @i{true} if @i{array} has a @i{fill pointer}; otherwise returns @i{false}. @subsubheading Examples:: @example (array-has-fill-pointer-p (make-array 4)) @result{} @i{implementation-dependent} (array-has-fill-pointer-p (make-array '(2 3))) @result{} @i{false} (array-has-fill-pointer-p (make-array 8 :fill-pointer 2 :initial-element 'filler)) @result{} @i{true} @end example @subsubheading Exceptional Situations:: Should signal an error of @i{type} @b{type-error} if its argument is not an @i{array}. @subsubheading See Also:: @ref{make-array} , @ref{fill-pointer} @subsubheading Notes:: Since @i{arrays} of @i{rank} other than one cannot have a @i{fill pointer}, @b{array-has-fill-pointer-p} always returns @b{nil} when its argument is such an array. @node array-displacement, array-in-bounds-p, array-has-fill-pointer-p, Arrays Dictionary @subsection array-displacement [Function] @code{array-displacement} @i{array} @result{} @i{displaced-to, displaced-index-offset} @subsubheading Arguments and Values:: @i{array}---an @i{array}. @i{displaced-to}---an @i{array} or @b{nil}. @i{displaced-index-offset}---a non-negative @i{fixnum}. @subsubheading Description:: If the @i{array} is a @i{displaced array}, returns the @i{values} of the @t{:displaced-to} and @t{:displaced-index-offset} options for the @i{array} (see the @i{functions} @b{make-array} and @b{adjust-array}). If the @i{array} is not a @i{displaced array}, @b{nil} and @t{0} are returned. If @b{array-displacement} is called on an @i{array} for which a @i{non-nil} @i{object} was provided as the @t{:displaced-to} @i{argument} to @b{make-array} or @b{adjust-array}, it must return that @i{object} as its first value. It is @i{implementation-dependent} whether @b{array-displacement} returns a @i{non-nil} @i{primary value} for any other @i{array}. @subsubheading Examples:: @example (setq a1 (make-array 5)) @result{} # (setq a2 (make-array 4 :displaced-to a1 :displaced-index-offset 1)) @result{} # (array-displacement a2) @result{} #, 1 (setq a3 (make-array 2 :displaced-to a2 :displaced-index-offset 2)) @result{} # (array-displacement a3) @result{} #, 2 @end example @subsubheading Exceptional Situations:: Should signal an error of @i{type} @b{type-error} if @i{array} is not an @i{array}. @subsubheading See Also:: @ref{make-array} @node array-in-bounds-p, array-rank, array-displacement, Arrays Dictionary @subsection array-in-bounds-p [Function] @code{array-in-bounds-p} @i{array {&rest} subscripts} @result{} @i{generalized-boolean} @subsubheading Arguments and Values:: @i{array}---an @i{array}. @i{subscripts}---a list of @i{integers} of length equal to the @i{rank} of the @i{array}. @i{generalized-boolean}---a @i{generalized boolean}. @subsubheading Description:: Returns @i{true} if the @i{subscripts} are all in bounds for @i{array}; otherwise returns @i{false}. (If @i{array} is a @i{vector} with a @i{fill pointer}, that @i{fill pointer} is ignored.) @subsubheading Examples:: @example (setq a (make-array '(7 11) :element-type 'string-char)) (array-in-bounds-p a 0 0) @result{} @i{true} (array-in-bounds-p a 6 10) @result{} @i{true} (array-in-bounds-p a 0 -1) @result{} @i{false} (array-in-bounds-p a 0 11) @result{} @i{false} (array-in-bounds-p a 7 0) @result{} @i{false} @end example @subsubheading See Also:: @ref{array-dimensions} @subsubheading Notes:: @example (array-in-bounds-p array subscripts) @equiv{} (and (not (some #'minusp (list subscripts))) (every #'< (list subscripts) (array-dimensions array))) @end example @node array-rank, array-row-major-index, array-in-bounds-p, Arrays Dictionary @subsection array-rank [Function] @code{array-rank} @i{array} @result{} @i{rank} @subsubheading Arguments and Values:: @i{array}---an @i{array}. @i{rank}---a non-negative @i{integer}. @subsubheading Description:: Returns the number of @i{dimensions} of @i{array}. @subsubheading Examples:: @example (array-rank (make-array '())) @result{} 0 (array-rank (make-array 4)) @result{} 1 (array-rank (make-array '(4))) @result{} 1 (array-rank (make-array '(2 3))) @result{} 2 @end example @subsubheading Exceptional Situations:: Should signal an error of @i{type} @b{type-error} if its argument is not an @i{array}. @subsubheading See Also:: @ref{array-rank-limit} , @ref{make-array} @node array-row-major-index, array-total-size, array-rank, Arrays Dictionary @subsection array-row-major-index [Function] @code{array-row-major-index} @i{array {&rest} subscripts} @result{} @i{index} @subsubheading Arguments and Values:: @i{array}---an @i{array}. @i{subscripts}---a @i{list} of @i{valid array indices} for the @i{array}. @i{index}---a @i{valid array row-major index} for the @i{array}. @subsubheading Description:: Computes the position according to the row-major ordering of @i{array} for the element that is specified by @i{subscripts}, and returns the offset of the element in the computed position from the beginning of @i{array}. For a one-dimensional @i{array}, the result of @b{array-row-major-index} equals @i{subscript}. @b{array-row-major-index} ignores @i{fill pointers}. @subsubheading Examples:: @example (setq a (make-array '(4 7) :element-type '(unsigned-byte 8))) (array-row-major-index a 1 2) @result{} 9 (array-row-major-index (make-array '(2 3 4) :element-type '(unsigned-byte 8) :displaced-to a :displaced-index-offset 4) 0 2 1) @result{} 9 @end example @subsubheading Notes:: A possible definition of @b{array-row-major-index}, with no error-checking, is @example (defun array-row-major-index (a &rest subscripts) (apply #'+ (maplist #'(lambda (x y) (* (car x) (apply #'* (cdr y)))) subscripts (array-dimensions a)))) @end example @node array-total-size, arrayp, array-row-major-index, Arrays Dictionary @subsection array-total-size [Function] @code{array-total-size} @i{array} @result{} @i{size} @subsubheading Arguments and Values:: @i{array}---an @i{array}. @i{size}---a non-negative @i{integer}. @subsubheading Description:: Returns the @i{array total size} of the @i{array}. @subsubheading Examples:: @example (array-total-size (make-array 4)) @result{} 4 (array-total-size (make-array 4 :fill-pointer 2)) @result{} 4 (array-total-size (make-array 0)) @result{} 0 (array-total-size (make-array '(4 2))) @result{} 8 (array-total-size (make-array '(4 0))) @result{} 0 (array-total-size (make-array '())) @result{} 1 @end example @subsubheading Exceptional Situations:: Should signal an error of @i{type} @b{type-error} if its argument is not an @i{array}. @subsubheading See Also:: @ref{make-array} , @ref{array-dimensions} @subsubheading Notes:: If the @i{array} is a @i{vector} with a @i{fill pointer}, the @i{fill pointer} is ignored when calculating the @i{array total size}. Since the product of no arguments is one, the @i{array total size} of a zero-dimensional @i{array} is one. @example (array-total-size x) @equiv{} (apply #'* (array-dimensions x)) @equiv{} (reduce #'* (array-dimensions x)) @end example @node arrayp, fill-pointer, array-total-size, Arrays Dictionary @subsection arrayp [Function] @code{arrayp} @i{object} @result{} @i{generalized-boolean} @subsubheading Arguments and Values:: @i{object}---an @i{object}. @i{generalized-boolean}---a @i{generalized boolean}. @subsubheading Description:: Returns @i{true} if @i{object} is of @i{type} @b{array}; otherwise, returns @i{false}. @subsubheading Examples:: @example (arrayp (make-array '(2 3 4) :adjustable t)) @result{} @i{true} (arrayp (make-array 6)) @result{} @i{true} (arrayp #*1011) @result{} @i{true} (arrayp "hi") @result{} @i{true} (arrayp 'hi) @result{} @i{false} (arrayp 12) @result{} @i{false} @end example @subsubheading See Also:: @ref{typep} @subsubheading Notes:: @example (arrayp @i{object}) @equiv{} (typep @i{object} 'array) @end example @node fill-pointer, row-major-aref, arrayp, Arrays Dictionary @subsection fill-pointer [Accessor] @code{fill-pointer} @i{vector} @result{} @i{fill-pointer} (setf (@code{ fill-pointer} @i{vector}) new-fill-pointer)@* @subsubheading Arguments and Values:: @i{vector}---a @i{vector} with a @i{fill pointer}. @i{fill-pointer}, @i{new-fill-pointer}---a @i{valid fill pointer} for the @i{vector}. @subsubheading Description:: @i{Accesses} the @i{fill pointer} of @i{vector}. @subsubheading Examples:: @example (setq a (make-array 8 :fill-pointer 4)) @result{} #(NIL NIL NIL NIL) (fill-pointer a) @result{} 4 (dotimes (i (length a)) (setf (aref a i) (* i i))) @result{} NIL a @result{} #(0 1 4 9) (setf (fill-pointer a) 3) @result{} 3 (fill-pointer a) @result{} 3 a @result{} #(0 1 4) (setf (fill-pointer a) 8) @result{} 8 a @result{} #(0 1 4 9 NIL NIL NIL NIL) @end example @subsubheading Exceptional Situations:: Should signal an error of @i{type} @b{type-error} if @i{vector} is not a @i{vector} with a @i{fill pointer}. @subsubheading See Also:: @ref{make-array} , @ref{length} @subsubheading Notes:: There is no @i{operator} that will remove a @i{vector}'s @i{fill pointer}. @node row-major-aref, upgraded-array-element-type, fill-pointer, Arrays Dictionary @subsection row-major-aref [Accessor] @code{row-major-aref} @i{array index} @result{} @i{element} (setf (@code{ row-major-aref} @i{array index}) new-element)@* @subsubheading Arguments and Values:: @i{array}---an @i{array}. @i{index}---a @i{valid array row-major index} for the @i{array}. @i{element}, @i{new-element}---an @i{object}. @subsubheading Description:: Considers @i{array} as a @i{vector} by viewing its @i{elements} in row-major order, and returns the @i{element} of that @i{vector} which is referred to by the given @i{index}. @b{row-major-aref} is valid for use with @b{setf}. @subsubheading See Also:: @ref{aref} , @ref{array-row-major-index} @subsubheading Notes:: @example (row-major-aref array index) @equiv{} (aref (make-array (array-total-size array) :displaced-to array :element-type (array-element-type array)) index) (aref array i1 i2 ...) @equiv{} (row-major-aref array (array-row-major-index array i1 i2)) @end example @node upgraded-array-element-type, array-dimension-limit, row-major-aref, Arrays Dictionary @subsection upgraded-array-element-type [Function] @code{upgraded-array-element-type} @i{typespec {&optional} environment} @result{} @i{upgraded-typespec} @subsubheading Arguments and Values:: @i{typespec}---a @i{type specifier}. @i{environment}---an @i{environment} @i{object}. The default is @b{nil}, denoting the @i{null lexical environment} and the current @i{global environment}. @i{upgraded-typespec}---a @i{type specifier}. @subsubheading Description:: Returns the @i{element type} of the most @i{specialized} @i{array} representation capable of holding items of the @i{type} denoted by @i{typespec}. The @i{typespec} is a @i{subtype} of (and possibly @i{type equivalent} to) the @i{upgraded-typespec}. If @i{typespec} is @b{bit}, the result is @i{type equivalent} to @t{bit}. If @i{typespec} is @b{base-char}, the result is @i{type equivalent} to @t{base-char}. If @i{typespec} is @b{character}, the result is @i{type equivalent} to @t{character}. The purpose of @b{upgraded-array-element-type} is to reveal how an implementation does its @i{upgrading}. The @i{environment} is used to expand any @i{derived type specifiers} that are mentioned in the @i{typespec}. @subsubheading See Also:: @ref{array-element-type} , @ref{make-array} @subsubheading Notes:: Except for storage allocation consequences and dealing correctly with the optional @i{environment} @i{argument}, @b{upgraded-array-element-type} could be defined as: @example (defun upgraded-array-element-type (type &optional environment) (array-element-type (make-array 0 :element-type type))) @end example @node array-dimension-limit, array-rank-limit, upgraded-array-element-type, Arrays Dictionary @subsection array-dimension-limit [Constant Variable] @subsubheading Constant Value:: A positive @i{fixnum}, the exact magnitude of which is @i{implementation-dependent}, but which is not less than @t{1024}. @subsubheading Description:: The upper exclusive bound on each individual @i{dimension} of an @i{array}. @subsubheading See Also:: @ref{make-array} @node array-rank-limit, array-total-size-limit, array-dimension-limit, Arrays Dictionary @subsection array-rank-limit [Constant Variable] @subsubheading Constant Value:: A positive @i{fixnum}, the exact magnitude of which is @i{implementation-dependent}, but which is not less than @t{8}. @subsubheading Description:: The upper exclusive bound on the @i{rank} of an @i{array}. @subsubheading See Also:: @ref{make-array} @node array-total-size-limit, simple-vector-p, array-rank-limit, Arrays Dictionary @subsection array-total-size-limit [Constant Variable] @subsubheading Constant Value:: A positive @i{fixnum}, the exact magnitude of which is @i{implementation-dependent}, but which is not less than @t{1024}. @subsubheading Description:: The upper exclusive bound on the @i{array total size} of an @i{array}. The actual limit on the @i{array total size} imposed by the @i{implementation} might vary according the @i{element type} of the @i{array}; in this case, the value of @b{array-total-size-limit} will be the smallest of these possible limits. @subsubheading See Also:: @ref{make-array} , @ref{array-element-type} @node simple-vector-p, svref, array-total-size-limit, Arrays Dictionary @subsection simple-vector-p [Function] @code{simple-vector-p} @i{object} @result{} @i{generalized-boolean} @subsubheading Arguments and Values:: @i{object}---an @i{object}. @i{generalized-boolean}---a @i{generalized boolean}. @subsubheading Description:: Returns @i{true} if @i{object} is of @i{type} @b{simple-vector}; otherwise, returns @i{false}.. @subsubheading Examples:: @example (simple-vector-p (make-array 6)) @result{} @i{true} (simple-vector-p "aaaaaa") @result{} @i{false} (simple-vector-p (make-array 6 :fill-pointer t)) @result{} @i{false} @end example @subsubheading See Also:: @b{simple-vector} @subsubheading Notes:: @example (simple-vector-p @i{object}) @equiv{} (typep @i{object} 'simple-vector) @end example @node svref, vector, simple-vector-p, Arrays Dictionary @subsection svref [Accessor] @code{svref} @i{simple-vector index} @result{} @i{element} (setf (@code{ svref} @i{simple-vector index}) new-element)@* @subsubheading Arguments and Values:: @i{simple-vector}---a @i{simple vector}. @i{index}---a @i{valid array index} for the @i{simple-vector}. @i{element}, @i{new-element}---an @i{object} (whose @i{type} is a @i{subtype} of the @i{array element type} of the @i{simple-vector}). @subsubheading Description:: @i{Accesses} the @i{element} of @i{simple-vector} specified by @i{index}. @subsubheading Examples:: @example (simple-vector-p (setq v (vector 1 2 'sirens))) @result{} @i{true} (svref v 0) @result{} 1 (svref v 2) @result{} SIRENS (setf (svref v 1) 'newcomer) @result{} NEWCOMER v @result{} #(1 NEWCOMER SIRENS) @end example @subsubheading See Also:: @ref{aref} , @b{sbit}, @b{schar}, @ref{vector} , @ref{Compiler Terminology} @subsubheading Notes:: @b{svref} is identical to @b{aref} except that it requires its first argument to be a @i{simple vector}. @example (svref @i{v} @i{i}) @equiv{} (aref (the simple-vector @i{v}) @i{i}) @end example @node vector, vector-pop, svref, Arrays Dictionary @subsection vector [Function] @code{vector} @i{{&rest} objects} @result{} @i{vector} @subsubheading Arguments and Values:: @i{object}---an @i{object}. @i{vector}---a @i{vector} of @i{type} @t{(vector t @t{*})}. @subsubheading Description:: Creates a @i{fresh} @i{simple general vector} whose size corresponds to the number of @i{objects}. The @i{vector} is initialized to contain the @i{objects}. @subsubheading Examples:: @example (arrayp (setq v (vector 1 2 'sirens))) @result{} @i{true} (vectorp v) @result{} @i{true} (simple-vector-p v) @result{} @i{true} (length v) @result{} 3 @end example @subsubheading See Also:: @ref{make-array} @subsubheading Notes:: @b{vector} is analogous to @b{list}. @example (vector a{{}_1} a{{}_2} ... a{{}_n}) @equiv{} (make-array (list @i{n}) :element-type t :initial-contents (list a{{}_1} a{{}_2} ... a{{}_n})) @end example @node vector-pop, vector-push, vector, Arrays Dictionary @subsection vector-pop [Function] @code{vector-pop} @i{vector} @result{} @i{element} @subsubheading Arguments and Values:: @i{vector}---a @i{vector} with a @i{fill pointer}. @i{element}---an @i{object}. @subsubheading Description:: Decreases the @i{fill pointer} of @i{vector} by one, and retrieves the @i{element} of @i{vector} that is designated by the new @i{fill pointer}. @subsubheading Examples:: @example (vector-push (setq fable (list 'fable)) (setq fa (make-array 8 :fill-pointer 2 :initial-element 'sisyphus))) @result{} 2 (fill-pointer fa) @result{} 3 (eq (vector-pop fa) fable) @result{} @i{true} (vector-pop fa) @result{} SISYPHUS (fill-pointer fa) @result{} 1 @end example @subsubheading Side Effects:: The @i{fill pointer} is decreased by one. @subsubheading Affected By:: The value of the @i{fill pointer}. @subsubheading Exceptional Situations:: An error of @i{type} @b{type-error} is signaled if @i{vector} does not have a @i{fill pointer}. If the @i{fill pointer} is zero, @b{vector-pop} signals an error of @i{type} @b{error}. @subsubheading See Also:: @ref{vector-push; vector-push-extend} , @b{vector-push-extend}, @ref{fill-pointer} @node vector-push, vectorp, vector-pop, Arrays Dictionary @subsection vector-push, vector-push-extend [Function] @code{vector-push} @i{new-element vector} @result{} @i{new-index-p} @code{vector-push-extend} @i{new-element vector {&optional} extension} @result{} @i{new-index} @subsubheading Arguments and Values:: @i{new-element}---an @i{object}. @i{vector}---a @i{vector} with a @i{fill pointer}. @i{extension}---a positive @i{integer}. The default is @i{implementation-dependent}. @i{new-index-p}---a @i{valid array index} for @i{vector}, or @b{nil}. @i{new-index}---a @i{valid array index} for @i{vector}. @subsubheading Description:: @b{vector-push} and @b{vector-push-extend} store @i{new-element} in @i{vector}. @b{vector-push} attempts to store @i{new-element} in the element of @i{vector} designated by the @i{fill pointer}, and to increase the @i{fill pointer} by one. If the @t{(>= (fill-pointer @i{vector}) (array-dimension @i{vector} 0))}, neither @i{vector} nor its @i{fill pointer} are affected. Otherwise, the store and increment take place and @b{vector-push} returns the former value of the @i{fill pointer} which is one less than the one it leaves in @i{vector}. @b{vector-push-extend} is just like @b{vector-push} except that if the @i{fill pointer} gets too large, @i{vector} is extended using @b{adjust-array} so that it can contain more elements. @i{Extension} is the minimum number of elements to be added to @i{vector} if it must be extended. @b{vector-push} and @b{vector-push-extend} return the index of @i{new-element} in @i{vector}. If @t{(>= (fill-pointer @i{vector}) (array-dimension @i{vector} 0))}, @b{vector-push} returns @b{nil}. @subsubheading Examples:: @example (vector-push (setq fable (list 'fable)) (setq fa (make-array 8 :fill-pointer 2 :initial-element 'first-one))) @result{} 2 (fill-pointer fa) @result{} 3 (eq (aref fa 2) fable) @result{} @i{true} (vector-push-extend #\X (setq aa (make-array 5 :element-type 'character :adjustable t :fill-pointer 3))) @result{} 3 (fill-pointer aa) @result{} 4 (vector-push-extend #\Y aa 4) @result{} 4 (array-total-size aa) @result{} at least 5 (vector-push-extend #\Z aa 4) @result{} 5 (array-total-size aa) @result{} 9 ;(or more) @end example @subsubheading Affected By:: The value of the @i{fill pointer}. How @i{vector} was created. @subsubheading Exceptional Situations:: An error of @i{type} @b{error} is signaled by @b{vector-push-extend} if it tries to extend @i{vector} and @i{vector} is not @i{actually adjustable}. An error of @i{type} @b{error} is signaled if @i{vector} does not have a @i{fill pointer}. @subsubheading See Also:: @ref{adjustable-array-p} , @ref{fill-pointer} , @ref{vector-pop} @node vectorp, bit, vector-push, Arrays Dictionary @subsection vectorp [Function] @code{vectorp} @i{object} @result{} @i{generalized-boolean} @subsubheading Arguments and Values:: @i{object}---an @i{object}. @i{generalized-boolean}---a @i{generalized boolean}. @subsubheading Description:: Returns @i{true} if @i{object} is of @i{type} @b{vector}; otherwise, returns @i{false}. @subsubheading Examples:: @example (vectorp "aaaaaa") @result{} @i{true} (vectorp (make-array 6 :fill-pointer t)) @result{} @i{true} (vectorp (make-array '(2 3 4))) @result{} @i{false} (vectorp #*11) @result{} @i{true} (vectorp #b11) @result{} @i{false} @end example @subsubheading Notes:: @example (vectorp @i{object}) @equiv{} (typep @i{object} 'vector) @end example @node bit, bit-and, vectorp, Arrays Dictionary @subsection bit, sbit [Accessor] @code{bit} @i{bit-array {&rest} subscripts} @result{} @i{bit} @code{sbit} @i{bit-array {&rest} subscripts} @result{} @i{bit} (setf (@code{bit} @i{bit-array {&rest} subscripts}) new-bit)@*(setf (@code{sbit} @i{bit-array {&rest} subscripts}) new-bit)@* @subsubheading Arguments and Values:: @i{bit-array}---for @b{bit}, a @i{bit array}; for @b{sbit}, a @i{simple bit array}. @i{subscripts}---a @i{list} of @i{valid array indices} for the @i{bit-array}. @i{bit}---a @i{bit}. @subsubheading Description:: @b{bit} and @b{sbit} @i{access} the @i{bit-array} @i{element} specified by @i{subscripts}. These @i{functions} ignore the @i{fill pointer} when @i{accessing} @i{elements}. @subsubheading Examples:: @example (bit (setq ba (make-array 8 :element-type 'bit :initial-element 1)) 3) @result{} 1 (setf (bit ba 3) 0) @result{} 0 (bit ba 3) @result{} 0 (sbit ba 5) @result{} 1 (setf (sbit ba 5) 1) @result{} 1 (sbit ba 5) @result{} 1 @end example @subsubheading See Also:: @ref{aref} , @ref{Compiler Terminology} @subsubheading Notes:: @b{bit} and @b{sbit} are like @b{aref} except that they require @i{arrays} to be a @i{bit array} and a @i{simple bit array}, respectively. @b{bit} and @b{sbit}, unlike @b{char} and @b{schar}, allow the first argument to be an @i{array} of any @i{rank}. @node bit-and, bit-vector-p, bit, Arrays Dictionary @subsection bit-and, bit-andc1, bit-andc2, bit-eqv, @subheading bit-ior, bit-nand, bit-nor, bit-not, bit-orc1, bit-orc2, bit-xor @flushright @i{[Function]} @end flushright @code{bit-and} @i{bit-array1 bit-array2 {&optional} opt-arg} @result{} @i{resulting-bit-array} @code{bit-andc1} @i{bit-array1 bit-array2 {&optional} opt-arg} @result{} @i{resulting-bit-array} @code{bit-andc2} @i{bit-array1 bit-array2 {&optional} opt-arg} @result{} @i{resulting-bit-array} @code{bit-eqv} @i{bit-array1 bit-array2 {&optional} opt-arg} @result{} @i{resulting-bit-array} @code{bit-ior} @i{bit-array1 bit-array2 {&optional} opt-arg} @result{} @i{resulting-bit-array} @code{bit-nand} @i{bit-array1 bit-array2 {&optional} opt-arg} @result{} @i{resulting-bit-array} @code{bit-nor} @i{bit-array1 bit-array2 {&optional} opt-arg} @result{} @i{resulting-bit-array} @code{bit-orc1} @i{bit-array1 bit-array2 {&optional} opt-arg} @result{} @i{resulting-bit-array} @code{bit-orc2} @i{bit-array1 bit-array2 {&optional} opt-arg} @result{} @i{resulting-bit-array} @code{bit-xor} @i{bit-array1 bit-array2 {&optional} opt-arg} @result{} @i{resulting-bit-array} @code{bit-not} @i{bit-array {&optional} opt-arg} @result{} @i{resulting-bit-array} @subsubheading Arguments and Values:: @i{bit-array}, @i{bit-array1}, @i{bit-array2}---a @i{bit array}. @i{Opt-arg}---a @i{bit array}, or @b{t}, or @b{nil}. The default is @b{nil}. @i{Bit-array}, @i{bit-array1}, @i{bit-array2}, and @i{opt-arg} (if an @i{array}) must all be of the same @i{rank} and @i{dimensions}. @i{resulting-bit-array}---a @i{bit array}. @subsubheading Description:: These functions perform bit-wise logical operations on @i{bit-array1} and @i{bit-array2} and return an @i{array} of matching @i{rank} and @i{dimensions}, such that any given bit of the result is produced by operating on corresponding bits from each of the arguments. In the case of @b{bit-not}, an @i{array} of @i{rank} and @i{dimensions} matching @i{bit-array} is returned that contains a copy of @i{bit-array} with all the bits inverted. If @i{opt-arg} is of type @t{(array bit)} the contents of the result are destructively placed into @i{opt-arg}. If @i{opt-arg} is the symbol @b{t}, @i{bit-array} or @i{bit-array1} is replaced with the result; if @i{opt-arg} is @b{nil} or omitted, a new @i{array} is created to contain the result. Figure 15--4 indicates the logical operation performed by each of the @i{functions}. 2 @group @noindent @w{@b{Function} @b{Operation} } @w{_______________________________________________________________________________________________________} @w{ } @w{@b{bit-and} and } @w{@b{bit-eqv} equivalence (exclusive nor) } @w{@b{bit-not} complement } @w{@b{bit-ior} inclusive or } @w{@b{bit-xor} exclusive or } @w{@b{bit-nand} complement of @i{bit-array1} and @i{bit-array2} } @w{@b{bit-nor} complement of @i{bit-array1} or @i{bit-array2} } @w{@b{bit-andc1} and complement of @i{bit-array1} with @i{bit-array2}} @w{@b{bit-andc2} and @i{bit-array1} with complement of @i{bit-array2}} @w{@b{bit-orc1} or complement of @i{bit-array1} with @i{bit-array2} } @w{@b{bit-orc2} or @i{bit-array1} with complement of @i{bit-array2} } @w{@w{ Figure 15--3: Bit-wise Logical Operations on Bit Arrays} } @end group @subsubheading Examples:: @example (bit-and (setq ba #*11101010) #*01101011) @result{} #*01101010 (bit-and #*1100 #*1010) @result{} #*1000 (bit-andc1 #*1100 #*1010) @result{} #*0010 (setq rba (bit-andc2 ba #*00110011 t)) @result{} #*11001000 (eq rba ba) @result{} @i{true} (bit-not (setq ba #*11101010)) @result{} #*00010101 (setq rba (bit-not ba (setq tba (make-array 8 :element-type 'bit)))) @result{} #*00010101 (equal rba tba) @result{} @i{true} (bit-xor #*1100 #*1010) @result{} #*0110 @end example @subsubheading See Also:: @b{lognot}, @ref{logand; logandc1; logandc2; logeqv; logior; lognand; lognor; lognot; logorc1; logorc2; logxor} @node bit-vector-p, simple-bit-vector-p, bit-and, Arrays Dictionary @subsection bit-vector-p [Function] @code{bit-vector-p} @i{object} @result{} @i{generalized-boolean} @subsubheading Arguments and Values:: @i{object}---an @i{object}. @i{generalized-boolean}---a @i{generalized boolean}. @subsubheading Description:: Returns @i{true} if @i{object} is of @i{type} @b{bit-vector}; otherwise, returns @i{false}. @subsubheading Examples:: @example (bit-vector-p (make-array 6 :element-type 'bit :fill-pointer t)) @result{} @i{true} (bit-vector-p #*) @result{} @i{true} (bit-vector-p (make-array 6)) @result{} @i{false} @end example @subsubheading See Also:: @ref{typep} @subsubheading Notes:: @example (bit-vector-p @i{object}) @equiv{} (typep @i{object} 'bit-vector) @end example @node simple-bit-vector-p, , bit-vector-p, Arrays Dictionary @subsection simple-bit-vector-p [Function] @code{simple-bit-vector-p} @i{object} @result{} @i{generalized-boolean} @subsubheading Arguments and Values:: @i{object}---an @i{object}. @i{generalized-boolean}---a @i{generalized boolean}. @subsubheading Description:: Returns @i{true} if @i{object} is of @i{type} @b{simple-bit-vector}; otherwise, returns @i{false}. @subsubheading Examples:: @example (simple-bit-vector-p (make-array 6)) @result{} @i{false} (simple-bit-vector-p #*) @result{} @i{true} @end example @subsubheading See Also:: @ref{simple-vector-p} @subsubheading Notes:: @example (simple-bit-vector-p @i{object}) @equiv{} (typep @i{object} 'simple-bit-vector) @end example @c end of including dict-arrays @c %**end of chapter