org.rexxla.bsf.engines.rexx

## Class ArrayWrapper

- java.lang.Object
- - org.rexxla.bsf.engines.rexx.ArrayWrapper

-     public class ArrayWrapper
      extends java.lang.Object

  This class serves as a wrapper for Java arrays. Its methods allow to fully interact with arrays of any type from Rexx (and other non-Java-based languages). Names of methods are called after their Object Rexx counterparts, if any.

      ------------------------ Apache Version 2.0 license -------------------------
          Copyright (C) 2001-2021 Rony G. Flatscher

          Licensed under the Apache License, Version 2.0 (the "License");
          you may not use this file except in compliance with the License.
          You may obtain a copy of the License at

              http://www.apache.org/licenses/LICENSE-2.0

          Unless required by applicable law or agreed to in writing, software
          distributed under the License is distributed on an "AS IS" BASIS,
          WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
          See the License for the specific language governing permissions and
          limitations under the License.
       -----------------------------------------------------------------------------

  Version:
    1.6, 2021-02-05
  Author:
    Rony G. Flatscher (WU-Wien/Wirtschaftsuniversität Wien, http://www.wu-wien.ac.at/english)

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `java.lang.Class` | `componentType`
    `int` | `dimensions` Stores the total number of dimensions.
    `int` | `items` Stores the total size (maximum number of entries) of the entire array.
    `int[]` | `sizeOfDimension` Array of `int` which stores the size (maximum number of entries) of the appropriate dimension.
    `static java.lang.String` | `version` Version string indicating version of this class (majorVersion*100+minorVersion concatenated with a dot and the sorted date of last change.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ArrayWrapper(java.lang.Object objArray)` Creates and returns an instance of this class, allowing easier access to Java arrays.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `dimension(int i)` Returns the size of the given dimension.
    `java.lang.Object` | `get(int[] idxArr)` Get a value (item, element) from the array at the given position.
    `java.lang.Object[]` | `makearray(boolean bSupplier, boolean bRexxStyle)` Modelled after Object Rexx `MAKEARRAY` method of the array class.
    `void` | `put(java.lang.Object valueObj, int[] idxArr)` Put a value (item, element) into the array object at the given position.
    `Supplier` | `supplier()` Creates a supplier object for allowing to enumerate the array together with the appropriate indices (Java style: index starts with `0` and is enclosed in square brackets).
    `Supplier` | `supplier(boolean bRexxStyle)` Creates a supplier object for allowing to enumerate the array together with the appropriate indices.
    `RexxProxy` | `supplier(RexxProxy clzSupplier)` Creates a Rexx supplier object (from the supplied ooRexx .Supplier class object) for allowing to enumerate the array together with the appropriate indices.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### version

          public static java.lang.String version

      Version string indicating version of this class (majorVersion*100+minorVersion concatenated with a dot and the sorted date of last change.

    - #### dimensions

          public int dimensions

      Stores the total number of dimensions.

    - #### sizeOfDimension

          public int[] sizeOfDimension

      Array of `int` which stores the size (maximum number of entries) of the appropriate dimension.

    - #### items

          public int items

      Stores the total size (maximum number of entries) of the entire array.

    - #### componentType

          public java.lang.Class componentType

  - ### Constructor Detail

    - #### ArrayWrapper

          public ArrayWrapper(java.lang.Object objArray)
                       throws java.lang.ClassNotFoundException,
                              org.apache.bsf.BSFException

      Creates and returns an instance of this class, allowing easier access to Java arrays. The methods `get(int[] idxArr)`, `put(Object valueObj, int[] idxArr)`, `supplier()`, `supplier(boolean bRexxStyle)` and `( boolean bSupplier, boolean bRexxStyle )` are modelled after ooRexx (eg. cf. ooRexx class `Array`).
      Parameters:
        `objArray` - the array object for which an ArrayWrapper instance is sought
      Throws:
        `java.lang.ClassNotFoundException`
        `org.apache.bsf.BSFException`

  - ### Method Detail

    - #### dimension

          public int dimension(int i)

      Returns the size of the given dimension.
      Parameters:
        `i` - indicates the dimension of interest (Java index, i.e. first dimension to be indicated/indexed with the value `0`).
      Returns:
        the size of the given dimension.

    - #### get

          public java.lang.Object get(int[] idxArr)

      Get a value (item, element) from the array at the given position.
      Parameters:
        `idxArr` - a one-dimensional array of `int`s determining the location in the array.
      Returns:
        the Object stored at the specified location.

    - #### put

          public void put(java.lang.Object valueObj,
                          int[] idxArr)

      Put a value (item, element) into the array object at the given position.
      Parameters:
        `idxArr` - a one-dimensional array of `int`s determining the location in the array.
        `valueObj` - the Object to store; in the case of primitives the appropriate conversions takes place, curtesy of `Array`.

    - #### supplier

          public Supplier supplier()

      Creates a supplier object for allowing to enumerate the array together with the appropriate indices (Java style: index starts with `0` and is enclosed in square brackets).
      Returns:
        an instance of class `Supplier`, allowing for enumerating the contents of the array.

    - #### supplier

          public Supplier supplier(boolean bRexxStyle)

      Creates a supplier object for allowing to enumerate the array together with the appropriate indices.
      Parameters:
        `bRexxStyle` - determines whether the index value is [Object] Rexx style (index starts with `1`, multiple indices are separated by a comma) or Java style (index starts with `0`, indices are enclosed in square brackets)
      Returns:
        an instance of class `Supplier`, allowing for enumerating the contents of the array.

    - #### supplier

          public RexxProxy supplier(RexxProxy clzSupplier)
                             throws org.apache.bsf.BSFException

      Creates a Rexx supplier object (from the supplied ooRexx .Supplier class object) for allowing to enumerate the array together with the appropriate indices.
      Parameters:
        `clzSupplier` - the ooRexx "Supplier" class object to be used for creating a genuine ooRexx supplier (to allow ooRexx 5.0 new "DO WITH" to work)
      Returns:
        the ooRexx supplier object (a Java `RexxProxy`)
      Throws:
        `org.apache.bsf.BSFException`

    - #### makearray

          public java.lang.Object[] makearray(boolean bSupplier,
                                              boolean bRexxStyle)

      Modelled after Object Rexx `MAKEARRAY` method of the array class. This method is executed synchronized.
      Parameters:
        `bSupplier` - boolean value to indicate whether a `supplier` array (containing the appropriate indices as Strings) is to be prepared and returned (if set to `true`).
        `bRexxStyle` - boolean value to indicate whether using Rexx (index starts at: `1`) or Java (index starts at: `0`) style for creating the indices for a `supplier`.
      Returns:
        a two-dimensional array of Objects, where the first element contains the single dimensioned array and the second element the optional supplier array