15.1 Types and conversion between Lisp and Java

15.1.1 Mapping of Java primitive types to and from Lisp types

The 8 primitive Java types map naturally to Lisp types:

Mapping from primitive Java types to Lisp types
Java	Lisp
`long`, `int`, `short`, `byte`	integer
`double`	double-float
`float`	single-float
`char`	integer
`boolean`	`(member t nil)`

The mapping from Lisp to Java is not always obvious, for example because a Lisp integer can map to long, int, short, char or byte. In most cases, like method calls, the target Java type is known. In these cases, LispWorks allows integer in the acceptable range for byte, short, int, long amd char, any Lisp float for float and double, t and nil for boolean.

When the target is not known, like storing a value in a Java array object (that is type java.lang.Object[]) or using lisp-to-jobject, LispWorks uses this mapping:

Mapping from Lisp when target Java type is unknown
Lisp	Java
Integers that fit in 32 bits	`int`
Integers that do not fit into 32 bits but fit into 64 bits	`long`
Double floats	`double`
Other floats	`float`
`t` or `nil`	`boolean`
Other Lisp values	Cannot be converted.

LispWorks has a set of keywords and FLI types to match the primitive types, which can be used to specify these types, for example as the type of an array. The keyword names are the Java name (uppercased), and the FLI type names are the Java name preceded by J (and uppercased), exported from LW-JI. These are shown in the table below.

Keywords and FLI types matching primitive types
Java type	Keyword	FLI type	Underlying FLI type
`short`	`:short`	jshort	`:short`
`long`	`:long`	jlong	`:int64`
`byte`	`:byte`	jbyte	`:byte`
`char`	`:char`	jchar	`(:unsigned :short)`
`double`	`:double`	jdouble	`:double`
`float`	`:float`	jfloat	`:float`
`boolean`	`:boolean`	jboolean	Boolean, see below
`int`	`:int`	jint	`:int`

Note: The Java type char (and hence the class Character) corresponds to UTF-16 code units. which is equivalent to unsigned short. It does not correspond to Unicode characters, and therefore cannot be mapped to LispWorks characters.

Note: The Lisp values for the FLI type jboolean are nil and t, rather than integers. The conversion to/from the underlying value of FLI type (:unsigned :char) is done implicitly when storing/loading the value.

15.1.2 java.lang.String

LispWorks deals specially with java.lang.String objects, converting them automatically to Lisp strings when receiving them (return value of methods or arguments to calls into Lisp), and converting Lisp strings to java.lang.String when passing them (argument to method calls, return values from calls into Lisp). It is therefore possible to think of strings as another primitive type. The overhead associated with this conversion for short strings (tens of characters) is smaller than the overhead associated with passing a Java non-primitive object. Even for larger strings, the fact that all the data in the string is passed in one call without further Java/Lisp interaction make it an effective way of passing data.

15.1.3 Java non-primitive objects

All Java non-primitive objects are represented in LispWorks as foreign pointers of type jobject. jobject is a proper Lisp type, that is you can use cl:typep and specialize methods on it. The actual Java class of the object is not consistently represented, unless you explicitly ask for it using jobject-class-name. You can get a string describing the Java object in the way that Java "thinks" (that is the result of toString) using jobject-string. If you need a Java null value, then you can use the constant *java-null*.

Instances of standard-java-object are also considered to represent Java objects. standard-java-object instances have a slot that contains the actual jobject, which is used when an instance of standard-java-object is passed to the interface functions. In the text below, when argument is specified as "java-object" or "Java object", it can be either a jobject or an instance of standard-java-object.