mthl
/
texinfo


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273
							<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:pls="http://www.w3.org/2005/01/pronunciation-lexicon" xmlns:ssml="http://www.w3.org/2001/10/synthesis" xmlns:svg="http://www.w3.org/2000/svg">
  <head>
    <title>Vectors</title>
    <link rel="stylesheet" type="text/css" href="docbook-epub.css"/>
    <link rel="stylesheet" type="text/css" href="kawa.css"/>
    <script src="kawa-ebook.js" type="text/javascript"/>
    <meta name="generator" content="DocBook XSL-NS Stylesheets V1.79.1"/>
    <link rel="prev" href="Overall-Index.xhtml" title="Index"/>
    <link rel="next" href="Uniform-vectors.xhtml" title="Uniform vectors"/>
  </head>
  <body>
    <header/>
    <section class="sect1" title="Vectors" epub:type="subchapter" id="Vectors">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both">Vectors</h2>
          </div>
        </div>
      </div>
      <p>Vectors are heterogeneous structures whose elements are indexed by
integers.  A vector typically occupies less space than a list of the
same length, and the average time needed to access a randomly chosen
element is typically less for the vector than for the list.
</p>
      <p>The <span class="emphasis"><em>length</em></span> of a vector is the number of elements that it
contains.  This number is a non–negative integer that is fixed when the
vector is created.  The <span class="emphasis"><em>valid indices</em></span> of a vector are the exact
non–negative integer objects less than the length of the vector.  The
first element in a vector is indexed by zero, and the last element is
indexed by one less than the length of the vector.
</p>
      <p>Vectors are written using the notation <code class="literal">#(<em class="replaceable"><code>obj</code></em> ...)</code>.
For example, a vector of length 3 3 containing the number zero
in element 0, the list <code class="literal">(2 2 2 2)</code> in element 1, and the
string <code class="literal">"Anna"</code> in element 2 can be written as following:
</p>
      <pre class="screen">#(0 (2 2 2 2) "Anna")
</pre>
      <p>Note that this is the external representation of a vector.
In Kawa, a vector datum is self-evaluating,
but for style (and compatibility with R7RS) is is suggested
you quote a vector constant:
</p>
      <pre class="screen">’#(0 (2 2 2 2) "Anna")  ⇒ #(0 (2 2 2 2) "Anna")
</pre>
      <p>Compare these different ways of creating a vector:
</p>
      <div class="variablelist" epub:type="list">
        <dl class="variablelist">
          <dt class="term"><code class="literal">(vector a b c)</code>
</dt>
          <dd>
            <p>In this case <code class="literal">a</code>, <code class="literal">b</code>, and <code class="literal">c</code> are expressions evaluated at
run-time and the results used to initialize a newly-allocated 3-element vector.
</p>
          </dd>
          <dt class="term"><code class="literal">[a b c]</code>
</dt>
          <dd>
            <p>Same as using vector, but more concise, and results in an immutable
(non-modifiable) vector.
</p>
          </dd>
          <dt class="term"><code class="literal">#(a b c)</code>
</dt>
          <dd>
            <p>This is reader syntax and creates a vector literal,
at read-time, early in compile-time.
The symbols <code class="literal">a</code>, <code class="literal">b</code>, and <code class="literal">c</code> are not evaluated
but instead used literally.
</p>
          </dd>
          <dt class="term"><code class="literal">`#(,a ,b ,c)</code>
</dt>
          <dd>
            <p>This is reader-syntax, using quasi-quotation,
so <code class="literal">a</code>, <code class="literal">b</code>, and <code class="literal">c</code> are expressions evaluated at run-time.
This is equivalent to <code class="literal">[a b c]</code> in that it results in an immutable vector.
</p>
          </dd>
        </dl>
      </div>
      <p class="synopsis" kind="Type"><span class="kind">Type</span><span class="ignore">: </span><a id="idm139667874462704" class="indexterm"/> <code class="function">vector</code></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>The type of vector objects.
</p>
        </blockquote>
      </div>
      <p class="synopsis" kind="Constructor"><span class="kind">Constructor</span><span class="ignore">: </span><a id="idm139667874459728" class="indexterm"/> <code class="function">vector</code> <em class="replaceable"><code><em class="replaceable"><code>obj</code></em></code></em> <em class="replaceable"><code>…</code></em></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>Return a newly allocated vector whose elements contain the given
arguments.  Analogous to <code class="literal">list</code>.
</p>
          <pre class="screen">(vector 'a 'b 'c)               ⇒  #(a b c)
</pre>
          <p>Alternatively, you can use square-bracket syntax,
which results in an immutable vector:
</p>
          <pre class="screen">['a 'b 'c]               ⇒  #(a b c)
</pre>
        </blockquote>
      </div>
      <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667874454048" class="indexterm"/> <code class="function">make-vector</code> <em class="replaceable"><code><em class="replaceable"><code>k</code></em></code></em></p>
      <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667874451120" class="indexterm"/> <code class="function">make-vector</code> <em class="replaceable"><code><em class="replaceable"><code>k</code></em></code></em> <em class="replaceable"><code><em class="replaceable"><code>fill</code></em></code></em></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>Return a newly allocated vector of <em class="replaceable"><code>k</code></em> elements.  If a second
argument is given, then each element is initialized to <em class="replaceable"><code>fill</code></em>.
Otherwise the initial contents of each element is <code class="literal">#!null</code>.
</p>
        </blockquote>
      </div>
      <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667874445712" class="indexterm"/> <code class="function">vector?</code> <em class="replaceable"><code><em class="replaceable"><code>obj</code></em></code></em></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>Return <code class="literal">#t</code> if <em class="replaceable"><code>obj</code></em> is a vector, <code class="literal">#f</code> otherwise.
</p>
        </blockquote>
      </div>
      <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667874440992" class="indexterm"/> <code class="function">vector-length</code> <em class="replaceable"><code><em class="replaceable"><code>vector</code></em></code></em></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>Return the number of elements in <em class="replaceable"><code>vector</code></em> as an exact integer.
</p>
        </blockquote>
      </div>
      <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667874436896" class="indexterm"/> <code class="function">vector-ref</code> <em class="replaceable"><code><em class="replaceable"><code>vector</code></em></code></em> <em class="replaceable"><code><em class="replaceable"><code>k</code></em></code></em></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>It is an error if <em class="replaceable"><code>k</code></em> is not a valid index of <em class="replaceable"><code>vector</code></em>.
The <code class="literal">vector-ref</code>
procedure returns the contents of element <em class="replaceable"><code>k</code></em> of <em class="replaceable"><code>vector</code></em>.
</p>
          <pre class="screen">(vector-ref '#(1 1 2 3 5 8 13 21) 5)     ⇒  8
(vector-ref '#(1 1 2 3 5 8 13 21)
  (inexact-&gt;exact (round (* 2 (acos -1)))))
⇒ 13
</pre>
        </blockquote>
      </div>
      <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667874430016" class="indexterm"/> <code class="function">vector-set!</code> <em class="replaceable"><code><em class="replaceable"><code>vector</code></em></code></em> <em class="replaceable"><code><em class="replaceable"><code>k</code></em></code></em> <em class="replaceable"><code><em class="replaceable"><code>obj</code></em></code></em></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>It is an error if <em class="replaceable"><code>k</code></em> is not a valid index of <em class="replaceable"><code>vector</code></em>.
The <code class="literal">vector-set!</code>
procedure stores <em class="replaceable"><code>obj</code></em> in element <em class="replaceable"><code>k</code></em> of <em class="replaceable"><code>vector</code></em>, and
returns no values.
</p>
          <pre class="screen">(let ((vec (vector 0 '(2 2 2 2) "Anna")))
  (vector-set! vec 1 '("Sue" "Sue"))
  vec)
  ⇒  #(0 ("Sue" "Sue") "Anna")

(vector-set! '#(0 1 2) 1 "doe")
  ⇒  <span class="emphasis"><em>error</em></span>    ;; constant vector
</pre>
        </blockquote>
      </div>
      <p>A concise alternative to <code class="literal">vector-ref</code> and <code class="literal">vector-set!</code>
is to use function call syntax.  For example:
</p>
      <pre class="screen">(let ((vec (vector 0 '(2 2 2 2) "Anna")))
  (set! (vec 1) '("Sue" "Sue"))
  (list (vec 2) (vec 1)))
  ⇒  ("Anna" ("Sue" "Sue"))
</pre>
      <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667874419904" class="indexterm"/> <code class="function">vector-&gt;list</code> <em class="replaceable"><code><em class="replaceable"><code>vector</code></em></code></em> [<em class="replaceable"><code><em class="replaceable"><code>start</code></em></code></em> [<em class="replaceable"><code><em class="replaceable"><code>end</code></em></code></em>]]</p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>The <code class="literal">vector-&gt;list</code> procedure returns a newly allocated list of the
objects contained in the elements of <em class="replaceable"><code>vector</code></em>
between <em class="replaceable"><code>start</code></em> and <em class="replaceable"><code>end</code></em>.
</p>
          <pre class="screen">(vector-&gt;list '#(dah dah didah))        ⇒  (dah dah didah)
(vector-&gt;list '#(dah dah didah) 1 2)    ⇒  (dah)
</pre>
        </blockquote>
      </div>
      <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667874412816" class="indexterm"/> <code class="function">list-&gt;vector</code> <em class="replaceable"><code><em class="replaceable"><code>list</code></em></code></em></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>The <code class="literal">list-&gt;vector</code> procedure returns a newly created vector
initialized to the elements of the list <em class="replaceable"><code>list</code></em>, in order.
</p>
          <pre class="screen">(list-&gt;vector '(dididit dah))           ⇒  #(dididit dah)
</pre>
        </blockquote>
      </div>
      <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667874407984" class="indexterm"/> <code class="function">vector-copy</code> <em class="replaceable"><code>vector</code></em> [<em class="replaceable"><code>start</code></em> [<em class="replaceable"><code>end</code></em>]]</p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>Returns a newly allocated copy of the elements of the given
<em class="replaceable"><code>vector</code></em> between <em class="replaceable"><code>start</code></em> and <em class="replaceable"><code>end</code></em> . The elements of the new
vector are the same (in the sense of <code class="literal">eqv?</code>) as the elements
of the old.
</p>
          <pre class="screen">(define a #(1 8 2 8)) ; a may be immutable
(define b (vector-copy a))
(vector-set! b 0 3)   ; b is mutable
b                     ⇒      #(3 8 2 8)
(define c (vector-copy b 1 3))
c                     ⇒ #(8 2)
</pre>
        </blockquote>
      </div>
      <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667874401136" class="indexterm"/> <code class="function">vector-copy!</code> <em class="replaceable"><code>to</code></em> <em class="replaceable"><code>at</code></em> <em class="replaceable"><code>from</code></em> [<em class="replaceable"><code>start</code></em> [<em class="replaceable"><code>end</code></em>]]</p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>Copies the elements of vector from between start and end
to vector to, starting at at. The order in which elements
are copied is unspecified, except that if the source and
destination overlap, copying takes place as if the source is first
copied into a temporary vector and then into the destination.
This can be achieved without allocating storage by making
sure to copy in the correct direction in such circumstances.
</p>
          <p>It is an error if <em class="replaceable"><code>at</code></em> is less than zero or greater than the length
of <em class="replaceable"><code>to</code></em>.
It is also an error if <code class="literal">(- (vector-length <em class="replaceable"><code>to</code></em>) <em class="replaceable"><code>at</code></em>)</code> is less
than <code class="literal">(- <em class="replaceable"><code>end</code></em> <em class="replaceable"><code>start</code></em>)</code>.
</p>
          <pre class="screen">(define a (vector 1 2 3 4 5))
(define b (vector 10 20 30 40 50))
(vector-copy! b 1 a 0 2)
b    ⇒ #(10 1 2 40 50)
</pre>
        </blockquote>
      </div>
      <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667874391376" class="indexterm"/> <code class="function">vector-append</code> <em class="replaceable"><code><em class="replaceable"><code>arg</code></em></code></em><em class="replaceable"><code>...</code></em></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>Creates a newly allocated vector whose elements are the
concatenation of the elements of the given arguments.
Each <em class="replaceable"><code>arg</code></em> may be a vector or a list.
</p>
          <pre class="screen">(vector-append #(a b c) #(d e f))
    ⇒ #(a b c d e f)
</pre>
        </blockquote>
      </div>
      <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667874386768" class="indexterm"/> <code class="function">vector-fill!</code> <em class="replaceable"><code><em class="replaceable"><code>vector fill</code></em></code></em> [<em class="replaceable"><code><em class="replaceable"><code>start</code></em></code></em> [<em class="replaceable"><code><em class="replaceable"><code>end</code></em></code></em>]]</p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>Stores <em class="replaceable"><code>fill</code></em> in in the elements of <em class="replaceable"><code>vector</code></em>
between <em class="replaceable"><code>start</code></em> and <em class="replaceable"><code>end</code></em>.
</p>
          <pre class="screen">(define a (vector 1 2 3 4 5))
(vector-fill! a 'smash 2 4)
a  ⇒ #(1 2 smash smash 5)
</pre>
        </blockquote>
      </div>
      <p>The procedures <code class="literal">vector-map</code> and <code class="literal">vector-for-each</code>
are documented in <a class="link" href="Mapping-functions.xhtml" title="Mapping functions">Mapping functions</a>.
</p>
    </section>
    <footer>
      <div class="navfooter">
        <p>
          Up: <a accesskey="u" href="Data-structures.xhtml">Data structures</a></p>
        <p>
        Previous: <a accesskey="p" href="Lists.xhtml">Lists</a></p>
        <p>
        Next: <a accesskey="n" href="Uniform-vectors.xhtml">Uniform vectors</a></p>
      </div>
    </footer>
  </body>
</html>