Interface ObjectArray<E>

All Superinterfaces:
Array
All Known Subinterfaces:
MutableObjectArray<E>, MutableObjectInPlaceArray<E>, ObjectInPlaceArray<E>, UpdatableObjectArray<E>, UpdatableObjectInPlaceArray<E>
All Known Implementing Classes:
AbstractObjectArray, AbstractUpdatableObjectArray

public interface ObjectArray<E> extends Array

AlgART array of some objects (non-primitive values) with the specified generic type E, read-only access.

Any class implementing this interface must contain non-primitive elements (elementType() must not return a primitive type).

Author:
Daniel Alievsky
  • Method Details

    • elementType

      Class<E> elementType()
      Description copied from interface: Array
      Returns the type of array elements. For arrays of primitive types, returns: All elements of the array are values of this type or (for non-primitive types) some inheritor of this type.

      There is a guarantee that this method works very quickly (usually it just returns a value of some private field).

      Specified by:
      elementType in interface Array
      Returns:
      the type of array elements.
      See Also:
    • type

      Class<? extends ObjectArray<E>> type()
      Description copied from interface: Array
      Returns the canonical AlgART type of this array: the class of one of 9 basic interfaces, describing all kinds of AlgART arrays for 8 primitive and any non-primitive element types. More precisely, returns:

      There is a guarantee that this method works very quickly (usually it just returns a constant value).

      Specified by:
      type in interface Array
      Returns:
      canonical AlgART type of this array.
    • updatableType

      Class<? extends UpdatableObjectArray<E>> updatableType()
      Description copied from interface: Array
      Returns the canonical updatable AlgART type of arrays with the same element types: the class of one of 9 basic interfaces, describing all kinds of updatable AlgART arrays for 8 primitive and any non-primitive element types. More precisely, returns:

      There is a guarantee that this method works very quickly (usually it just returns a constant value).

      Specified by:
      updatableType in interface Array
      Returns:
      canonical AlgART type of an updatable array of the same kind.
    • mutableType

      Class<? extends MutableObjectArray<E>> mutableType()
      Description copied from interface: Array
      Returns the canonical resizable AlgART type of arrays with the same element types: the class of one of 9 basic interfaces, describing all kinds of resizable AlgART arrays for 8 primitive and any non-primitive element types. More precisely, returns:

      There is a guarantee that this method works very quickly (usually it just returns a constant value).

      Specified by:
      mutableType in interface Array
      Returns:
      canonical AlgART type of a resizable array of the same kind.
    • get

      E get(long index)
      Equivalent to getElement(index).
      Parameters:
      index - index of element to get.
      Returns:
      the element at the specified position in this array.
      Throws:
      IndexOutOfBoundsException - if index is out of range 0..length()-1.
    • indexOf

      long indexOf(long lowIndex, long highIndex, E value)
      Returns the minimal index k, so that lowIndex<=k<min(highIndex,thisArray.length()) and value!=null?value.equals(thisArray.get(k)):thisArray.get(k)==null, or -1 if there is no such array element.

      In particular, if lowIndex>=thisArray.length()} or lowIndex>=highIndex, this method returns -1, and if lowIndex<0, the result is the same as if lowIndex==0.

      You may specify lowIndex=0 and highIndex=Long.MAX_VALUE to search through all array elements.

      Unlike the standard List.indexOf method, this method never throws ClassCastException.

      Parameters:
      lowIndex - the low index in the array for search (inclusive).
      highIndex - the high index in the array for search (exclusive).
      value - the value to be found.
      Returns:
      the index of the first occurrence of this value in this array in range lowIndex<=index<highIndex, or -1 if this value does not occur in this range.
    • lastIndexOf

      long lastIndexOf(long lowIndex, long highIndex, E value)
      Returns the maximal index k, so that highIndex>k>=max(lowIndex,0) and value!=null?value.equals(thisArray.get(k)):thisArray.get(k)==null, or -1 if there is no such array element.

      In particular, if highIndex<=0 or highIndex<=lowIndex, this method returns -1, and if highIndex>=thisArray.length(), the result is the same as if highIndex==thisArray.length().

      You may specify lowIndex=0 and highIndex=Long.MAX_VALUE to search through all array elements.

      Unlike the standard List.indexOf method, this method never throws ClassCastException.

      Parameters:
      lowIndex - the low index in the array for search (inclusive).
      highIndex - the high index in the array for search (exclusive).
      value - the value to be found.
      Returns:
      the index of the last occurrence of this value in this array in range lowIndex<=index<highIndex, or -1 if this value does not occur in this range.
    • cast

      <D> ObjectArray<D> cast(Class<D> elementType)
      Returns this array cast to the specified generic element type or throws ClassCastException if the elements cannot be cast to the required type (because the element type is not its subclass). Equivalent to (ObjectArray)thisArray, but is compiled without "unchecked cast" warning or "inconvertible type" error.

      Unlike ArrayList architecture, such casting is safe here, because all methods, storing data in the AlgART array, always check the element type and do not allow saving illegal elements.

      Parameters:
      elementType - the required generic type.
      Returns:
      this array cast to the specified generic element type.
      Throws:
      NullPointerException - if the argument is null.
      ClassCastException - if the elements cannot be cast to the required type.
    • buffer

      DataObjectBuffer<E> buffer(DataBuffer.AccessMode mode, long capacity)
      Description copied from interface: Array
      Returns a data buffer allowing block access to this array with the specified access mode and buffer capacity.

      If this array does not implement UpdatableArray interface (so, it is probably immutable or trusted immutable), the mode argument must be DataBuffer.AccessMode.READ.

      The capacity argument must be in range 0..237-1 for bit arrays or 0..231-1 for all other element types.

      If the capacity argument is greater than this array Array.length(), it is truncated to this length.

      Specified by:
      buffer in interface Array
      Parameters:
      mode - the access mode for new buffer.
      capacity - the capacity of the buffer.
      Returns:
      new data buffer for accessing this array.
      See Also:
    • buffer

      Description copied from interface: Array
      Equivalent to buffer(mode, someCapacity), where mode is the argument of this method and someCapacity is chosen automatically to provide good performance in typical situations. Usually, the capacity is chosen to get a buffer occupying several kilobytes, that can fit in an internal cache of most processors.

      In any case, you can be sure that the chosen capacity will not be greater than Integer.MAX_VALUE-64.

      Specified by:
      buffer in interface Array
      Parameters:
      mode - the access mode for new buffer.
      Returns:
      new data buffer for accessing this array.
    • buffer

      DataObjectBuffer<E> buffer(long capacity)
      Description copied from interface: Array
      Equivalent to buffer(suitableMode, capacity), where capacity is the argument of this method and suitableMode is chosen automatically. Namely, suitableMode is:
      Specified by:
      buffer in interface Array
      Parameters:
      capacity - the capacity of the buffer.
      Returns:
      new data buffer for accessing this array.
    • buffer

      DataObjectBuffer<E> buffer()
      Description copied from interface: Array
      Equivalent to buffer(suitableMode, someCapacity), where both suitableMode and someCapacity arguments are chosen automatically. The algorithm of choosing these arguments is the same as for Array.buffer(net.algart.arrays.DataBuffer.AccessMode) and Array.buffer(long) methods.

      In any case, you can be sure that the chosen capacity will not be greater than Integer.MAX_VALUE-64.

      Specified by:
      buffer in interface Array
      Returns:
      new data buffer for accessing this array.
    • asImmutable

      ObjectArray<E> asImmutable()
      Description copied from interface: Array
      Returns an immutable view of this array. If this array is already immutable (i.e. Array.isImmutable() is true), returns a reference to this object.

      A array is considered to be immutable, if there are no ways to modify its content or state with help of this instance. In particular, immutable arrays never implement UpdatableArray or DirectAccessible interfaces. Moreover, any third-party implementation of Array interface must return an instance of a class, which has no methods or fields allowing to change this instance.

      Query operations on the returned array "read through" to this array. The returned view is also unresizable (see UpdatableArray.asUnresizable()).

      The returned view (when it is not a reference to this object) contains the same elements as this array, but independent length, start offset, capacity, copy-on-next-write and possible other information about array characteristics besides its elements, as for Array.shallowClone() method. If modifications of this array characteristics lead to reallocation of the internal storage, then the returned array ceases to be a view of this array. The only possible reasons for reallocation are the following: calling MutableArray.length(long), MutableArray.ensureCapacity(long) or MutableArray.trim() methods for this array, or any modification of this or returned array in a case when this array is copy-on-next-write.

      By default, the array factories (memory models) create mutable arrays, but they can be converted to immutable by this method.

      Note: Array.isNew() method, called for the result of this method, always returns false — because it does not implement UpdatableArray.

      Also note: Array.isNewReadOnlyView() method, called for the result of this method, always returns the same value as Array.isNewReadOnlyView() for this object. Really,

      Specified by:
      asImmutable in interface Array
      Returns:
      an immutable view of this array (or a reference to this array if it is already immutable).
      See Also:
    • asTrustedImmutable

      ObjectArray<E> asTrustedImmutable()
      Description copied from interface: Array
      Returns a trusted immutable view of this array. If this array is already trusted immutable, returns a reference to this object.

      A array is considered to be "trusted" immutable, if it potentially can change its elements, but the Java code working with this array promises that it will not change them. The returned instance never implements UpdatableArray, but may implement DirectAccessible, that allow quick access to its elements. As for usual immutable view, query operations on the returned array "read through" to this array.

      The only standard way allowing to change elements of returned array is using DirectAccessible.javaArray() method, in a case when the array is backed by an accessible array. But the Java code, processing the trusted immutable array, must use this method only for quick reading elements and not try to change them. If, despite the promise, the elements of the trusted immutable array will be changed, the UnallowedMutationError may be thrown by the call of Array.checkUnallowedMutation() method.

      In some implementations — for example, if DirectAccessible interface is not supported by this array — this method may return the same result as Array.asImmutable().

      The returned view is always unresizable.

      The returned view (when it is not a reference to this object) contains the same elements as this array, but independent length, start offset, capacity, copy-on-next-write and possible other information about array characteristics besides its elements, as for Array.shallowClone() method. If modifications of this array characteristics lead to reallocation of the internal storage, then the returned array ceases to be a view of this array. The only possible reasons for reallocation are the following: calling MutableArray.length(long), MutableArray.ensureCapacity(long) or MutableArray.trim() methods for this array, or any modification of this or returned array in a case when this array is copy-on-next-write.

      Trusted immutable view is a compromise between absolute safety, provided by usual immutable view, and maximal efficiency, achieved while using the original non-protected array. Please see the package description to learn more about possible usage of this method.

      Specified by:
      asTrustedImmutable in interface Array
      Returns:
      a trusted immutable view of this array (or a reference to this array if it is already trusted immutable).
      See Also:
    • mutableClone

      MutableObjectArray<E> mutableClone(MemoryModel memoryModel)
      Description copied from interface: Array
      Returns a mutable resizable copy of this array. This method is equivalent to the following code:
       memoryModel.newArray(thisArray).copy(thisArray);
       

      Please note: this method is a good choice for cloning little arrays (thousands, maybe millions elements). If you clone large arrays by this method, the user, in particular, has no ways to view the progress of copying or to interrupt copying. To clone large arrays, we recommend the following code:

       MutableArray clone = memoryModel.newArray(thisArray);
       Arrays.copy(someContext, clone, a);
       
      Specified by:
      mutableClone in interface Array
      Parameters:
      memoryModel - the memory model, used for allocation a new copy of this array.
      Returns:
      a mutable copy of this array.
      See Also:
    • updatableClone

      UpdatableObjectArray<E> updatableClone(MemoryModel memoryModel)
      Description copied from interface: Array
      Returns an unresizable updatable copy of this array. This method is equivalent to the following code:
       memoryModel.newUnresizableArray(thisArray).copy(thisArray);
       

      Please note: this method is a good choice for cloning little arrays (thousands, maybe millions elements). If you clone large arrays by this method, the user, in particular, has no ways to view the progress of copying or to interrupt copying. To clone large arrays, we recommend the following code:

       UpdatableArray clone = memoryModel.newUnresizableArray(thisArray);
       Arrays.copy(someContext, clone, a);
       
      Specified by:
      updatableClone in interface Array
      Parameters:
      memoryModel - the memory model, used for allocation a new copy of this array.
      Returns:
      an updatable copy of this array.
      See Also:
    • matrix

      default Matrix<? extends ObjectArray<E>> matrix(long... dim)
      Description copied from interface: Array
      Equivalent to matrix(thisArray, dim).
      Specified by:
      matrix in interface Array
      Parameters:
      dim - the matrix dimensions.
      Returns:
      new matrix backed by array with the given dimensions.