r5497: Automatic commit for debian_version_1_3_0-1

[uffi.git] / doc / ref.sgml

diff --git a/doc/ref.sgml b/doc/ref.sgml
index cbf5336613c678cbf354dee67f10c2463dac9c63..99234c410e200a23bb2ee9a97bd182e5436f3849 100644 (file)
--- a/doc/ref.sgml
+++ b/doc/ref.sgml
@@ -1515,7 +1515,7 @@ if a cstring returned by a function is &null;.
       <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
-         <function>with-cast-pointer</function> <replaceable>binding-name ptr type &amp; body body</replaceable> => <returnvalue>value</returnvalue>
+         <function>with-cast-pointer</function> (<replaceable>binding-name ptr type) &amp; body body</replaceable> => <returnvalue>value</returnvalue>
        </synopsis>
       </refsynopsisdiv>
       <refsect1>
@@ -1547,11 +1547,11 @@ if a cstring returned by a function is &null;.
       <refsect1>
        <title>Description</title>
        <para>
-  Executes BODY with POINTER casted to be a pointer to type TYPE. If
-  BINDING-NAME is provided the casted pointer will be bound to this
+  Executes BODY with POINTER cast to be a pointer to type TYPE. If
+  BINDING-NAME is provided the cast pointer will be bound to this
   name during the execution of BODY. If BINDING-NAME is not provided
   POINTER must be a name bound to the pointer which should be
-  casted. This name will be bound to the casted pointer during the
+  cast. This name will be bound to the cast pointer during the
   execution of BODY.
 
   This is a no-op in AllegroCL but will wrap BODY in a LET form if
@@ -1562,6 +1562,21 @@ if a cstring returned by a function is &null;.
   DEREF-POINTER or DEREF-ARRAY.
        </para>
       </refsect1>
+      <refsect1>
+       <title>Examples</title>
+<programlisting>
+(with-foreign-object (size :int)
+   ;; FOO is a foreign function returning a :POINTER-VOID
+   (let ((memory (foo size)))
+      (when (mumble)
+         ;; at this point we know for some reason that MEMORY points
+         ;; to an array of unsigned bytes
+         (with-cast-pointer (memory :unsigned-byte)
+           (dotimes (i (deref-pointer size :int))
+            (do-something-with
+              (deref-array memory '(:array :unsigned-byte) i)))))))
+</programlisting>
+      </refsect1>
       <refsect1>
        <title>Side Effects</title>
        <para>None.</para>