public interface MutablePFixedArray extends UpdatablePFixedArray, MutablePArray
Resizable AlgART array of any fixed-point numeric, character or bit primitive elements (byte, short, int, long, char or boolean).
Any class implementing this interface must implement one of
MutableBitArray, MutableCharArray,
MutableByteArray, MutableShortArray,
MutableIntArray, MutableLongArray
subinterfaces.
| Modifier and Type | Method and Description |
|---|---|
MutablePFixedArray |
append(Array appendedArray)
Appends the specified array to the end of this array.
|
MutablePFixedArray |
asCopyOnNextWrite()
Returns a copy-on-next-write view of this array.
|
MutablePFixedArray |
copy(Array src)
|
MutablePFixedArray |
ensureCapacity(long minCapacity)
Increases the capacity of this instance, if necessary,
to ensure that it can hold at least the given number of elements.
|
MutablePFixedArray |
length(long newLength)
Changes the current number of elements in this array.
|
MutablePFixedArray |
setData(long arrayPos,
java.lang.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. |
MutablePFixedArray |
setData(long arrayPos,
java.lang.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.
|
MutablePFixedArray |
shallowClone()
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.
|
MutablePFixedArray |
swap(UpdatableArray another)
|
MutablePFixedArray |
trim()
Trims the capacity of this array to be the array's current length.
|
asUnresizable, subArr, subArrayasImmutable, asTrustedImmutable, getInt, getLong, indexOf, lastIndexOf, maxPossibleValue, minPossibleValue, mutableClone, updatableClonefill, fill, fill, fill, setDouble, setInt, setLong, updatableTypebitsPerElement, getDouble, indexOf, isZeroFilled, lastIndexOf, maxPossibleValue, minPossibleValue, mutableType, typelength, popElement, pushElementcopy, copy, setElement, setNonNew, swap, swapbuffer, buffer, buffer, buffer, byteOrder, capacity, checkUnallowedMutation, elementType, equals, flushResources, flushResources, freeResources, freeResources, getData, getData, getElement, hashCode, isCopyOnNextWrite, isImmutable, isLazy, isNew, isNewReadOnlyView, isUnresizable, length, loadResources, newJavaArray, toStringMutablePFixedArray setData(long arrayPos, java.lang.Object srcArray, int srcArrayOffset, int count)
UpdatableArrayFor 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).
setData in interface MutableArraysetData in interface MutablePArraysetData in interface UpdatableArrayarrayPos - 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.DirectAccessible,
Array.getData(long, Object, int, int)MutablePFixedArray setData(long arrayPos, java.lang.Object srcArray)
UpdatableArraylength() - 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).
setData in interface MutableArraysetData in interface MutablePArraysetData in interface UpdatableArrayarrayPos - starting position in this AlgART array.srcArray - the source Java array.DirectAccessible,
UpdatableArray.setData(long, Object, int, int),
Array.getData(long, Object),
UpdatableBitArray.setBits(long, long[], long, long)MutablePFixedArray copy(Array src)
UpdatableArraylength(), 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.
copy in interface MutableArraycopy in interface MutablePArraycopy in interface UpdatableArraysrc - the source array.Arrays.copy(ArrayContext, UpdatableArray, Array)MutablePFixedArray swap(UpdatableArray another)
UpdatableArraylength(), 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.
swap in interface MutableArrayswap in interface MutablePArrayswap in interface UpdatableArrayanother - another array.MutablePFixedArray length(long newLength)
MutableArrayNotice: 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.
length in interface MutableArraylength in interface MutablePArraynewLength - the desired new number of elements.Arrays.lengthUnsigned(MutableArray, long)MutablePFixedArray ensureCapacity(long minCapacity)
MutableArrayensureCapacity in interface MutableArrayensureCapacity in interface MutablePArrayminCapacity - the desired minimum capacity.MutablePFixedArray trim()
MutableArraytrim in interface MutableArraytrim in interface MutablePArrayMutablePFixedArray append(Array appendedArray)
MutableArrayArray.elementType()) are the same.
IllegalArgumentException will be thrown.append in interface MutableArrayappend in interface MutablePArrayappendedArray - appended array.UpdatableArray.asUnresizable()MutablePFixedArray asCopyOnNextWrite()
ArrayUpdatableArray 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 a 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.
asCopyOnNextWrite in interface ArrayasCopyOnNextWrite in interface MutableArrayasCopyOnNextWrite in interface MutablePArrayasCopyOnNextWrite in interface UpdatableArrayArray.isCopyOnNextWrite(),
MemoryModel.newLazyCopy(Array),
MemoryModel.newUnresizableLazyCopy(Array)MutablePFixedArray shallowClone()
ArrayPlease 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 a 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.
shallowClone in interface ArrayshallowClone in interface MutableArrayshallowClone in interface MutablePArrayshallowClone in interface UpdatableArrayArray.length(),
Array.capacity(),
DirectAccessible.javaArrayOffset(),
Array.isCopyOnNextWrite()