mirror of https://github.com/swig/swig
cdata doc updates
The cdata.i docs in C#, Java, D, Go had a confusing mix of target language and C declarations. Improve the main cdata documentation in Library.html instead.
This commit is contained in:
William S Fulton
parent
300e5e313b
commit
ea2380d52a
|
|
@ -8,27 +8,23 @@ Version 4.3.0 (in progress)
|
|||
===========================
|
||||
|
||||
2024-02-29: erezgeva
|
||||
#2609 Fix Java typemap '(const char *STRING, size_t LENGTH)'
|
||||
to use string type.
|
||||
Add (const char *STRING, size_t LENGTH) typemap to most languages.
|
||||
All languages uses string type with the
|
||||
'(const char *STRING, size_t LENGTH)' typemap.
|
||||
Add char_binary test to most languages and
|
||||
director_binary test to languages supporting director class.
|
||||
Add new typemap '(const void *BYTES, size_t LENGTH)' to
|
||||
use with C raw data (cdata).
|
||||
Add '(const void *BYTES, size_t LENGTH)' typemap to most languages.
|
||||
Rebase 'cdata.i' files to improve coherent among different languages.
|
||||
Add li_cdata test to most languages.
|
||||
Languages with static type use byte array for
|
||||
'(const void *BYTES, size_t LENGTH)'.
|
||||
While dynamic type languages retain string.
|
||||
incompatibilities:
|
||||
* '(const char *STRING, size_t LENGTH)': Java uses String
|
||||
Users replace it with '(const void *BYTES, size_t LENGTH)' to use
|
||||
bytes array.
|
||||
#2609 Fix Java typemap (const char *STRING, size_t LENGTH) to
|
||||
marshall as Java String instead of Java byte[]. If the old behaviour
|
||||
is required, replace with typemap (const void *BYTES, size_t LENGTH).
|
||||
Add multi-argument typemaps to most languages:
|
||||
(const char *STRING, size_t LENGTH)
|
||||
All languages now use a target language string type for this typemap.
|
||||
|
||||
New multi-argument typemaps have been added to most target languages
|
||||
for use with C raw data (cdata):
|
||||
(const void *BYTES, size_t LENGTH) to
|
||||
Statically typed languages use a byte array for this typemap, while
|
||||
scripting languages remain using a string.
|
||||
|
||||
*** POTENTIAL INCOMPATIBILITY ***
|
||||
|
||||
* Raw C data: Go uses byte array and int64 for size.
|
||||
Users can use '(const char *STRING, size_t LENGTH)' to use strings.
|
||||
Users can use the (const char *STRING, size_t LENGTH) typemaps for strings.
|
||||
|
||||
2024-02-28: wsfulton
|
||||
Fix compilation errors in generated code when instantiating a templated
|
||||
|
|
|
|||
|
|
@ -21,7 +21,6 @@
|
|||
<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>
|
||||
|
|
@ -922,64 +921,6 @@ 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>
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -21,7 +21,6 @@
|
|||
<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>
|
||||
|
|
@ -310,64 +309,6 @@ $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>
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -46,9 +46,6 @@
|
|||
<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>
|
||||
|
|
@ -1531,62 +1528,5 @@ 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>
|
||||
|
|
|
|||
|
|
@ -129,7 +129,6 @@
|
|||
<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>
|
||||
|
|
@ -5557,7 +5556,7 @@ 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:
|
||||
The typemap uses Java <tt>String::getBytes()</tt> to convert the string to the default system encoding. If you wish to use another encoding, you can modify the typemap. For example to convert the string to UTF-8 use:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
|
|
@ -7204,64 +7203,6 @@ 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>
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -719,11 +719,22 @@ Now, in a script:
|
|||
|
||||
|
||||
<p>
|
||||
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
|
||||
The <tt>cdata.i</tt> module defines functions for converting raw C data to and from a target language type.
|
||||
The target language type is either:
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li> A string for the scripting languages. The scripting language must support strings with embedded binary data in order for this to work.</li>
|
||||
<li> A byte array for the statically typed languages; namely, <tt>byte[]</tt> for C# and Java, <tt>ubyte[]</tt> for D, <tt>[]byte</tt> for Go.</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
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.
|
||||
The target language must support strings with embedded binary data
|
||||
in order for this to work.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The available APIs are:
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
|
@ -731,7 +742,7 @@ in order for this to work.
|
|||
</p>
|
||||
|
||||
<div class="indent"><p>
|
||||
Converts <tt>nbytes</tt> of data at <tt>ptr</tt> into a string. <tt>ptr</tt> can be any
|
||||
Converts <tt>nbytes</tt> of data at <tt>ptr</tt> into the target language type. <tt>ptr</tt> can be any
|
||||
pointer.
|
||||
</p></div>
|
||||
|
||||
|
|
@ -740,13 +751,13 @@ pointer.
|
|||
</p>
|
||||
|
||||
<div class="indent"><p>
|
||||
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
|
||||
<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
|
||||
extracted from the language specific string <tt>s</tt> in the underlying wrapper code.
|
||||
This is actually a wrapper of the standard C library <tt>memmove</tt> function,
|
||||
<b><tt>void *memmove(void *ptr, const void *src, size_t n)</tt></b>,
|
||||
which copies <tt>n</tt> bytes of data from <tt>src</tt> into the destination pointed to by <tt>ptr</tt>.
|
||||
Multi-argument typemaps are used so that the last two parameters, <tt>src</tt> and <tt>n</tt> are replaced by
|
||||
<tt>s</tt>, a string or byte array target language type, mentioned earlier.
|
||||
The string/byte array may contain embedded NULL bytes.
|
||||
Unlike the C library function nothing is returned by the wrapper function.
|
||||
</p></div>
|
||||
|
||||
<p>
|
||||
|
|
@ -813,10 +824,8 @@ char *cdata_<em>name</em>(type* ptr, int nitems)
|
|||
</div>
|
||||
|
||||
<p>
|
||||
<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>
|
||||
<b>Note:</b> These functions provide direct access to memory and can be used to overwrite data.
|
||||
Clearly they are unsafe.
|
||||
</p>
|
||||
|
||||
<H2><a name="Library_nn8">12.3 C string handling</a></H2>
|
||||
|
|
|
|||
|
|
@ -4473,7 +4473,7 @@ just such a typemap is already defined. Just do this:
|
|||
<pre>
|
||||
%apply (char *STRING, size_t LENGTH) { (char *data, size_t size) };
|
||||
...
|
||||
int parity(char *data, int size, int initial);
|
||||
int parity(char *data, size_t size, int initial);
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@
|
|||
|
||||
%apply (const void *BYTES, size_t LENGTH) { (const void *BYTES, int LENGTH) }
|
||||
%apply (void *BYTES, size_t LENGTH) { (void *BYTES, int LENGTH) }
|
||||
/* type map for memmove() function */
|
||||
/* typemap for memmove() function */
|
||||
%apply (const void *BYTES, size_t LENGTH) { (const void *indata, size_t inlen) }
|
||||
|
||||
#endif
|
||||
|
|
|
|||
Loading…
Reference in New Issue