Package net.algart.arrays

Interface MutablePArray

All Superinterfaces:
Array, ArrayExchanger, MutableArray, PArray, Stack, UpdatableArray, UpdatablePArray
All Known Subinterfaces:
MutableBitArray, MutableByteArray, MutableCharArray, MutableDoubleArray, MutableFloatArray, MutableIntArray, MutableLongArray, MutablePFixedArray, MutablePFloatingArray, MutablePIntegerArray, MutablePNumberArray, MutableShortArray
public interface MutablePArray extends UpdatablePArray, MutableArray

Resizable AlgART array of primitive elements (boolean, char, byte, short, int, long, float or double).

Any class implementing this interface must implement one of MutableBitArray, MutableCharArray, MutableByteArray, MutableShortArray, MutableIntArray, MutableLongArray, MutableFloatArray, MutableDoubleArray subinterfaces.

Author:
Daniel Alievsky

  • Method Details

    • popDouble

      double popDouble()
      Removes the last element at this array and returns its value, converted to double: (double)(value&0xFF) for byte value, (double)(value&0xFFFF) for short value, (double)value for int, long, float, double, char values, or value?1.0:0.0 for boolean values. Please note that this method returns unsigned values for byte and short arrays. Returned value contains full information stored in the element, excepting the case of very large long elements. If this array is empty, the method throws EmptyStackException.

      Depending on the specific subinterface implemented by the object, this method is equivalent to one of the following expressions:

      Returns:
      the last element at array (it is removed from the array).
      Throws:
      EmptyStackException - if this array is empty.

    • addDouble

      void addDouble(double value)
      Appends value element to the end of this array with conversion from double, as (xxx)value for numeric element type xxx (byte, short, int, long, float, double or char), or as value!=0.0 for boolean element type.

      The same action may be performed by the following code:

       array.length(array.length()+1);
 array.setDouble(array.length()-1, value);
      Parameters:
      value - to be added to the top of this array.
      Throws:
      TooLargeArrayException - if the resulting stack length is too large for this type of array.

    • addLong

      void addLong(long value)
      Appends value element to the end of this array with conversion from long, as (xxx)value for numeric element type xxx (byte, short, int, long, float, double or char), or as value!=0 for boolean element type.

      The same action may be performed by the following code:

       array.length(array.length()+1);
 array.setLong(array.length()-1, value);
      Parameters:
      value - to be added to the top of this array.
      Throws:
      TooLargeArrayException - if the resulting stack length is too large for this type of array.

    • addInt

      void addInt(int value)
      Appends value element to the end of this array with conversion from int, as (xxx)value for numeric element type xxx (byte, short, int, long, float, double or char), or as value!=0 for boolean element type.

      This method is equivalent to both addLong(index, (long) value) and addDouble((double) value), but can work little faster.

      Parameters:
      value - to be added to the top of this array.
      Throws:
      TooLargeArrayException - if the resulting stack length is too large for this type of array.

    • setData

      MutablePArray 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 MutableArray
      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

      MutablePArray 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 MutableArray
      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

      MutablePArray 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 MutableArray
      Specified by:
      copy in interface UpdatableArray
      Parameters:
      src - the source array.
      Returns:
      a reference to this array.
      See Also:

    • swap

      MutablePArray 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 MutableArray
      Specified by:
      swap in interface UpdatableArray
      Parameters:
      another - another array.
      Returns:
      a reference to this array.

    • length

      MutablePArray length(long newLength)
      Description copied from interface: MutableArray
      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.

      Specified by:
      length in interface MutableArray
      Parameters:
      newLength - the desired new number of elements.
      Returns:
      a reference to this array.
      See Also:

    • ensureCapacity

      MutablePArray ensureCapacity(long minCapacity)
      Description copied from interface: MutableArray
      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.
      Specified by:
      ensureCapacity in interface MutableArray
      Parameters:
      minCapacity - the desired minimum capacity.
      Returns:
      a reference to this array.

    • trim

      MutablePArray trim()
      Description copied from interface: MutableArray
      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.
      Specified by:
      trim in interface MutableArray
      Returns:
      a reference to this array.

    • append

      MutablePArray append(Array appendedArray)
      Description copied from interface: MutableArray
      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.
      Specified by:
      append in interface MutableArray
      Parameters:
      appendedArray - appended array.
      Returns:
      a reference to this array.
      See Also:

    • asCopyOnNextWrite

      MutablePArray 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 MutableArray
      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

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