Package com.illumon.iris.db.v2.utils.rsp.container

Class Container

java.lang.Object
com.illumon.iris.db.v2.utils.rsp.container.Container
Direct Known Subclasses:
ArrayContainer, BitmapContainer, ImmutableContainer, RunContainer
public abstract class Container extends Object
Base container class.

  • Field Details

    • DEBUG

      public static final boolean DEBUG

    • MAX_RANGE

      public static final int MAX_RANGE
      The maximum possible cardinality of a container, as an int. Also the maximum possible exclusive end for a range that can be stored in a container.
      See Also:

    • MAX_VALUE

      public static final int MAX_VALUE
      The maxumum possible value that can be stored in a container, as an int.
      See Also:

    • threadLocalBuf

      protected static final ThreadLocal<short[]> threadLocalBuf

    • ContainerNames

      public static final String[] ContainerNames
      Name of the various possible containers

  • Constructor Details

    • Container

      public Container()

  • Method Details

    • ifDebugValidate

      public final void ifDebugValidate()

    • check

      public Container check()

    • validate

      public abstract void validate()

    • singleton

      public static Container singleton(short v)

    • singleRange

      public static Container singleRange(int start, int end)

    • full

      public static Container full()

    • rangeOfOnes

      public static Container rangeOfOnes(int start, int end)
      Create a container initialized with a range of consecutive values
      Parameters:
      start - first index
      end - last index (range is exclusive)
      Returns:
      a new container initialized with the specified values

    • twoValues

      public static Container twoValues(short v1, short v2)

    • twoRanges

      public static Container twoRanges(int start1, int end1, int start2, int end2)
      Returns a new Container containing the two provided ranges. The ranges provided should be nonempty, disjoint and provided in appearance order, ie, start2 > start1.
      Parameters:
      start1 - start of first range, inclusive.
      end1 - end of first range, exclusive.
      start2 - start of second range, inclusive.
      end2 - end of second range, exclusive.
      Returns:
      A new Container containing the provided ranges.

    • empty

      public static Container empty()
      Returns:
      An empty container.

    • add

      public abstract Container add(int begin, int end)
      Return a new container with all shorts in [begin,end) added using an unsigned interpretation.
      Parameters:
      begin - start of range (inclusive)
      end - end of range (exclusive)
      Returns:
      the new container

    • iset

      public abstract Container iset(short x)
      Insert a short to the container. May generate a new container.
      Parameters:
      x - short to be added
      Returns:
      the resulting container

    • set

      public abstract Container set(short x)
      Return a new container with the short given as parameter added.
      Parameters:
      x - a short to be added
      Returns:
      a new container with x added

    • and

      public abstract Container and(ArrayContainer x)
      Computes the bitwise AND of this container with another (intersection). This container as well as the provided container are left unaffected.
      Parameters:
      x - Another container
      Returns:
      aggregated container

    • and

      public abstract Container and(BitmapContainer x)
      Computes the bitwise AND of this container with another (intersection). This container as well as the provided container are left unaffected.
      Parameters:
      x - Another container
      Returns:
      aggregated container

    • and

      public abstract Container and(RunContainer x)
      Computes the bitwise AND of this container with another (intersection). This container as well as the provided container are left unaffected.
      Parameters:
      x - Another container
      Returns:
      aggregated container

    • and

      public Container and(Container x)
      Computes the bitwise AND of this container with another (intersection). This container as well as the provided container are left unaffected.
      Parameters:
      x - Another container
      Returns:
      aggregated container

    • andRange

      public abstract Container andRange(int start, int end)
      Calculate the intersection of this container and a range, in a new container. The existing container is not modified.
      Parameters:
      start - start of range
      end - end of range, exclusive.
      Returns:
      a new Container containing the intersction of this container and the given range.

    • iandRange

      public abstract Container iandRange(int start, int end)
      Calculate the intersection of this container and a range; may overwrite the existing container or return a new one.
      Parameters:
      start - start of range
      end - end of range, exclusive.
      Returns:
      a Container containing the intersction of this container and the given range.

    • andNot

      public abstract Container andNot(ArrayContainer x)
      Computes the bitwise ANDNOT of this container with another (difference). This container as well as the provided container are left unaffected.
      Parameters:
      x - Another container
      Returns:
      aggregated container

    • andNot

      public abstract Container andNot(BitmapContainer x)
      Computes the bitwise ANDNOT of this container with another (difference). This container as well as the provided container are left unaffected.
      Parameters:
      x - Another container
      Returns:
      aggregated container

    • andNot

      public abstract Container andNot(RunContainer x)
      Computes the bitwise ANDNOT of this container with another (difference). This container as well as the provided container are left unaffected.
      Parameters:
      x - Another container
      Returns:
      aggregated container

    • andNot

      public Container andNot(Container x)
      Computes the bitwise ANDNOT of this container with another (difference). This container as well as the provided container are left unaffected.
      Parameters:
      x - Another container
      Returns:
      aggregated container

    • deepCopy

      public abstract Container deepCopy()
      Get a full deep copy of the container in a new container object.
      Returns:
      A copy of the container as a new object.

    • cowRef

      public abstract Container cowRef()
      Get a shared, copy-on-write copy of an existing container. Mutations on the returned container will always return a copy and leave the original container unchanged.

      This operation allows for cheap read-only references to the same values, at the cost of an additional copy for any first mutation.

      Returns:
      A copy-on-write reference to the container.

    • isEmpty

      public abstract boolean isEmpty()
      Checks whether the container is empty or not.
      Returns:
      true if the container is empty.

    • isAllOnes

      public abstract boolean isAllOnes()
      Checks whether the container spans the full 2^16 range (ie, contains every short value) This is an O(1) operation in all container types (some do not cache cardinality).
      Returns:
      true if the container does not miss any single short value.

    • isSingleElement

      public boolean isSingleElement()
      Checks whether the container has exactly one element (meaningful since cardinality may not be cached in some Container types, eg, Run).
      Returns:
      true if the container contains exactly one element, false otherwise.

    • isFull

      @Deprecated public final boolean isFull()
      Deprecated.
      Checks whether the container spans the full 2^16 range (ie, contains every short value) This is an O(1) operation in all container types (some do not cache cardinality).
      Returns:
      true if the container does not miss any single short value. This method is deprecated, prefer isAllOnes instead.

    • contains

      public abstract boolean contains(short x)
      Checks whether the contain contains the provided value
      Parameters:
      x - value to check
      Returns:
      whether the value is in the container

    • contains

      public abstract boolean contains(int rangeStart, int rangeEnd)
      Checks whether the container contains the entire range
      Parameters:
      rangeStart - the inclusive lower bound of the range
      rangeEnd - the exclusive upper bound of the range
      Returns:
      true if the container contains the range

    • contains

      protected abstract boolean contains(ArrayContainer arrayContainer)

    • contains

      protected abstract boolean contains(BitmapContainer bitmapContainer)

    • contains

      protected abstract boolean contains(RunContainer runContainer)

    • contains

      public boolean contains(Container subset)
      Checks whether the container is a subset of this container or not
      Parameters:
      subset - the container to be tested
      Returns:
      true if the parameter is a subset of this container

    • iflip

      public abstract Container iflip(short x)
      Add a short to the container if it is not present, otherwise remove it. May generate a new container.
      Parameters:
      x - short to be added
      Returns:
      the new container

    • getCardinality

      public abstract int getCardinality()
      Computes the distinct number of short values in the container. Can be expected to run in constant time.
      Returns:
      the cardinality

    • getContainerName

      public String getContainerName()
      Get the name of this container.
      Returns:
      name of the container

    • forEach

      public abstract boolean forEach(ShortConsumer sc)
      Iterate through the values of this container in order and pass them along to the ShortConsumer.
      Parameters:
      sc - a shortConsumer
      Returns:
      false if the consumer returned false at some point, true otherwise.

    • forEach

      public abstract boolean forEach(int rankOffset, ShortConsumer sc)
      Like forEach, but skipping the first rankOffset elements.
      Parameters:
      rankOffset - the position (rank) offset of the element where to start
      sc - a ShortConsumer
      Returns:
      false if the consumer returned false at some point, true otherwise.

    • forEachRange

      public abstract boolean forEachRange(int rankOffset, ShortRangeConsumer sc)

    • getReverseShortIterator

      public abstract ShortAdvanceIterator getReverseShortIterator()
      Iterator to visit the short values in the container in descending order.
      Returns:
      iterator

    • getShortIterator

      public abstract ShortIterator getShortIterator()
      Iterator to visit the short values in the container in ascending order.
      Returns:
      iterator

    • getShortBatchIterator

      public abstract ContainerShortBatchIterator getShortBatchIterator(int skipFromStartCount)
      Gets an iterator to visit the contents of the container in batches of short values
      Parameters:
      skipFromStartCount - number of elements to skip from the start of the container.
      Returns:
      iterator

    • getShortRangeIterator

      public abstract SearchRangeIterator getShortRangeIterator(int skipFromStartCount)
      Iterator to visit the short values in container in [start, end) ranges, in increasing order of start values.
      Returns:
      iterator

    • iadd

      public abstract Container iadd(int begin, int end)
      Add all shorts in [begin,end) using an unsigned interpretation. May generate a new container.
      Parameters:
      begin - start of range (inclusive)
      end - end of range (exclusive)
      Returns:
      the new container

    • iappend

      public abstract Container iappend(int begin, int end)
      Add all shorts in [begin,end) using an unsigned interpretation. May generate a new container. The beginning of the range should be strictly greater than the last value already present in the container, if there is one.
      Parameters:
      begin - start of range (inclusive)
      end - end of range (exclusive)
      Returns:
      the new container

    • iand

      public abstract Container iand(ArrayContainer x)
      Computes the in-place bitwise AND of this container with another (intersection). The current container is generally modified, whereas the provided container (x) is unaffected. May generate a new container.
      Parameters:
      x - Another container
      Returns:
      aggregated container

    • iand

      public abstract Container iand(BitmapContainer x)
      Computes the in-place bitwise AND of this container with another (intersection). The current container is generally modified, whereas the provided container (x) is unaffected. May generate a new container.
      Parameters:
      x - Another container
      Returns:
      aggregated container

    • iand

      public abstract Container iand(RunContainer x)
      Computes the in-place bitwise AND of this container with another (intersection). The current container is generally modified, whereas the provided container (x) is unaffected. May generate a new container.
      Parameters:
      x - Another container
      Returns:
      aggregated container

    • iand

      public Container iand(Container x)
      Computes the in-place bitwise AND of this container with another (intersection). The current container is generally modified, whereas the provided container (x) is unaffected. May generate a new container.
      Parameters:
      x - Another container
      Returns:
      aggregated container

    • iandNot

      public abstract Container iandNot(ArrayContainer x)
      Computes the in-place bitwise ANDNOT of this container with another (difference). The current container is generally modified, whereas the provided container (x) is unaffected. May generate a new container.
      Parameters:
      x - Another container
      Returns:
      aggregated container

    • iandNot

      public abstract Container iandNot(BitmapContainer x)
      Computes the in-place bitwise ANDNOT of this container with another (difference). The current container is generally modified, whereas the provided container (x) is unaffected. May generate a new container.
      Parameters:
      x - Another container
      Returns:
      aggregated container

    • iandNot

      public abstract Container iandNot(RunContainer x)
      Computes the in-place bitwise ANDNOT of this container with another (difference). The current container is generally modified, whereas the provided container (x) is unaffected. May generate a new container.
      Parameters:
      x - Another container
      Returns:
      aggregated container

    • iandNot

      public Container iandNot(Container x)
      Computes the in-place bitwise ANDNOT of this container with another (difference). The current container is generally modified, whereas the provided container (x) is unaffected. May generate a new container.
      Parameters:
      x - Another container
      Returns:
      aggregated container

    • inot

      public abstract Container inot(int rangeStart, int rangeEnd)
      Computes the in-place bitwise NOT of this container (complement). Only those bits within the range are affected. The current container is generally modified. May generate a new container.
      Parameters:
      rangeStart - beginning of range (inclusive); 0 is beginning of this container.
      rangeEnd - ending of range (exclusive)
      Returns:
      (partially) complemented container

    • ior

      public abstract Container ior(ArrayContainer x)
      Computes the in-place bitwise OR of this container with another (union). The current container is generally modified, whereas the provided container (x) is unaffected. May generate a new container.
      Parameters:
      x - Another container
      Returns:
      aggregated container

    • ior

      public abstract Container ior(BitmapContainer x)
      Computes the in-place bitwise OR of this container with another (union). The current container is generally modified, whereas the provided container (x) is unaffected. May generate a new container.
      Parameters:
      x - Another container
      Returns:
      aggregated container

    • ior

      public abstract Container ior(RunContainer x)
      Computes the in-place bitwise OR of this container with another (union). The current container is generally modified, whereas the provided container (x) is unaffected. May generate a new container.
      Parameters:
      x - Another container
      Returns:
      aggregated container

    • ior

      public Container ior(Container x)
      Computes the in-place bitwise OR of this container with another (union). The current container is generally modified, whereas the provided container (x) is unaffected. May generate a new container.
      Parameters:
      x - Another container
      Returns:
      aggregated container

    • iremove

      public abstract Container iremove(int begin, int end)
      Remove shorts in [begin,end) using an unsigned interpretation. May generate a new container.
      Parameters:
      begin - start of range (inclusive)
      end - end of range (exclusive)
      Returns:
      the new container

    • ixor

      public abstract Container ixor(ArrayContainer x)
      Computes the in-place bitwise XOR of this container with another (symmetric difference). The current container is generally modified, whereas the provided container (x) is unaffected. May generate a new container.
      Parameters:
      x - Another container
      Returns:
      aggregated container

    • ixor

      public abstract Container ixor(BitmapContainer x)
      Computes the in-place bitwise XOR of this container with another (symmetric difference). The current container is generally modified, whereas the provided container (x) is unaffected. May generate a new container.
      Parameters:
      x - Another container
      Returns:
      aggregated container

    • ixor

      public abstract Container ixor(RunContainer x)
      Computes the in-place bitwise XOR of this container with another (symmetric difference). The current container is generally modified, whereas the provided container (x) is unaffected. May generate a new container.
      Parameters:
      x - Another container
      Returns:
      aggregated container

    • ixor

      public Container ixor(Container x)
      Computes the in-place bitwise XOR of this container with another. The current container is generally modified, whereas the provided container (x) is unaffected. May generate a new container.
      Parameters:
      x - Another container
      Returns:
      xor result as a new container reference

    • not

      public abstract Container not(int rangeStart, int rangeEnd)
      Computes the bitwise NOT of this container (complement). Only those bits within the range are affected. This is equivalent to an xor with a range of ones for the given range. The current container is left unaffected.
      Parameters:
      rangeStart - beginning of range (inclusive); 0 is beginning of this container.
      rangeEnd - ending of range (exclusive)
      Returns:
      (partially) complemented container

    • numberOfRanges

      public int numberOfRanges()
      Computes the number of ranges that a RangeIterator would provide on this container.
      Returns:
      The number of ranges that a RangeIterator would provide on this container.

    • or

      public abstract Container or(ArrayContainer x)
      Computes the bitwise OR of this container with another (union). This container as well as the provided container are left unaffected.
      Parameters:
      x - Another container
      Returns:
      aggregated container

    • or

      public abstract Container or(BitmapContainer x)
      Computes the bitwise OR of this container with another (union). This container as well as the provided container are left unaffected.
      Parameters:
      x - Another container
      Returns:
      aggregated container

    • or

      public abstract Container or(RunContainer x)
      Computes the bitwise OR of this container with another (union). This container as well as the provided container are left unaffected.
      Parameters:
      x - Another container
      Returns:
      aggregated container

    • or

      public Container or(Container x)
      Computes the bitwise OR of this container with another (union). This container as well as the provided container are left unaffected.
      Parameters:
      x - Another container
      Returns:
      aggregated container

    • rank

      public abstract int rank(short lowbits)
      Rank returns the number of integers that are smaller or equal to x (Rank(infinity) would be GetCardinality()).
      Parameters:
      lowbits - upper limit
      Returns:
      the rank

    • remove

      public abstract Container remove(int begin, int end)
      Return a new container with all shorts in [begin,end) remove using an unsigned interpretation.
      Parameters:
      begin - start of range (inclusive)
      end - end of range (exclusive)
      Returns:
      the new container

    • remove

      @Deprecated public final Container remove(short x)
      Deprecated.
      Remove the short from this container. May create a new container. Note this legacy method does not respect the naming convention of an i prefix for inplace operations; prefer iunset.
      Parameters:
      x - to be removed
      Returns:
      resulting container.

    • unset

      public abstract Container unset(short x)
      Remove the short from this container. May create a new container.
      Parameters:
      x - to be removed
      Returns:
      resulting container.

    • iunset

      public abstract Container iunset(short x)
      Create a new container with the short removed.
      Parameters:
      x - to be removed
      Returns:
      New container without x.

    • runOptimize

      public abstract Container runOptimize()
      Convert to RunContainers, when the result is smaller. Overridden by RunContainer to possibility switch from RunContainer to a smaller alternative. Overridden by BitmapContainer with a more efficient approach.
      Returns:
      the new container

    • select

      public abstract short select(int j)
      Return the jth value
      Parameters:
      j - index of the value
      Returns:
      the value

    • select

      public abstract Container select(int startRank, int endRank)
      Returns a new container with all values between ranks startPos and endPos.
      Parameters:
      startRank - rank for the start of the range
      endRank - rank for the end of the range, exclusive
      Returns:
      a new Container with all the values between ranks [startPos, endPos)

    • find

      public abstract int find(short x)
      Searches for the specified short value
      Parameters:
      x - value to search for
      Returns:
      Relative position of the value in the sorted set of elements in this container, in the range [0 .. cardinality - 1]. If not present, (-(insertion point) - 1) similar to Array.binarySearch.

      For values of x that contains(short) returns true, this method returns the same value as rank(short).

    • selectRanges

      public abstract void selectRanges(RangeConsumer outValues, RangeIterator inPositions)
      As select but for all the positions in a range.
      Parameters:
      outValues - accept is called in this consumer for each resulting range.
      inPositions - input iterator that provides the position ranges.

    • findRanges

      public abstract boolean findRanges(RangeConsumer outPositions, RangeIterator inValues, int maxPos)
      As find but for all the values in a range.
      Parameters:
      outPositions - accept is called in this consumer for each resulting position range.
      inValues - input iterator that provides the key ranges; these must each exist in the container.
      maxPos - maximum position to add to outPositions; values of position > maxPos are not added.
      Returns:
      true if maxPos was reached, false otherwise.

    • trim

      public abstract void trim()
      If possible, recover wasted memory.

    • xor

      public abstract Container xor(ArrayContainer x)
      Computes the bitwise XOR of this container with another (symmetric difference). This container as well as the provided container are left unaffected.
      Parameters:
      x - Another container
      Returns:
      aggregated container

    • xor

      public abstract Container xor(BitmapContainer x)
      Computes the bitwise XOR of this container with another (symmetric difference). This container as well as the provided container are left unaffected.
      Parameters:
      x - Another container
      Returns:
      aggregated container

    • xor

      public abstract Container xor(RunContainer x)
      Computes the bitwise XOR of this container with another (symmetric difference). This container as well as the provided container are left unaffected.
      Parameters:
      x - Another container
      Returns:
      aggregated container

    • xor

      public Container xor(Container x)
      Computes the bitwise OR of this container with another (symmetric difference). This container as well as the provided container are left unaffected.
      Parameters:
      x - other parameter
      Returns:
      aggregated container

    • toBitmapContainer

      public abstract BitmapContainer toBitmapContainer()
      Convert the current container to a BitmapContainer, if a conversion is needed. If the container is already a bitmap, the container is returned unchanged.

      When multiple container "merge" operations are done it might be more efficient to convert to bitmap first, and then at the end convert to the efficient container type, to avoid multiple container type conversions, since bitmap can always stay a bitmap.

      Returns:
      a bitmap container

    • nextValue

      public abstract int nextValue(short fromValue)
      Gets the first value greater than or equal to the lower bound, or -1 if no such value exists.
      Parameters:
      fromValue - the lower bound (inclusive)
      Returns:
      the next value

    • first

      public abstract int first()
      Get the first integer held in the container
      Returns:
      the first integer in the container
      Throws:
      NoSuchElementException - if empty

    • last

      public abstract int last()
      Get the last integer held in the container
      Returns:
      the last integer in the container
      Throws:
      NoSuchElementException - if empty

    • subsetOf

      public abstract boolean subsetOf(ArrayContainer x)
      Parameters:
      x - Another container
      Returns:
      true if every key in this container is also a key in x.

    • subsetOf

      public abstract boolean subsetOf(BitmapContainer x)
      Parameters:
      x - Another container
      Returns:
      true if every key in this container is also a key in x.

    • subsetOf

      public abstract boolean subsetOf(RunContainer x)
      Parameters:
      x - Another container
      Returns:
      true if every key in this container is also a key in x.

    • subsetOf

      public boolean subsetOf(Container x)
      Parameters:
      x - Another container
      Returns:
      true if every key in this container is also a key in x.

    • intersects

      public final boolean intersects(Container x)
      Parameters:
      x - Another container
      Returns:
      true if some key in this container is also a key in x.

    • intersects

      public final boolean intersects(int start, int end)
      Parameters:
      start - the beginning of the range, as an int.
      end - the end of the range (exclusive), as an int.
      Returns:
      true if there is any element in this container in the range provided.

    • overlaps

      public abstract boolean overlaps(ArrayContainer x)
      Parameters:
      x - Another container
      Returns:
      true if at least one key in this container is also a key in x.

    • overlaps

      public abstract boolean overlaps(BitmapContainer x)
      Parameters:
      x - Another container
      Returns:
      true if at least one key in this container is also a key in x.

    • overlaps

      public abstract boolean overlaps(RunContainer x)
      Parameters:
      x - Another container
      Returns:
      true if at least one key in this container is also a key in x.

    • overlapsRange

      public abstract boolean overlapsRange(int start, int end)
      Parameters:
      start - the beginning of the range, as an int.
      end - the end of the range (exclusive), as an int.
      Returns:
      true if there is any element in this container in the range provided.

    • overlaps

      public boolean overlaps(Container x)
      Parameters:
      x - Another container
      Returns:
      true if some key in this container is also a key in x.

    • setCopyOnWrite

      public abstract void setCopyOnWrite()

    • bytesAllocated

      public abstract int bytesAllocated()
      Returns:
      The allocated size in bytes of the underlying array backing store used by this container.

    • bytesUsed

      public abstract int bytesUsed()
      Returns:
      The size in bytes of the used portion out of the total allocated bytes for the underlying array backing store used by this container.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • isShared

      public abstract boolean isShared()