com.apple.foundationdb.tuple

## Class ByteArrayUtil

- java.lang.Object
- - com.apple.foundationdb.tuple.ByteArrayUtil

    public class ByteArrayUtil
    extends java.lang.Object

Utility functions for operating on byte arrays. Although built for the FoundationDB tuple layer, some functions may be useful otherwise, such as use of `printable(byte[])` for debugging non-text keys and values.

### Method Summary

All Methods Static Methods Concrete Methods
`static int` `compareUnsigned(byte[] l, byte[] r)` Compare byte arrays for equality and ordering purposes.
`static long` `decodeInt(byte[] src)` Decode a little-endian encoded long integer from an 8-byte array.
`static byte[]` `encodeInt(long i)` Encode an 64-bit integer (long) into a byte array.
`static byte[]` `join(byte[]... parts)` Joins a variable number of byte arrays into one larger array.
`static byte[]` `join(byte[] interlude, java.util.List<byte[]> parts)` Joins a set of byte arrays into a larger array.
`static java.lang.String` `printable(byte[] val)` Gets a human readable version of a byte array.
`static byte[]` `replace(byte[] src, byte[] pattern, byte[] replacement)` Replaces occurrences of a pattern in a byte array.
`static byte[]` `replace(byte[] src, int offset, int length, byte[] pattern, byte[] replacement)` Replaces occurrences of a pattern in a byte array.
`static java.util.List<byte[]>` `split(byte[] src, byte[] delimiter)` Splits a byte array at each occurrence of a pattern.
`static java.util.List<byte[]>` `split(byte[] src, int offset, int length, byte[] delimiter)` Splits a byte array at each occurrence of a pattern.
`static boolean` `startsWith(byte[] array, byte[] prefix)` Check if a byte array starts with another byte array.
`static byte[]` `strinc(byte[] key)` Computes the first key that would sort outside the range prefixed by `key`.

### Methods inherited from class java.lang.Object

`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Method Detail

#### join

    public static byte[] join(byte[] interlude,
                              java.util.List<byte[]> parts)

Joins a set of byte arrays into a larger array. The `interlude` is placed between each of the elements, but not at the beginning or end. In the case that the list is empty or `null`, a zero-length byte array will be returned.

Parameters:
  `interlude` - can be `null` or zero length. Placed internally between concatenated elements.
  `parts` - the pieces to be joined. May be `null`, but does not allow for elements in the list to be `null`.
Returns:
  a newly created concatenation of the input

#### join

    public static byte[] join(byte[]... parts)

Joins a variable number of byte arrays into one larger array.

Parameters:
  `parts` - the elements to join. `null` elements are not allowed.
Returns:
  a newly created concatenation of the input

#### replace

    public static byte[] replace(byte[] src,
                                 byte[] pattern,
                                 byte[] replacement)

Replaces occurrences of a pattern in a byte array. Does not mutate the contents of the parameter `src`.

Parameters:
  `src` - the source to search for `pattern`
  `pattern` - the pattern for which to search
  `replacement` - the sequence of bytes to replace `pattern` with.
Returns:
  a newly created array where `pattern` replaced with `replacement`

#### replace

    public static byte[] replace(byte[] src,
                                 int offset,
                                 int length,
                                 byte[] pattern,
                                 byte[] replacement)

Replaces occurrences of a pattern in a byte array. Does not mutate the contents of the parameter `src`.

Parameters:
  `src` - the source to search for `pattern`
  `offset` - the location in `src` at which to start the operation
  `length` - the number of bytes past `offset` to search for `pattern`
  `pattern` - the pattern for which to search
  `replacement` - the sequence of bytes to replace `pattern` with.
Returns:
  a newly created array where `pattern` replaced with `replacement`

#### split

    public static java.util.List<byte[]> split(byte[] src,
                                               byte[] delimiter)

Splits a byte array at each occurrence of a pattern. If the pattern is found at the beginning or end of the array the result will have a leading or trailing zero-length array. The delimiter is not included in the output array. Does not mutate the contents the source array.

Parameters:
  `src` - the array to split
  `delimiter` - the byte pattern on which to split
Returns:
  a list of byte arrays from `src` now not containing `delimiter`

#### split

    public static java.util.List<byte[]> split(byte[] src,
                                               int offset,
                                               int length,
                                               byte[] delimiter)

Splits a byte array at each occurrence of a pattern. If the pattern is found at the beginning or end of the array the result will have a leading or trailing zero-length array. The delimiter is not included in the output array. Does not mutate the contents the source array.

Parameters:
  `src` - the array to split
  `offset` - the location in the array at which to start the operation
  `length` - the number of bytes to search, must not extend past the end of `src`
  `delimiter` - the byte pattern on which to split
Returns:
  a list of byte arrays from `src` now not containing `delimiter`

#### compareUnsigned

    public static int compareUnsigned(byte[] l,
                                      byte[] r)

Compare byte arrays for equality and ordering purposes. Elements in the array are interpreted and compared as unsigned bytes. Neither parameter may be `null`.

Parameters:
  `l` - byte array on the left-hand side of the inequality
  `r` - byte array on the right-hand side of the inequality
Returns:
  return -1, 0, or 1 if `l` is less than, equal to, or greater than `r`.

#### startsWith

    public static boolean startsWith(byte[] array,
                                     byte[] prefix)

Check if a byte array starts with another byte array.

Parameters:
  `array` - the source byte array
  `prefix` - the byte array that we are checking if `src` starts with.
Returns:
  `true` if `array` starts with `prefix`

#### strinc

    public static byte[] strinc(byte[] key)

Computes the first key that would sort outside the range prefixed by `key`. `key` must be non-null, and contain at least some character this is not `\xFF` (255).

Parameters:
  `key` - prefix key
Returns:
  a newly created byte array

#### encodeInt

    public static byte[] encodeInt(long i)

Encode an 64-bit integer (long) into a byte array. Encodes the integer in little endian byte order. The result is valid for use with `Transaction.mutate(...)`.

Parameters:
  `i` - the number to encode
Returns:
  an 8-byte array containing the
See Also:
  `Transaction.mutate(com.apple.foundationdb.MutationType, byte[], byte[])`

#### decodeInt

    public static long decodeInt(byte[] src)

Decode a little-endian encoded long integer from an 8-byte array.

Parameters:
  `src` - the non-null, 8-element byte array from which to decode
Returns:
  a decoded 64-bit integer

#### printable

    public static java.lang.String printable(byte[] val)

Gets a human readable version of a byte array. The bytes that correspond with ASCII printable characters [32-127) are passed through. Other bytes are replaced with `\x` followed by a two character zero-padded hex code for the byte.

Parameters:
  `val` - the byte array for which to create a human readable form
Returns:
  a modification of the byte array with unprintable characters replaced.