Package com.apple.foundationdb.tuple

## Class IterableComparator

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

All Implemented Interfaces:
  `java.util.Comparator<java.lang.Iterable<?>>`

    public class IterableComparator
    extends java.lang.Object
    implements java.util.Comparator<java.lang.Iterable<?>>

A `Tuple`-compatible `Comparator` that will sort `Iterable`s in a manner that is consistent with the byte-representation of `Tuple`s. In particular, if one has two `Tuple`s, `tuple1` and `tuple2`, it is the case that:

        tuple1.compareTo(tuple2)
          == new IterableComparator().compare(tuple1, tuple2)
          == new IterableComparator().compare(tuple1.getItems(), tuple2.getItems()),
          == ByteArrayUtil.compareUnsigned(tuple1.pack(), tuple2.pack())

The individual elements of the `Iterable` must be of a type that can be serialized by a `Tuple`. For items of identical types, they will be sorted in a way that is consistent with their natural ordering with a few caveats:

- For floating point types, negative NaN values are sorted before all regular values, and positive NaN values are sorted after all regular values.
- Single-precision floating point numbers are sorted before all double-precision floating point numbers.
- UUIDs are sorted by their unsigned Big-Endian byte representation rather than their signed byte representation (which is the behavior of `UUID.compareTo()`).
- Strings are sorted explicitly by their UTF-8 byte representation
- Nested `Tuple`s and `List`s are sorted element-wise.

### Constructor Summary

Constructors
`IterableComparator()` Creates a new `IterableComparator`.

### Method Summary

All Methods Instance Methods Concrete Methods
`int` `compare​(java.lang.Iterable<?> iterable1, java.lang.Iterable<?> iterable2)` Compare two `Iterable`s in a way consistent with their byte representation.

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

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

### Methods inherited from interface java.util.Comparator

`equals, reversed, thenComparing, thenComparing, thenComparing, thenComparingDouble, thenComparingInt, thenComparingLong`

### Constructor Detail

#### IterableComparator

    public IterableComparator()

Creates a new `IterableComparator`. This `Comparator` has no internal state.

### Method Detail

#### compare

    public int compare​(java.lang.Iterable<?> iterable1,
                       java.lang.Iterable<?> iterable2)

Compare two `Iterable`s in a way consistent with their byte representation. This is done element-wise and is consistent with a number of other ways of sorting `Tuple`s. This will raise an `IllegalArgumentException` if any of the items of either `Iterable` cannot be serialized by a `Tuple`.

Specified by:
  `compare` in interface `java.util.Comparator<java.lang.Iterable<?>>`
Parameters:
  `iterable1` - the first `Iterable` of items
  `iterable2` - the second `Iterable` of items
Returns:
  a negative number if the first iterable would sort before the second when serialized, a positive number if the opposite is true, and zero if the two are equal