# HG changeset patch
# User Ernst Reissner <rei3ner@arcor.de>
# Date 1471395188 -7200
#      Wed Aug 17 02:53:08 2016 +0200
# Node ID b660951b3cc443ace5e186d81556ae14d71fe97f
# Parent  5ff9ea552af4ec4a6db2c81d3ee29c42a2631203
Java interface: added section 'Type conversions between Java and Octave'

diff -r 5ff9ea552af4 -r b660951b3cc4 doc/interpreter/external.txi
--- a/doc/interpreter/external.txi	Tue Aug 16 23:56:35 2016 +0200
+++ b/doc/interpreter/external.txi	Wed Aug 17 02:53:08 2016 +0200
@@ -1842,6 +1842,7 @@
 * Java Interface Functions::
 * Making Java classes available::
 * Creating an instance of a Java class::
+* Type conversions between Java and Octave::
 * Handling Java memory limitations::
 @end menu
 
@@ -2113,6 +2114,182 @@
 Passenger = javaObject ("package.FirstClass", row, seat);
 @end example
 
+@node Type conversions between Java and Octave
+@subsection Type conversions between Java and Octave
+@cindex conversion 
+
+Java is a quite strictly typed language. 
+The so called @dfn{primitive types} are 
+
+@itemize
+@item
+@code{boolean} represeting logical values, 
+@item
+@code{double} and @code{float} 
+representing 64 bit and 32 bit floating point numbers 
+according to the standard IEEE 754 
+@item
+@code{long}, @code{int}, @code{short} and @code{byte} 
+representing 64, 32, 16 and 8 bit signed integer numbers
+@item
+@code{char} representing an unicode character as an unsigned 16 bit number 
+@item
+and @code{void} representing the return type of a method 
+which does not return a value. 
+@end itemize
+
+Besides the @dfn{primitive types}, there are @dfn{reference types}. 
+Roughtly speaking, reference types are either @dfn{Object types} or
+array types. 
+There is a single special value, @code{null}, 
+which is common to all reference types, 
+which represents the 'reference to nowhere'.
+
+For Java's primitive types, 
+there are rough counterparts in Octave's type system. 
+The value @code{null} is represented by the empty matrix @code{[]} 
+with Octave type @code{null_matrix}. 
+
+
+
+The functions @code{javaObject} and @code{javaArray}
+create Java objects and return them
+wrapped in an instance of the Octave type @code{octave_java}.
+
+Instances of type @code{octave_java} can be passed
+to the functions of the java interface
+like @code{java_set}, @code{java_get} and @code{javaMethod}.
+Of course Octave hands over to the JVM (Java Virtual Machine),
+not the instance of @code{octave_java} but the Java object wrapped therein.
+
+Passing @code{[]}, the @code{null_matrix} on the side of Octave, 
+is seen as @code{null} at Java's side. 
+
+
+It is also possible, to pass arguments of Octave types
+given in the first column of @ref{tab:ConvTypes}.
+They are converted to instances of primitive Java types
+specified in the second column of @ref{tab:ConvTypes} 
+before being passed to the JVM. 
+
+
+@float Table,tab:ConvTypes
+@multitable{Octave Types} {primitive Java Types} {Java Wrapper Types}
+@headitem Octave Types @tab primitive Java Types @tab Java Wrapper Types
+@item       scalar  @tab double  @tab java.lang.Double
+@item float scalar  @tab float   @tab java.lang.Float
+@item bool          @tab boolean @tab java.lang.Boolean 
+@item int8,  uint8  @tab byte    @tab java.lang.Byte 
+@item int16, uint16 @tab short   @tab java.lang.Short
+@item int32, uint32 @tab int     @tab java.lang.Integer
+@item int64, uint64 @tab long    @tab java.lang.Long
+@end multitable
+@caption{Octave types, according Java primitive types and their wrapper types}
+@end float
+
+Let us consider @ref{tab:ConvTypes} in more detail: 
+Since the 64 bit floating point types @code{scalar} and @code{double} 
+both conform fairly with the standard IEEE 754, 
+they are essentially equivalent and conversion is straightforward. 
+Accordingly 
+for the 32 bit floating point types @code{scalar float} and @code{float}. 
+Also the logical types @code{bool} and @code{boolean} correspond
+fully. 
+
+A little bit more difficult is the situation for the integer types. 
+Java knows only signed integer types. 
+Octave integers of unsigend types greater than half of the maximum value
+are encoded with leading digit @c 1
+and are thus are converted into negative Java numbers of according type, 
+which is most likely to be an error. 
+We thus recommend to pass only singed integer types 
+to functions of the Java interface. 
+
+But even the signed integer types in Octave and in Java are equivalent
+only as long as no overflow/underflow occurs: 
+Whereas in Octave @code{intmax('int8')+1} is just @code{intmax('int8')}, 
+in Java @code{intmax('int8')+1} is @code{intmin('int8')}. 
+So it may make a difference whether computations are carried out 
+in Octave or in Java. 
+
+In Java to each primitive type, a wrapper type is associated. 
+Whereas the primitive types are outside the inheritance hierarchy, 
+their wrapper types are reference types.
+The last two columns of @ref{tab:ConvTypes} 
+associate primitive types and their wrapper types. 
+In fact, the JVM converts primitive types and their wrapper types by
+need through so called boxing and unboxing conversions, 
+except the @code{null} which is of no primitive type.
+Thus the Octave types in column one of @ref{tab:ConvTypes}
+may substitute primitive types and also their wrapper types.
+
+Polymorphism of methods and constructors 
+in conjunction with boxing and unboxing in Java may lead to ambiguities: 
+For example, if a class @code{Xxx} 
+has constructors @code{Xxx(Double)} and @code{Xxx(double)}, 
+Octave's Java interface chooses and calls an arbitrary constructor 
+without displaying a warning on the ambiguity 
+when @code{javaObject(Xxx, @dots{})} is invoked. 
+It is recommended to avoid ambiguities 
+(which is easier for methods than for constructors) 
+or to define constructors and methods in a way, 
+that the result is the same, 
+no matter which constructor and which method is called. 
+
+The type conversions from Octave to Java given by @ref{tab:ConvTypes},
+also apply to arrays, 
+no matter, whether @emph{column} vectors or @emph{row} vectors. 
+For example one-dimensional Octave vectors with @code{bool} entries, 
+are converted to Java arrays of type @code{boolean[]} or
+@code{Boolean[]}, as needed. 
+
+
+As stated at the beginning of this section, 
+@code{javaObject} returns an instance of @code{octave_java} 
+wrapping a java object. 
+Reading a field value via @code{java_get} 
+or invoking a method with @code{javaMethod} also returns a Java object, 
+and in general, this is also wrapped in a @code{octave_java}. 
+
+Note that if a method @code{mthd} has @code{void} return type, 
+@code{javaMethod(mthd,@dots{})} returns @code{null} 
+which is transformed into @code{[]}. 
+If a method has a reference return type, it may really return @code{null} 
+which is passed to Octave as @code{[]} as well. 
+Similarly for @code{java_get} applied to fields with reference type. 
+
+
+For the primitive types and their wrapper types from @ref{tab:ConvTypes}, 
+as well as for one-dimensional arrays, 
+an automatic conversion to the according Java type is performed. 
+Note that Java arrays are always converted 
+into Octave @emph{column} vectors. 
+
+One should expect that conversion from Java to Octave 
+is again according to @ref{tab:ConvTypes}. 
+To ensure compatibilty with Matlab, 
+Octave must offer Matlab's conversion rules, 
+which we shall discuss now. 
+
+Whereas conversion is as expected for logical types @code{boolean} and
+@code{Boolean}, 
+for convenience 
+Matlab performs for @emph{all} numeric types a conversion to @code{double}. 
+This works without loss of precision, 
+except in case of conversion of @code{long}: 
+Both @code{long} and @code{double} are encoded in 64 bit 
+and one bit is the sign. 
+Whereas @code{long}'s mantissa has 63 digits, 
+@code{double} 's mantissa has 53 digits only because 10 bits are
+required for the exponent. 
+That way, conversion drops precision of 10 binary digits. 
+For one-dimensional arrays, 
+Matlab performs the conversion given by @ref{tab:ConvTypes} 
+also for numeric types, to save memory. 
+
+
+
+
 @node Handling Java memory limitations
 @subsection Handling Java memory limitations
 @cindex memory, limitations
