clqr-arrays.tex

   1 % Copyright (C) 2008, 2009, 2010, 2011, 2012, 2014, 2018
   2 % Bert Burgemeister
   3 %
   4 % Permission is granted to copy, distribute and/or modify this
   5 % document under the terms of the GNU Free Documentation License,
   6 % Version 1.2; 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   \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   % No default subscripts in standard.
  42
  43 \end{LIST}
  44
  45
  46 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  47 \subsection{Array Functions}
  48 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  49 \begin{LIST}{1cm}
  50
  51   \IT{(\xorGOO{%
  52       \FU*{MAKE-ARRAY}\VAR{ dimension-sizes }
  53       \OP{\kwd{:adjustable} \VAR{ bool}\DF{\NIL}}\\
  54       \FU*{ADJUST-ARRAY } \DES{\VAR{array}}
  55       \VAR{ dimension-sizes}}{\}}
  56     \orGOO{\kwd{:element-type} \VAR{ type}\DF{\T}\\
  57       \kwd{:fill-pointer } \Goo{\VAR{num}\XOR\VAR{bool}}\DF{\NIL}\\
  58       \xorGOO{\kwd{:initial-element} \VAR{ obj}\\
  59         \kwd{:initial-contents} \VAR{ tree-or-array}\\
  60         \kwd{:displaced-to } \VAR{array}\DF{\NIL}\text{ }
  61         \Op{\kwd{:displaced-index-offset } \VAR{i}\DF{\LIT{0}}}}{.}}{\}})}
  62   {
  63   Return fresh, or readjust, respectively, \retval{vector} or \retval{array}.
  64   }
  65
  66   \IT{(\FU*{AREF} \VAR{array} \OP{\VAR{subscripts}})}
  67   {
  68   Return
  69   \retval{array element} pointed to by \VAR{subscripts}. \kwd{setf}able.
  70   }
  71   % No subscripts means sole element of rank zero array.
  72
  73   \IT{(\FU*{ROW-MAJOR-AREF} \VAR{array} \VAR{i})}
  74   {
  75   Return \retval{\VAR{i}th element} of \VAR{array} in row-major
  76   order. \kwd{setf}able.
  77   }
  78
  79   \IT{(\FU*{ARRAY-ROW-MAJOR-INDEX} \VAR{array} \Op{\VAR{subscripts}})}
  80   {
  81   \retval{Index} in row-major order of the element denoted by \VAR{subscripts}.
  82   }
  83
  84   \IT{(\FU*{ARRAY-DIMENSIONS} \VAR{array})}
  85   {
  86   \retval{List} containing the lengths of \VAR{array}'s dimensions.
  87   }
  88
  89   \IT{(\FU*{ARRAY-DIMENSION} \VAR{array} \VAR{i})}
  90   {
  91   \retval{Length of \VAR{i}th dimension} of \VAR{array}.
  92   }
  93
  94   \IT{(\FU*{ARRAY-TOTAL-SIZE} \VAR{array})}
  95   {
  96     \retval{Number of elements} in \VAR{array}.
  97   }
  98
  99   \IT{(\FU*{ARRAY-RANK} \VAR{array})}
 100   {
 101     \retval{Number of dimensions} of \VAR{array}.
 102   }
 103
 104   \IT{(\FU*{ARRAY-DISPLACEMENT} \VAR{array})}
 105   {
 106   \retval{Target array} and \retvalii{offset}.
 107   }
 108
 109   \IT{\arrGOO{(\FU*{BIT} \VAR{ bit-array } \Op{\VAR{subscripts}})\\
 110       (\FU*{SBIT} \VAR{ simple-bit-array } \Op{\VAR{subscripts}})}{.}}
 111   {
 112   Return \retval{element} of \VAR{bit-array} or of
 113   \VAR{simple-bit-array}. \kwd{setf}\-able.
 114   }
 115
 116   \IT{(\FU*{BIT-NOT} \DES{\VAR{bit-array}} \Op{\DES{\VAR{result-bit-array}}\DF{\NIL}})}
 117   {
 118   Return \retval{result} of bitwise negation of \VAR{bit-array}. If \VAR{result-bit-array} is \T, put
 119   result in \VAR{bit-array}; if it is \NIL, make a new array for
 120   result.
 121   }
 122
 123   \IT{(\xorGOO{%
 124       \FU*{BIT-EQV}\\
 125       \FU*{BIT-AND}\\
 126       \FU*{BIT-ANDC1}\\
 127       \FU*{BIT-ANDC2}\\
 128       \FU*{BIT-NAND}\\
 129       \FU*{BIT-IOR}\\
 130       \FU*{BIT-ORC1}\\
 131       \FU*{BIT-ORC2}\\
 132       \FU*{BIT-XOR}\\
 133       \FU*{BIT-NOR}}{\}} \DES{\VAR{bit-array-a}} \VAR{bit-array-b}
 134     \Op{\DES{\VAR{result-bit-array}}\DF{\NIL}})}
 135   {
 136   Return \retval{result} of bitwise logical operations
 137   (cf.\ operations of \FU{boole}, page \pageref{section:Logic Functions}) on
 138   \VAR{bit-array-a} and  \VAR{bit-array-b}.  If \VAR{result-bit-array} is \T, put result in
 139   \VAR{bit-array-a}; if it is \NIL, make a new array for
 140   result.
 141   }
 142
 143   \IT{\CNS*{ARRAY-RANK-LIMIT}}
 144   {
 145   Upper bound of array rank; $\geq 8$.
 146   }
 147
 148   \IT{\CNS*{ARRAY-DIMENSION-LIMIT}}
 149   {
 150   Upper bound of an array dimension; $\geq 1024$.
 151   }
 152
 153   \IT{\CNS*{ARRAY-TOTAL-SIZE-LIMIT}}
 154   {
 155   Upper bound of array size; $\geq 1024$.
 156   }
 157
 158 \end{LIST}
 159
 160
 161 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 162 \subsection{Vector Functions}
 163 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 164
 165 Vectors can as well be manipulated by sequence functions; see
 166 section~\ref{section:Sequences}.
 167
 168 \begin{LIST}{1cm}
 169
 170   \IT{(\FU*{VECTOR} \OPn{\VAR{foo}})}
 171   {
 172     Return fresh \retval{simple vector of \VAR{foo}s}.
 173   }
 174   % No default foo in standard.
 175
 176   \IT{(\FU*{SVREF} \VAR{vector} \VAR{i})}
 177   {
 178     \retval{Element \VAR{i}} of simple \VAR{vector}. \kwd{setf}able.
 179   }
 180
 181   \IT{(\FU*{VECTOR-PUSH} \VAR{foo} \DES{\VAR{vector}})}
 182   {
 183   Return \retval{\NIL} if \VAR{vector}'s fill pointer equals size of
 184   \VAR{vector}. Otherwise replace element of \VAR{vector} pointed to
 185   by \retval{fill pointer} with \VAR{foo}; then increment fill
 186   pointer.
 187   }
 188
 189   \IT{(\FU*{VECTOR-PUSH-EXTEND} \VAR{foo} \DES{\VAR{vector}}
 190     \Op{\VAR{num}})}
 191   {
 192   Replace element of \VAR{vector} pointed to by \retval{fill pointer} with
 193   \VAR{foo}, then increment fill pointer. Extend \VAR{vector}'s size by
 194   $\ge \VAR{num}$ if necessary.
 195   }
 196
 197   \IT{(\FU*{VECTOR-POP} \DES{\VAR{vector}})}
 198   {
 199   Return \retval{element of \VAR{vector}} its fillpointer points to
 200   after decrementation.
 201   }
 202
 203   \IT{(\FU*{FILL-POINTER} \VAR{vector})}
 204   {
 205   \retval{Fill pointer} of \VAR{vector}. \kwd{setf}able.
 206   }
 207
 208 \end{LIST}
 209
 210
 211
 212 %%% Local Variables:
 213 %%% mode: latex
 214 %%% TeX-master: "clqr"
 215 %%% End: