org.opensolaris.os.dtrace
Class Tuple

java.lang.Object
  extended by org.opensolaris.os.dtrace.Tuple
All Implemented Interfaces:
java.io.Serializable, java.lang.Comparable<Tuple>, java.lang.Iterable<ValueRecord>

public final class Tuple
extends java.lang.Object
implements java.io.Serializable, java.lang.Comparable<Tuple>, java.lang.Iterable<ValueRecord>

Multi-element key to a value in an Aggregation.

Tuple equality is based on the length of each tuple and the equality of each corresponding element. The natural ordering of tuples is based on a lenient comparison designed not to throw exceptions when corresponding elements are not mutually comparable or the number of tuple elements differs.

Immutable. Supports persistence using XMLEncoder.

See Also:
Serialized Form

Field Summary
static Tuple EMPTY
          The empty tuple has zero elements and may be used to obtain the singleton AggregationRecord of a non-keyed Aggregation, such as the one derived from the D statement @a = count().
 
Constructor Summary
Tuple(java.util.List<ValueRecord> tupleElements)
          Creates a tuple with the given element list in the given list order.
Tuple(ValueRecord... tupleElements)
          Creates a tuple with the given elements in the given order.
 
Method Summary
 java.util.List<ValueRecord> asList()
          Gets a read-only List view of this tuple.
static int compare(Tuple t1, Tuple t2, int pos)
          Compares corresponding tuple elements at the given zero-based index.
 int compareTo(Tuple t)
          Defines the natural ordering of tuples.
 boolean equals(java.lang.Object o)
          Compares the specified object with this Tuple instance for equality.
 ValueRecord get(int index)
          Gets the element at the given tuple index (starting at zero).
 java.util.List<ValueRecord> getElements()
          Gets a modifiable list of this tuple's elements in the same order as their corresponding variables in the original D program tuple.
 int hashCode()
          Overridden to ensure that equals instances have equal hash codes.
 boolean isEmpty()
          Returns true if this tuple has no elements.
 java.util.Iterator<ValueRecord> iterator()
          Gets an iterator over the elements of this tuple.
 int size()
          Gets the number of elements in this tuple.
 java.lang.String toString()
          Gets a string representation of this tuple's elements in the same format as that returned by AbstractCollection.toString().
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

EMPTY

public static final Tuple EMPTY
The empty tuple has zero elements and may be used to obtain the singleton AggregationRecord of a non-keyed Aggregation, such as the one derived from the D statement @a = count(). (In D, an aggregation without square brackets aggregates a single value.)

Constructor Detail

Tuple

public Tuple(ValueRecord... tupleElements)
Creates a tuple with the given elements in the given order.

Parameters:
tupleElements - ordered series of tuple elements
Throws:
java.lang.NullPointerException - if the given array or any of its elements is null

Tuple

public Tuple(java.util.List<ValueRecord> tupleElements)
Creates a tuple with the given element list in the given list order.

Parameters:
tupleElements - ordered list of tuple elements
Throws:
java.lang.NullPointerException - if the given list or any of its elements is null
Method Detail

getElements

public java.util.List<ValueRecord> getElements()
Gets a modifiable list of this tuple's elements in the same order as their corresponding variables in the original D program tuple. Modifying the returned list has no effect on this tuple. Supports XML persistence.

Returns:
a modifiable list of this tuple's elements in the same order as their corresponding variables in the original D program tuple

asList

public java.util.List<ValueRecord> asList()
Gets a read-only List view of this tuple.

Returns:
a read-only List view of this tuple

size

public int size()
Gets the number of elements in this tuple.

Returns:
non-negative element count

isEmpty

public boolean isEmpty()
Returns true if this tuple has no elements.

Returns:
true if this tuple has no elements, false otherwise
See Also:
EMPTY

get

public ValueRecord get(int index)
Gets the element at the given tuple index (starting at zero).

Returns:
non-null tuple element at the given zero-based index

iterator

public java.util.Iterator<ValueRecord> iterator()
Gets an iterator over the elements of this tuple.

Specified by:
iterator in interface java.lang.Iterable<ValueRecord>
Returns:
an iterator over the elements of this tuple

equals

public boolean equals(java.lang.Object o)
Compares the specified object with this Tuple instance for equality. Defines equality as having the same elements in the same order.

Overrides:
equals in class java.lang.Object
Returns:
true if and only if the specified object is of type Tuple and both instances have the same size and equal elements at corresponding tuple indexes

hashCode

public int hashCode()
Overridden to ensure that equals instances have equal hash codes.

Overrides:
hashCode in class java.lang.Object

compareTo

public int compareTo(Tuple t)
Defines the natural ordering of tuples. Uses a lenient algorithm designed not to throw exceptions. Sorts tuples by the natural ordering of corresponding elements, starting with the first pair of corresponding elements and comparing subsequent pairs only when all previous pairs are equal (as a tie breaker). If corresponding elements are not mutually comparable, it compares the string values of those elements. If all corresponding elements are equal, then the tuple with more elements sorts higher than the tuple with fewer elements.

Specified by:
compareTo in interface java.lang.Comparable<Tuple>
Returns:
a negative integer, zero, or a postive integer as this tuple is less than, equal to, or greater than the given tuple
See Also:
compare(Tuple t1, Tuple t2, int pos)

compare

public static int compare(Tuple t1,
                          Tuple t2,
                          int pos)
Compares corresponding tuple elements at the given zero-based index. Elements are ordered as defined in the native DTrace library, which treats integer values as unsigned when sorting.

Parameters:
t1 - first tuple
t2 - second tuple
pos - nth tuple element, starting at zero
Returns:
a negative integer, zero, or a postive integer as the element in the first tuple is less than, equal to, or greater than the element in the second tuple
Throws:
java.lang.IndexOutOfBoundsException - if the given tuple index pos is out of range (pos < 0 || pos >= size()) for either of the given tuples

toString

public java.lang.String toString()
Gets a string representation of this tuple's elements in the same format as that returned by AbstractCollection.toString(). The representation, although specified, is subject to change.

Overrides:
toString in class java.lang.Object