ZelphirKaltstahl
/
guile-examples


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412
							<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>&lt;GBytes&gt;: </title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.2">
<link rel="home" href="index.html" title="">
<link rel="up" href="ch01.html" title="GLib">
<link rel="prev" href="re04.html" title="&lt;GByteArray&gt;">
<link rel="next" href="re06.html" title="&lt;GChecksum&gt;">
<meta name="generator" content="GTK-Doc V1.33.1 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><img src="up-insensitive.png" width="16" height="16" border="0"></td>
<td><a accesskey="p" href="re04.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="re06.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry">
<a name="id-1.1.6"></a><div class="titlepage"></div>
<div class="refnamediv">
<h2>&lt;GBytes&gt;</h2>
<p>&lt;GBytes&gt;</p>
</div>
<div class="refsect1">
<a name="id-1.1.6.2"></a><h2>Description</h2>
<p>A simple refcounted data type representing an immutable sequence of zero or
more bytes from an unspecified origin.
</p>
<p>The purpose of a <span class="type">GBytes</span> is to keep the memory region that it holds
alive for as long as anyone holds a reference to the bytes.  When
the last reference count is dropped, the memory is released. Multiple
unrelated callers can use byte data in the <span class="type">GBytes</span> without coordinating
their activities, resting assured that the byte data will not change or
move while they hold a reference.
</p>
<p>A <span class="type">GBytes</span> can come from many different origins that may have
different procedures for freeing the memory region.  Examples are
memory from <code class="function">g_malloc()</code>, from memory slices, from a <span class="type">GMappedFile</span> or
memory from other allocators.
</p>
<p><span class="type">GBytes</span> work well as keys in <span class="type">GHashTable</span>. Use <code class="function">g_bytes_equal()</code> and
<code class="function">g_bytes_hash()</code> as parameters to <code class="function">g_hash_table_new()</code> or <code class="function">g_hash_table_new_full()</code>.
<span class="type">GBytes</span> can also be used as keys in a <span class="type">GTree</span> by passing the <code class="function">g_bytes_compare()</code>
function to <code class="function">g_tree_new()</code>.
</p>
<p>The data pointed to by this bytes must not be modified. For a mutable
array of bytes see <span class="type">GByteArray</span>. Use <code class="function">g_bytes_unref_to_array()</code> to create a
mutable array for a <span class="type">GBytes</span> sequence. To create an immutable <span class="type">GBytes</span> from
a mutable <span class="type">GByteArray</span>, use the <code class="function">g_byte_array_free_to_bytes()</code> function.</p>
</div>
<div class="refsect1">
<a name="id-1.1.6.3"></a><h2>Functions</h2>
<div class="refsect2">
<a name="id-1.1.6.3.2"></a><h3>compare</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (bytes:compare self bytes2))
</pre></div>
<p>Compares the two <span class="type">GBytes</span> values.
</p>
<p>This function can be used to sort GBytes instances in lexicographical order.
</p>
<p>If <em class="parameter"><code>bytes1</code></em> and <em class="parameter"><code>bytes2</code></em> have different length but the shorter one is a
prefix of the longer one then the shorter one is considered to be less than
the longer one. Otherwise the first byte where both differ is used for
comparison. If <em class="parameter"><code>bytes1</code></em> has a smaller value at that position it is
considered less, otherwise greater than <em class="parameter"><code>bytes2</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.6.3.2.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>bytes1</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">GBytes</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>bytes2</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">GBytes</span> to compare with <em class="parameter"><code>bytes1</code></em></p>
<p>Passed as <code class="code">bytes2</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.6.3.3"></a><h3>equal?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (bytes:equal? self bytes2))
</pre></div>
<p>Compares the two <span class="type">GBytes</span> values being pointed to and returns
<code class="constant">TRUE</code> if they are equal.
</p>
<p>This function can be passed to <code class="function">g_hash_table_new()</code> as the <em class="parameter"><code>key_equal_func</code></em>
parameter, when using non-<code class="constant">NULL</code> <span class="type">GBytes</span> pointers as keys in a <span class="type">GHashTable</span>.</p>
<div class="refsect3">
<a name="id-1.1.6.3.3.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>bytes1</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">GBytes</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>bytes2</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">GBytes</span> to compare with <em class="parameter"><code>bytes1</code></em></p>
<p>Passed as <code class="code">bytes2</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.6.3.4"></a><h3>get-data</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return size) (bytes:get-data self))
</pre></div>
<p>Get the byte data in the <span class="type">GBytes</span>. This data should not be modified.
</p>
<p>This function will always return the same pointer for a given <span class="type">GBytes</span>.
</p>
<p><code class="constant">NULL</code> may be returned if <em class="parameter"><code>size</code></em> is 0. This is not guaranteed, as the <span class="type">GBytes</span>
may represent an empty string with <em class="parameter"><code>data</code></em> non-<code class="constant">NULL</code> and <em class="parameter"><code>size</code></em> as 0. <code class="constant">NULL</code> will
not be returned if <em class="parameter"><code>size</code></em> is non-zero.</p>
<div class="refsect3">
<a name="id-1.1.6.3.4.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>bytes</p></td>
<td class="parameter_description">
<p>a <span class="type">GBytes</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>size</p></td>
<td class="parameter_description">
<p>location to return size of byte data</p>
<p>Inferred from <code class="code">%return</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.6.3.5"></a><h3>get-region</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (bytes:get-region self element-size offset n-elements))
</pre></div>
<p>Undocumented</p>
<div class="refsect3">
<a name="id-1.1.6.3.5.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>bytes</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>element_size</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">element-size</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>offset</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">offset</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>n_elements</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">n-elements</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.6.3.6"></a><h3>get-size</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (bytes:get-size self))
</pre></div>
<p>Get the size of the byte data in the <span class="type">GBytes</span>.
</p>
<p>This function will always return the same value for a given <span class="type">GBytes</span>.</p>
<div class="refsect3">
<a name="id-1.1.6.3.6.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>bytes</p></td>
<td class="parameter_description">
<p>a <span class="type">GBytes</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.6.3.7"></a><h3>hash</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (bytes:hash self))
</pre></div>
<p>Creates an integer hash code for the byte data in the <span class="type">GBytes</span>.
</p>
<p>This function can be passed to <code class="function">g_hash_table_new()</code> as the <em class="parameter"><code>key_hash_func</code></em>
parameter, when using non-<code class="constant">NULL</code> <span class="type">GBytes</span> pointers as keys in a <span class="type">GHashTable</span>.</p>
<div class="refsect3">
<a name="id-1.1.6.3.7.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>bytes</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">GBytes</span> key</p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.6.3.8"></a><h3>new-from-bytes</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (bytes:new-from-bytes self offset length))
</pre></div>
<p>Creates a <span class="type">GBytes</span> which is a subsection of another <span class="type">GBytes</span>. The <em class="parameter"><code>offset</code></em> +
<em class="parameter"><code>length</code></em> may not be longer than the size of <em class="parameter"><code>bytes</code></em>.
</p>
<p>A reference to <em class="parameter"><code>bytes</code></em> will be held by the newly created <span class="type">GBytes</span> until
the byte data is no longer needed.
</p>
<p>Since 2.56, if <em class="parameter"><code>offset</code></em> is 0 and <em class="parameter"><code>length</code></em> matches the size of <em class="parameter"><code>bytes</code></em>, then
<em class="parameter"><code>bytes</code></em> will be returned with the reference count incremented by 1. If <em class="parameter"><code>bytes</code></em>
is a slice of another <span class="type">GBytes</span>, then the resulting <span class="type">GBytes</span> will reference
the same <span class="type">GBytes</span> instead of <em class="parameter"><code>bytes</code></em>. This allows consumers to simplify the
usage of <span class="type">GBytes</span> when asynchronously writing to streams.</p>
<div class="refsect3">
<a name="id-1.1.6.3.8.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>bytes</p></td>
<td class="parameter_description">
<p>a <span class="type">GBytes</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>offset</p></td>
<td class="parameter_description">
<p>offset which subsection starts at</p>
<p>Passed as <code class="code">offset</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>length</p></td>
<td class="parameter_description">
<p>length of subsection</p>
<p>Passed as <code class="code">length</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.6.3.9"></a><h3>ref</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (bytes:ref self))
</pre></div>
<p>Increase the reference count on <em class="parameter"><code>bytes</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.6.3.9.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>bytes</p></td>
<td class="parameter_description">
<p>a <span class="type">GBytes</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.6.3.10"></a><h3>unref</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (bytes:unref self))
</pre></div>
<p>Releases a reference on <em class="parameter"><code>bytes</code></em>.  This may result in the bytes being
freed. If <em class="parameter"><code>bytes</code></em> is <code class="constant">NULL</code>, it will return immediately.</p>
<div class="refsect3">
<a name="id-1.1.6.3.10.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>bytes</p></td>
<td class="parameter_description">
<p>a <span class="type">GBytes</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.6.3.11"></a><h3>unref-to-array</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (bytes:unref-to-array self))
</pre></div>
<p>Unreferences the bytes, and returns a new mutable <span class="type">GByteArray</span> containing
the same byte data.
</p>
<p>As an optimization, the byte data is transferred to the array without copying
if this was the last reference to bytes and bytes was created with
<code class="function">g_bytes_new()</code>, <code class="function">g_bytes_new_take()</code> or <code class="function">g_byte_array_free_to_bytes()</code>. In all
other cases the data is copied.</p>
<div class="refsect3">
<a name="id-1.1.6.3.11.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>bytes</p></td>
<td class="parameter_description">
<p>a <span class="type">GBytes</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.6.3.12"></a><h3>unref-to-data</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return size) (bytes:unref-to-data self))
</pre></div>
<p>Unreferences the bytes, and returns a pointer the same byte data
contents.
</p>
<p>As an optimization, the byte data is returned without copying if this was
the last reference to bytes and bytes was created with <code class="function">g_bytes_new()</code>,
<code class="function">g_bytes_new_take()</code> or <code class="function">g_byte_array_free_to_bytes()</code>. In all other cases the
data is copied.</p>
<div class="refsect3">
<a name="id-1.1.6.3.12.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>bytes</p></td>
<td class="parameter_description">
<p>a <span class="type">GBytes</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>size</p></td>
<td class="parameter_description">
<p>location to place the length of the returned data</p>
<p>Inferred from <code class="code">%return</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.6.3.13"></a><h3>bytes:new-take</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (bytes:new-take data))
</pre></div>
<p>Undocumented</p>
<div class="refsect3">
<a name="id-1.1.6.3.13.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>data</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">data</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>size</p></td>
<td class="parameter_description">
<p></p>
<p>Inferred from <code class="code">data</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.6.3.14"></a><h3>bytes:new</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (bytes:new data))
</pre></div>
<p>Undocumented</p>
<div class="refsect3">
<a name="id-1.1.6.3.14.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>data</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">data</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>size</p></td>
<td class="parameter_description">
<p></p>
<p>Inferred from <code class="code">data</code></p>
</td>
</tr>
</table></div>
</div>
</div>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.33.1</div>
</body>
</html>