Package org.apache.lucene.util

Class BytesRef

  • All Implemented Interfaces:
    java.lang.Cloneable, java.lang.Comparable<BytesRef>
    public final class BytesRef
extends java.lang.Object
implements java.lang.Comparable<BytesRef>, java.lang.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 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​(java.lang.CharSequence text)
      Initialize the byte[] from the UTF8 bytes for the provided String.

    • 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​(java.lang.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​(java.lang.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.

      • 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 java.lang.Object

      • equals

        public boolean equals​(java.lang.Object other)
        Overrides:
        equals in class java.lang.Object

      • utf8ToString

        public java.lang.String utf8ToString()
        Interprets stored bytes as UTF8 bytes, returning the resulting string

      • toString

        public java.lang.String toString()
        Returns hex encoded bytes, eg [0x6c 0x75 0x63 0x65 0x6e 0x65]
        Overrides:
        toString in class java.lang.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 java.lang.Comparable<BytesRef>

      • getUTF8SortedAsUnicodeComparator

        public static java.util.Comparator<BytesRef> getUTF8SortedAsUnicodeComparator()

      • getUTF8SortedAsUTF16Comparator

        @Deprecated
public static java.util.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)