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

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `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.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DEFAULT_CAPACITY`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `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

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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
    `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

    - #### 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

Copyright © 2000-2013 Apache Software Foundation. All Rights Reserved.