XS-MLVP
/
swig
mirror of https://github.com/swig/swig
5
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve documentation. 

Follow @wsfulton reviews.

Signed-off-by: Erez Geva <ErezGeva2@gmail.com>
This commit is contained in:
Erez Geva 2024-03-09 15:33:04 +01:00
parent 0caf9e0aa4
commit 53a6c691c7
6 changed files with 308 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
Doc/Manual/CSharp.html
View File

@ -21,6 +21,7 @@
<li><a href="#CSharp_primitive_types">Primitive types</a>
<li><a href="#CSharp_other_type_mappings">Other types</a>
<li><a href="#CSharp_void_pointers">Void pointers</a>
<li><a href="#CSharp_cdata_i">cdata.i</a>
</ul>
<li><a href="#CSharp_arrays">C# Arrays</a>
<ul>
@ -921,6 +922,64 @@ void * f(void *v);
</pre>
</div>
<H3><a name="CSharp_cdata_i">23.3.4 cdata.i</a></H3>
<p>
The <tt>cdata.i</tt> module defines functions for converting raw C data to and from C# byte array.
The primary applications of this module would be passing binary data.
</p>
<p>
<b><tt>byte[] cdata(void *ptr, size_t nbytes)</tt></b>
</p>
<div class="indent"><p>
Converts <tt>nbytes</tt> of data at <tt>ptr</tt> into a C# byte array, <tt>ptr</tt> can point to any data.
</p></div>
<p>
<b><tt>void memmove(void *ptr, const byte b[])</tt></b>
</p>
<div class="indent"><p>
Copies the byte array in <tt>b</tt> into the memory pointed to by
<tt>ptr</tt>.
This is actually a wrapper to the standard C library <tt>memmove</tt> function, which is
declared as <b><tt>void memmove(void *ptr, const void *src, size_t n)</tt></b>.
The <tt>src</tt> and length <tt>n</tt> parameters are
Jave byte array <tt>b</tt> length and content in the underlying wrapper code.
</p></div>
<p>
The default <tt>cdata</tt> is defined for C <tt>void *</tt>, yet user may define
other types with:
</p>
<p>
<b><tt>%cdata(type [, name=type])</tt></b>
</p>
<div class="indent">
<p>
And generates the following function for extracting C data of the given type.
</p>
<div class="code">
<pre>
byte[] cdata_<em>name</em>(type* ptr, int nitems)
</pre>
</div>
<p>
<tt>nitems</tt> is the number of items of the given type to extract.
</p>
</div>
<H2><a name="CSharp_arrays">23.4 C# Arrays</a></H2>

6
Doc/Manual/Contents.html
View File

@ -809,6 +809,7 @@
<li><a href="CSharp.html#CSharp_primitive_types">Primitive types</a>
<li><a href="CSharp.html#CSharp_other_type_mappings">Other types</a>
<li><a href="CSharp.html#CSharp_void_pointers">Void pointers</a>
<li><a href="CSharp.html#CSharp_cdata_i">cdata.i</a>
</ul>
<li><a href="CSharp.html#CSharp_arrays">C# Arrays</a>
<ul>
@ -863,6 +864,7 @@
<li><a href="D.html#D_typecheck_typemaps">typecheck typemaps</a>
<li><a href="D.html#D_code_injection_typemaps">Code injection typemaps</a>
<li><a href="D.html#D_special_variables">Special variable macros</a>
<li><a href="D.html#D_cdata_i">cdata.i</a>
</ul>
<li><a href="D.html#D_other_code_control">Other D code control features</a>
<ul>
@ -926,6 +928,9 @@
<li><a href="Go.html#Go_output_arguments">Output arguments</a>
<li><a href="Go.html#Go_adding_additional_code">Adding additional go code</a>
<li><a href="Go.html#Go_typemaps">Go typemaps</a>
<ul>
<li><a href="Go.html#Go_cdata_i">cdata.i</a>
</ul>
</ul>
</ul>
</div>
@ -1091,6 +1096,7 @@
<li><a href="Java.html#Java_typemaps_for_c_and_cpp">Typemaps for both C and C++ compilation</a>
<li><a href="Java.html#Java_code_typemaps">Java code typemaps</a>
<li><a href="Java.html#Java_directors_typemaps">Director specific typemaps</a>
<li><a href="Java.html#Java_cdata_i">cdata.i</a>
</ul>
<li><a href="Java.html#Java_typemap_examples">Typemap Examples</a>
<ul>

59
Doc/Manual/D.html
View File

@ -21,6 +21,7 @@
<li><a href="#D_typecheck_typemaps">typecheck typemaps</a>
<li><a href="#D_code_injection_typemaps">Code injection typemaps</a>
<li><a href="#D_special_variables">Special variable macros</a>
<li><a href="#D_cdata_i">cdata.i</a>
</ul>
<li><a href="#D_other_code_control">Other D code control features</a>
<ul>
@ -309,6 +310,64 @@ $importtype(AnotherInterface)
</dl>
<H3><a name="D_cdata_i">24.3.8 cdata.i</a></H3>
<p>
The <tt>cdata.i</tt> module defines functions for converting raw C data to and from D byte array.
The primary applications of this module would be passing binary data.
</p>
<p>
<b><tt>ubyte[] cdata(void *ptr, size_t nbytes)</tt></b>
</p>
<div class="indent"><p>
Converts <tt>nbytes</tt> of data at <tt>ptr</tt> into a D byte array, <tt>ptr</tt> can point to any data.
</p></div>
<p>
<b><tt>void memmove(void *ptr, const ubyte b[])</tt></b>
</p>
<div class="indent"><p>
Copies the byte array in <tt>b</tt> into the memory pointed to by
<tt>ptr</tt>.
This is actually a wrapper to the standard C library <tt>memmove</tt> function, which is
declared as <b><tt>void memmove(void *ptr, const void *src, size_t n)</tt></b>.
The <tt>src</tt> and length <tt>n</tt> parameters are
Jave byte array <tt>b</tt> length and content in the underlying wrapper code.
</p></div>
<p>
The default <tt>cdata</tt> is defined for C <tt>void *</tt>, yet user may define
other types with:
</p>
<p>
<b><tt>%cdata(type [, name=type])</tt></b>
</p>
<div class="indent">
<p>
And generates the following function for extracting C data of the given type.
</p>
<div class="code">
<pre>
ubyte[] cdata_<em>name</em>(type* ptr, int nitems)
</pre>
</div>
<p>
<tt>nitems</tt> is the number of items of the given type to extract.
</p>
</div>
<H2><a name="D_other_code_control">24.4 Other D code control features</a></H2>

60
Doc/Manual/Go.html
View File

@ -46,6 +46,9 @@
<li><a href="#Go_output_arguments">Output arguments</a>
<li><a href="#Go_adding_additional_code">Adding additional go code</a>
<li><a href="#Go_typemaps">Go typemaps</a>
<ul>
<li><a href="#Go_cdata_i">cdata.i</a>
</ul>
</ul>
</ul>
</div>
@ -1528,5 +1531,62 @@ be cast to the desired type.
</table>
<H4><a name="Go_cdata_i">25.4.13.1 cdata.i</a></H4>
<p>
The <tt>cdata.i</tt> module defines functions for converting raw C data to and from Go byte array.
The primary applications of this module would be passing binary data.
</p>
<p>
<b><tt>[]byte cdata(void *ptr, size_t nbytes)</tt></b>
</p>
<div class="indent"><p>
Converts <tt>nbytes</tt> of data at <tt>ptr</tt> into a go byte array, <tt>ptr</tt> can point to any data.
</p></div>
<p>
<b><tt>void memmove(void *ptr, const []byte b)</tt></b>
</p>
<div class="indent"><p>
Copies the byte array in <tt>b</tt> into the memory pointed to by
<tt>ptr</tt>.
This is actually a wrapper to the standard C library <tt>memmove</tt> function, which is
declared as <b><tt>void memmove(void *ptr, const void *src, size_t n)</tt></b>.
The <tt>src</tt> and length <tt>n</tt> parameters are
Jave byte array <tt>b</tt> length and content in the underlying wrapper code.
</p></div>
<p>
The default <tt>cdata</tt> is defined for C <tt>void *</tt>, yet user may define
other types with:
</p>
<p>
<b><tt>%cdata(type [, name=type])</tt></b>
</p>
<div class="indent">
<p>
And generates the following function for extracting C data of the given type.
</p>
<div class="code">
<pre>
[]byte cdata_<em>name</em>(type* ptr, int nitems)
</pre>
</div>
<p>
<tt>nitems</tt> is the number of items of the given type to extract.
</p>
</div>
</body>
</html>

115
Doc/Manual/Java.html
View File

@ -114,6 +114,7 @@
<li><a href="#Java_simple_pointers">Simple pointers</a>
<li><a href="#Java_c_arrays">Wrapping C arrays with Java arrays</a>
<li><a href="#Java_unbounded_c_arrays">Unbounded C Arrays</a>
<li><a href="#Java_string_length">Passing a string with length</a>
<li><a href="#Java_heap_allocations">Overriding new and delete to allocate from Java heap</a>
</ul>
<li><a href="#Java_typemaps">Java typemaps</a>
@ -128,6 +129,7 @@
<li><a href="#Java_typemaps_for_c_and_cpp">Typemaps for both C and C++ compilation</a>
<li><a href="#Java_code_typemaps">Java code typemaps</a>
<li><a href="#Java_directors_typemaps">Director specific typemaps</a>
<li><a href="#Java_cdata_i">cdata.i</a>
</ul>
<li><a href="#Java_typemap_examples">Typemap Examples</a>
<ul>
@ -5511,7 +5513,60 @@ well suited for applications in which you need to create buffers,
package binary data, etc.
</p>
<H3><a name="Java_heap_allocations">27.8.5 Overriding new and delete to allocate from Java heap</a></H3>
<H3><a name="Java_string_length">27.8.5 Passing a string with length</a></H3>
<p>
SWIG provides multi-argument typemap available as mentioned in <a href="Library.html#Library_nn10">Passing a string with length</a>.
The following simple example demonstrates passing a string to the wrapped function.
</p>
<div class="code">
<pre>
%apply (char *STRING, size_t LENGTH) { (const char data[], size_t len) }
%inline %{
void binaryChar1(const char data[], size_t len) {
printf("len: %d data: ", len);
for (size_t i=0; i&lt;len; ++i)
printf("%x ", data[i]);
printf("\n");
}
%}
</pre>
</div>
<p>
Calling from Java requires a string to be passed in as the multi-argument typemap being applied reduces the number of arguments in the target language to one, from the original two:
</p>
<div class="code">
<pre>
String str = "hi\0jk";
example.binaryChar1(str);
</pre>
</div>
<p>
resulting in the output
</p>
<div class="code"><pre>
$ java runme
len: 5 data: 68 69 0 6a 6b
</pre></div>
<p>
The typemap use Java <tt>String::getBytes()</tt> to convert the string to defualt system encoding. If you wish to use a other encoding, you can modify the typemap. For example to convert the string to UTF-8 use:
</p>
<div class="code"><pre>
%typemap(javain, throws="java.io.IllegalCharsetNameException")<br>
(const char *STRING, size_t LENGTH) %{($javainput == null) ? null : $javainput.getBytes("UTF-8")%}
</pre></div>
<H3><a name="Java_heap_allocations">27.8.6 Overriding new and delete to allocate from Java heap</a></H3>
<p>
@ -7149,6 +7204,64 @@ The basic strategy here is to provide a default package typemap for the majority
</div>
<H3><a name="Java_cdata_i">27.9.11 cdata.i</a></H3>
<p>
The <tt>cdata.i</tt> module defines functions for converting raw C data to and from Java byte array.
The primary applications of this module would be passing binary data.
</p>
<p>
<b><tt>byte[] cdata(void *ptr, size_t nbytes)</tt></b>
</p>
<div class="indent"><p>
Converts <tt>nbytes</tt> of data at <tt>ptr</tt> into a Java byte array, <tt>ptr</tt> can point to any data.
</p></div>
<p>
<b><tt>void memmove(void *ptr, const byte b[])</tt></b>
</p>
<div class="indent"><p>
Copies the byte array in <tt>b</tt> into the memory pointed to by
<tt>ptr</tt>.
This is actually a wrapper to the standard C library <tt>memmove</tt> function, which is
declared as <b><tt>void memmove(void *ptr, const void *src, size_t n)</tt></b>.
The <tt>src</tt> and length <tt>n</tt> parameters are
Jave byte array <tt>b</tt> length and content in the underlying wrapper code.
</p></div>
<p>
The default <tt>cdata</tt> is defined for C <tt>void *</tt>, yet user may define
other types with:
</p>
<p>
<b><tt>%cdata(type [, name=type])</tt></b>
</p>
<div class="indent">
<p>
And generates the following function for extracting C data of the given type.
</p>
<div class="code">
<pre>
byte[] cdata_<em>name</em>(type* ptr, int nitems)
</pre>
</div>
<p>
<tt>nitems</tt> is the number of items of the given type to extract.
</p>
</div>
<H2><a name="Java_typemap_examples">27.10 Typemap Examples</a></H2>

25
Doc/Manual/Library.html
View File

@ -719,18 +719,11 @@ Now, in a script:
<p>
The <tt>cdata.i</tt> module defines functions for converting raw C data to and
from the target language. Static typed target languages (C#, Java, go, D)
uses array of bytes, while dynamic typed languages uses string.
The primary applications of this module would be packing/unpacking of
The <tt>cdata.i</tt> module defines functions for converting raw C data to and from strings
in the target language. The primary applications of this module would be packing/unpacking of
binary data structures---for instance, if you needed to extract data from a buffer.
Target dynamic typed language must support strings with embedded binary data
in order for benefit from this module, and should support a 'pack' and 'unpack'
functions to convert string to array of numbers and via versa.
Most static typed languages uses string with defined encoding,
which does not make them suitable for holding raw data.
Yet most dynamic typed language do not support arrays of bytes and
do not have a defined encoding of strings, which make them proper for holding raw data.
The target language must support strings with embedded binary data
in order for this to work.
</p>
<p>
@ -738,7 +731,7 @@ Yet most dynamic typed language do not support arrays of bytes and
</p>
<div class="indent"><p>
Converts <tt>nbytes</tt> of data at <tt>ptr</tt> into a string or array bytes when using static typed languages. <tt>ptr</tt> can be any
Converts <tt>nbytes</tt> of data at <tt>ptr</tt> into a string. <tt>ptr</tt> can be any
pointer.
</p></div>
@ -747,7 +740,7 @@ pointer.
</p>
<div class="indent"><p>
Copies all of the string data or array bytes when using static typed languages in <tt>s</tt> into the memory pointed to by
Copies all of the string data in <tt>s</tt> into the memory pointed to by
<tt>ptr</tt>. The string may contain embedded NULL bytes.
This is actually a wrapper to the standard C library <tt>memmove</tt> function, which is
declared as
@ -820,8 +813,10 @@ char *cdata_<em>name</em>(type* ptr, int nitems)
</div>
<p>
<b>Note:</b> These functions provide direct access to memory and can be used to overwrite data.
Clearly they are unsafe.
<b>Note:</b> Static typed target languages uses array of bytes instead of strings.<br>
<div class="indent">
See: <a href="Java.html#Java_cdata_i">Java</a>, <a href="CSharp.html#CSharp_cdata_i">C#</a>, <a href="Go.html#Go_cdata_i">Go</a> and <a href="D.html#D_cdata_i">D</a>.
</div>
</p>
<H2><a name="Library_nn8">12.3 C string handling</a></H2>