Package org.apache.lucene.util

## Class BytesRef

- java.lang.Object
- - org.apache.lucene.util.BytesRef

- All Implemented Interfaces:
    `Cloneable`, `Comparable<BytesRef>`

      public final class BytesRef
      extends Object
      implements Comparable<BytesRef>, Cloneable

  Represents byte[], as a slice (offset + length) into an existing byte[]. The `bytes` member should never be null; use `EMPTY_BYTES` if necessary.

  Important note: Unless otherwise noted, Lucene uses this class to represent terms that are encoded as UTF8 bytes in the index. To convert them to a Java `String` (which is UTF16), use `utf8ToString()`. Using code like `new String(bytes, offset, length)` to do this is wrong, as it does not respect the correct character set and may return wrong results (depending on the platform's defaults)!

  `BytesRef` implements `Comparable`. The underlying byte arrays are sorted lexicographically, numerically treating elements as unsigned. This is identical to Unicode codepoint order.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `byte[]` | `bytes` | The contents of the BytesRef.
    `static byte[]` | `EMPTY_BYTES` | An empty byte array for convenience
    `int` | `length` | Length of used bytes.
    `int` | `offset` | Offset of first valid byte.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `BytesRef()` | Create a BytesRef with `EMPTY_BYTES`
    `BytesRef​(byte[] bytes)` | This instance will directly reference bytes w/o making a copy.
    `BytesRef​(byte[] bytes, int offset, int length)` | This instance will directly reference bytes w/o making a copy.
    `BytesRef​(int capacity)` | Create a BytesRef pointing to a new array of size `capacity`.
    `BytesRef​(CharSequence text)` | Initialize the byte[] from the UTF8 bytes for the provided String.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `bytesEquals​(BytesRef other)` | Expert: compares the bytes against another BytesRef, returning true if the bytes are equal.
    `BytesRef` | `clone()` | Returns a shallow clone of this instance (the underlying bytes are not copied and will be shared by both the returned object and this object.
    `int` | `compareTo​(BytesRef other)` | Unsigned byte order comparison
    `static BytesRef` | `deepCopyOf​(BytesRef other)` | Creates a new BytesRef that points to a copy of the bytes from `other`
    `boolean` | `equals​(Object other)` |
    `int` | `hashCode()` | Calculates the hash code as required by TermsHash during indexing.
    `boolean` | `isValid()` | Performs internal consistency checks.
    `String` | `toString()` | Returns hex encoded bytes, eg [0x6c 0x75 0x63 0x65 0x6e 0x65]
    `String` | `utf8ToString()` | Interprets stored bytes as UTF8 bytes, returning the resulting string

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

      `finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### EMPTY_BYTES

          public static final byte[] EMPTY_BYTES

      An empty byte array for convenience

    - #### bytes

          public byte[] bytes

      The contents of the BytesRef. Should never be `null`.

    - #### offset

          public int offset

      Offset of first valid byte.

    - #### length

          public int length

      Length of used bytes.

  - ### Constructor Detail

    - #### BytesRef

          public BytesRef()

      Create a BytesRef with `EMPTY_BYTES`

    - #### BytesRef

          public BytesRef​(byte[] bytes,
                          int offset,
                          int length)

      This instance will directly reference bytes w/o making a copy. bytes should not be null.

    - #### BytesRef

          public BytesRef​(byte[] bytes)

      This instance will directly reference bytes w/o making a copy. bytes should not be null

    - #### BytesRef

          public BytesRef​(int capacity)

      Create a BytesRef pointing to a new array of size `capacity`. Offset and length will both be zero.

    - #### BytesRef

          public BytesRef​(CharSequence text)

      Initialize the byte[] from the UTF8 bytes for the provided String.
      Parameters:
        `text` - This must be well-formed unicode text, with no unpaired surrogates.

  - ### Method Detail

    - #### bytesEquals

          public boolean bytesEquals​(BytesRef other)

      Expert: compares the bytes against another BytesRef, returning true if the bytes are equal.
      Parameters:
        `other` - Another BytesRef, should not be null.
      NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

    - #### clone

          public BytesRef clone()

      Returns a shallow clone of this instance (the underlying bytes are not copied and will be shared by both the returned object and this object.
      Overrides:
        `clone` in class `Object`
      See Also:
        `deepCopyOf(org.apache.lucene.util.BytesRef)`

    - #### hashCode

          public int hashCode()

      Calculates the hash code as required by TermsHash during indexing.

      This is currently implemented as MurmurHash3 (32 bit), using the seed from `StringHelper.GOOD_FAST_HASH_SEED`, but is subject to change from release to release.

      Overrides:
        `hashCode` in class `Object`

    - #### equals

          public boolean equals​(Object other)

      Overrides:
        `equals` in class `Object`

    - #### utf8ToString

          public String utf8ToString()

      Interprets stored bytes as UTF8 bytes, returning the resulting string

    - #### toString

          public String toString()

      Returns hex encoded bytes, eg [0x6c 0x75 0x63 0x65 0x6e 0x65]
      Overrides:
        `toString` in class `Object`

    - #### compareTo

          public int compareTo​(BytesRef other)

      Unsigned byte order comparison
      Specified by:
        `compareTo` in interface `Comparable<BytesRef>`

    - #### deepCopyOf

          public static BytesRef deepCopyOf​(BytesRef other)

      Creates a new BytesRef that points to a copy of the bytes from `other`

      The returned BytesRef will have a length of other.length and an offset of zero.

    - #### isValid

          public boolean isValid()

      Performs internal consistency checks. Always returns true (or throws IllegalStateException)