1
0
Fork 0
cl-sites/ecl.common-lisp.dev/static/manual/Arrays.html
2024-12-24 19:15:49 +01:00

500 lines
40 KiB
HTML

<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.0.3, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Arrays (ECL Manual)</title>
<meta name="description" content="Arrays (ECL Manual)">
<meta name="keywords" content="Arrays (ECL Manual)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">
<link href="index.html" rel="start" title="Top">
<link href="Indexes.html" rel="index" title="Indexes">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Standards.html" rel="up" title="Standards">
<link href="Strings.html#Strings" rel="next" title="Strings">
<link href="Conses.html" rel="prev" title="Conses">
<style type="text/css">
<!--
/* colors */
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
div.example {margin-left: 3.2em}
span.r {font-family: initial; font-weight: normal; font-style: normal}
span:hover a.copiable-link {visibility: visible}
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
ul.mark-bullet {list-style-type: disc}
@media (prefers-color-scheme: dark) {
/* dark theme */
html { color: seashell;
background: #1A1A1A; }
body { background: #1A1A1A; }
th { border-bottom: 2px solid lightgray; }
h1, h2, h3, h4, h5 { background-image: linear-gradient(to left, #202020, #3A3A3A); }
code, var, code a { color: darkorange;
background: #2A2A2A; }
a { color: seashell; }
pre { background: #2A2A2A;
color: seashell;
/* mark longer code block with stripe on the left */
border-left: 5px solid darkorange;
padding-left: 10px; }
pre.screen { background: #2A2A2A;
border: 1px solid lightgray; }
pre.programlisting { background: #2A2A2A;
border-left: 1px solid lightgray;
border-top: 1px solid lightgray; }
/* we need a light background in order for the images to be readable */
img { background: white }
}
@media (prefers-color-scheme: light) {
/* light theme */
html { background: white }
body { background: white }
th { border-bottom: 2px solid gray; }
h1, h2, h3, h4, h5 { background: lightgray; }
code, var, code a { color: darkred;
background: whitesmoke; }
a { color: #000; }
pre { background: whitesmoke;
color: black;
/* mark longer code block with stripe on the left */
border-left: 5px solid darkred;
padding-left: 10px; }
pre.screen { background: #EEE;
border: 1px solid black; }
pre.programlisting { background: #EEEEEE;
border-left: 1px solid black;
border-top: 1px solid black; }
}
body {
margin: 1em 125px 0 10%;
line-height: 1.5em;
padding: 0 2em 1em 2em;
font: 13px Verdana,Arial, sans-serif
}
ul, dd, dl, dt { margin-top: 0; margin-bottom: 0; }
p, code, td, dl, dt {
line-height: 1.5em;
}
table {
font: inherit;
border-collapse: collapse;
}
th, td {
vertical-align: top;
}
h1, h2, h3 { padding-left: 15px; }
h4, h5 { padding-left: 5px; }
code, pre {
font-size: 1em;
font-family: monospace;
}
var {
font-size: 1em;
}
/* links inside code appear the same as the code itself */
code a {
font-weight: normal;
text-decoration: none;
}
/* but get an underline when hovering */
code a:hover {
text-decoration: underline;
}
/* ordinary links appear in bold */
a { font-weight: bold; }
pre.verbatim {
margin: 0 0 0 0;
}
pre {
overflow: auto;
}
pre.screen {
font-weight: bold;
padding: 0.5em;
}
pre.programlisting {
padding: 0.5em;
}
div p { padding: 0 2em }
li p { padding: 0; margin: 0 }
hr { display: none; }
div.funcsynopsis p {
text-indent: -2em;
}
div.variablelist {
padding: 0 2em;
}
.type, .funcsynopsis, .symbol {
font-family: monospace;
}
.type, .symbol, .replaceable {
white-space: nowrap;
}
-->
</style>
</head>
<body lang="en">
<div class="section-level-extent" id="Arrays">
<div class="nav-panel">
<p>
Next: <a href="Strings.html#Strings" accesskey="n" rel="next">Strings</a>, Previous: <a href="Conses.html" accesskey="p" rel="prev">Conses</a>, Up: <a href="Standards.html" accesskey="u" rel="up">Standards</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
</div>
<h3 class="section" id="Arrays-1">2.13 Arrays</h3>
<a class="index-entry-id" id="index-Arrays"></a>
<ul class="mini-toc">
<li><a href="Arrays.html#Arrays-_002d-Array-limits" accesskey="1">Array limits</a></li>
<li><a href="Arrays.html#Arrays-_002d-Specializations" accesskey="2">Specializations</a></li>
<li><a href="Arrays.html#Arrays-_002d-C-Reference" accesskey="3">C Reference</a></li>
</ul>
<hr>
<div class="subsection-level-extent" id="Arrays-_002d-Array-limits">
<div class="nav-panel">
<p>
Next: <a href="Arrays.html#Arrays-_002d-Specializations" accesskey="n" rel="next">Specializations</a>, Up: <a href="Arrays.html#Arrays" accesskey="u" rel="up">Arrays</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
</div>
<h4 class="subsection" id="Array-limits">2.13.1 Array limits</h4>
<p>ECL arrays can have up to 64 dimensions. Common-Lisp constants related to arrays have the following values in ECL.
</p><table class="multitable">
<thead><tr><th width="50%">Constant</th><th width="50%">Value</th></tr></thead>
<tbody><tr><td width="50%">array-rank-limit</td><td width="50%">64</td></tr>
<tr><td width="50%">array-dimension-limit</td><td width="50%">most-positive-fixnum</td></tr>
<tr><td width="50%">array-total-size-limit</td><td width="50%">array-dimension-limit</td></tr>
</tbody>
</table>
<hr>
</div>
<div class="subsection-level-extent" id="Arrays-_002d-Specializations">
<div class="nav-panel">
<p>
Next: <a href="Arrays.html#Arrays-_002d-C-Reference" accesskey="n" rel="next">C Reference</a>, Previous: <a href="Arrays.html#Arrays-_002d-Array-limits" accesskey="p" rel="prev">Array limits</a>, Up: <a href="Arrays.html#Arrays" accesskey="u" rel="up">Arrays</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
</div>
<h4 class="subsection" id="Specializations">2.13.2 Specializations</h4>
<p>When the elements of an array are declared to have some precise type, such as a small or large integer, a character or a floating point number, ECL has means to store those elements in a more compact form, known as a <em class="emph">specialized array</em>. The list of types for which ECL specializes arrays is platform dependent, but is summarized in the following table, together with the C type which is used internally and the expected size.
</p>
<table class="multitable">
<thead><tr><th width="33%">Specialized type</th><th width="33%">Element C type</th><th width="33%">Size</th></tr></thead>
<tbody><tr><td width="33%">bit</td><td width="33%">-</td><td width="33%">1 bit</td></tr>
<tr><td width="33%">character</td><td width="33%">unsigned char or uint32_t</td><td width="33%">Depends on character range</td></tr>
<tr><td width="33%">base-char</td><td width="33%">unsigned char</td><td width="33%"></td></tr>
<tr><td width="33%">fixnum</td><td width="33%">cl_fixnum</td><td width="33%">Machine word (32 or 64 bits)</td></tr>
<tr><td width="33%">ext:cl-index</td><td width="33%">cl_index</td><td width="33%">Machine word (32 or 64 bits)</td></tr>
<tr><td width="33%">(signed-byte 8)</td><td width="33%">int8_t</td><td width="33%">8 bits</td></tr>
<tr><td width="33%">(unsigned-byte 8)</td><td width="33%">uint8_t</td><td width="33%">8 bits</td></tr>
<tr><td width="33%">(signed-byte 16)</td><td width="33%">int16_t</td><td width="33%">16 bits</td></tr>
<tr><td width="33%">(unsigned-byte 16)</td><td width="33%">uint16_t</td><td width="33%">16 bits</td></tr>
<tr><td width="33%">(signed-byte 32)</td><td width="33%">int32_t</td><td width="33%">32 bits</td></tr>
<tr><td width="33%">(unsigned-byte 32)</td><td width="33%">uint32_t</td><td width="33%">32 bits</td></tr>
<tr><td width="33%">(signed-byte 64)</td><td width="33%">int64_t</td><td width="33%">64 bits</td></tr>
<tr><td width="33%">(unsigned-byte 64)</td><td width="33%">uint64_t</td><td width="33%">64 bits</td></tr>
<tr><td width="33%">single-float or short-float</td><td width="33%">float</td><td width="33%">32-bits IEEE float</td></tr>
<tr><td width="33%">double-float</td><td width="33%">double</td><td width="33%">64-bits IEEE float</td></tr>
<tr><td width="33%">long-float</td><td width="33%">long double</td><td width="33%">Between 96 and 128 bits</td></tr>
<tr><td width="33%">(complex single-float)</td><td width="33%">float _Complex</td><td width="33%">64 bits</td></tr>
<tr><td width="33%">(complex double-float)</td><td width="33%">double _Complex</td><td width="33%">128 bits</td></tr>
<tr><td width="33%">(complex long-float)</td><td width="33%">long double _Complex</td><td width="33%">Between 192 and 256 bits</td></tr>
<tr><td width="33%">t</td><td width="33%">cl_object</td><td width="33%">Size of a pointer.</td></tr>
</tbody>
</table>
<p>Let us remark that some of these specialized types might not exist in your platform. This is detected using conditional reading and features (See <a class="xref" href="Numbers.html#Numbers">Numbers</a>).
</p>
<hr>
</div>
<div class="subsection-level-extent" id="Arrays-_002d-C-Reference">
<div class="nav-panel">
<p>
Previous: <a href="Arrays.html#Arrays-_002d-Specializations" accesskey="p" rel="prev">Specializations</a>, Up: <a href="Arrays.html#Arrays" accesskey="u" rel="up">Arrays</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
</div>
<h4 class="subsection" id="C-Reference-13">2.13.3 C Reference</h4>
<ul class="mini-toc">
<li><a href="Arrays.html#Types-and-constants" accesskey="1">Types and constants</a></li>
<li><a href="Arrays.html#ecl_005faet_005fto_005fsymbol_002c-ecl_005fsymbol_005fto_005faet" accesskey="2">ecl_aet_to_symbol, ecl_symbol_to_aet</a></li>
<li><a href="Arrays.html#Constructors-1" accesskey="3">Constructors</a></li>
<li><a href="Arrays.html#Accessors-1" accesskey="4">Accessors</a></li>
<li><a href="Arrays.html#Array-properties" accesskey="5">Array properties</a></li>
<li><a href="Arrays.html#ANSI-Dictionary-9" accesskey="6">ANSI Dictionary</a></li>
</ul>
<div class="subsubsection-level-extent" id="Types-and-constants">
<h4 class="subsubsection">2.13.3.1 Types and constants</h4>
<p>C types, limits and enumerations
</p>
<h4 class="subsubheading" id="Constants-and-types">Constants and types</h4>
<a class="anchor" id="ECL_005fARRAY_005fRANK_005fLIMIT"></a><a class="index-entry-id" id="index-ECL_005fARRAY_005fRANK_005fLIMIT"></a>
<a class="anchor" id="ECL_005fARRAY_005fDIMENSION_005fLIMIT"></a><a class="index-entry-id" id="index-ECL_005fARRAY_005fDIMENSION_005fLIMIT"></a>
<a class="anchor" id="ECL_005fARRAY_005fTOTAL_005fLIMIT"></a><a class="index-entry-id" id="index-ECL_005fARRAY_005fTOTAL_005fLIMIT"></a>
<a class="anchor" id="cl_005felttype"></a><a class="index-entry-id" id="index-cl_005felttype"></a>
<dl class="first-defvr">
<dt class="defvr" id="index-ECL_005fARRAY_005fRANK_005fLIMIT-1"><span class="category-def">Constant: </span><span><strong class="def-name">ECL_ARRAY_RANK_LIMIT</strong><a class="copiable-link" href='Arrays.html#index-ECL_005fARRAY_005fRANK_005fLIMIT-1'> &para;</a></span></dt>
<dt class="defvrx def-cmd-defvr" id="index-ECL_005fARRAY_005fDIMENSION_005fLIMIT-1"><span class="category-def">Constant: </span><span><strong class="def-name">ECL_ARRAY_DIMENSION_LIMIT</strong><a class="copiable-link" href='Arrays.html#index-ECL_005fARRAY_005fDIMENSION_005fLIMIT-1'> &para;</a></span></dt>
<dt class="defvrx def-cmd-defvr" id="index-ECL_005fARRAY_005fTOTAL_005fLIMIT-1"><span class="category-def">Constant: </span><span><strong class="def-name">ECL_ARRAY_TOTAL_LIMIT</strong><a class="copiable-link" href='Arrays.html#index-ECL_005fARRAY_005fTOTAL_005fLIMIT-1'> &para;</a></span></dt>
</dl>
<dl class="first-deftp">
<dt class="deftp" id="index-cl_005felttype-2"><span class="category-def">enum: </span><span><strong class="def-name">cl_elttype</strong> <var class="def-var-arguments">{ecl_aet_object, ...}</var><a class="copiable-link" href='Arrays.html#index-cl_005felttype-2'> &para;</a></span></dt>
<dd>
<table class="multitable">
<thead><tr><th width="25%">Lisp or C type</th><th width="25%">Enumeration value</th><th width="25%">Lisp or C type</th><th width="25%">Enumeration value</th></tr></thead>
<tbody><tr><td width="25%">t</td><td width="25%">ecl_aet_object</td><td width="25%">(unsigned-byte 1)</td><td width="25%">ecl_aet_bit</td></tr>
<tr><td width="25%">cl_fixnum</td><td width="25%">ecl_aet_fix</td><td width="25%">cl_index</td><td width="25%">ecl_aet_index</td></tr>
<tr><td width="25%">(unsigned-byte 8)</td><td width="25%">ecl_aet_b8</td><td width="25%">(signed-byte 8)</td><td width="25%">ecl_aet_i8</td></tr>
<tr><td width="25%">(unsigned-byte 16)</td><td width="25%">ecl_aet_b16</td><td width="25%">(signed-byte 16)</td><td width="25%">ecl_aet_i16</td></tr>
<tr><td width="25%">(unsigned-byte 32)</td><td width="25%">ecl_aet_b32</td><td width="25%">(signed-byte 32)</td><td width="25%">ecl_aet_i32</td></tr>
<tr><td width="25%">(unsigned-byte 64)</td><td width="25%">ecl_aet_b64</td><td width="25%">(signed-byte 64)</td><td width="25%">ecl_aet_i64</td></tr>
<tr><td width="25%">ecl_character</td><td width="25%">ecl_aet_ch</td><td width="25%">ecl_base_char</td><td width="25%">ecl_aet_bc</td></tr>
<tr><td width="25%">single-float</td><td width="25%">ecl_aet_sf</td><td width="25%">double-float</td><td width="25%">ecl_aet_df</td></tr>
<tr><td width="25%">long-float</td><td width="25%">ecl_aet_lf</td><td width="25%">(complex long-float)</td><td width="25%">ecl_aet_clf</td></tr>
<tr><td width="25%">(complex single-float)</td><td width="25%">ecl_aet_csf</td><td width="25%">(complex double-float)</td><td width="25%">ecl_aet_cdf</td></tr>
</tbody>
</table>
<p><b class="b">Description</b>
</p>
<p>This list contains the constants that limit the rank of an array
(<code class="code"><a class="ref" href="Arrays.html#ECL_005fARRAY_005fRANK_005fLIMIT">ECL_ARRAY_RANK_LIMIT</a></code>), the maximum size of each dimension
(<code class="code"><a class="ref" href="Arrays.html#ECL_005fARRAY_005fDIMENSION_005fLIMIT">ECL_ARRAY_DIMENSION_LIMIT</a></code>) and the maximum number of elements
in an array (<code class="code"><a class="ref" href="Arrays.html#ECL_005fARRAY_005fTOTAL_005fLIMIT">ECL_ARRAY_TOTAL_LIMIT</a></code>).
</p>
<p>ECL uses also internally a set of constants to describe the different
specialized arrays. The constants form up the enumeration type
<code class="code"><a class="ref" href="Arrays.html#cl_005felttype">cl_elttype</a></code>. They are listed in the table above, which
associates enumeration values with the corresponding Common Lisp element
type.
</p></dd></dl>
</div>
<div class="subsubsection-level-extent" id="ecl_005faet_005fto_005fsymbol_002c-ecl_005fsymbol_005fto_005faet">
<h4 class="subsubsection">2.13.3.2 ecl_aet_to_symbol, ecl_symbol_to_aet</h4>
<p>To and from element types
</p>
<h4 class="subsubheading" id="Functions-7">Functions</h4>
<a class="anchor" id="ecl_005faet_005fto_005fsymbol"></a><a class="index-entry-id" id="index-ecl_005faet_005fto_005fsymbol"></a>
<a class="anchor" id="ecl_005fsymbol_005fto_005faet"></a><a class="index-entry-id" id="index-ecl_005fsymbol_005fto_005faet"></a>
<dl class="first-deftypefn first-deftypefun-alias-first-deftypefn">
<dt class="deftypefn deftypefun-alias-deftypefn" id="index-ecl_005faet_005fto_005fsymbol-1"><span class="category-def">Function: </span><span><code class="def-type">cl_object</code> <strong class="def-name">ecl_aet_to_symbol</strong> <code class="def-code-arguments">(cl_elttype param)</code><a class="copiable-link" href='Arrays.html#index-ecl_005faet_005fto_005fsymbol-1'> &para;</a></span></dt>
<dt class="deftypefnx deftypefunx-alias-deftypefnx def-cmd-deftypefn" id="index-ecl_005fsymbol_005fto_005faet-1"><span class="category-def">Function: </span><span><code class="def-type">cl_elttype</code> <strong class="def-name">ecl_symbol_to_aet</strong> <code class="def-code-arguments">(cl_object type)</code><a class="copiable-link" href='Arrays.html#index-ecl_005fsymbol_005fto_005faet-1'> &para;</a></span></dt>
<dd>
<p><b class="b">Description</b>
</p>
<p><code class="code"><a class="ref" href="Arrays.html#ecl_005faet_005fto_005fsymbol">ecl_aet_to_symbol</a></code> returns the Lisp type associated to the elements of that specialized array class. <code class="code"><a class="ref" href="Arrays.html#ecl_005fsymbol_005fto_005faet">ecl_symbol_to_aet</a></code> does the converse, computing the C constant that is associated to a Lisp element type.
</p>
<p>The functions may signal an error if any of the arguments is an invalid C or Lisp type.
</p></dd></dl>
</div>
<div class="subsubsection-level-extent" id="Constructors-1">
<h4 class="subsubsection">2.13.3.3 Constructors</h4>
<p>Creating array and vectors
</p>
<h4 class="subsubheading" id="Functions-8">Functions</h4>
<a class="anchor" id="ecl_005falloc_005fsimple_005fvector"></a><a class="index-entry-id" id="index-ecl_005falloc_005fsimple_005fvector"></a>
<a class="anchor" id="si_005fmake_005fvector"></a><a class="index-entry-id" id="index-si_005fmake_005fvector"></a>
<a class="anchor" id="si_005fmake_005farray"></a><a class="index-entry-id" id="index-si_005fmake_005farray"></a>
<a class="anchor" id="si_005fadjust_005fvector"></a><a class="index-entry-id" id="index-si_005fadjust_005fvector"></a>
<dl class="first-deftypefn first-deftypefun-alias-first-deftypefn">
<dt class="deftypefn deftypefun-alias-deftypefn" id="index-ecl_005falloc_005fsimple_005fvector-1"><span class="category-def">Function: </span><span><code class="def-type">cl_object</code> <strong class="def-name">ecl_alloc_simple_vector</strong> <code class="def-code-arguments">(cl_index length, cl_elttype element_type);</code><a class="copiable-link" href='Arrays.html#index-ecl_005falloc_005fsimple_005fvector-1'> &para;</a></span></dt>
<dt class="deftypefnx deftypefunx-alias-deftypefnx def-cmd-deftypefn" id="index-si_005fmake_005fvector-1"><span class="category-def">Function: </span><span><code class="def-type">cl_object</code> <strong class="def-name">si_make_vector</strong> <code class="def-code-arguments">(cl_object element_type, cl_object length, cl_object adjustablep, cl_object fill_pointerp, cl_object displaced_to, cl_object displacement);</code><a class="copiable-link" href='Arrays.html#index-si_005fmake_005fvector-1'> &para;</a></span></dt>
<dt class="deftypefnx deftypefunx-alias-deftypefnx def-cmd-deftypefn" id="index-si_005fmake_005farray-1"><span class="category-def">Function: </span><span><code class="def-type">cl_object</code> <strong class="def-name">si_make_array</strong> <code class="def-code-arguments">(cl_object element_type, cl_object dimensions, cl_object adjustablep, cl_object fill_pointerp, cl_object displaced_to, cl_object displacement);</code><a class="copiable-link" href='Arrays.html#index-si_005fmake_005farray-1'> &para;</a></span></dt>
<dt class="deftypefnx deftypefunx-alias-deftypefnx def-cmd-deftypefn" id="index-si_005fadjust_005fvector-1"><span class="category-def">Function: </span><span><code class="def-type">cl_object</code> <strong class="def-name">si_adjust_vector</strong> <code class="def-code-arguments">(cl_object vector, cl_object length);</code><a class="copiable-link" href='Arrays.html#index-si_005fadjust_005fvector-1'> &para;</a></span></dt>
<dd>
<p><b class="b">Description</b>
</p>
<p>The function <code class="code"><a class="ref" href="Arrays.html#ecl_005falloc_005fsimple_005fvector">ecl_alloc_simple_vector</a></code> is the simplest
constructor, creating a simple vector (i.e. non-adjustable and without
a fill pointer), of the given size, preallocating the memory for the
array data. The first argument, <em class="emph">element_type</em>, is a C constant
that represents a valid array element type (See <code class="code"><a class="ref" href="Arrays.html#cl_005felttype">cl_elttype</a></code>).
</p>
<p>The function <code class="code"><a class="ref" href="Arrays.html#si_005fmake_005fvector">si_make_vector</a></code> does the same job but allows creating an array with fill pointer, which is adjustable or displaced to another array.
</p><ul class="itemize mark-bullet">
<li>element_type is now a Common Lisp type descriptor, which is a symbol or list denoting a valid element type
</li><li>dimension is a non-negative fixnum with the vector size.
</li><li>fill_pointerp is either ECL_NIL or a non-negative fixnum denoting the fill pointer value.
</li><li>displaced_to is either ECL_NIL or a valid array to which the new array is displaced.
</li><li>displacement is either ECL_NIL or a non-negative value with the array displacement.
</li></ul>
<p>Adjustable vector may be adjusted with the function <code class="code"><a class="ref" href="Arrays.html#si_005fadjust_005fvector">si_adjust_vector</a></code>.
</p>
<p>Finally, the function <code class="code"><a class="ref" href="Arrays.html#si_005fmake_005farray">si_make_array</a></code> does a similar job to
<code class="code"><a class="ref" href="Arrays.html#si_005fmake_005fvector">si_make_vector</a></code> but its second argument, <em class="emph">dimension</em>,
can be a list of dimensions, to create a multidimensional array.
</p>
<p><b class="b">Examples</b>
</p>
<p>Create one-dimensional <code class="code">base-string</code> with room for 11 characters:
</p>
<div class="example">
<pre class="example-preformatted">cl_object s = ecl_alloc_simple_vector(11, ecl_aet_bc);
</pre></div>
<p>Create a one-dimensional <code class="code">array</code> with a fill pointer
</p>
<div class="example">
<pre class="example-preformatted">cl_object type = ecl_make_symbol(&quot;BYTE8&quot;,&quot;EXT&quot;);
cl_object a = si_make_vector(type, ecl_make_fixnum(16), ECL_NIL, /* adjustable */
ecl_make_fixnum(0) /* fill-pointer */,
ECL_NIL /* displaced_to */,
ECL_NIL /* displacement */);
</pre></div>
<p>An alternative formulation
</p>
<div class="example">
<pre class="example-preformatted">cl_object type = ecl_make_symbol(&quot;BYTE8&quot;,&quot;EXT&quot;);
cl_object a = si_make_array(type, ecl_make_fixnum(16), ECL_NIL, /* adjustable */
ecl_make_fixnum(0) /* fill-pointer */,
ECL_NIL /* displaced_to */,
ECL_NIL /* displacement */);
</pre></div>
<p>Create a 2-by-3 two-dimensional <code class="code">array</code>, specialized for an integer type:
</p>
<div class="example">
<pre class="example-preformatted">cl_object dims = cl_list(2, ecl_make_fixnum(2), ecl_make_fixnum(3));
cl_object type = ecl_make_symbol(&quot;BYTE8&quot;,&quot;EXT&quot;);
cl_object a = si_make_array(dims, type, ECL_NIL, /* adjustable */
ECL_NIL /* fill-pointer */,
ECL_NIL /* displaced_to */,
ECL_NIL /* displacement */);
</pre></div>
</dd></dl>
</div>
<div class="subsubsection-level-extent" id="Accessors-1">
<h4 class="subsubsection">2.13.3.4 Accessors</h4>
<a class="anchor" id="ecl_005faref"></a><a class="index-entry-id" id="index-ecl_005faref"></a>
<a class="anchor" id="ecl_005faset"></a><a class="index-entry-id" id="index-ecl_005faset"></a>
<a class="anchor" id="ecl_005faref1"></a><a class="index-entry-id" id="index-ecl_005faref1"></a>
<a class="anchor" id="ecl_005faset1"></a><a class="index-entry-id" id="index-ecl_005faset1"></a>
<p>Reading and writing array elements
</p>
<h4 class="subsubheading" id="Functions-9">Functions</h4>
<dl class="first-deftypefn first-deftypefun-alias-first-deftypefn">
<dt class="deftypefn deftypefun-alias-deftypefn" id="index-ecl_005faref-2"><span class="category-def">Function: </span><span><code class="def-type">cl_object</code> <strong class="def-name">ecl_aref</strong> <code class="def-code-arguments">(cl_object array, cl_index row_major_index);</code><a class="copiable-link" href='Arrays.html#index-ecl_005faref-2'> &para;</a></span></dt>
<dt class="deftypefnx deftypefunx-alias-deftypefnx def-cmd-deftypefn" id="index-ecl_005faset-2"><span class="category-def">Function: </span><span><code class="def-type">cl_object</code> <strong class="def-name">ecl_aset</strong> <code class="def-code-arguments">(cl_object array, cl_index row_major_index, cl_object new_value);</code><a class="copiable-link" href='Arrays.html#index-ecl_005faset-2'> &para;</a></span></dt>
<dt class="deftypefnx deftypefunx-alias-deftypefnx def-cmd-deftypefn" id="index-ecl_005faref1-2"><span class="category-def">Function: </span><span><code class="def-type">cl_object</code> <strong class="def-name">ecl_aref1</strong> <code class="def-code-arguments">(cl_object vector, cl_index row_major_index);</code><a class="copiable-link" href='Arrays.html#index-ecl_005faref1-2'> &para;</a></span></dt>
<dt class="deftypefnx deftypefunx-alias-deftypefnx def-cmd-deftypefn" id="index-ecl_005faset1-2"><span class="category-def">Function: </span><span><code class="def-type">cl_object</code> <strong class="def-name">ecl_aset1</strong> <code class="def-code-arguments">(cl_object vector, cl_index row_major_index, cl_object new_value);</code><a class="copiable-link" href='Arrays.html#index-ecl_005faset1-2'> &para;</a></span></dt>
<dd>
<p><b class="b">Description</b>
</p>
<p><code class="code"><a class="ref" href="Arrays.html#ecl_005faref">ecl_aref</a></code> accesses an array using the supplied <em class="emph">row_major_index</em>, checking the array bounds and returning a Lisp object for the value at that position. <code class="code"><a class="ref" href="Arrays.html#ecl_005faset">ecl_aset</a></code> does the converse, storing a Lisp value at the given <em class="emph">row_major_index</em>.
</p>
<p>The first argument to <code class="code"><a class="ref" href="Arrays.html#ecl_005faref">ecl_aref</a></code> or <code class="code"><a class="ref" href="Arrays.html#ecl_005faset">ecl_aset</a></code> is an array of any number of dimensions. For an array of rank <code class="code">N</code> and dimensions <code class="code">d1, d2 ...</code> up to <code class="code">dN</code>, the row major index associated to the indices (<code class="code">i1,i2,...iN</code>) is computed using the formula <code class="code">i1+d1*(i2+d3*(i3+...))</code>.
</p>
<p><code class="code"><a class="ref" href="Arrays.html#ecl_005faref1">ecl_aref1</a></code> and <code class="code"><a class="ref" href="Arrays.html#ecl_005faset1">ecl_aset1</a></code> are specialized versions that only work with one-dimensional arrays or vectors. They verify that the first argument is indeed a vector.
</p>
<p>All functions above check that the index does not exceed the array bounds, that the values match the array element type and that the argument is an array (or a vector). If these conditions are not met, a <code class="code">type-error</code> is signaled.
</p></dd></dl>
</div>
<div class="subsubsection-level-extent" id="Array-properties">
<h4 class="subsubsection">2.13.3.5 Array properties</h4>
<a class="anchor" id="ecl_005farray_005felttype"></a><a class="index-entry-id" id="index-ecl_005farray_005felttype"></a>
<a class="anchor" id="ecl_005farray_005frank"></a><a class="index-entry-id" id="index-ecl_005farray_005frank"></a>
<a class="anchor" id="ecl_005farray_005fdimension"></a><a class="index-entry-id" id="index-ecl_005farray_005fdimension"></a>
<p>Array size, fill pointer, etc.
</p>
<h4 class="subsubheading" id="Functions-10">Functions</h4>
<dl class="first-deftypefn first-deftypefun-alias-first-deftypefn">
<dt class="deftypefn deftypefun-alias-deftypefn" id="index-ecl_005farray_005felttype-2"><span class="category-def">Function: </span><span><code class="def-type">cl_elttype</code> <strong class="def-name">ecl_array_elttype</strong> <code class="def-code-arguments">(cl_object array);</code><a class="copiable-link" href='Arrays.html#index-ecl_005farray_005felttype-2'> &para;</a></span></dt>
<dt class="deftypefnx deftypefunx-alias-deftypefnx def-cmd-deftypefn" id="index-ecl_005farray_005frank-1"><span class="category-def">Function: </span><span><code class="def-type">cl_index</code> <strong class="def-name">ecl_array_rank</strong> <code class="def-code-arguments">(cl_object array);</code><a class="copiable-link" href='Arrays.html#index-ecl_005farray_005frank-1'> &para;</a></span></dt>
<dt class="deftypefnx deftypefunx-alias-deftypefnx def-cmd-deftypefn" id="index-ecl_005farray_005fdimension-1"><span class="category-def">Function: </span><span><code class="def-type">cl_index</code> <strong class="def-name">ecl_array_dimension</strong> <code class="def-code-arguments">(cl_object array, cl_index index);</code><a class="copiable-link" href='Arrays.html#index-ecl_005farray_005fdimension-1'> &para;</a></span></dt>
<dd>
<p><b class="b">Description</b>
</p>
<p>These functions query various properties of the arrays. Some of them belong to the list of functions in the Common Lisp package, without any need for specialized versions. More precisely
</p>
<ul class="itemize mark-bullet">
<li><code class="code"><a class="ref" href="Arrays.html#ecl_005farray_005felttype">ecl_array_elttype</a></code> returns the array element type, with the encoding found in the enumeration cl_elttype.
</li><li><code class="code"><a class="ref" href="Arrays.html#ecl_005farray_005frank">ecl_array_rank</a></code> returns the number of dimensions of the vector or array.
</li><li><code class="code"><a class="ref" href="Arrays.html#ecl_005farray_005fdimension">ecl_array_dimension</a></code> queries the dimension of an array, where index is a non-negative integer between 0 and <code class="code">ecl_array_dimension(array)-1</code>.
</li></ul>
</dd></dl>
</div>
<div class="subsubsection-level-extent" id="ANSI-Dictionary-9">
<h4 class="subsubsection">2.13.3.6 ANSI Dictionary</h4>
<p>Common Lisp and C equivalence
</p>
<table class="multitable">
<thead><tr><th width="32%">Lisp symbol</th><th width="68%">C function</th></tr></thead>
<tbody><tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_mk_ar.htm">make-array</a></td><td width="68%">cl_object cl_make_array(cl_narg narg, cl_object dimension...)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_adjust.htm">adjust-array</a></td><td width="68%">cl_object cl_adjust_array(cl_narg narg, cl_object array, cl_object dimensions, ...)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_adju_1.htm">adjustable-array-p</a></td><td width="68%">cl_object cl_adjustable_array_p(cl_object array)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_aref.htm">aref</a></td><td width="68%">cl_object cl_aref(cl_narg narg, cl_object array, ...)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_aref.htm">(setf aref)</a></td><td width="68%">cl_object si_aset(cl_narg narg, cl_object array, ...)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_ar_dim.htm">array-dimension</a></td><td width="68%">cl_object cl_array_dimension(cl_object array, cl_object index)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_ar_d_1.htm">array-dimensions</a></td><td width="68%">cl_object cl_array_dimensions(cl_object array)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_ar_ele.htm">array-element-type</a></td><td width="68%">cl_object cl_array_element_type(cl_object array)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_ar_has.htm">array-has-fill-pointer-p</a></td><td width="68%">cl_object cl_array_has_fill_pointer_p(cl_object array)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_ar_dis.htm">array-displacement</a></td><td width="68%">cl_object cl_array_displacement(cl_object array)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_ar_in_.htm">array-in-bounds-p</a></td><td width="68%">cl_object cl_array_in_bounds_p(cl_narg narg, cl_object array, ...)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_ar_ran.htm">array-rank</a></td><td width="68%">cl_object cl_array_rank(cl_object array)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_ar_row.htm">array-row-major-index</a></td><td width="68%">cl_object cl_array_row_major_index(cl_narg narg, cl_object array, ...)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_ar_tot.htm">array-total-size</a></td><td width="68%">cl_object cl_array_total_size(cl_object array)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_arrayp.htm">arrayp</a></td><td width="68%">cl_object cl_arrayp(cl_object array)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_fill_p.htm">fill-pointer</a></td><td width="68%">cl_object cl_fill_pointer(cl_object array)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_fill_p.htm">(setf fill-pointer)</a></td><td width="68%">cl_object si_fill_pointer_set(cl_object array, cl_object fill_pointer)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_row_ma.htm">row-major-aref</a></td><td width="68%">cl_object cl_row_major_aref(cl_object array, cl_object index)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_row_ma.htm">(setf row-major-aref)</a></td><td width="68%">cl_object si_row_major_aset(cl_object array, cl_object index, cl_object value)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_upgr_1.htm">upgraded-array-element-type</a></td><td width="68%">cl_object cl_upgraded_array_element_type(cl_narg narg, cl_object typespec, ...)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_smp_ve.htm">simple-vector-p</a></td><td width="68%">cl_object cl_simple_vector_p(cl_object object)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_svref.htm">svref</a></td><td width="68%">cl_object cl_svref(cl_object simple_vector, cl_object index)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_svref.htm">(setf svref)</a></td><td width="68%">cl_object si_svset(cl_object simple_vector, cl_object index, cl_object value)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_vector.htm">vector</a></td><td width="68%">cl_object cl_vector(cl_narg narg, ...)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_vec_po.htm">vector-pop</a></td><td width="68%">cl_object cl_vector_pop(cl_object vector)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_vec_ps.htm">vector-push</a></td><td width="68%">cl_object cl_vector_push(cl_object new_element, cl_object vector)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_vec_ps.htm">vector-push-extend</a></td><td width="68%">cl_object cl_vector_push_extend(cl_narg narg, cl_object new_element, cl_object vector, ...)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_vecp.htm">vectorp</a></td><td width="68%">cl_object cl_vectorp(cl_object object)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_bt_sb.htm">bit</a></td><td width="68%">cl_object cl_bit(cl_narg narg, cl_object bit_array, ...)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_bt_sb.htm">(setf bit)</a></td><td width="68%">cl_object si_aset(cl_narg narg, cl_object array, ...)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_bt_sb.htm">sbit</a></td><td width="68%">cl_object cl_sbit(cl_narg narg, cl_object bit_array, ...)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_bt_sb.htm">(setf sbit)</a></td><td width="68%">cl_object si_aset(cl_narg narg, cl_object array, ...)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_bt_and.htm">bit-and</a></td><td width="68%">cl_object cl_bit_and(cl_narg narg, cl_object array1, cl_object array2, ...)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_bt_and.htm">bit-andc1</a></td><td width="68%">cl_object cl_bit_andc1(cl_narg narg, cl_object array1, cl_object array2, ...)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_bt_and.htm">bit-andc2</a></td><td width="68%">cl_object cl_bit_andc2(cl_narg narg, cl_object array1, cl_object array2, ...)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_bt_and.htm">bit-eqv</a></td><td width="68%">cl_object cl_bit_eqv(cl_narg narg, cl_object array1, cl_object array2, ...)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_bt_and.htm">bit-ior</a></td><td width="68%">cl_object cl_bit_ior(cl_narg narg, cl_object array1, cl_object array2, ...)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_bt_and.htm">bit-nand</a></td><td width="68%">cl_object cl_bit_nand(cl_narg narg, cl_object array1, cl_object array2, ...)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_bt_and.htm">bit-nor</a></td><td width="68%">cl_object cl_bit_nor(cl_narg narg, cl_object array1, cl_object array2, ...)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_bt_and.htm">bit-orc1</a></td><td width="68%">cl_object cl_bit_orc1(cl_narg narg, cl_object array1, cl_object array2, ...)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_bt_and.htm">bit-orc2</a></td><td width="68%">cl_object cl_bit_orc1(cl_narg narg, cl_object array1, cl_object array2, ...)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_bt_and.htm">bit-xor</a></td><td width="68%">cl_object cl_bit_xor(cl_narg narg, cl_object array1, cl_object array2, ...)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_bt_and.htm">bit-not</a></td><td width="68%">cl_object cl_bit_not(cl_narg narg, cl_object array, ...)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_bt_vec.htm">bit-vector-p</a></td><td width="68%">cl_object cl_bit_vector_p(cl_object object)</td></tr>
<tr><td width="32%"><a class="url" href="http://www.lispworks.com/documentation/HyperSpec/Body/f_smp_bt.htm">simple-bit-vector-p</a></td><td width="68%">cl_object cl_simple_bit_vector_p(cl_object object)</td></tr>
</tbody>
</table>
</div>
</div>
</div>
<hr>
<div class="nav-panel">
<p>
Next: <a href="Strings.html#Strings" accesskey="n" rel="next">Strings</a>, Previous: <a href="Conses.html" accesskey="p" rel="prev">Conses</a>, Up: <a href="Standards.html" accesskey="u" rel="up">Standards</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>