## org.apache.lucene.util
Class BytesRefHash

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

    public final class BytesRefHash

extends Object

`BytesRefHash` is a special purpose hash-map like data-structure optimized for `BytesRef` instances. BytesRefHash maintains mappings of byte arrays to ordinal (Map<BytesRef,int>) storing the hashed bytes efficiently in continuous storage. The mapping to the ordinal is encapsulated inside `BytesRefHash` and is guaranteed to be increased for each added `BytesRef`.

Note: The maximum capacity `BytesRef` instance passed to `add(BytesRef)` must not be longer than `ByteBlockPool.BYTE_BLOCK_SIZE`-2. The internal storage is limited to 2GB total byte storage.

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

Nested Class Summary
`static class` `BytesRefHash.BytesStartArray` Manages allocation of the per-term addresses.
`static class` `BytesRefHash.DirectBytesStartArray` A simple `BytesRefHash.BytesStartArray` that tracks memory allocation using a private `AtomicLong` instance.
`static class` `BytesRefHash.MaxBytesLengthExceededException` Thrown if a `BytesRef` exceeds the `BytesRefHash` limit of `ByteBlockPool.BYTE_BLOCK_SIZE`-2.
`static class` `BytesRefHash.TrackingDirectBytesStartArray` A simple `BytesRefHash.BytesStartArray` that tracks all memory allocation using a shared `AtomicLong` instance.

Field Summary
`static int` `DEFAULT_CAPACITY`

Constructor Summary
`BytesRefHash()` Creates a new `BytesRefHash` with a `ByteBlockPool` using a `ByteBlockPool.DirectAllocator`.
`BytesRefHash(ByteBlockPool pool)` Creates a new `BytesRefHash`
`BytesRefHash(ByteBlockPool pool, int capacity, BytesRefHash.BytesStartArray bytesStartArray)` Creates a new `BytesRefHash`

Method Summary
`int` `add(BytesRef bytes)` Adds a new `BytesRef`
`int` `add(BytesRef bytes, int code)` Adds a new `BytesRef` with a pre-calculated hash code.
`int` `addByPoolOffset(int offset)`
`int` `byteStart(int ord)` Returns the bytesStart offset into the internally used `ByteBlockPool` for the given ord
`void` `clear()`
`void` `clear(boolean resetPool)` Clears the `BytesRef` which maps to the given `BytesRef`
`void` `close()` Closes the BytesRefHash and releases all internally used memory
`int[]` `compact()` Returns the ords array in arbitrary order.
`BytesRef` `get(int ord, BytesRef ref)` Populates and returns a `BytesRef` with the bytes for the given ord.
`void` `reinit()` reinitializes the `BytesRefHash` after a previous `clear()` call.
`int` `size()` Returns the number of `BytesRef` values in this `BytesRefHash`.
`int[]` `sort(Comparator<BytesRef> comp)` Returns the values array sorted by the referenced byte values.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### DEFAULT_CAPACITY

    public static final int DEFAULT_CAPACITY

See Also:
  Constant Field Values

Constructor Detail

### BytesRefHash

    public BytesRefHash()

  Creates a new `BytesRefHash` with a `ByteBlockPool` using a `ByteBlockPool.DirectAllocator`.

### BytesRefHash

    public BytesRefHash(ByteBlockPool pool)

  Creates a new `BytesRefHash`

### BytesRefHash

    public BytesRefHash(ByteBlockPool pool,
                        int capacity,
                        BytesRefHash.BytesStartArray bytesStartArray)

  Creates a new `BytesRefHash`

Method Detail

### size

    public int size()

  Returns the number of `BytesRef` values in this `BytesRefHash`.

  Returns:
    the number of `BytesRef` values in this `BytesRefHash`.

### get

    public BytesRef get(int ord,
                        BytesRef ref)

  Populates and returns a `BytesRef` with the bytes for the given ord.

  Note: the given ord must be a positive integer less that the current size ( `size()`)

  Parameters:
    `ord` - the ord
    `ref` - the `BytesRef` to populate
  Returns:
    the given BytesRef instance populated with the bytes for the given ord

### compact

    public int[] compact()

  Returns the ords array in arbitrary order. Valid ords start at offset of 0 and end at a limit of `size()` - 1

  Note: This is a destructive operation. `clear()` must be called in order to reuse this `BytesRefHash` instance.

### sort

    public int[] sort(Comparator<BytesRef> comp)

  Returns the values array sorted by the referenced byte values.

  Note: This is a destructive operation. `clear()` must be called in order to reuse this `BytesRefHash` instance.

  Parameters:
    `comp` - the `Comparator` used for sorting

### clear

    public void clear(boolean resetPool)

  Clears the `BytesRef` which maps to the given `BytesRef`

### clear

    public void clear()

### close

    public void close()

  Closes the BytesRefHash and releases all internally used memory

### add

    public int add(BytesRef bytes)

  Adds a new `BytesRef`

  Parameters:
    `bytes` - the bytes to hash
  Returns:
    the ord the given bytes are hashed if there was no mapping for the given bytes, otherwise `(-(ord)-1)`. This guarantees that the return value will always be >= 0 if the given bytes haven't been hashed before.
  Throws:
    `BytesRefHash.MaxBytesLengthExceededException` - if the given bytes are > 2 + `ByteBlockPool.BYTE_BLOCK_SIZE`

### add

    public int add(BytesRef bytes,
                   int code)

  Adds a new `BytesRef` with a pre-calculated hash code.

  Parameters:
    `bytes` - the bytes to hash
    `code` - the bytes hash code

    Hashcode is defined as:

         int hash = 0;
         for (int i = offset; i < offset + length; i++) {
           hash = 31 * hash + bytes[i];
         }

  Returns:
    the ord the given bytes are hashed if there was no mapping for the given bytes, otherwise `(-(ord)-1)`. This guarantees that the return value will always be >= 0 if the given bytes haven't been hashed before.
  Throws:
    `BytesRefHash.MaxBytesLengthExceededException` - if the given bytes are > `ByteBlockPool.BYTE_BLOCK_SIZE` - 2

### addByPoolOffset

    public int addByPoolOffset(int offset)

### reinit

    public void reinit()

  reinitializes the `BytesRefHash` after a previous `clear()` call. If `clear()` has not been called previously this method has no effect.

### byteStart

    public int byteStart(int ord)

  Returns the bytesStart offset into the internally used `ByteBlockPool` for the given ord

  Parameters:
    `ord` - the ord to look up
  Returns:
    the bytesStart offset into the internally used `ByteBlockPool` for the given ord