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{\arrGOO{%
  21       (\FU*{ARRAYP} \VAR{ foo})\\
  22       (\FU*{VECTORP} \VAR{ foo})\\
  23       (\FU*{SIMPLE-VECTOR-P} \VAR{ foo})\\
  24       (\FU*{BIT-VECTOR-P} \VAR{ foo})\\
  25       (\FU*{SIMPLE-BIT-VECTOR-P} \VAR{ foo})}{.}}
  26   {
  27   \retval{\T} if \VAR{foo} is of indicated type.
  28   }
  29
  30   \IT{\arrGOO{(\FU*{ADJUSTABLE-ARRAY-P} \VAR{ array})\\
  31       (\FU*{ARRAY-HAS-FILL-POINTER-P} \VAR{ array})}{.}}
  32   {
  33   Return \retval{\T} if \VAR{array} is adjustable/has a fill pointer,
  34   respectively.
  35   }
  36
  37   \IT{(\FU*{ARRAY-IN-BOUNDS-P} \VAR{array} \Op{\VAR{subscripts}})}
  38   {
  39   Return \retval{\T} if \VAR{subscripts} are in \VAR{array}'s bounds.
  40   }
  41
  42 \end{LIST}
  43
  44
  45 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  46 \subsection{Array Functions}
  47 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  48 \begin{LIST}{1cm}
  49
  50   \IT{(\xorGOO{\FU*{MAKE-ARRAY}\\
  51       \FU*{ADJUST-ARRAY } \DES{\VAR{array}}}{\}}
  52     \VAR{dimensions}
  53     \orGOO{\kwd{:element-type} \VAR{ type}\DF{\T}\\
  54       \kwd{:adjustable} \VAR{ bool}\DF{\NIL}\\
  55       \kwd{:fill-pointer } \Goo{\VAR{num}\XOR\VAR{bool}}\DF{\NIL}\\
  56       \xorGOO{\kwd{:initial-element} \VAR{ obj}\\
  57         \kwd{:initial-contents} \VAR{ sequence}\\
  58         \kwd{:displaced-to } \VAR{array}\DF{\NIL}\text{ }
  59         \Op{\kwd{:displaced-index-offset } \VAR{i}\DF{\LIT{0}}}}{.}}{\}})}
  60   {
  61   Return fresh, or readjust, respectively, \retval{vector or array} of
  62     \VAR{dimensions}.
  63   }
  64
  65   \IT{(\FU*{AREF} \VAR{array} \OP{\VAR{subscripts}})}
  66   {
  67   Return
  68   \retval{array element} pointed to by \VAR{subscripts}. \kwd{setf}able.
  69   }
  70
  71   \IT{(\FU*{ROW-MAJOR-AREF} \VAR{array} \VAR{i})}
  72   {
  73   Return \retval{\VAR{i}th element} of \VAR{array} in row-major
  74   order. \kwd{setf}able.
  75   }
  76
  77   \IT{(\FU*{ARRAY-ROW-MAJOR-INDEX} \VAR{array} \Op{\VAR{subscripts}})}
  78   {
  79   \retval{Index} in row-major order of the element denoted by \VAR{subscripts}.
  80   }
  81
  82   \IT{(\FU*{ARRAY-DIMENSIONS} \VAR{array})}
  83   {
  84   \retval{List} containing the lengths of \VAR{array}'s dimensions.
  85   }
  86
  87   \IT{(\FU*{ARRAY-DIMENSION} \VAR{array} \VAR{i})}
  88   {
  89   \retval{Length of \VAR{i}th dimension} of \VAR{array}.
  90   }
  91
  92   \IT{(\FU*{ARRAY-TOTAL-SIZE} \VAR{array})}
  93   {
  94   \retval{Number of elements} in \VAR{array}.
  95   }
  96
  97   \IT{(\FU*{ARRAY-DISPLACEMENT} \VAR{array})}
  98   {
  99   \retval{Target array} and \retvalii{offset}.
 100   }
 101
 102    \IT{(\FU*{ARRAY-RANK} \VAR{array})}
 103    {
 104   \retval{Number of dimensions} of \VAR{array}.
 105   }
 106
 107   \IT{\arrGOO{(\FU*{BIT} \VAR{ bit-array } \Op{\VAR{subscripts}})\\
 108       (\FU*{SBIT} \VAR{ simple-bit-array } \Op{\VAR{subscripts}})}{.}}
 109   {
 110   Return \retval{element} of \VAR{bit-array} or of
 111   \VAR{simple-bit-array}. \kwd{setf}able.
 112   }
 113
 114   \IT{(\FU*{BIT-NOT} \DES{\VAR{bit-array}} \Op{\DES{\VAR{result-bit-array}}\DF{\NIL}})}
 115   {
 116   Return \retval{result} of bit-wise negation of \VAR{bit-array}. If \VAR{result-bit-array} is \T, put
 117   result in \VAR{bit-array}; if it is \NIL, make a new array for
 118   result.
 119   }
 120
 121   \IT{(\xorGOO{%
 122       \FU*{BIT-EQV}\\
 123       \FU*{BIT-AND}\\
 124       \FU*{BIT-ANDC1}\\
 125       \FU*{BIT-ANDC2}\\
 126       \FU*{BIT-NAND}\\
 127       \FU*{BIT-IOR}\\
 128       \FU*{BIT-ORC1}\\
 129       \FU*{BIT-ORC2}\\
 130       \FU*{BIT-XOR}\\
 131       \FU*{BIT-NOR}}{\}} \DES{\VAR{bit-array-a}} \VAR{bit-array-b}
 132     \Op{\DES{\VAR{result-bit-array}}\DF{\NIL}})}
 133   {
 134   Return \retval{result} of bit-wise logical operations
 135   (cf.\ operations of \FU{boole}, p.\ \pageref{section:Logic Functions}) on
 136   \VAR{bit-array-a} and  \VAR{bit-array-b}.  If \VAR{result-bit-array} is \T, put result in
 137   \VAR{bit-array-a}; if it is \NIL, make a new array for
 138   result.
 139   }
 140
 141   \IT{\CNS*{ARRAY-RANK-LIMIT}}
 142   {
 143   Upper bound of array rank, $\geq 8$.
 144   }
 145
 146   \IT{\CNS*{ARRAY-DIMENSION-LIMIT}}
 147   {
 148   Upper bound of an array dimension, $\geq 1024$.
 149   }
 150
 151   \IT{\CNS*{ARRAY-TOTAL-SIZE-LIMIT}}
 152   {
 153   Upper bound of array size, $\geq 1024$.
 154   }
 155
 156 \end{LIST}
 157
 158
 159 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 160 \subsection{Vector Functions}
 161 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 162
 163 Vectors can as well be manipulated by sequence functions, see
 164 s.~\ref{section:Sequences}.
 165
 166 \begin{LIST}{1cm}
 167
 168   \IT{(\FU*{VECTOR} \OPn{\VAR{foo}})}
 169   {
 170   Return fresh \retval{simple vector of \VAR{foo}s}.
 171   }
 172
 173   \IT{(\FU*{SVREF} \VAR{vector} \VAR{i})}
 174   {
 175   Return \retval{\VAR{i}th
 176     element} of \VAR{vector}. \kwd{setf}able.
 177   }
 178
 179   \IT{(\FU*{VECTOR-PUSH} \VAR{foo} \DES{\VAR{vector}})}
 180   {
 181   Return \retval{\NIL} if \VAR{vector}'s fill pointer equals size of
 182   \VAR{vector}. Otherwise replace element of \VAR{vector} pointed to
 183   by \retval{fill pointer} with \VAR{foo}; then increment fill
 184   pointer.
 185   }
 186
 187   \IT{(\FU*{VECTOR-PUSH-EXTEND} \VAR{foo} \DES{\VAR{vector}}
 188     \Op{\VAR{num}})}
 189   {
 190   Replace element of \VAR{vector} pointed to by \retval{fill pointer} with
 191   \VAR{foo}, then increment fill pointer. Extend \VAR{vector}'s size by
 192   $\ge \VAR{num}$ if necessary.
 193   }
 194
 195   \IT{(\FU*{VECTOR-POP} \DES{\VAR{vector}})}
 196   {
 197   Return \retval{element of \VAR{vector}} its fillpointer points to
 198   after decrementation.
 199   }
 200
 201   \IT{(\FU*{FILL-POINTER} \VAR{vector})}
 202   {
 203   Return \retval{fill pointer} of \VAR{vector}. \kwd{setf}able.
 204   }
 205
 206 \end{LIST}
 207
 208