## Package ucar.multiarray

Provides an abstraction for multidimensional array access, some concrete implementations, and ways to view a MultiArray as if it had a different structure.

See:
Description

Interface Summary
Accessor: Interface for multidimensional array data access.
IndexMap: This interface defines the services required by MultiArrayProxy to manipulate indexes and the dimensions of a MultiArray.
IntMap: An immutable Map of int by int key.
MultiArray: Interface for multidimensional arrays.
MultiArrayInfo: Inquiry or introspection interface for abstract multidimensional arrays.
RemoteAccessor: This interface is the same as Accessor, just tagged as java.rmi.Remote.

Class Summary
AbstractAccessor: This abstract class provides a skeletal implementation of the Accessor interface.
ArrayMultiArray: MultiArray implementation which is an adapter for java language arrays.
ClipMap: Use with MultiArrayProxy to limit the bounds of an index to the delegate on a given dimension.
ConcreteIndexMap: Base class which provides framework for implementations of IndexMap.
DecimateMap: Use with MultiArrayProxy to reduce the length along a particular dimension by sampling the domain according to a (repeated) pattern.
FlattenMap: Use with MultiArrayProxy to reduce apparent rank by merging adjacent dimensions.
FlipMap: Use with MultiArrayProxy to flip (invert) the indexing along a particular dimension.
IndexIterator: An IndexIterator is a helper class used for stepping through the index values of a MultiArray.
IntArrayAdapter: Apply the "Adapter" pattern to convert the interface of Class (int []) to interface IntMap.
MultiArrayImpl: A concrete, space efficent implementation of the MultiArray interface.
MultiArrayProxy: This MultiArray implementation wraps another MultiArray and an IndexMap to provide a different view of the wrapped MultiArray.
OffsetDualIndexIterator
OffsetIndexIterator: An IndexIterator where the lower bound is non-zero.
ScalarMultiArray: MultiArray implementation which can only contain single values, aka scalars.
SliceMap: Use with MultiArrayProxy to reduce the apparent rank of the delegate by fixing an index at particular value.
StringCharAdapter: This MultiArray implementation wraps another MultiArray of Character componentType to produce a MultiArray of one less rank with String componentType.
TransposeMap: Use with MultiArrayProxy to transpose two dimensions.

## Package ucar.multiarray Description

Provides an abstraction for multidimensional array access, some concrete implementations, and ways to view a MultiArray as if it had a different structure. The MultiArrayProxy and IndexMaps provide techniques to make any MultiArray appear as if it were transposed, flipped, flattened, clipped, sliced, subsampled, or any composition of these.

In the following, we use the unadorned term "array" to mean the Java language construct, and the term "multidimensional array" for the mathematical abstraction modeled by the MultiArray class in this package.

A multidimensional array is a collection of elements that are accessed by index. The elements may be objects or primitives. The index is a one dimensional array of integers. The number of dimensions of a multidimensional array is called its rank. Each of the dimensions has a length, which determines the possible values of the corresponding index element. A multidimensional array of rank 1 is often referred to as a vector. A multidimensional array of rank 0 is referred to as a scalar.

Like C and C++, the Java programming language provides an array primitive which is actually a (fixed length) vector. Also like C and C++, this primitive is used in the language to build up multidimensional arrays as vectors of vectors. For example, a two dimensional M by N array would be constructed as a vector of M references to M vectors each of length N. This strategy wastes some storage, and the waste increases for higher dimensioned arrays. In random access patterns, the added level of indirection for each dimension incurs a performance penalty as well. Numerical programs in C or C++ often avoid direct use of the language construct for multidimensional arrays. The availability of pointers and pointer arithmetic can be used to trade off against the costs, but these features are not available in Java. This suggests a need for Java library classes that abstract the notion of multidimensional array and implement commonly used array operations. These are included in this package.

The MultiArray API consists of:

- MultiArrayInfo Interface - A reflection or introspection interface for multidimensional arrays. Methods to discover the rank, shape and component type.
- Accessor Interface - Methods to set and get single values of a multidimensional array. Also methods for aggregate copy in and out of the array.
- MultiArray Interface - The union of MultiArrayInfo and Accessor interfaces. This is the interface that client code should use. The artificial factorization into MultiArrayInfo and Accessor interfaces is only needed for the convenience of some implementations, notably ucar.netcdf.Variable.
- MultiArray Implementations- Wrappers for Java arrays (ArrayMultiArray) and scalar objects (ScalarMultiArray), as well as a space efficient implementation (MultiArrayImpl).
- IndexIterator utility class - Used to step through the possible index values.
- MultiArrayProxy / IndexMap Interface Framework - MultiArrayProxy uses an IndexMap to provide a different view of some MultiArray. The new view typically has a different structure than the backing MultiArray. For example, we may wish to reduce the rank by one, fixing the index for a given dimension at a specific value.
- Concrete IndexMap classes - Concrete IndexMap primitives that are used with MultiArrayProxy to slice, clip, subsample, flip, transpose, or flatten a MultiArray. These may be functionally composed to form complex operations by using nested construction.
- AbstractAccessor abstract class - A partial implementation of the Accessor Interface that handles primitive type conversions.
- StringCharAdapter class - An adapter for MultiArray of `char` component type that presents a MultiArray of String interface.

The MultiArray methods to get() and set() values operate on single values. To grab a slice, clipped region or some other aggregate out of a MultiArray, use MultiArrayProxy and the appropriate concrete IndexMaps to create that view of the MultiArray. The concrete MultiArrayImpl provides a copy constructor for which the view can be used as initializer. The copyin() and copyout() methods of MultiArray may also be used for simple clippings.

There is an example program, DemoMultiArrays.java, which shows some ways to use the interface.