352 lines
30 KiB
HTML
352 lines
30 KiB
HTML
|
<!DOCTYPE html>
|
||
|
|
<html>
|
||
|
|
<!-- Created by GNU Texinfo 7.1, https://www.gnu.org/software/texinfo/ -->
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<!-- This manual documents Guile version 3.0.10.
|
||
|
|
|
||
|
|
Copyright (C) 1996-1997, 2000-2005, 2009-2023 Free Software Foundation,
|
||
|
|
Inc.
|
||
|
|
|
||
|
|
Copyright (C) 2021 Maxime Devos
|
||
|
|
|
||
|
|
Copyright (C) 2024 Tomas Volf
|
||
|
|
|
||
|
|
|
||
|
|
Permission is granted to copy, distribute and/or modify this document
|
||
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
||
|
|
any later version published by the Free Software Foundation; with no
|
||
|
|
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
|
||
|
|
copy of the license is included in the section entitled "GNU Free
|
||
|
|
Documentation License." -->
|
||
|
|
<title>Accessing Arrays from C (Guile Reference Manual)</title>
|
||
|
|
|
||
|
|
<meta name="description" content="Accessing Arrays from C (Guile Reference Manual)">
|
||
|
|
<meta name="keywords" content="Accessing Arrays from C (Guile Reference Manual)">
|
||
|
|
<meta name="resource-type" content="document">
|
||
|
|
<meta name="distribution" content="global">
|
||
|
|
<meta name="Generator" content=".texi2any-real">
|
||
|
|
<meta name="viewport" content="width=device-width,initial-scale=1">
|
||
|
|
|
||
|
|
<link href="index.html" rel="start" title="Top">
|
||
|
|
<link href="Concept-Index.html" rel="index" title="Concept Index">
|
||
|
|
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
|
||
|
|
<link href="Arrays.html" rel="up" title="Arrays">
|
||
|
|
<link href="Arrays-as-arrays-of-arrays.html" rel="prev" title="Arrays as arrays of arrays">
|
||
|
|
<style type="text/css">
|
||
|
|
<!--
|
||
|
|
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
|
||
|
|
div.example {margin-left: 3.2em}
|
||
|
|
span:hover a.copiable-link {visibility: visible}
|
||
|
|
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
|
||
|
|
-->
|
||
|
|
</style>
|
||
|
|
<link rel="stylesheet" type="text/css" href="https://www.gnu.org/software/gnulib/manual.css">
|
||
|
|
|
||
|
|
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body lang="en">
|
||
|
|
<div class="subsubsection-level-extent" id="Accessing-Arrays-from-C">
|
||
|
|
<div class="nav-panel">
|
||
|
|
<p>
|
||
|
|
Previous: <a href="Arrays-as-arrays-of-arrays.html" accesskey="p" rel="prev">Arrays as arrays of arrays</a>, Up: <a href="Arrays.html" accesskey="u" rel="up">Arrays</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
|
||
|
|
</div>
|
||
|
|
<hr>
|
||
|
|
<h4 class="subsubsection" id="Accessing-Arrays-from-C-1"><span>6.6.13.5 Accessing Arrays from C<a class="copiable-link" href="#Accessing-Arrays-from-C-1"> ¶</a></span></h4>
|
||
|
|
|
||
|
|
<p>For interworking with external C code, Guile provides an API to allow C
|
||
|
|
code to access the elements of a Scheme array. In particular, for
|
||
|
|
uniform numeric arrays, the API exposes the underlying uniform data as a
|
||
|
|
C array of numbers of the relevant type.
|
||
|
|
</p>
|
||
|
|
<p>While pointers to the elements of an array are in use, the array itself
|
||
|
|
must be protected so that the pointer remains valid. Such a protected
|
||
|
|
array is said to be <em class="dfn">reserved</em>. A reserved array can be read but
|
||
|
|
modifications to it that would cause the pointer to its elements to
|
||
|
|
become invalid are prevented. When you attempt such a modification, an
|
||
|
|
error is signaled.
|
||
|
|
</p>
|
||
|
|
<p>(This is similar to locking the array while it is in use, but without
|
||
|
|
the danger of a deadlock. In a multi-threaded program, you will need
|
||
|
|
additional synchronization to avoid modifying reserved arrays.)
|
||
|
|
</p>
|
||
|
|
<p>You must take care to always unreserve an array after reserving it,
|
||
|
|
even in the presence of non-local exits. If a non-local exit can
|
||
|
|
happen between these two calls, you should install a dynwind context
|
||
|
|
that releases the array when it is left (see <a class="pxref" href="Dynamic-Wind.html">Dynamic Wind</a>).
|
||
|
|
</p>
|
||
|
|
<p>In addition, array reserving and unreserving must be properly
|
||
|
|
paired. For instance, when reserving two or more arrays in a certain
|
||
|
|
order, you need to unreserve them in the opposite order.
|
||
|
|
</p>
|
||
|
|
<p>Once you have reserved an array and have retrieved the pointer to its
|
||
|
|
elements, you must figure out the layout of the elements in memory.
|
||
|
|
Guile allows slices to be taken out of arrays without actually making a
|
||
|
|
copy, such as making an alias for the diagonal of a matrix that can be
|
||
|
|
treated as a vector. Arrays that result from such an operation are not
|
||
|
|
stored contiguously in memory and when working with their elements
|
||
|
|
directly, you need to take this into account.
|
||
|
|
</p>
|
||
|
|
<p>The layout of array elements in memory can be defined via a
|
||
|
|
<em class="emph">mapping function</em> that computes a scalar position from a vector of
|
||
|
|
indices. The scalar position then is the offset of the element with the
|
||
|
|
given indices from the start of the storage block of the array.
|
||
|
|
</p>
|
||
|
|
<p>In Guile, this mapping function is restricted to be <em class="dfn">affine</em>: all
|
||
|
|
mapping functions of Guile arrays can be written as <code class="code">p = b +
|
||
|
|
c[0]*i[0] + c[1]*i[1] + ... + c[n-1]*i[n-1]</code> where <code class="code">i[k]</code> is the
|
||
|
|
<code class="code">k</code>th index and <code class="code">n</code> is the rank of the array. For
|
||
|
|
example, a matrix of size 3x3 would have <code class="code">b == 0</code>, <code class="code">c[0] ==
|
||
|
|
3</code> and <code class="code">c[1] == 1</code>. When you transpose this matrix (with
|
||
|
|
<code class="code">transpose-array</code>, say), you will get an array whose mapping
|
||
|
|
function has <code class="code">b == 0</code>, <code class="code">c[0] == 1</code> and <code class="code">c[1] == 3</code>.
|
||
|
|
</p>
|
||
|
|
<p>The function <code class="code">scm_array_handle_dims</code> gives you (indirect) access to
|
||
|
|
the coefficients <code class="code">c[k]</code>.
|
||
|
|
</p>
|
||
|
|
<p>Note that there are no functions for accessing the elements of a
|
||
|
|
character array yet. Once the string implementation of Guile has been
|
||
|
|
changed to use Unicode, we will provide them.
|
||
|
|
</p>
|
||
|
|
<dl class="first-deftp">
|
||
|
|
<dt class="deftp" id="index-scm_005ft_005farray_005fhandle"><span class="category-def">C Type: </span><span><strong class="def-name">scm_t_array_handle</strong><a class="copiable-link" href="#index-scm_005ft_005farray_005fhandle"> ¶</a></span></dt>
|
||
|
|
<dd><p>This is a structure type that holds all information necessary to manage
|
||
|
|
the reservation of arrays as explained above. Structures of this type
|
||
|
|
must be allocated on the stack and must only be accessed by the
|
||
|
|
functions listed below.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deftypefn">
|
||
|
|
<dt class="deftypefn" id="index-scm_005farray_005fget_005fhandle"><span class="category-def">C Function: </span><span><code class="def-type">void</code> <strong class="def-name">scm_array_get_handle</strong> <code class="def-code-arguments">(SCM array, scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fget_005fhandle"> ¶</a></span></dt>
|
||
|
|
<dd><p>Reserve <var class="var">array</var>, which must be an array, and prepare <var class="var">handle</var> to
|
||
|
|
be used with the functions below. You must eventually call
|
||
|
|
<code class="code">scm_array_handle_release</code> on <var class="var">handle</var>, and do this in a
|
||
|
|
properly nested fashion, as explained above. The structure pointed to
|
||
|
|
by <var class="var">handle</var> does not need to be initialized before calling this
|
||
|
|
function.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<a class="anchor" id="x_002dscm_005farray_005fhandle_005frelease"></a><dl class="first-deftypefn">
|
||
|
|
<dt class="deftypefn" id="index-scm_005farray_005fhandle_005frelease"><span class="category-def">C Function: </span><span><code class="def-type">void</code> <strong class="def-name">scm_array_handle_release</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005frelease"> ¶</a></span></dt>
|
||
|
|
<dd><p>End the array reservation represented by <var class="var">handle</var>. After a call to
|
||
|
|
this function, <var class="var">handle</var> might be used for another reservation.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deftypefn">
|
||
|
|
<dt class="deftypefn" id="index-scm_005farray_005fhandle_005frank"><span class="category-def">C Function: </span><span><code class="def-type">size_t</code> <strong class="def-name">scm_array_handle_rank</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005frank"> ¶</a></span></dt>
|
||
|
|
<dd><p>Return the rank of the array represented by <var class="var">handle</var>.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deftp">
|
||
|
|
<dt class="deftp" id="index-scm_005ft_005farray_005fdim"><span class="category-def">C Type: </span><span><strong class="def-name">scm_t_array_dim</strong><a class="copiable-link" href="#index-scm_005ft_005farray_005fdim"> ¶</a></span></dt>
|
||
|
|
<dd><p>This structure type holds information about the layout of one dimension
|
||
|
|
of an array. It includes the following fields:
|
||
|
|
</p>
|
||
|
|
<dl class="table">
|
||
|
|
<dt><code class="code">ssize_t lbnd</code></dt>
|
||
|
|
<dt><code class="code">ssize_t ubnd</code></dt>
|
||
|
|
<dd><p>The lower and upper bounds (both inclusive) of the permissible index
|
||
|
|
range for the given dimension. Both values can be negative, but
|
||
|
|
<var class="var">lbnd</var> is always less than or equal to <var class="var">ubnd</var>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code class="code">ssize_t inc</code></dt>
|
||
|
|
<dd><p>The distance from one element of this dimension to the next. Note, too,
|
||
|
|
that this can be negative.
|
||
|
|
</p></dd>
|
||
|
|
</dl>
|
||
|
|
</dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deftypefn">
|
||
|
|
<dt class="deftypefn" id="index-scm_005farray_005fhandle_005fdims"><span class="category-def">C Function: </span><span><code class="def-type">const scm_t_array_dim *</code> <strong class="def-name">scm_array_handle_dims</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005fdims"> ¶</a></span></dt>
|
||
|
|
<dd><p>Return a pointer to a C vector of information about the dimensions of
|
||
|
|
the array represented by <var class="var">handle</var>. This pointer is valid as long as
|
||
|
|
the array remains reserved. As explained above, the
|
||
|
|
<code class="code">scm_t_array_dim</code> structures returned by this function can be used
|
||
|
|
calculate the position of an element in the storage block of the array
|
||
|
|
from its indices.
|
||
|
|
</p>
|
||
|
|
<p>This position can then be used as an index into the C array pointer
|
||
|
|
returned by the various <code class="code">scm_array_handle_<foo>_elements</code>
|
||
|
|
functions, or with <code class="code">scm_array_handle_ref</code> and
|
||
|
|
<code class="code">scm_array_handle_set</code>.
|
||
|
|
</p>
|
||
|
|
<p>Here is how one can compute the position <var class="var">pos</var> of an element given
|
||
|
|
its indices in the vector <var class="var">indices</var>:
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">ssize_t indices[RANK];
|
||
|
|
scm_t_array_dim *dims;
|
||
|
|
ssize_t pos;
|
||
|
|
size_t i;
|
||
|
|
|
||
|
|
pos = 0;
|
||
|
|
for (i = 0; i < RANK; i++)
|
||
|
|
{
|
||
|
|
if (indices[i] < dims[i].lbnd || indices[i] > dims[i].ubnd)
|
||
|
|
out_of_range ();
|
||
|
|
pos += (indices[i] - dims[i].lbnd) * dims[i].inc;
|
||
|
|
}
|
||
|
|
</pre></div>
|
||
|
|
</dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deftypefn">
|
||
|
|
<dt class="deftypefn" id="index-scm_005farray_005fhandle_005fpos"><span class="category-def">C Function: </span><span><code class="def-type">ssize_t</code> <strong class="def-name">scm_array_handle_pos</strong> <code class="def-code-arguments">(scm_t_array_handle *handle, SCM indices)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005fpos"> ¶</a></span></dt>
|
||
|
|
<dd><p>Compute the position corresponding to <var class="var">indices</var>, a list of
|
||
|
|
indices. The position is computed as described above for
|
||
|
|
<code class="code">scm_array_handle_dims</code>. The number of the indices and their
|
||
|
|
range is checked and an appropriate error is signaled for invalid
|
||
|
|
indices.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deftypefn">
|
||
|
|
<dt class="deftypefn" id="index-scm_005farray_005fhandle_005fref"><span class="category-def">C Function: </span><span><code class="def-type">SCM</code> <strong class="def-name">scm_array_handle_ref</strong> <code class="def-code-arguments">(scm_t_array_handle *handle, ssize_t pos)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005fref"> ¶</a></span></dt>
|
||
|
|
<dd><p>Return the element at position <var class="var">pos</var> in the storage block of the
|
||
|
|
array represented by <var class="var">handle</var>. Any kind of array is acceptable. No
|
||
|
|
range checking is done on <var class="var">pos</var>.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deftypefn">
|
||
|
|
<dt class="deftypefn" id="index-scm_005farray_005fhandle_005fset"><span class="category-def">C Function: </span><span><code class="def-type">void</code> <strong class="def-name">scm_array_handle_set</strong> <code class="def-code-arguments">(scm_t_array_handle *handle, ssize_t pos, SCM val)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005fset"> ¶</a></span></dt>
|
||
|
|
<dd><p>Set the element at position <var class="var">pos</var> in the storage block of the array
|
||
|
|
represented by <var class="var">handle</var> to <var class="var">val</var>. Any kind of array is
|
||
|
|
acceptable. No range checking is done on <var class="var">pos</var>. An error is
|
||
|
|
signaled when the array can not store <var class="var">val</var>.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deftypefn">
|
||
|
|
<dt class="deftypefn" id="index-scm_005farray_005fhandle_005felements"><span class="category-def">C Function: </span><span><code class="def-type">const SCM *</code> <strong class="def-name">scm_array_handle_elements</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005felements"> ¶</a></span></dt>
|
||
|
|
<dd><p>Return a pointer to the elements of a ordinary array of general Scheme
|
||
|
|
values (i.e., a non-uniform array) for reading. This pointer is valid
|
||
|
|
as long as the array remains reserved.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deftypefn">
|
||
|
|
<dt class="deftypefn" id="index-scm_005farray_005fhandle_005fwritable_005felements"><span class="category-def">C Function: </span><span><code class="def-type">SCM *</code> <strong class="def-name">scm_array_handle_writable_elements</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005fwritable_005felements"> ¶</a></span></dt>
|
||
|
|
<dd><p>Like <code class="code">scm_array_handle_elements</code>, but the pointer is good for
|
||
|
|
reading and writing.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deftypefn">
|
||
|
|
<dt class="deftypefn" id="index-scm_005farray_005fhandle_005funiform_005felements"><span class="category-def">C Function: </span><span><code class="def-type">const void *</code> <strong class="def-name">scm_array_handle_uniform_elements</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005funiform_005felements"> ¶</a></span></dt>
|
||
|
|
<dd><p>Return a pointer to the elements of a uniform numeric array for reading.
|
||
|
|
This pointer is valid as long as the array remains reserved. The size
|
||
|
|
of each element is given by <code class="code">scm_array_handle_uniform_element_size</code>.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deftypefn">
|
||
|
|
<dt class="deftypefn" id="index-scm_005farray_005fhandle_005funiform_005fwritable_005felements"><span class="category-def">C Function: </span><span><code class="def-type">void *</code> <strong class="def-name">scm_array_handle_uniform_writable_elements</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005funiform_005fwritable_005felements"> ¶</a></span></dt>
|
||
|
|
<dd><p>Like <code class="code">scm_array_handle_uniform_elements</code>, but the pointer is good
|
||
|
|
reading and writing.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deftypefn">
|
||
|
|
<dt class="deftypefn" id="index-scm_005farray_005fhandle_005funiform_005felement_005fsize"><span class="category-def">C Function: </span><span><code class="def-type">size_t</code> <strong class="def-name">scm_array_handle_uniform_element_size</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005funiform_005felement_005fsize"> ¶</a></span></dt>
|
||
|
|
<dd><p>Return the size of one element of the uniform numeric array represented
|
||
|
|
by <var class="var">handle</var>.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deftypefn">
|
||
|
|
<dt class="deftypefn" id="index-scm_005farray_005fhandle_005fu8_005felements"><span class="category-def">C Function: </span><span><code class="def-type">const scm_t_uint8 *</code> <strong class="def-name">scm_array_handle_u8_elements</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005fu8_005felements"> ¶</a></span></dt>
|
||
|
|
<dt class="deftypefnx def-cmd-deftypefn" id="index-scm_005farray_005fhandle_005fs8_005felements"><span class="category-def">C Function: </span><span><code class="def-type">const scm_t_int8 *</code> <strong class="def-name">scm_array_handle_s8_elements</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005fs8_005felements"> ¶</a></span></dt>
|
||
|
|
<dt class="deftypefnx def-cmd-deftypefn" id="index-scm_005farray_005fhandle_005fu16_005felements"><span class="category-def">C Function: </span><span><code class="def-type">const scm_t_uint16 *</code> <strong class="def-name">scm_array_handle_u16_elements</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005fu16_005felements"> ¶</a></span></dt>
|
||
|
|
<dt class="deftypefnx def-cmd-deftypefn" id="index-scm_005farray_005fhandle_005fs16_005felements"><span class="category-def">C Function: </span><span><code class="def-type">const scm_t_int16 *</code> <strong class="def-name">scm_array_handle_s16_elements</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005fs16_005felements"> ¶</a></span></dt>
|
||
|
|
<dt class="deftypefnx def-cmd-deftypefn" id="index-scm_005farray_005fhandle_005fu32_005felements"><span class="category-def">C Function: </span><span><code class="def-type">const scm_t_uint32 *</code> <strong class="def-name">scm_array_handle_u32_elements</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005fu32_005felements"> ¶</a></span></dt>
|
||
|
|
<dt class="deftypefnx def-cmd-deftypefn" id="index-scm_005farray_005fhandle_005fs32_005felements"><span class="category-def">C Function: </span><span><code class="def-type">const scm_t_int32 *</code> <strong class="def-name">scm_array_handle_s32_elements</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005fs32_005felements"> ¶</a></span></dt>
|
||
|
|
<dt class="deftypefnx def-cmd-deftypefn" id="index-scm_005farray_005fhandle_005fu64_005felements"><span class="category-def">C Function: </span><span><code class="def-type">const scm_t_uint64 *</code> <strong class="def-name">scm_array_handle_u64_elements</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005fu64_005felements"> ¶</a></span></dt>
|
||
|
|
<dt class="deftypefnx def-cmd-deftypefn" id="index-scm_005farray_005fhandle_005fs64_005felements"><span class="category-def">C Function: </span><span><code class="def-type">const scm_t_int64 *</code> <strong class="def-name">scm_array_handle_s64_elements</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005fs64_005felements"> ¶</a></span></dt>
|
||
|
|
<dt class="deftypefnx def-cmd-deftypefn" id="index-scm_005farray_005fhandle_005ff32_005felements"><span class="category-def">C Function: </span><span><code class="def-type">const float *</code> <strong class="def-name">scm_array_handle_f32_elements</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005ff32_005felements"> ¶</a></span></dt>
|
||
|
|
<dt class="deftypefnx def-cmd-deftypefn" id="index-scm_005farray_005fhandle_005ff64_005felements"><span class="category-def">C Function: </span><span><code class="def-type">const double *</code> <strong class="def-name">scm_array_handle_f64_elements</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005ff64_005felements"> ¶</a></span></dt>
|
||
|
|
<dt class="deftypefnx def-cmd-deftypefn" id="index-scm_005farray_005fhandle_005fc32_005felements"><span class="category-def">C Function: </span><span><code class="def-type">const float *</code> <strong class="def-name">scm_array_handle_c32_elements</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005fc32_005felements"> ¶</a></span></dt>
|
||
|
|
<dt class="deftypefnx def-cmd-deftypefn" id="index-scm_005farray_005fhandle_005fc64_005felements"><span class="category-def">C Function: </span><span><code class="def-type">const double *</code> <strong class="def-name">scm_array_handle_c64_elements</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005fc64_005felements"> ¶</a></span></dt>
|
||
|
|
<dd><p>Return a pointer to the elements of a uniform numeric array of the
|
||
|
|
indicated kind for reading. This pointer is valid as long as the array
|
||
|
|
remains reserved.
|
||
|
|
</p>
|
||
|
|
<p>The pointers for <code class="code">c32</code> and <code class="code">c64</code> uniform numeric arrays point
|
||
|
|
to pairs of floating point numbers. The even index holds the real part,
|
||
|
|
the odd index the imaginary part of the complex number.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deftypefn">
|
||
|
|
<dt class="deftypefn" id="index-scm_005farray_005fhandle_005fu8_005fwritable_005felements"><span class="category-def">C Function: </span><span><code class="def-type">scm_t_uint8 *</code> <strong class="def-name">scm_array_handle_u8_writable_elements</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005fu8_005fwritable_005felements"> ¶</a></span></dt>
|
||
|
|
<dt class="deftypefnx def-cmd-deftypefn" id="index-scm_005farray_005fhandle_005fs8_005fwritable_005felements"><span class="category-def">C Function: </span><span><code class="def-type">scm_t_int8 *</code> <strong class="def-name">scm_array_handle_s8_writable_elements</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005fs8_005fwritable_005felements"> ¶</a></span></dt>
|
||
|
|
<dt class="deftypefnx def-cmd-deftypefn" id="index-scm_005farray_005fhandle_005fu16_005fwritable_005felements"><span class="category-def">C Function: </span><span><code class="def-type">scm_t_uint16 *</code> <strong class="def-name">scm_array_handle_u16_writable_elements</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005fu16_005fwritable_005felements"> ¶</a></span></dt>
|
||
|
|
<dt class="deftypefnx def-cmd-deftypefn" id="index-scm_005farray_005fhandle_005fs16_005fwritable_005felements"><span class="category-def">C Function: </span><span><code class="def-type">scm_t_int16 *</code> <strong class="def-name">scm_array_handle_s16_writable_elements</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005fs16_005fwritable_005felements"> ¶</a></span></dt>
|
||
|
|
<dt class="deftypefnx def-cmd-deftypefn" id="index-scm_005farray_005fhandle_005fu32_005fwritable_005felements"><span class="category-def">C Function: </span><span><code class="def-type">scm_t_uint32 *</code> <strong class="def-name">scm_array_handle_u32_writable_elements</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005fu32_005fwritable_005felements"> ¶</a></span></dt>
|
||
|
|
<dt class="deftypefnx def-cmd-deftypefn" id="index-scm_005farray_005fhandle_005fs32_005fwritable_005felements"><span class="category-def">C Function: </span><span><code class="def-type">scm_t_int32 *</code> <strong class="def-name">scm_array_handle_s32_writable_elements</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005fs32_005fwritable_005felements"> ¶</a></span></dt>
|
||
|
|
<dt class="deftypefnx def-cmd-deftypefn" id="index-scm_005farray_005fhandle_005fu64_005fwritable_005felements"><span class="category-def">C Function: </span><span><code class="def-type">scm_t_uint64 *</code> <strong class="def-name">scm_array_handle_u64_writable_elements</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005fu64_005fwritable_005felements"> ¶</a></span></dt>
|
||
|
|
<dt class="deftypefnx def-cmd-deftypefn" id="index-scm_005farray_005fhandle_005fs64_005fwritable_005felements"><span class="category-def">C Function: </span><span><code class="def-type">scm_t_int64 *</code> <strong class="def-name">scm_array_handle_s64_writable_elements</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005fs64_005fwritable_005felements"> ¶</a></span></dt>
|
||
|
|
<dt class="deftypefnx def-cmd-deftypefn" id="index-scm_005farray_005fhandle_005ff32_005fwritable_005felements"><span class="category-def">C Function: </span><span><code class="def-type">float *</code> <strong class="def-name">scm_array_handle_f32_writable_elements</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005ff32_005fwritable_005felements"> ¶</a></span></dt>
|
||
|
|
<dt class="deftypefnx def-cmd-deftypefn" id="index-scm_005farray_005fhandle_005ff64_005fwritable_005felements"><span class="category-def">C Function: </span><span><code class="def-type">double *</code> <strong class="def-name">scm_array_handle_f64_writable_elements</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005ff64_005fwritable_005felements"> ¶</a></span></dt>
|
||
|
|
<dt class="deftypefnx def-cmd-deftypefn" id="index-scm_005farray_005fhandle_005fc32_005fwritable_005felements"><span class="category-def">C Function: </span><span><code class="def-type">float *</code> <strong class="def-name">scm_array_handle_c32_writable_elements</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005fc32_005fwritable_005felements"> ¶</a></span></dt>
|
||
|
|
<dt class="deftypefnx def-cmd-deftypefn" id="index-scm_005farray_005fhandle_005fc64_005fwritable_005felements"><span class="category-def">C Function: </span><span><code class="def-type">double *</code> <strong class="def-name">scm_array_handle_c64_writable_elements</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005fc64_005fwritable_005felements"> ¶</a></span></dt>
|
||
|
|
<dd><p>Like <code class="code">scm_array_handle_<kind>_elements</code>, but the pointer is good
|
||
|
|
for reading and writing.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deftypefn">
|
||
|
|
<dt class="deftypefn" id="index-scm_005farray_005fhandle_005fbit_005felements"><span class="category-def">C Function: </span><span><code class="def-type">const scm_t_uint32 *</code> <strong class="def-name">scm_array_handle_bit_elements</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005fbit_005felements"> ¶</a></span></dt>
|
||
|
|
<dd><p>Return a pointer to the words that store the bits of the represented
|
||
|
|
array, which must be a bit array.
|
||
|
|
</p>
|
||
|
|
<p>Unlike other arrays, bit arrays have an additional offset that must be
|
||
|
|
figured into index calculations. That offset is returned by
|
||
|
|
<code class="code">scm_array_handle_bit_elements_offset</code>.
|
||
|
|
</p>
|
||
|
|
<p>To find a certain bit you first need to calculate its position as
|
||
|
|
explained above for <code class="code">scm_array_handle_dims</code> and then add the
|
||
|
|
offset. This gives the absolute position of the bit, which is always a
|
||
|
|
non-negative integer.
|
||
|
|
</p>
|
||
|
|
<p>Each word of the bit array storage block contains exactly 32 bits, with
|
||
|
|
the least significant bit in that word having the lowest absolute
|
||
|
|
position number. The next word contains the next 32 bits.
|
||
|
|
</p>
|
||
|
|
<p>Thus, the following code can be used to access a bit whose position
|
||
|
|
according to <code class="code">scm_array_handle_dims</code> is given in <var class="var">pos</var>:
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">SCM bit_array;
|
||
|
|
scm_t_array_handle handle;
|
||
|
|
scm_t_uint32 *bits;
|
||
|
|
ssize_t pos;
|
||
|
|
size_t abs_pos;
|
||
|
|
size_t word_pos, mask;
|
||
|
|
|
||
|
|
scm_array_get_handle (&bit_array, &handle);
|
||
|
|
bits = scm_array_handle_bit_elements (&handle);
|
||
|
|
|
||
|
|
pos = ...
|
||
|
|
abs_pos = pos + scm_array_handle_bit_elements_offset (&handle);
|
||
|
|
word_pos = abs_pos / 32;
|
||
|
|
mask = 1L << (abs_pos % 32);
|
||
|
|
|
||
|
|
if (bits[word_pos] & mask)
|
||
|
|
/* bit is set. */
|
||
|
|
|
||
|
|
scm_array_handle_release (&handle);
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
</dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deftypefn">
|
||
|
|
<dt class="deftypefn" id="index-scm_005farray_005fhandle_005fbit_005fwritable_005felements"><span class="category-def">C Function: </span><span><code class="def-type">scm_t_uint32 *</code> <strong class="def-name">scm_array_handle_bit_writable_elements</strong> <code class="def-code-arguments">(scm_t_array_handle *handle)</code><a class="copiable-link" href="#index-scm_005farray_005fhandle_005fbit_005fwritable_005felements"> ¶</a></span></dt>
|
||
|
|
<dd><p>Like <code class="code">scm_array_handle_bit_elements</code> but the pointer is good for
|
||
|
|
reading and writing. You must take care not to modify bits outside of
|
||
|
|
the allowed index range of the array, even for contiguous arrays.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
</div>
|
||
|
|
<hr>
|
||
|
|
<div class="nav-panel">
|
||
|
|
<p>
|
||
|
|
Previous: <a href="Arrays-as-arrays-of-arrays.html">Arrays as arrays of arrays</a>, Up: <a href="Arrays.html">Arrays</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|