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)!

  • 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
    void
    append(BytesRef other)
    Appends the bytes from the given BytesRef
    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
    void
    copyBytes(BytesRef other)
    Copies the bytes from the given BytesRef
    void
    copyChars(CharSequence text)
    Copies the UTF8 bytes for this string.
    static BytesRef
    deepCopyOf(BytesRef other)
    Creates a new BytesRef that points to a copy of the bytes from other
    boolean
    equals(Object other)
     
    static Comparator<BytesRef>
    getUTF8SortedAsUnicodeComparator()
     
    static Comparator<BytesRef>
    getUTF8SortedAsUTF16Comparator()
    Deprecated.
    This comparator is only a transition mechanism
    void
    grow(int newLength)
    Used to grow the reference array.
    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 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

    • copyChars

      public void copyChars(CharSequence text)
      Copies the UTF8 bytes for this string.
      Parameters:
      text - Must be well-formed unicode text, with no unpaired surrogates or invalid UTF16 code units.

    • 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.

    • 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:

    • hashCode

      public int hashCode()
      Calculates the hash code as required by TermsHash during indexing.

      It is defined as: 

        int hash = 0;
  for (int i = offset; i < offset + length; i++) {
    hash = 31*hash + bytes[i];
  }
      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

    • copyBytes

      public void copyBytes(BytesRef other)
      Copies the bytes from the given BytesRef

      NOTE: if this would exceed the array size, this method creates a new reference array.

    • append

      public void append(BytesRef other)
      Appends the bytes from the given BytesRef

      NOTE: if this would exceed the array size, this method creates a new reference array.

    • grow

      public void grow(int newLength)
      Used to grow the reference array. In general this should not be used as it does not take the offset into account.

    • compareTo

      public int compareTo(BytesRef other)
      Unsigned byte order comparison
      Specified by:
      compareTo in interface Comparable<BytesRef>

    • getUTF8SortedAsUnicodeComparator

      public static Comparator<BytesRef> getUTF8SortedAsUnicodeComparator()

    • getUTF8SortedAsUTF16Comparator

      @Deprecated public static Comparator<BytesRef> getUTF8SortedAsUTF16Comparator()
      Deprecated.
      This comparator is only a transition mechanism

    • 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)