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

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

  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, e.g.
  `String`
  `utf8ToString()`
  Interprets stored bytes as UTF-8 bytes, returning the resulting string.

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

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

- ## Field Details

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

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

  - ### 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 UTF-8 bytes, returning the resulting string. May throw an `AssertionError` or a `RuntimeException` if the data is not well-formed UTF-8.

  - ### toString

    public String toString()
    Returns hex encoded bytes, e.g. "[6c 75 63 65 6e 65]"
    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)