clqr-arrays.tex

   1 % Copyright (C) 2008 Bert Burgemeister
   2 %
   3 % Permission is granted to copy, distribute and/or modify this
   4 % document under the terms of the GNU Free Documentation License,
   5 % Version 1.2 or any later version published by the Free Software
   6 % Foundation; with no Invariant Sections, no Front-Cover Texts and
   7 % no Back-Cover Texts. For details see file COPYING.
   8 %
   9
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11 \section{Arrays}
  12 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  13 \label{section:Arrays}
  14
  15 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  16 \subsection{Predicates}
  17 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  18 \begin{LIST}{1cm}
  19
  20   \IT{(\FU*{ARRAYP} \VAR{foo})}
  21   Return \retval{\T} if \VAR{foo} is of type \kwd{array}.
  22
  23   \IT{\arrGOO{(\FU*{ADJUSTABLE-ARRAY-P} \VAR{ array})\\
  24       (\FU*{ARRAY-HAS-FILL-POINTER-P} \VAR{ array})}{\}}}
  25   Return \retval{\T} if \VAR{array} is adjustable/has a fill pointer,
  26   resp.
  27
  28   \IT{(\FU*{ARRAY-IN-BOUNDS-P} \VAR{array} \Op{\VAR{subscripts}})}
  29   Return \retval{\T} if \VAR{subscripts} are in \VAR{array}'s bounds.
  30
  31   \IT{\arrGOO{%
  32       (\FU*{VECTORP} \VAR{ foo})\\
  33       (\FU*{SIMPLE-VECTOR-P} \VAR{ foo})\\
  34       (\FU*{BIT-VECTOR-P} \VAR{ foo})\\
  35       (\FU*{SIMPLE-BIT-VECTOR-P} \VAR{ foo})}{\}}}
  36   \retval{\T} if \VAR{foo} is of indicated type.
  37
  38 \end{LIST}
  39
  40
  41 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  42 \subsection{Array Functions}
  43 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  44 \begin{LIST}{1cm}
  45
  46   \IT{(\xorGOO{\FU*{MAKE-ARRAY}\\\FU*{ADJUST-ARRAY} \VAR{ array}}{\}}%
  47     \xorGOO{\VAR{dim}\\\kwd{'}(\OPn{\VAR{dim}})}{\}}
  48     \orGOO{\kwd{:element-type} \VAR{ type}\DF{\T}\\
  49       \kwd{:adjustable} \VAR{ bool}\DF{\NIL}\\
  50       \kwd{:fill-pointer} \Goo{\VAR{num}\XOR\VAR{bool}}\DF{\NIL}\\
  51       \xorGOO{\kwd{:initial-element} \VAR{ obj}\\
  52         \kwd{:initial-contents} \VAR{ seq}\\
  53         \kwd{:displaced-to} \xorGOO{\VAR{array}\\\VAR{bool}\DF{\NIL}}{\}}
  54         \Op{\kwd{:displaced-index-offset} \VAR{i}\DF{0}}}{.}}{\}})}
  55   Return fresh, or readjust, resp., \retval{vector or array of
  56     dimension(s) \VAR{dim}}.
  57
  58   \IT{(\kwd*{AREF} \VAR{array} \OP{\VAR{subscripts}})} Return
  59   \retval{array element} pointed to by \VAR{subscripts}. \kwd{setf}able.
  60
  61   \IT{(\FU*{ROW-MAJOR-AREF} \VAR{array} \VAR{i})}
  62   Return \retval{\VAR{i}th element} of \VAR{array} in row-major order.
  63
  64   \IT{(\FU*{ARRAY-ROW-MAJOR-INDEX} \VAR{array} \VAR{subscripts})}
  65   \retval{Index} in row-major order of element denoted by \VAR{subscripts}.
  66
  67   \IT{(\FU*{ARRAY-DIMENSIONS} \VAR{array})}
  68   \retval{List} containing \VAR{array}'s dimensions.
  69
  70   \IT{(\FU*{ARRAY-DIMENSION} \VAR{array} \VAR{i})}
  71   \retval{length of \VAR{i}th dimension} of \VAR{array}.
  72
  73   \IT{(\FU*{ARRAY-TOTAL-SIZE} \VAR{array})}
  74   \retval{Number of elements} in \VAR{array}.
  75
  76   \IT{(\FU*{ARRAY-DISPLACEMENT} \VAR{array})}
  77   \retval{Target array} and \retval{offset}.
  78
  79    \IT{(\FU*{ARRAY-RANK} \VAR{array})}
  80   \retval{Number of dimensions} of \VAR{array}.
  81
  82   \IT{\arrGOO{(\FU*{BIT} \VAR{ bit-array} \VAR{ subscripts})\\
  83       (\FU*{SBIT} \VAR{ simple-bit-array} \VAR{ subscripts})}{\}}}
  84   Return \retval{element} of \VAR{bit-array} or of
  85   \VAR{simple-bit-array}. \kwd{setf}able.
  86
  87   \IT{(\FU*{BIT-NOT} \VAR{bit-array} \Op{\VAR{arg}\DF{\NIL}})}
  88   Return \retval{result} of bit-wise negation of \VAR{bit-array}. If
  89   \VAR{arg} is a bit array, put result there. If \VAR{arg} is \T, put
  90   result in \VAR{bit-arry}. If \VAR{arg} is \NIL, make a new array for
  91   result.
  92
  93   \IT{(\xorGOO{\FU*{BIT-AND}\\
  94       \FU*{BIT-ANDC1}\\
  95       \FU*{BIT-ANDC2}\\
  96       \FU*{BIT-EQV}\\
  97       \FU*{BIT-IOR}\\
  98       \FU*{BIT-NAND}\\
  99       \FU*{BIT-NOR}\\
 100       \FU*{BIT-ORC1}\\
 101       \FU*{BIT-ORC2}\\
 102       \FU*{BIT-XOR}}{\}} \VAR{bit-array-a} \VAR{bit-array-b}
 103     \Op{\VAR{arg}\DF{\NIL}})}
 104   Return \retval{result} of bit-wise logical operations on
 105   \VAR{bit-array-a} and  \VAR{bit-array-b}. If \VAR{arg} is a bit
 106   array, put result there. If \VAR{arg} is \T, put result in
 107   \VAR{bit-arry-a}. If \VAR{arg} is \NIL, make a new array for
 108   result.
 109
 110   \IT{\CNS*{ARRAY-RANK-LIMIT}}
 111   Upper bound of array rank, $> 8$.
 112
 113   \IT{\CNS*{ARRAY-DIMENSION-LIMIT}}
 114   Upper bound of an array dimension, $> 1024$.
 115
 116   \IT{\CNS*{ARRAY-TOTAL-SIZE-LIMIT}}
 117   Upper bound of array size, $> 1024$.
 118
 119 \end{LIST}
 120
 121
 122 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 123 \subsection{Vector Functions}
 124 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 125
 126 Vectors can as well be manipulated by sequence functions, see
 127 s.\ \ref{section:Sequences}.
 128
 129 \begin{LIST}{1cm}
 130
 131   \IT{(\FU*{VECTOR} \OPn{\VAR{foo}})}
 132   Return fresh \retval{vector of \VAR{foo}s}.
 133
 134   \IT{(\kwd*{SVREF} \VAR{vector} \VAR{i})}
 135   Return \retval{\VAR{i}th
 136     element} of \VAR{vector}. \kwd{setf}able.
 137
 138   \IT{(\FU*{VECTOR-PUSH} \VAR{foo} \VAR{vector})}
 139   Return \retval{\NIL} if \VAR{vector}'s fill pointer equals size of
 140   \VAR{vector}. Otherwise replace element of \VAR{vector} pointed to
 141   by \retval{fill pointer} with \VAR{foo}, then increment fill
 142   pointer.
 143
 144   \IT{(\FU*{VECTOR-PUSH-EXTEND} \VAR{foo} \VAR{vector} \Op{\VAR{num}})}
 145   Replace element of \VAR{vector} pointed to by \retval{fill pointer} with
 146   \VAR{foo}, then increment fill pointer. Extend \VAR{vector}'s size by
 147   $\ge \VAR{num}$ if necessary.
 148
 149   \IT{(\FU*{VECTOR-POP} \VAR{vector})}
 150   Return \retval{element of \VAR{vector}} its fillpointer points to
 151   after decrementation.
 152
 153 \end{LIST}
 154
 155