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 and 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 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
    Modifier and Type | Method and 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()`
    `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)

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