Package net.algart.arrays

Interface UpdatableArray

All Superinterfaces:
Array, ArrayExchanger
All Known Subinterfaces:
MutableArray, MutableBitArray, MutableByteArray, MutableCharArray, MutableDoubleArray, MutableFloatArray, MutableIntArray, MutableLongArray, MutableObjectArray<E>, MutableObjectInPlaceArray<E>, MutablePArray, MutablePFixedArray, MutablePFloatingArray, MutablePIntegerArray, MutablePNumberArray, MutableShortArray, UpdatableBitArray, UpdatableByteArray, UpdatableCharArray, UpdatableDoubleArray, UpdatableFloatArray, UpdatableIntArray, UpdatableLongArray, UpdatableObjectArray<E>, UpdatableObjectInPlaceArray<E>, UpdatablePArray, UpdatablePFixedArray, UpdatablePFloatingArray, UpdatablePIntegerArray, UpdatablePNumberArray, UpdatableShortArray
All Known Implementing Classes:
AbstractUpdatableBitArray, AbstractUpdatableByteArray, AbstractUpdatableCharArray, AbstractUpdatableDoubleArray, AbstractUpdatableFloatArray, AbstractUpdatableIntArray, AbstractUpdatableLongArray, AbstractUpdatableObjectArray, AbstractUpdatableShortArray
public interface UpdatableArray extends Array, ArrayExchanger

AlgART one-dimensional array of any elements, read/write access, no resizing.

It is a superinterface for MutableArray. Unlike MutableArray, the methods of this interface does not allow to change number of elements. The instances of this interface are usually returned by asUnresizable() method.

If elements of this array are primitive values (byte, short, etc.), the array must implement one of UpdatableBitArray, UpdatableCharArray, UpdatableByteArray, UpdatableShortArray, UpdatableIntArray, UpdatableLongArray, UpdatableFloatArray, UpdatableDoubleArray subinterfaces.

In other case, this array must implement UpdatableObjectArray subinterface.

Updatable arrays, implementing this interface, are not thread-safe, but are thread-compatible and can be synchronized manually if multithread access is necessary. Please see more details in the package description.

Author:
Daniel Alievsky
See Also:

  • Method Details

    • setElement

      void setElement(long index, Object value)
      Sets the element #index to specified value. The new value is first automatically unwrapped if this array contains elements of primitive types.

      It is a low-level method. For arrays of primitive elements, implementing one of corresponding interfaces UpdatableBitArray, UpdatableCharArray, UpdatableByteArray, UpdatableShortArray, UpdatableIntArray, UpdatableLongArray, UpdatableFloatArray, UpdatableDoubleArray, we recommend to use more efficient equivalent method of that interfaces: UpdatableBitArray.setBit(long, boolean), UpdatableCharArray.setChar(long, char), UpdatableByteArray.setByte(long, byte), UpdatableShortArray.setShort(long, short), UpdatableIntArray.setInt(long, int), UpdatableLongArray.setLong(long, long), UpdatableFloatArray.setFloat(long, float), UpdatableDoubleArray.setDouble(long, double). For other arrays, implementing ObjectArray, we recommend to use UpdatableObjectArray.set(long, Object).

      For arrays of primitive elements, this method throws NullPointerException if value == null. For arrays of non-primitive elements, this method does not throw NullPointerException in this case, but may set the element to some default value, if null elements are not supported by the memory model (as in a case of CombinedMemoryModel).

      Parameters:
      index - index of element to replace.
      value - element to be stored at the specified position.
      Throws:
      IndexOutOfBoundsException - if index is out of range 0..length()-1.
      NullPointerException - if value == null and it is an array of primitive elements.
      ClassCastException - if it is an array of primitive elements and value is not a corresponding wrapped class (Boolean, Integer, etc.)
      ArrayStoreException - if it is an array of non-primitive elements and value is not an instance of Array.elementType() class.

    • setData

      UpdatableArray setData(long arrayPos, Object srcArray, int srcArrayOffset, int count)
      Copies count elements from the specified Java array of corresponding type, starting from srcArrayOffset index, into this array, starting from arrayPos index.

      For arrays of non-primitive elements, if some elements of Java array are null, this method does not throw NullPointerException, but may set the corresponding array elements to some default value, if null elements are not supported by the memory model (as in a case of CombinedMemoryModel).

      Note: if IndexOutOfBoundsException occurs due to attempt to read data outside the passed Java array, this AlgART array can be partially filled. In other words, this method can be non-atomic regarding this failure. All other possible exceptions are checked in the very beginning of this method before any other actions (the standard way for checking exceptions).

      Parameters:
      arrayPos - starting position in this AlgART array.
      srcArray - the source Java array.
      srcArrayOffset - starting position in the source Java array.
      count - the number of elements to be copied.
      Returns:
      a reference to this AlgART array.
      Throws:
      NullPointerException - if srcArray argument is null.
      IllegalArgumentException - if srcArray argument is not an array.
      IndexOutOfBoundsException - if copying would cause access of data outside this array or source Java array.
      ArrayStoreException - if destArray element type mismatches with this array elementType().
      ClassCastException - if destArray element type mismatches with this array elementType() (both this and ArrayStoreException are possible, depending on implementation).
      See Also:

    • setData

      UpdatableArray setData(long arrayPos, Object srcArray)
      Copies min(this.length() - arrayPos, srcArray.length}) elements from the specified Java array of corresponding type, starting from 0 index, into this array, starting from arrayPos index.

      For arrays of non-primitive elements, if some elements of Java array are null, this method does not throw NullPointerException, but may set the corresponding array elements to some default value, if null elements are not supported by the memory model (as in a case of CombinedMemoryModel).

      Parameters:
      arrayPos - starting position in this AlgART array.
      srcArray - the source Java array.
      Returns:
      a reference to this AlgART array.
      Throws:
      NullPointerException - if srcArray argument is null.
      IllegalArgumentException - if srcArray argument is not an array.
      ArrayStoreException - if destArray element type mismatches with this array Array.elementType().
      ClassCastException - if destArray element type mismatches with this array Array.elementType() (both this and ArrayStoreException are possible, depending on implementation).
      See Also:

    • copy

      void copy(long destIndex, long srcIndex)
      Copies element #srcIndex to position #destIndex inside this array.
      Parameters:
      destIndex - index of element to replace.
      srcIndex - index of element to be copied.
      Throws:
      IndexOutOfBoundsException - if one of indexes is out of range 0..length()-1.

    • copy

      void copy(long destIndex, long srcIndex, long count)
      Copies count elements, starting from srcIndex index, to the same array, starting from destIndex index.

      This method works correctly even if the copied areas overlap, i.e. if Math.abs(destIndex - srcIndex) < count. More precisely, in this case the copying is performed as if the elements at positions srcIndex..srcIndex+count-1 were first copied to a temporary array with count elements and then the contents of the temporary array were copied into positions destIndex..destIndex+count-1 of this array.

      Parameters:
      destIndex - starting index of element to replace.
      srcIndex - starting index of element to be copied.
      count - the number of elements to be copied.
      Throws:
      IndexOutOfBoundsException - if one of indexes is out of range 0..length()-1.

    • swap

      void swap(long firstIndex, long secondIndex)
      Swaps elements at positions #firstIndex and #secondIndex inside this array.
      Specified by:
      swap in interface ArrayExchanger
      Parameters:
      firstIndex - first index of element to exchange.
      secondIndex - second index of element to exchange.
      Throws:
      IndexOutOfBoundsException - if one of indexes is out of range 0..length()-1.

    • swap

      void swap(long firstIndex, long secondIndex, long count)
      Swaps count elements, starting from firstIndex index, with count elements in the same array, starting from secondIndex index.

      Some elements may be swapped incorrectly if the swapped areas overlap, i.e. if Math.abs(firstIndex - secondIndex) < count.

      Parameters:
      firstIndex - starting first index of element to exchange.
      secondIndex - starting second index of element to exchange.
      count - the number of elements to be exchanged.
      Throws:
      IndexOutOfBoundsException - if one of indexes is out of range 0..length()-1.

    • copy

      UpdatableArray copy(Array src)
      Copies min(this.length(), src.length()) elements of src array, starting from index 0, to this array, starting from index 0.

      You may use subArray(long, long) or subArr(long, long) methods to copy any portion of one array to any position of another array, for example:

       destArray.subArr(destPos, count).copy(srcArray.subArr(srcPos, count));

      Some elements may be copied incorrectly if this array and src are views of the same data and the swapped data areas overlap (in the example above, Math.abs(destPos - srcPos) < count). However, for arrays, created by SimpleMemoryModel, this method work correctly always, even for overlapping areas. For any arrays, if the copied areas of the underlying data are the same (for example, if src if some view of this array generated by Arrays.asFuncArray, but not Arrays.asShifted method), this method work correctly: any elements will be read before they will be updated.

      This method works only if the element types of this and src arrays (returned by Array.elementType()) are the same, or (for non-primitive elements) if element type of this array is a superclass of the source element type.

      For non-primitive element type (ObjectArray, UpdatableObjectArray, MutableObjectArray subinterfaces), this method may copy only references to elements, but also may copy the content of elements: it depends on implementation.

      Please note: this method is a good choice for copying little arrays (thousands, maybe hundreds of thousands elements). If you copy large arrays by this method, the user, in particular, has no ways to view the progress of copying or to interrupt copying. In most situations, we recommend more "intellectual" method Arrays.copy(ArrayContext, UpdatableArray, Array) for copying large arrays.

      Parameters:
      src - the source array.
      Returns:
      a reference to this array.
      Throws:
      NullPointerException - if src argument is null.
      IllegalArgumentException - if the source and this element types do not match.
      See Also:

    • swap

      UpdatableArray swap(UpdatableArray another)
      Swaps min(this.length(), src.length()) elements of another array, starting from index 0, and the same number of elements of this array, starting from index 0.

      You may use subArray(long, long) or subArr(long, long) methods to swap any portions of two array, for example:

       array1.subArr(pos1, count).swap(array2.subArr(pos2, count));

      Some elements may be swapped incorrectly if this array and another is the same array, or are views of the same data, and the swapped areas overlap (in the example above, Math.abs(pos1 - pos2) < count).

      This method must work always if the element types of this and src arrays (returned by Array.elementType()) are the same.

      For non-primitive element type (ObjectArray, UpdatableObjectArray, MutableObjectArray subinterfaces), this method may swap only references to elements, but also may swap the content of elements: it depends on implementation.

      Please note: this method is a good choice for swapping little arrays (thousands, maybe hundreds of thousands elementthousands elements). If you swap large arrays by this method, the user, in particular, has no ways to view the progress of copying or to interrupt copying. To swap large arrays, you can split them to little regions and swap the regions in a loop by this method, with calling ArrayContext methods to allow interruption and showing progress.

      Parameters:
      another - another array.
      Returns:
      a reference to this array.
      Throws:
      NullPointerException - if another argument is null.
      IllegalArgumentException - if another and this element types do not match.

    • asUnresizable

      UpdatableArray asUnresizable()
      Returns an unresizable view of this array. If this array is not resizable already, returns a reference to this object. Query operations on the returned array "read through" and "write through" to this array.

      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 shallowClone() method. If modifications of this or returned 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.

      Resizable arrays, created by this package, implement full MutableArray interface, but unresizable ones implement only its UpdatableArray superinterface.

      Returns:
      an unresizable view of this array.
      See Also:

    • setNonNew

      void setNonNew()
      Clears the "new status" for this array instance. After this call, the Array.isNew() method will return false for this instance. If the internal storage of this array will be reallocated in future, this instance may become "new" again.

      The access to the "new status", provided by this and Array.isNew() method, is always internally synchronized. So, clearing "new status" by this method will be immediately visible in all threads, using this instance.

    • subArray

      UpdatableArray subArray(long fromIndex, long toIndex)
      Description copied from interface: Array
      Returns a view of the portion of this array between fromIndex, inclusive, and toIndex, exclusive.
      • If fromIndex and toIndex are equal, the returned array is empty.
      • The returned array is backed by this array, so — if this array is not immutable — any changes of the elements of the returned array are reflected in this array, and vice-versa.
      • The capacity of returned array (returned by Array.capacity() method) will be equal to the its length (returned by Array.length(), that is toIndex-fromIndex.
      • The type of elements of the returned array is the same as the type of elements of this array.
      • The returned array is immutable, trusted immutable or copy-on-next-write, if, and only if, this array is immutable, trusted immutable or copy-on-next-write correspondingly.
      • If (and only if) this array implements UpdatableArray interface, then the returned array also implements it. If (and only if) this array implements DirectAccessible interface, then the returned array also implements it. The returned array never implements MutableArray interface; it is always unresizable.

      Like List.subList method, this method eliminates the need for explicit range operations. For example, you may use Arrays.sort(UpdatableArray, ArrayComparator) method for sorting a fragment of the array.

      Unlike List.subList, the semantics of the array returned by this method is well-defined in any case, even in case of resizing of the source array. Namely, if the internal storage of this or returned array is reallocated, then the returned array will cease 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. Also, if the length of this array will be reduced, it can lead to clearing some elements in returned array: see comments to MutableArray.length(long) method.

      Specified by:
      subArray in interface Array
      Parameters:
      fromIndex - low endpoint (inclusive) of the subarray.
      toIndex - high endpoint (exclusive) of the subarray.
      Returns:
      a view of the specified range within this array.
      See Also:

    • subArr

      UpdatableArray subArr(long position, long count)
      Description copied from interface: Array
      Equivalent to subArray(position, position + count). The only possible difference is other exception messages. If position+count>Long.MAX_VALUE (overflow), an exception message is allowed to be not fully correct (maximal speed is more important than absolutely correct exception messages for such exotic situations).
      Specified by:
      subArr in interface Array
      Parameters:
      position - start position (inclusive) of the subarray.
      count - number of elements in the subarray.
      Returns:
      a view of the specified range within this array.
      See Also:

    • asCopyOnNextWrite

      UpdatableArray asCopyOnNextWrite()
      Description copied from interface: Array
      Returns a copy-on-next-write view of this array. If this array is immutable (and only in this case), returns a reference to this object. If (and only if) this array implements UpdatableArray interface, then the returned array also implements it. If (and only if) this array implements MutableArray interface, then the returned array also implements it.

      Copy-on-next-write array is an array with the following special feature: the next attempt (but not further!) to modify this array, or any other access that can lead to its modification (like DirectAccessible.javaArray() method), will lead to reallocation of the underlying storage, used for array elements, before performing the operation. In other words, you have a guarantee: if this array is a view of some another array or data (for example, a subarray or a view of Java array, that there are no ways to change that data via accessing the returned array. Any changes, it they will occur, will be performed with the newly allocated storage only.

      Please be careful: it you will want to change arrays created by this method, the result may be unexpected! For example, an attempt to copy other arrays into copy-on-next-write array by some methods like Arrays.copy(ArrayContext, UpdatableArray, Array) will probable do nothing. The reason is working with the array via its subarrays — for example, Arrays.copy method splits the source and target arrays into subarrays and copies these subarrays. (Usual copy(Array) method and other mutation methods of the resulting array will work normally.) The main goal of copy-on-next-write arrays is protection againts unwanted changing an original array; it is supposed that the client, in normal situation, will only read such arrays and will not try to change them.

      There are no guarantees that the returned array will be a view of this one, even immediately after creation. Some implementations of updatable arrays may just return the full (deep) copy of this object, alike Array.mutableClone(MemoryModel) method, and in this case TooLargeArrayException is possible. All implementations from this package, excepting AbstractUpdatableXxxArray classes, returns a view; but in AbstractUpdatableXxxArray classes this method is equivalent to updatableClone(Arrays.SMM).

      Please note that copy-on-next-write arrays are not traditional copy-on-write objects like CopyOnWriteArrayList! In particular, copy-on-next-write arrays are not thread-safe.

      The main purpose of using copy-on-next-write arrays is more efficient alternative to cloning and creating quite immutable views, when we need to be sure that original data will not be corrupted. Please see the package description to learn more about possible usage of this technique.

      Specified by:
      asCopyOnNextWrite in interface Array
      Returns:
      a copy-on-next-write view of this array (or a reference to this array if it is immutable).
      See Also:

    • shallowClone

      UpdatableArray shallowClone()
      Description copied from interface: Array
      Returns a "shallow" clone of this object: another array consisting of the same elements, but with independent length, start offset, capacity, copy-on-next-write and possible other information about any array characteristics besides its elements. In other words, any changes in the elements of the returned array are usually reflected in this array, and vice-versa; but changes of any other characteristics of the original or returned array, including the length, capacity, etc., will not be reflected in another array.

      Please note: this method never returns a reference to this object, even if this array is immutable! Moreover, the returned object does not store any references to this instance in any internal fields. It can be important while using weak references and reference queues: this object and its shallow copy are deallocated by the garbage collector separately.

      There are no guarantees that the returned array will share the elements with this one. Some implementations may return the full (deep) copy of this object, alike Array.updatableClone(MemoryModel) or Array.mutableClone(MemoryModel) methods. All implementations from this package returns a shallow (non-deep) copy.

      If modifications of this or returned 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.

      The values of Array.length(), Array.capacity(), DirectAccessible.javaArrayOffset(), Array.isCopyOnNextWrite() in the result will be the same as in this array. The returned instance implements the same set of interfaces as this array.

      This method is an analog of the standard Java NIO ByteBuffer.duplicate() method. However, unlike ByteBuffer.duplicate(), this method is necessary very rarely. Usually, you need another forms of array views: Array.asImmutable(), asUnresizable(), etc. The most often usage of this method is finalization via Finalizer class: see example in comments to Array.checkUnallowedMutation() method. Also this method can be useful if you need to pass an array with the same content into some another class, but must be sure that further resizing of the source array will not affect to correct work of that class.

      Specified by:
      shallowClone in interface Array
      Returns:
      a shallow copy of this object.
      See Also:

    • matrix

      default Matrix<? extends UpdatableArray> 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.