org.apache.lucene.util
Class BytesRef

java.lang.Object
  extended by 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
 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
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(CharSequence text)
          Initialize the byte[] from the UTF8 bytes for the provided String.
BytesRef(int capacity)
          Create a BytesRef pointing to a new array of size capacity.
 
Method Summary
 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 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 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.
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.

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.

NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

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)



Copyright © 2000-2014 Apache Software Foundation. All Rights Reserved.