Interface UpdatableBitArray

All Superinterfaces:
Array, ArrayExchanger, BitArray, PArray, PFixedArray, UpdatableArray, UpdatablePArray, UpdatablePFixedArray
All Known Subinterfaces:
MutableBitArray
All Known Implementing Classes:
AbstractUpdatableBitArray

public interface UpdatableBitArray extends BitArray, UpdatablePFixedArray

AlgART array of boolean values, read/write access, no resizing.

Author:
Daniel Alievsky
  • Method Details

    • setBit

      void setBit(long index, boolean value)
      Sets the element #index to specified value.
      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.
    • fill

      UpdatableBitArray fill(boolean value)
      Fills all elements of this array by the specified value. Equivalent to fill(0, thisArray.length(), value).
      Parameters:
      value - the value to be stored in all elements of the array.
      Returns:
      a reference to this array.
      See Also:
    • fill

      UpdatableBitArray fill(long position, long count, boolean value)
      Fills count elements of this array, starting from position index, by the specified value. Equivalent to the following loop:
       for (long k = 0; k < count; k++) {
           setBit(position + k, value);
       }
      but works much faster and checks indexes (and throws possible IndexOutOfBoundsException) in the very beginning.
      Parameters:
      position - start index (inclusive) to be filled.
      count - number of filled elements.
      value - the value to be stored in the elements of the array.
      Returns:
      a reference to this array.
      Throws:
      IndexOutOfBoundsException - for illegal position and count (position < 0 || count < 0 || position + count > length()).
      See Also:
    • subArray

      UpdatableBitArray 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
      Specified by:
      subArray in interface UpdatableArray
      Specified by:
      subArray in interface UpdatablePArray
      Specified by:
      subArray in interface UpdatablePFixedArray
      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

      UpdatableBitArray 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
      Specified by:
      subArr in interface UpdatableArray
      Specified by:
      subArr in interface UpdatablePArray
      Specified by:
      subArr in interface UpdatablePFixedArray
      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:
    • asUnresizable

      UpdatableBitArray asUnresizable()
      Description copied from interface: UpdatableArray
      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 UpdatableArray.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.

      Specified by:
      asUnresizable in interface UpdatableArray
      Specified by:
      asUnresizable in interface UpdatablePArray
      Specified by:
      asUnresizable in interface UpdatablePFixedArray
      Returns:
      an unresizable view of this array.
      See Also:
    • matrix

      default Matrix<UpdatableBitArray> matrix(long... dim)
      Description copied from interface: Array
      Equivalent to matrix(thisArray, dim).
      Specified by:
      matrix in interface Array
      Specified by:
      matrix in interface BitArray
      Specified by:
      matrix in interface PArray
      Specified by:
      matrix in interface PFixedArray
      Specified by:
      matrix in interface UpdatableArray
      Specified by:
      matrix in interface UpdatablePArray
      Specified by:
      matrix in interface UpdatablePFixedArray
      Parameters:
      dim - the matrix dimensions.
      Returns:
      new matrix backed by array with the given dimensions.
    • setBit

      void setBit(long index)
      Sets the bit #index to 1 (true).
      Parameters:
      index - index of element to replace.
      Throws:
      IndexOutOfBoundsException - if index out of range 0..length()-1.
    • clearBit

      void clearBit(long index)
      Clears the bit #index to 0 (false).
      Parameters:
      index - index of element to replace.
      Throws:
      IndexOutOfBoundsException - if index out of range 0..length()-1.
    • setBits

      UpdatableBitArray setBits(long arrayPos, long[] srcArray, long srcArrayOffset, long count)
      Copies count bits from the specified packed bit array, starting from srcArrayOffset index, into this array, starting from arrayPos index.

      This method is equivalent to the following loop:

       for (long k = 0; k < count; k++)
           thisArray.setBit(arrayPos + k, PackedBitArrays.getBit(srcArray, srcArrayOffset + k));
       

      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 packed bit array.
      srcArrayOffset - starting position in the source packed bit array.
      count - the number of bits to be copied.
      Returns:
      a reference to this AlgART array.
      Throws:
      NullPointerException - if srcArray argument is null.
      IndexOutOfBoundsException - if copying would cause access of data outside this array or source Java array.
      See Also: