Updated documentation

README.md

@@ -339,7 +339,9 @@ Returns **#t** if _obj_ is a null C pointer, otherwise returns **#f**.
 
 Frees _c-bytevector_ from memory.
 
-(**call-with-address-of**)
+(**call-with-address-of** _c-bytevector_ _thunk_)
+
+Calls _thunk_ with address pointer of _c-bytevector_.
 
 Since the support for calling C functions taking pointer address arguments, the
 ones you would prefix with &, varies, some additional ceremony is needed on

documentation/foreign-c.html

@@ -26,13 +26,71 @@ Schemes - 0.10.0</title>
         <li><a href="#documentation">Documentation</a>
         <ul>
         <li><a href="#types">Types</a></li>
-        <li><a href="#primitives-1">Primitives 1</a></li>
+        <li><a href="#primitives-1">Primitives 1</a>
-        <li><a href="#primitives-2">Primitives 2</a></li>
+        <ul>
+        <li>c-type-size</li>
+        <li>define-c-library</li>
+        <li>define-c-procedure</li>
+        <li>c-bytevector?</li>
+        <li>c-bytevector-u8-set!</li>
+        <li>c-bytevector-u8-ref</li>
+        <li>c-bytevector-pointer-set!</li>
+        <li>c-bytevector-pointer-ref</li>
+        </ul></li>
+        <li><a href="#primitives-2">Primitives 2</a>
+        <ul>
+        <li>define-c-callback</li>
+        </ul></li>
         <li><a href="#c-bytevector">c-bytevector</a>
         <ul>
-        <li><a href="#creation-and-deletion">Creationg and
+        <li>make-c-null</li>
-        deletion</a></li>
+        <li>c-null?</li>
-        <li><a href="#accessors">Accessors</a></li>
+        <li>c-free</li>
+        <li>make-c-bytevector</li>
+        <li>call-with-address-of</li>
+        <li>native-endianness</li>
+        <li>c-bytevector-s8-set!</li>
+        <li>c-bytevector-s8-ref</li>
+        <li>c-bytevector-s16-set!</li>
+        <li>c-bytevector-s16-ref</li>
+        <li>c-bytevector-s16-native-set!</li>
+        <li>c-bytevector-s16-native-ref</li>
+        <li>c-bytevector-u16-set!</li>
+        <li>c-bytevector-u16-ref</li>
+        <li>c-bytevector-u16-native-set!</li>
+        <li>c-bytevector-u16-native-ref</li>
+        <li>c-bytevector-s32-set!</li>
+        <li>c-bytevector-s32-ref</li>
+        <li>c-bytevector-s32-native-set!</li>
+        <li>c-bytevector-s32-native-ref</li>
+        <li>c-bytevector-u32-set!</li>
+        <li>c-bytevector-u32-ref</li>
+        <li>c-bytevector-u32-native-set!</li>
+        <li>c-bytevector-u32-native-ref</li>
+        <li>c-bytevector-s64-set!</li>
+        <li>c-bytevector-s64-ref</li>
+        <li>c-bytevector-s64-native-set!</li>
+        <li>c-bytevector-s64-native-ref</li>
+        <li>c-bytevector-u64-set!</li>
+        <li>c-bytevector-u64-ref</li>
+        <li>c-bytevector-u64-native-set!</li>
+        <li>c-bytevector-u64-native-ref</li>
+        <li>c-bytevector-sint-set!</li>
+        <li>c-bytevector-sint-ref</li>
+        <li>c-bytevector-uint-set!</li>
+        <li>c-bytevector-uint-ref</li>
+        <li>c-bytevector-ieee-single-set!</li>
+        <li>c-bytevector-ieee-single-native-set!</li>
+        <li>c-bytevector-ieee-single-ref</li>
+        <li>c-bytevector-ieee-single-native-ref</li>
+        <li>c-bytevector-ieee-double-set!</li>
+        <li>c-bytevector-ieee-double-native-set!</li>
+        <li>c-bytevector-ieee-double-ref</li>
+        <li>c-bytevector-ieee-double-native-ref</li>
+        <li>bytevector-&gt;c-bytevector</li>
+        <li>c-bytevector-&gt;bytevector</li>
+        <li>string-&gt;c-utf8</li>
+        <li>c-utf8-&gt;string</li>
         </ul></li>
         <li><a href="#environment-variables">Environment
         variables</a></li>
@@ -472,7 +530,9 @@ make -C snow/foreign/c SCHEME_IMPLEMENTATION_NAME</code></pre>
 (newline)
 ;&gt; (1 2 3)</code></pre>
         <h3 id="c-bytevector">c-bytevector</h3>
-        <h4 id="creation-and-deletion">Creation and deletion</h4>
+        <p>Foreign-c c-bytevector interface is copied from R6RS
+        bytevectors, with some added functionality for C null
+        pointers.</p>
         <p>(<strong>make-c-null</strong>)</p>
         <p>Returns a null C pointer.</p>
         <p>(<strong>c-null?</strong> <em>obj</em>)</p>
@@ -480,7 +540,30 @@ make -C snow/foreign/c SCHEME_IMPLEMENTATION_NAME</code></pre>
         pointer, otherwise returns <strong>#f</strong>.</p>
         <p>(<strong>c-free</strong> <em>c-bytevector</em>)</p>
         <p>Frees <em>c-bytevector</em> from memory.</p>
-        <p>(<strong>make-c-bytevector</strong> <em>k</em>)
+        <p>(<strong>call-with-address-of</strong>)</p>
+        <p>Since the support for calling C functions taking pointer
+        address arguments, the ones you would prefix with &amp;, varies,
+        some additional ceremony is needed on the Scheme side.</p>
+        <p>Example:</p>
+        <p>Calling from C:</p>
+        <pre><code>//void func(int** i);
+func(&amp;i);</code></pre>
+        <p>Calling from Scheme:</p>
+        <pre><code>(define cbv (make-bytevector (c-type-size &#39;int)))
+(call-with-address-of
+ cbv
+ (lambda (address)
+  (func address)))
+; Use cbv here</code></pre>
+        <p>The passed c-bytevector, in example named cbv, should only be
+        used <strong>after</strong> call to call-with-addres-of
+        ends.</p>
+        <p>(<strong>native-endianness</strong>)</p>
+        <p>Returns the endianness symbol associated implementation’s
+        preferred endianness (usually that of the underlying machine
+        architecture). This may be any &lt;endianness symbol&gt;,
+        including a symbol other than big and little.</p>
+        <p>(<strong>make-c-bytevector</strong> <em>k</em>)</br>
         (<strong>make-c-bytevector</strong> <em>k</em>
         <em>fill</em>)</p>
         <p>Returns a newly allocated c-bytevector of <em>k</em>
@@ -490,32 +573,76 @@ make -C snow/foreign/c SCHEME_IMPLEMENTATION_NAME</code></pre>
         <p>If the <em>fill</em> argument is present, it’s value must
         confine to C uint8_t values , it specifies the initial value for
         the bytes of the c-bytevector</p>
-        <h4 id="accessors">Accessors</h4>
+        <p>(<strong>c-bytevector-s8-set!</strong> <em>c-bytevector</em>
-        <p>(<strong>native-endianness</strong>)</p>
+        <em>k</em> <em>byte</em>)</p>
-        <p>c-bytevector-s8-set! c-bytevector-s8-ref
+        <p>If K is not a valid index of c-bytevector the behaviour is
-        c-bytevector-s16-set! c-bytevector-s16-ref
+        undefined.</p>
-        c-bytevector-s16-native-set! c-bytevector-s16-native-ref
+        <p>Stores the byte in element k of c-bytevector.</p>
-        c-bytevector-u16-set! c-bytevector-u16-ref
+        <p>(<strong>c-bytevector-s8-ref</strong> <em>c-bytevector</em>
-        c-bytevector-u16-native-set! c-bytevector-u16-native-ref
+        <em>k</em> <em>byte</em>)</p>
-        c-bytevector-s32-set! c-bytevector-s32-ref
+        <p>If K is not a valid index of c-bytevector the behaviour is
-        c-bytevector-s32-native-set! c-bytevector-s32-native-ref
+        undefined.</p>
-        c-bytevector-u32-set! c-bytevector-u32-ref
+        <p>Returns the byte at index k of c-bytevector.</p>
-        c-bytevector-u32-native-set! c-bytevector-u32-native-ref
+        <p>(<strong>c-bytevector-sint-set!</strong> <em>bytevector</em>
-        c-bytevector-s64-set! c-bytevector-s64-ref
+        <em>k</em> <em>endianness</em> <em>size</em>)</br>
-        c-bytevector-s64-native-set! c-bytevector-s64-native-ref
+        (<strong>c-bytevector-sint-ref</strong> <em>bytevector</em>
-        c-bytevector-u64-set! c-bytevector-u64-ref
+        <em>k</em> <em>endianness</em> <em>size</em>)</br>
-        c-bytevector-u64-native-set! c-bytevector-u64-native-ref
+        (<strong>c-bytevector-uint-set!</strong> <em>bytevector</em>
-        c-bytevector-sint-set! c-bytevector-sint-ref
+        <em>k</em> <em>endianness</em> <em>size</em>)</br>
-        c-bytevector-uint-set! c-bytevector-uint-ref
+        (<strong>c-bytevector-uint-ref</strong> <em>bytevector</em>
-        c-bytevector-ieee-single-set!
+        <em>k</em> <em>endianness</em> <em>size</em>)</p>
-        c-bytevector-ieee-single-native-set!
+        <p>Size must be a positive exact integer object. If K , . . . ,
-        c-bytevector-ieee-single-ref c-bytevector-ieee-single-native-ref
+        k + size − 1 is not valid indices of bytevector the behavior is
-        c-bytevector-ieee-double-set!
+        unspecified.</p>
-        c-bytevector-ieee-double-native-set!
+        <p>The c-bytevector-uint-ref procedure retrieves the exact
-        c-bytevector-ieee-double-ref c-bytevector-ieee-double-native-ref
+        integer object corresponding to the unsigned representation of
-        bytevector-&gt;c-bytevector c-bytevector-&gt;bytevector
+        size <em>size</em> and specified by <em>endianness</em> at
-        call-with-address-of</p>
+        indices <em>k</em>,…,<em>k</em> + <em>size</em> − 1.</p>
-        <p>string-&gt;c-utf8 c-utf8-&gt;string</p>
+        <p>The c-bytevector-sint-ref procedure retrieves the exact
+        integer object corresponding to the two’s-complement
+        representation of size size and specified by endianness at
+        indices k , . . . , k + size − 1. For c-bytevector-uint-set!, n
+        must be an exact integer object in the interval {0, . . . ,
+        256size − 1}.</p>
+        <p>The c-bytevector-uint-set! procedure stores the unsigned
+        representation of size size and specified by endianness into
+        bytevector at indices k , . . . , k + size − 1.</p>
+        <p>(<strong>c-bytevector-s16-set!</strong>)
+        (<strong>c-bytevector-s16-ref</strong>)
+        (<strong>c-bytevector-s16-native-set!</strong>)
+        (<strong>c-bytevector-s16-native-ref</strong>)
+        (<strong>c-bytevector-u16-set!</strong>)
+        (<strong>c-bytevector-u16-ref</strong>)
+        (<strong>c-bytevector-u16-native-set!</strong>)
+        (<strong>c-bytevector-u16-native-ref</strong>)
+        (<strong>c-bytevector-s32-set!</strong>)
+        (<strong>c-bytevector-s32-ref</strong>)
+        (<strong>c-bytevector-s32-native-set!</strong>)
+        (<strong>c-bytevector-s32-native-ref</strong>)
+        (<strong>c-bytevector-u32-set!</strong>)
+        (<strong>c-bytevector-u32-ref</strong>)
+        (<strong>c-bytevector-u32-native-set!</strong>)
+        (<strong>c-bytevector-u32-native-ref</strong>)
+        (<strong>c-bytevector-s64-set!</strong>)
+        (<strong>c-bytevector-s64-ref</strong>)
+        (<strong>c-bytevector-s64-native-set!</strong>)
+        (<strong>c-bytevector-s64-native-ref</strong>)
+        (<strong>c-bytevector-u64-set!</strong>)
+        (<strong>c-bytevector-u64-ref</strong>)
+        (<strong>c-bytevector-u64-native-set!</strong>)
+        (<strong>c-bytevector-u64-native-ref</strong>)
+        (<strong>c-bytevector-ieee-single-set!</strong>)
+        (<strong>c-bytevector-ieee-single-native-set!</strong>)
+        (<strong>c-bytevector-ieee-single-ref</strong>)
+        (<strong>c-bytevector-ieee-single-native-ref</strong>)
+        (<strong>c-bytevector-ieee-double-set!</strong>)
+        (<strong>c-bytevector-ieee-double-native-set!</strong>)
+        (<strong>c-bytevector-ieee-double-ref</strong>)
+        (<strong>c-bytevector-ieee-double-native-ref</strong>)
+        (<strong>bytevector-&gt;c-bytevector</strong>)
+        (<strong>c-bytevector-&gt;bytevector</strong>)
+        (<strong>string-&gt;c-utf8</strong>)
+        (<strong>c-utf8-&gt;string</strong>)</p>
         <h3 id="environment-variables">Environment variables</h3>
         <p>Setting environment variables like this on Windows works for
         this library:</p>