Skip to content

Commit

Permalink
Clarify array conversion docs
Browse files Browse the repository at this point in the history
  • Loading branch information
mhsmith committed Nov 20, 2023
1 parent 6812368 commit 0d45dda
Showing 1 changed file with 13 additions and 5 deletions.
18 changes: 13 additions & 5 deletions product/runtime/docs/sphinx/python.rst
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,9 @@ Data types are converted between Python and Java as follows:

* Java `String` and `char` both correspond to Python `str`.

* A Java array is represented by a :any:`jarray` object. Java array parameters and fields
can also be implicitly converted from any sequence, except a string.
* A Java array is represented by a :any:`jarray` object. Java arrays can also be
:ref:`implicitly created <python-array-create>` from any Python sequence, except a
string.

* All other Java objects are represented by a :any:`jclass` object.

Expand Down Expand Up @@ -164,10 +165,17 @@ useful, so the equivalent Python operations are defined as follows:
Creating
........

There's usually no need to create `jarray` objects directly, because any sequence (except a
string) can be passed directly to a Java method or field which takes an array type.
There's usually no need to create `jarray` objects directly, because any Python sequence
(except a string) can be passed directly to a Java method or field which takes an array
type:

However, where a method has multiple array-type overloads, you may need to disambiguate the
* When passing a sequence to a Java method, Chaquopy will create a Java array and copy
the sequence into it. If the sequence is writable, it will also copy the Java array
back into the sequence after the method returns.
* Assigning a sequence to a Java field is the same, except modifications will not be
copied back.

When a Java method has multiple array-type overloads, you may need to disambiguate the
call. For example, if a class defines both `f(long[] x)` and `f(int[] x)`, then calling
`f([1,2,3])` will fail with an ambiguous overload error. To call the `int[]` overload, use
`f(jarray(jint)([1,2,3]))`.
Expand Down

0 comments on commit 0d45dda

Please sign in to comment.