<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book [
<!ENTITY % eclent SYSTEM "ecl.ent">
%eclent;
]>
<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
<chapter>
<title>Arrays</title>
<section xml:id="ansi.arrays.c-dict">
<title>C Reference</title>
  <refentry xml:id="ansi.arrays.c-types">
    <refnamediv>
      <refname>Types and constants</refname>
      <refpurpose>C types, limits and enumerations</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <title>Constants and types</title>

      <synopsis><constant>ECL_ARRAY_RANK_LIMIT</constant></synopsis>

      <synopsis><constant>ECL_ARRAY_DIMENSION_LIMIT</constant></synopsis>

      <synopsis><constant>ECL_ARRAY_TOTAL_LIMIT</constant></synopsis>

      <synopsis><type>typedef enum { ecl_aet_object, ...} cl_elttype;</type></synopsis>

      <simplelist columns="4" type="horiz" xml:id="cl_elttype">
	<member>Lisp or C type</member>
	<member>Enumeration value</member>

	<member>Lisp or C type</member>
	<member>Enumeration value</member>

	<member><type>t</type></member>
	<member><type>ecl_aet_object</type></member>

	<member><type>(unsigned-byte 1)</type></member>
	<member><type>ecl_aet_bit</type></member>

	<member><type>cl_fixnum</type></member>
	<member><type>ecl_aet_fix</type></member>

	<member><type>cl_index</type></member>
	<member><type>ecl_aet_index</type></member>

	<member><type>(unsigned-byte 8)</type></member>
	<member><type>ecl_aet_b8</type></member>

	<member><type>(signed-byte 8)</type></member>
	<member><type>ecl_aet_i8</type></member>

	<member><type>(unsigned-byte 16)</type></member>
	<member><type>ecl_aet_b16</type></member>

	<member><type>(signed-byte 16)</type></member>
	<member><type>ecl_aet_i16</type></member>

	<member><type>(unsigned-byte 32)</type></member>
	<member><type>ecl_aet_b32</type></member>

	<member><type>(signed-byte 32)</type></member>
	<member><type>ecl_aet_i32</type></member>

	<member><type>(unsigned-byte 64)</type></member>
	<member><type>ecl_aet_b64</type></member>

	<member><type>(signed-byte 64)</type></member>
	<member><type>ecl_aet_i64</type></member>

	<member><type>ecl_character</type></member>
	<member><type>ecl_aet_ch</type></member>

	<member><type>ecl_base_char</type></member>
	<member><type>ecl_aet_bc</type></member>

	<member><type>single-float</type></member>
	<member><type>ecl_aet_sf</type></member>

	<member><type>double-float</type></member>
	<member><type>ecl_aet_df</type></member>
      </simplelist>
    </refsynopsisdiv>

    <refsect1>
      <title>Description</title>

      <para>This list contains the constants that limit the rank of an array (<constant>ECL_ARRAY_RANK_LIMIT</constant>), the maximum size of each dimension (<constant>ECL_ARRAY_DIMENSION_LIMIT</constant>) and the maximum number of elements in an array (<constant>ECL_ARRAY_TOTAL_LIMIT</constant>).</para>

      <para>&ECL; uses also internally a set of constants to describe the different specialized arrays. The constants form up the enumeration type <type>cl_elttype</type>. They are listed in the table above, which associates enumeration values with the corresponding Common Lisp element type.</para>
    </refsect1>
  </refentry>

  <refentry>
    <refnamediv>
      <refname><function>ecl_aet_to_symbol</function>,
      <function>ecl_symbol_to_aet</function></refname>
      <refpurpose>To and from element types</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <title>Functions</title>

      <funcsynopsis>
	<funcprototype>
	  <?dbhtml funcsynopsis-style='ansi'?>
	  <funcdef>cl_object <function>ecl_aet_to_symbol</function></funcdef>
	  <paramdef>cl_elttype <parameter>param</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>

      <funcsynopsis>
	<funcprototype>
	  <?dbhtml funcsynopsis-style='ansi'?>
	  <funcdef>cl_elttype <function>ecl_symbol_to_aet</function></funcdef>
	  <paramdef>cl_object <parameter>type</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </refsynopsisdiv>

    <refsect1>
      <title>Description</title>

      <para><function>ecl_aet_to_symbol</function> returns the Lisp type associated to the elements of that specialized array class. <function>ecl_symbol_to_aet</function> does the converse, computing the C constant that is associated to a Lisp elment type.</para>

      <para>The functions may signal an error if any of the arguments is an invalid C or Lisp type.</para>
    </refsect1>
  </refentry>

  <refentry>
    <refnamediv>
      <refname>Constructors</refname>
      <refpurpose>Creating arrays and vectors</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <title>Functions</title>
      <funcsynopsis>
	<funcprototype>
	  <?dbhtml funcsynopsis-style='ansi'?>
	  <funcdef>cl_object <function>ecl_alloc_simple_vector</function></funcdef>
	  <paramdef>cl_elttype <parameter>element_type</parameter></paramdef>
	  <paramdef>cl_index <parameter>length</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>

      <funcsynopsis>
	<funcprototype>
	  <?dbhtml funcsynopsis-style='ansi'?>
	  <funcdef>cl_object <function>si_make_vector</function></funcdef>
	  <paramdef>cl_object <parameter>element_type</parameter></paramdef>
	  <paramdef>cl_object <parameter>length</parameter></paramdef>
	  <paramdef>cl_object <parameter>adjustablep</parameter></paramdef>
	  <paramdef>cl_object <parameter>fill_pointerp</parameter></paramdef>
	  <paramdef>cl_object <parameter>displaced_to</parameter></paramdef>
	  <paramdef>cl_object <parameter>displacement</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>

      <funcsynopsis>
	<funcprototype>
	  <?dbhtml funcsynopsis-style='ansi'?>
	  <funcdef>cl_object <function>si_make_array</function></funcdef>
	  <paramdef>cl_object <parameter>element_type</parameter></paramdef>
	  <paramdef>cl_object <parameter>dimensions</parameter></paramdef>
	  <paramdef>cl_object <parameter>adjustablep</parameter></paramdef>
	  <paramdef>cl_object <parameter>fill_pointerp</parameter></paramdef>
	  <paramdef>cl_object <parameter>displaced_to</parameter></paramdef>
	  <paramdef>cl_object <parameter>displacement</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </refsynopsisdiv>

    <refsect1>
      <title>Description</title>

      <para>The function <function>ecl_alloc_simple_vector</function> 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, <replaceable>element_type</replaceable>, is a C constant that represents a valid array element type (See <link linkend="cl_elttype">cl_elttype</link>).</para>

      <para>The function <function>si_make_vector</function> does the same job but allows creating an array with fill pointer, which is adjustable or displaced to another array.</para>
      <itemizedlist>
	<listitem><para><replaceable>element_type</replaceable> is now a Common Lisp type descriptor, which is a symbol or list denoting a valid element type</para></listitem>
	<listitem><para><replaceable>dimension</replaceable> is a non-negative fixnum with the vector size.</para></listitem>
	<listitem><para><replaceable>fill_pointerp</replaceable> is either <symbol>Cnil</symbol> or a non-negative fixnum denoting the fill pointer value.</para></listitem>
	<listitem><para><replaceable>displaced_to</replaceable> is either <symbol>Cnil</symbol> or a valid array to which the new array is displaced.</para></listitem>
	<listitem><para><replaceable>displacement</replaceable> is either <symbol>Cnil</symbol> or a non-negative value with the array displacement.</para></listitem>
      </itemizedlist>
      <para>Finally, the function <function>si_make_array</function> does a similar job to <function>si_make_function</function> but its second argument, <replaceable>dimension</replaceable>, can be a list of dimensions, to create a multidimensional array.</para>

    </refsect1>

    <refsect1>
      <title>Example</title>

      <para>Create one-dimensional <type>base-string</type> with room for 11 characters:</para>
<programlisting>
cl_object s = ecl_alloc_simple_vector(ecl_aet_bc, 11);
</programlisting>

      <para>Create a one-dimensional <type>array</type> with a fill pointer</para>
<programlisting>
cl_object type = ecl_make_symbol("BYTE8","EXT");
cl_object a = si_make_vector(ecl_make_fixnum(16), type, Cnil, /* adjustable */
                             ecl_make_fixnum(0) /* fill-pointer */,
                             Cnil /* displaced_to */,
                             Cnil /* displacement */);
</programlisting>

      <para>An alternative formulation</para>
<programlisting>
cl_object type = ecl_make_symbol("BYTE8","EXT");
cl_object a = si_make_array(ecl_make_fixnum(16), type, Cnil, /* adjustable */
                            ecl_make_fixnum(0) /* fill-pointer */,
                            Cnil /* displaced_to */,
                            Cnil /* displacement */);
</programlisting>

      <para>Create a 2-by-3 two-dimensional <type>array</type>, specialized for an integer type:</para>
<programlisting>
cl_object dims = cl_list(2, ecl_make_fixnum(2), ecl_make_fixnum(3));
cl_object type = ecl_make_symbol("BYTE8","EXT");
cl_object a = si_make_array(dims, type, Cnil, /* adjustable */
                            Cnil /* fill-pointer */,
                            Cnil /* displaced_to */,
                            Cnil /* displacement */);
</programlisting>
    </refsect1>

  </refentry>

  <refentry>
    <refnamediv>
      <refname>Accessors</refname>
      <refpurpose>Reading and writing array elements</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <title>Functions</title>
      <funcsynopsis>
	<funcprototype>
	  <?dbhtml funcsynopsis-style='ansi'?>
	  <funcdef>cl_object <function>ecl_aref</function></funcdef>
	  <paramdef>cl_object <parameter>array</parameter></paramdef>
	  <paramdef>cl_index <parameter>row_major_index</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>

      <funcsynopsis>
	<funcprototype>
	  <?dbhtml funcsynopsis-style='ansi'?>
	  <funcdef>cl_object <function>ecl_aset</function></funcdef>
	  <paramdef>cl_object <parameter>array</parameter></paramdef>
	  <paramdef>cl_index <parameter>row_major_index</parameter></paramdef>
	  <paramdef>cl_object <parameter>new_value</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>

      <funcsynopsis>
	<funcprototype>
	  <?dbhtml funcsynopsis-style='ansi'?>
	  <funcdef>cl_object <function>ecl_aref1</function></funcdef>
	  <paramdef>cl_object <parameter>vector</parameter></paramdef>
	  <paramdef>cl_index <parameter>row_major_index</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>

      <funcsynopsis>
	<funcprototype>
	  <?dbhtml funcsynopsis-style='ansi'?>
	  <funcdef>cl_object <function>ecl_aset1</function></funcdef>
	  <paramdef>cl_object <parameter>vector</parameter></paramdef>
	  <paramdef>cl_index <parameter>row_major_index</parameter></paramdef>
	  <paramdef>cl_object <parameter>new_value</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </refsynopsisdiv>

    <refsect1>
      <title>Description</title>

      <para><function>ecl_aref</function> accesses an array using the supplied  <replaceable>row_major_index</replaceable>, checking the array bounds and returning a Lisp object for the value at that position. <function>ecl_aset</function> does the converse, storing a Lisp value at the given <replaceable>row_major_index</replaceable>.</para>

      <para>The first argument to <function>ecl_aref</function> or <function>ecl_aset</function> is an array of any number of dimensions. For an array of rank <replaceable>N</replaceable> and dimensions <replaceable>d1</replaceable>, <replaceable>d2</replaceable> ... up to <replaceable>dN</replaceable>, the row major index associated to the indices <replaceable>(i1,i2,...iN)</replaceable> is computed using the formula <code>i1+d1*(i2+d3*(i3+...))</code>.</para>

      <para><function>ecl_aref1</function> and <function>ecl_aset1</function> are specialized versions that only work with one-dimensional arrays or vectors. They verify that the first argument is indeed a vector.</para>

      <para>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 type error is signaled.</para>
    </refsect1>
  </refentry>

  <refentry>
    <refnamediv>
      <refname>Array properties</refname>
      <refpurpose>Array size, fill pointer, etc</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <funcsynopsis>
	<funcprototype>
	  <?dbhtml funcsynopsis-style='ansi'?>
	  <funcdef>cl_elttype <function>ecl_array_elttype</function></funcdef>
	  <paramdef>cl_object <parameter>array</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>

      <funcsynopsis>
	<funcprototype>
	  <?dbhtml funcsynopsis-style='ansi'?>
	  <funcdef>cl_index <function>ecl_array_rank</function></funcdef>
	  <paramdef>cl_object <parameter>array</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>

      <funcsynopsis>
	<funcprototype>
	  <?dbhtml funcsynopsis-style='ansi'?>
	  <funcdef>cl_index <function>ecl_array_dimension</function></funcdef>
	  <paramdef>cl_object <parameter>array</parameter></paramdef>
	  <paramdef>cl_index <parameter>index</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </refsynopsisdiv>

    <refsect1>
      <title>Description</title>

      <para>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</para>
      <itemizedlist>
	<listitem><para><function>ecl_array_elttype</function> returns the array element type, with the encoding found in the enumeration <link linkend="cl_elttype">cl_elttype</link>.</para></listitem>
	<listitem><para><function>ecl_array_rank</function> returns the number of dimensions of the vector or array.</para></listitem>
	<listitem><para><function>ecl_array_dimension</function> queries the dimension of an array, where <replaceable>index</replaceable> is a non-negative integer between 0 and <code>ecl_array_dimension(array)-1</code>.</para></listitem>
      </itemizedlist>
    </refsect1>
  </refentry>

  <refentry>
    <refnamediv>
      <refname>ANSI Dictionary</refname>
      <refpurpose>&ANSI-C-Dict;</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<simplelist columns="2" type="horiz">
<member>Lisp symbol</member>
<member>C function</member>

<member><ulink url="&clhs;f_mk_ar.htm"><symbol>make-array</symbol></ulink></member>
<member><code>cl_object cl_make_array(cl_narg narg, cl_object dimension...)</code></member>

<member><ulink url="&clhs;f_adjust.htm"><symbol>adjust-array</symbol></ulink></member>
<member><code>cl_object cl_adjust_array(cl_narg narg, cl_object array, cl_object dimensions, ...)</code></member>

<member><ulink url="&clhs;f_adju_1.htm"><symbol>adjustable-array-p</symbol></ulink></member>
<member><code>cl_object cl_adjustable_array_p(cl_object array)</code></member>

<member><ulink url="&clhs;f_aref.htm"><symbol>aref</symbol></ulink></member>
<member><code>cl_object cl_aref(cl_narg narg, cl_object array, ...)</code></member>

<member><ulink url="&clhs;f_ar_dim.htm"><symbol>array-dimension</symbol></ulink></member>
<member><code>cl_object cl_array_dimension(cl_object array, cl_object index)</code></member>

<member><ulink url="&clhs;f_ar_d_1.htm"><symbol>array-dimensions</symbol></ulink></member>
<member><code>cl_object cl_array_dimension(cl_object array)</code></member>

<member><ulink url="&clhs;f_ar_ele.htm"><symbol>array-element-type</symbol></ulink></member>
<member><code>cl_object cl_array_element_type(cl_object array)</code></member>

<member><ulink url="&clhs;f_ar_has.htm"><symbol>array-has-fill-pointer-p</symbol></ulink></member>
<member><code>cl_object cl_array_has_fill_pointer_p(cl_object array)</code></member>

<member><ulink url="&clhs;f_ar_dis.htm"><symbol>array-displacement</symbol></ulink></member>
<member><code>cl_object cl_array_displacement(cl_object array)</code></member>

<member><ulink url="&clhs;f_ar_in_.htm"><symbol>array-in-bounds-p</symbol></ulink></member>
<member><code>cl_object cl_array_in_bounds_p(cl_narg narg, cl_object array, ...)</code></member>

<member><ulink url="&clhs;f_ar_ran.htm"><symbol>array-rank</symbol></ulink></member>
<member><code>cl_object cl_array_rank(cl_object array)</code></member>

<member><ulink url="&clhs;f_ar_row.htm"><symbol>array-row-major-index</symbol></ulink></member>
<member><code>cl_object cl_array_row_major_index(cl_narg narg, cl_object array, ...)</code></member>

<member><ulink url="&clhs;f_ar_tot.htm"><symbol>array-total-size</symbol></ulink></member>
<member><code>cl_object cl_array_total_size(cl_object array)</code></member>

<member><ulink url="&clhs;f_arrayp.htm"><symbol>arrayp</symbol></ulink></member>
<member><code>cl_object cl_arrayp(cl_object array)</code></member>

<member><ulink url="&clhs;f_fill_p.htm"><symbol>fill-pointer</symbol></ulink></member>
<member><code>cl_object cl_fill_pointer(cl_object array)</code></member>

<member><ulink url="&clhs;f_row_ma.htm"><symbol>row-major-aref</symbol></ulink></member>
<member><code>cl_object cl_row_major_aref(cl_object array, cl_object index)</code></member>

<member><ulink url="&clhs;f_upgr_1.htm"><symbol>upgraded-array-element-type</symbol></ulink></member>
<member><code>cl_object cl_upgraded_array_element_type(cl_narg narg, cl_object typespec, ...) </code></member>

<member><ulink url="&clhs;f_smp_ve.htm"><symbol>simple-vector-p</symbol></ulink></member>
<member><code>cl_object cl_simple_vector_p(cl_object object)</code></member>

<member><ulink url="&clhs;f_svref.htm"><symbol>svref</symbol></ulink></member>
<member><code>cl_object cl_svref(cl_object simple_vector, cl_object index)</code></member>

<member><ulink url="&clhs;f_vector.htm"><symbol>vector</symbol></ulink></member>
<member><code>cl_object cl_vector(cl_narg narg, ...)</code></member>

<member><ulink url="&clhs;f_vec_po.htm"><symbol>vector-pop</symbol></ulink></member>
<member><code>cl_object cl_vector_pop(cl_object vector)</code></member>

<member><ulink url="&clhs;f_vec_ps.htm"><symbol>vector-push</symbol></ulink></member>
<member><code>cl_object cl_vector_push(cl_object new_element, cl_object vector)</code></member>

<member><ulink url="&clhs;f_vec_ps.htm"><symbol>vector-push-extend</symbol></ulink></member>
<member><code>cl_object cl_vector_push_extend(cl_narg narg, cl_object new_element, cl_object vector, ...)</code></member>

<member><ulink url="&clhs;f_vecp.htm"><symbol>vectorp</symbol></ulink></member>
<member><code>cl_object cl_vectorp(cl_object object)</code></member>

<member><ulink url="&clhs;f_bt_sb.htm"><symbol>bit</symbol></ulink></member>
<member><code>cl_object cl_bit(cl_narg narg, cl_object bit_array, ...)</code></member>

<member><ulink url="&clhs;f_bt_sb.htm"><symbol>sbit</symbol></ulink></member>
<member><code>cl_object cl_sbit(cl_narg narg, cl_object bit_array, ...)</code></member>

<member><ulink url="&clhs;f_bt_and.htm"><symbol>bit-and</symbol></ulink></member>
<member><code>cl_object cl_bit_and(cl_narg narg, cl_object array1, cl_object array2, ...)</code></member>

<member><ulink url="&clhs;f_bt_and.htm"><symbol>bit-andc1</symbol></ulink></member>
<member><code>cl_object cl_bit_andc1(cl_narg narg, cl_object array1, cl_object array2, ...)</code></member>

<member><ulink url="&clhs;f_bt_and.htm"><symbol>bit-andc2</symbol></ulink></member>
<member><code>cl_object cl_bit_andc2(cl_narg narg, cl_object array1, cl_object array2, ...)</code></member>

<member><ulink url="&clhs;f_bt_and.htm"><symbol>bit-eqv</symbol></ulink></member>
<member><code>cl_object cl_bit_eqv(cl_narg narg, cl_object array1, cl_object array2, ...)</code></member>

<member><ulink url="&clhs;f_bt_and.htm"><symbol>bit-ior</symbol></ulink></member>
<member><code>cl_object cl_bit_ior(cl_narg narg, cl_object array1, cl_object array2, ...)</code></member>

<member><ulink url="&clhs;f_bt_and.htm"><symbol>bit-nand</symbol></ulink></member>
<member><code>cl_object cl_bit_nand(cl_narg narg, cl_object array1, cl_object array2, ...)</code></member>

<member><ulink url="&clhs;f_bt_and.htm"><symbol>bit-nor</symbol></ulink></member>
<member><code>cl_object cl_bit_nor(cl_narg narg, cl_object array1, cl_object array2, ...)</code></member>

<member><ulink url="&clhs;f_bt_and.htm"><symbol>bit-orc1</symbol></ulink></member>
<member><code>cl_object cl_bit_orc1(cl_narg narg, cl_object array1, cl_object array2, ...)</code></member>

<member><ulink url="&clhs;f_bt_and.htm"><symbol>bit-orc2</symbol></ulink></member>
<member><code>cl_object cl_bit_orc1(cl_narg narg, cl_object array1, cl_object array2, ...)</code></member>

<member><ulink url="&clhs;f_bt_and.htm"><symbol>bit-xor</symbol></ulink></member>
<member><code>cl_object cl_bit_xor(cl_narg narg, cl_object array1, cl_object array2, ...)</code></member>

<member><ulink url="&clhs;f_bt_and.htm"><symbol>bit-not</symbol></ulink></member>
<member><code>cl_object cl_bit_not(cl_narg narg, cl_object array, ...)</code></member>

</simplelist>
    </refsynopsisdiv>

    <refsect1>
      <title>Description</title>
      <para></para>
    </refsect1>
  </refentry>
</section>
</chapter>
</book>