This is documentation for Mathematica 5, which was
based on an earlier version of the Wolfram Language.
View current documentation (Version 11.1)

Documentation / Mathematica / Add-ons & Links / J/Link / Part 1. Installable Java: Calling Java from Mathematica /

1.2.15 Ragged Arrays

Java allows arrays that are deeper than one dimension to be "ragged," or non-rectangular, meaning that they do not have the same length at every position at the same level. For example, {{1,2,3},{4,5},{6,7,8}} is a ragged two-dimensional array. J/Link allows you to send and receive ragged arrays, but it is not the default behavior. The reason for this is simply efficiency—the MathLink library has functions that allow very efficient transfer of rectangular arrays of most primitive types (e.g., byte, int, double, and so on), whereas ragged ones have to be picked apart tediously with a series of individual calls to get every piece. This all happens deep inside J/Link, so you do not have to be concerned with the mechanics of array passing, but it has a huge impact on speed. To maximize speed, J/Link assumes that arrays of primitive types are rectangular. You can toggle back and forth between allowing and rejecting ragged arrays by calling the AllowRaggedArrays function with either True or False.

Ragged array support.

With AllowRaggedArrays[True], sending of arrays deeper than one dimension is greatly slowed. Here is an example of array behavior and how it is affected. Assume the class Testing has the following method, which takes a two-dimensional array of ints and simply returns it:

public static int[][] intArrayIdentity(int[][] a) {

    return a;

}

Look what happens if we call it with a ragged array:

LoadClass["Testing"];
Testing`intArrayIdentity[{{1,2,3},{4,5}}]

An error occurs because the Mathematica definition for the Testing`intArrayIdentity() function requires that is argument be a two-dimensional rectangular array of integers. The call never even gets out of Mathematica.

Here we turn on support for ragged arrays, and the call works. This requires modifications in both the Mathematica-side type checking on method arguments and the Java-side array-reading routines:

AllowRaggedArrays[True]
Testing`intArrayIdentity[{{1,2,3},{4,5}}]

It is a good idea to turn off support for ragged arrays as soon as you no longer need it, since it slows arrays down so much:

AllowRaggedArrays[False]