Package org.apache.lucene.util

Class 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[].

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

    WARNING: This API is experimental and might change in incompatible ways in the next release.

    • 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

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

      • copyChars

        public void copyChars​(char[] text,
                      int offset,
                      int length)
        Copies the UTF8 bytes for this string.
        Parameters:
        text - Must be well-formed unicode text, with no unpaired surrogates.

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

      • startsWith

        public boolean startsWith​(BytesRef other)

      • endsWith

        public boolean endsWith​(BytesRef other)

      • 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

      • 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.
        NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

      • getUTF8SortedAsUnicodeComparator

        public static Comparator<BytesRef> getUTF8SortedAsUnicodeComparator()

      • getUTF8SortedAsUTF16Comparator

        public static Comparator<BytesRef> getUTF8SortedAsUTF16Comparator()

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