BytesRefArray (Lucene 10.5.1 core API)
Description: declaration: package: org.apache.lucene.util, class: BytesRefArray

Package org.apache.lucene.util

# Class BytesRefArray

java.lang.Object
org.apache.lucene.util.BytesRefArray

public final class BytesRefArray extends Object
A simple append only random-access `BytesRef` array that stores full copies of the appended bytes in a `ByteBlockPool`.

Note: This class is not Thread-Safe!

WARNING: This API is experimental and might change in incompatible ways in the next release.
NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static interface`
  `BytesRefArray.IndexedBytesRefIterator`
  An extension of `BytesRefIterator` that allows retrieving the index of the current element
  `static final class`
  `BytesRefArray.SortState`
  Used to iterate the elements of an array in a given order.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `BytesRefArray(Counter bytesUsed)`
  Creates a new `BytesRefArray` with a counter to track allocated bytes

- ## Method Summary

  Modifier and Type
  Method
  Description
  `int`
  `append(BytesRef bytes)`
  Appends a copy of the given `BytesRef` to this `BytesRefArray`.
  `void`
  `clear()`
  Clears this `BytesRefArray`
  `BytesRef`
  `get(BytesRefBuilder spare, int index)`
  Returns the n'th element of this `BytesRefArray`
  `BytesRefIterator`
  `iterator()`
  sugar for `iterator(Comparator)` with a `null` comparator
  `BytesRefIterator`
  `iterator(Comparator<BytesRef> comp)`
  Returns a `BytesRefIterator` with point in time semantics.
  `BytesRefArray.IndexedBytesRefIterator`
  `iterator(BytesRefArray.SortState sortState)`
  Returns an `BytesRefArray.IndexedBytesRefIterator` with point in time semantics.
  `int`
  `size()`
  Returns the current size of this `BytesRefArray`
  `BytesRefArray.SortState`
  `sort(Comparator<BytesRef> comp, boolean stable)`
  Returns a `BytesRefArray.SortState` representing the order of elements in this array.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### BytesRefArray

    public BytesRefArray(Counter bytesUsed)
    Creates a new `BytesRefArray` with a counter to track allocated bytes

- ## Method Details

  - ### clear

    public void clear()
    Clears this `BytesRefArray`

  - ### append

    public int append(BytesRef bytes)
    Appends a copy of the given `BytesRef` to this `BytesRefArray`.
    Parameters:
      `bytes` - the bytes to append
    Returns:
      the index of the appended bytes

  - ### size

    public int size()
    Returns the current size of this `BytesRefArray`
    Returns:
      the current size of this `BytesRefArray`

  - ### get

    public BytesRef get(BytesRefBuilder spare, int index)
    Returns the n'th element of this `BytesRefArray`
    Parameters:
      `spare` - a spare `BytesRef` instance
      `index` - the elements index to retrieve
    Returns:
      the n'th element of this `BytesRefArray`

  - ### sort

    public BytesRefArray.SortState sort(Comparator<BytesRef> comp, boolean stable)
    Returns a `BytesRefArray.SortState` representing the order of elements in this array. This is a non-destructive operation.
    Parameters:
      `comp` - The comparator to compare `BytesRef`s. A radix sort optimization is available if the comparator implements `BytesRefComparator`
      `stable` - If the sort needs to be stable
    Returns:
      A `BytesRefArray.SortState` that could be used in `iterator(SortState)`

  - ### iterator

    public BytesRefIterator iterator()
    sugar for `iterator(Comparator)` with a `null` comparator

  - ### iterator

    public BytesRefIterator iterator(Comparator<BytesRef> comp)
    Returns a `BytesRefIterator` with point in time semantics. The iterator provides access to all so far appended `BytesRef` instances.

    If a non `null` `Comparator` is provided the iterator will iterate the byte values in the order specified by the comparator. Otherwise the order is the same as the values were appended.

    This is a non-destructive operation.

  - ### iterator

    public BytesRefArray.IndexedBytesRefIterator iterator(BytesRefArray.SortState sortState)
    Returns an `BytesRefArray.IndexedBytesRefIterator` with point in time semantics. The iterator provides access to all so far appended `BytesRef` instances. If a non-null sortState is specified then the iterator will iterate the byte values in the order of the sortState; otherwise, the order is the same as the values were appended.