Module Prelude.PreludeArrays

Support for Java reflective arrays.

Imports

import Control.Category as Category
import Prelude.PreludeList as L
import Prelude.Maybe as Maybe
import Prelude.PreludeBase as PreludeBase
import Prelude.PreludeIO as PreludeIO
import Prelude.PreludeList as PreludeList
import Prelude.PreludeMonad as PreludeMonad
import Control.Semigroupoid as Semigroupoid

Table of Content

Definitions

type ArrayOf s a = Mutable s (JArray a)

class JavaType a ⇒ ArrayElement a

class (JavaType a, ArrayElement a) ⇒ PrimitiveArrayElement a

data JArray a = native java.lang.Object

genericToMaybeList ∷ JArray α → [Maybe α]

genericArrayFromIndexList ∷ JavaType α ⇒ [(Int, α)] → JArray α

genericArrayFold ∷ (α → β → α) → α → JArray β → α

arrayCacheST ∷ ArrayElement a ⇒ (Int → JArray a → a) → Int → STMutable s (JArray a)

arrayCache ∷ ArrayElement a ⇒ (Int → JArray a → a) → Int → JArray a

genericArrayMap ∷ (ArrayElement a, ArrayElement β) ⇒ (a → β) → JArray a → JArray β
Instances

instance ArrayElement (a, b)

instance ArrayElement (a, b, c)

instance ArrayElement (a→b)

instance ArrayElement Integer

instance ArrayElement String

instance ArrayElement [a]

instance Eq a ⇒ Eq (JArray a)

instance JavaType (JArray Int)

instance ListSource JArray

instance PrimitiveArrayElement Bool

instance PrimitiveArrayElement Char

instance PrimitiveArrayElement Double

instance PrimitiveArrayElement Float

instance PrimitiveArrayElement Int

instance PrimitiveArrayElement Long
Functions and Values by Type

Definitions

type ArrayOf s a = Mutable s (JArray a)

short hand for Mutable s (JArray a)

data JArray a = native java.lang.Object

The type JArray X corresponds to Java's J[] for any type X where J is the corresponding java type of X, but note that Java does not really have generic arrays.

We can use arrays of non-primitive types generically inside Frege, but native code that expects or returns arrays will not be generic.

The native interface will take every occurrence of

 JArray X

 Mutable s (JArray X)

in native declarations to denote the corresponding Java array type. But when the type argument is variable, it will be just Object. This corresponds to the usage in the array reflection API.

Multi-dimensional arrays are not very well supported out of the box. If one needs more than 1 dimensions, the type will get quite complex, as of course arrays are mutable and so one will have multiple levels of JArray nested in Mutable nested in JArray and so forth. Moreover, multi-dimensional arrays cannot be generic at all.

Note that there are really two different APIs:

With the JArray.getElemAt, JArray.getAt, JArray.setAt, JArray.setElemAt, JArray.itemAt and JArray.elemAt it is possible to work on Java objects with java compile time type X[] for some (non primitive!) java type X.
With the ArrayElement.newArray, ArrayElement.getElemAt, ArrayElement.getAt, ArrayElement.setAt, ArrayElement.setElemAt, ArrayElement.itemAt and ArrayElement.elemAt functions of the ArrayElement class for some type F that is an instance of ArrayElement, we can work on Java objects with Java compile time type X[], where X is the Java type corresponding to F, but the run time type is always X[].

The former ones are usable only in polymorphic functions where the type argument for JArray is a variable and we don't (want to) have ArrayElement constraints. They are not good for interfacing native methods that take or return arrays of a certain type. Run time type errors are possible because native methods could put anything there. However, when used in Frege only, the typing is safe.

The latter ones are truly type safe, because their Frege type corresponds to the expected Java compile time type, which is also the actual run time type.

Here is a cheat sheet for the different array get and set methods:

             Array type            Argument/    Description
                                   Result

 setAt       Mutable (JArray s X)  Maybe X     set null or data element
 setElemAt   Mutable (JArray s X)  X           set data element
 getAt       Mutable (JArray s X)  Maybe X     get null or data element
 getElemAt   Mutable (JArray s X)  X           get data element (unsafe)
 itemAt      JArray s X            Maybe X     get null or data element (pure)
 elemAt      JArray s X            X           get data element (pure, unsafe)

"unsafe" in this context applies only to non-primitive types and means that the function will fail with a NullPointerException if the value accessed is a Java null.