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
`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 and 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(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

Methods
`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()`
`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()

Overrides:
  `clone` in class `Object`

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