Package net.algart.arrays

Interface MutableArray

All Superinterfaces:
Array, ArrayExchanger, Stack, UpdatableArray
All Known Subinterfaces:
MutableBitArray, MutableByteArray, MutableCharArray, MutableDoubleArray, MutableFloatArray, MutableIntArray, MutableLongArray, MutableObjectArray<E>, MutableObjectInPlaceArray<E>, MutablePArray, MutablePFixedArray, MutablePFloatingArray, MutablePIntegerArray, MutablePNumberArray, MutableShortArray
public interface MutableArray extends Stack, UpdatableArray

AlgART one-dimensional array of any elements, full access (reading, writing, resizing).

If the elements of this array are primitive values (byte, short, etc.), the array must implement one of MutableBitArray, MutableCharArray, MutableByteArray, MutableShortArray, MutableIntArray, MutableLongArray, MutableFloatArray, MutableDoubleArray subinterfaces. In other case, this array must implement MutableObjectArray subinterface.

Resizable 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

    • length

      MutableArray length(long newLength)
      Changes the current number of elements in this array. If newLength is greater than current number of elements, all new elements will be always zero (0 for numbers, false for booleans, null or some "empty" objects for non-primitive elements).

      Notice: if newLength is less than current number of elements, then the unused elements (from newLength to (current length)-1) may be changed (for example, filled by zero) while calling this method. It is not important usually, because the array doesn't provide access to elements after (current length)-1. But if there are some "views" of this array, for examples, created by UpdatableArray.subArray(long, long) or UpdatableArray.asUnresizable() methods, you need to remember that reducing length of the source array can lead to changing last elements of such views.

      Parameters:
      newLength - the desired new number of elements.
      Returns:
      a reference to this array.
      Throws:
      TooLargeArrayException - if the specified length is too large for this type of arrays.
      IllegalArgumentException - if the specified length is negative.
      See Also:

    • clear

      default MutableArray clear()
      Equivalent to the call length(0).
      Specified by:
      clear in interface Stack
      Returns:
      a reference to this array.

    • ensureCapacity

      MutableArray ensureCapacity(long minCapacity)
      Increases the capacity of this instance, if necessary, to ensure that it can hold at least the given number of elements. After this call, the current capacity will be >=minCapacity.
      Parameters:
      minCapacity - the desired minimum capacity.
      Returns:
      a reference to this array.
      Throws:
      TooLargeArrayException - if the specified capacity is too large for this type of arrays.
      IllegalArgumentException - if the specified capacity is negative.

    • trim

      MutableArray trim()
      Trims the capacity of this array to be the array's current length. An application can use this operation to minimize the memory used by this instance. This method is the only way to reduce the capacity: all other methods can only increase the capacity of this instance.
      Returns:
      a reference to this array.

    • append

      MutableArray append(Array appendedArray)
      Appends the specified array to the end of this array. This method must work always if the element types of this and appended arrays (returned by Array.elementType()) are the same. IllegalArgumentException will be thrown.
      Parameters:
      appendedArray - appended array.
      Returns:
      a reference to this array.
      Throws:
      NullPointerException - if appendedArray argument is null.
      IllegalArgumentException - if the source and this element types do not match.
      TooLargeArrayException - if the resulting array length is too large for this type of arrays.
      See Also:

    • setData

      MutableArray setData(long arrayPos, Object srcArray, int srcArrayOffset, int count)
      Description copied from interface: UpdatableArray
      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).

      Specified by:
      setData in interface UpdatableArray
      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.
      See Also:

    • setData

      MutableArray setData(long arrayPos, Object srcArray)
      Description copied from interface: UpdatableArray
      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).

      Specified by:
      setData in interface UpdatableArray
      Parameters:
      arrayPos - starting position in this AlgART array.
      srcArray - the source Java array.
      Returns:
      a reference to this AlgART array.
      See Also:

    • copy

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

      You may use UpdatableArray.subArray(long, long) or UpdatableArray.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.

      Specified by:
      copy in interface UpdatableArray
      Parameters:
      src - the source array.
      Returns:
      a reference to this array.
      See Also:

    • swap

      MutableArray swap(UpdatableArray another)
      Description copied from interface: UpdatableArray
      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 UpdatableArray.subArray(long, long) or UpdatableArray.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.

      Specified by:
      swap in interface UpdatableArray
      Parameters:
      another - another array.
      Returns:
      a reference to this array.

    • asCopyOnNextWrite

      MutableArray 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 UpdatableArray.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
      Specified by:
      asCopyOnNextWrite in interface UpdatableArray
      Returns:
      a copy-on-next-write view of this array (or a reference to this array if it is immutable).
      See Also:

    • shallowClone

      MutableArray 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 length(long), ensureCapacity(long) or 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(), UpdatableArray.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
      Specified by:
      shallowClone in interface UpdatableArray
      Returns:
      a shallow copy of this object.
      See Also: