There are ten tuple classes in javatuples:
Plus a couple of very common 2-element tuple classes equivalent to Pair, just for the sake of code semantics:
All tuple classes are:
Tuples can be instanced in a semantically elegant way, using the with(...) methods from each of the tuple classes:
Pair<String,Integer> pair = Pair.with("hello", Integer.valueOf(23));
...
Quintet<String,Integer,Double,String,String> quintet =
Quintet.with("a", Integer.valueOf(3), Double.valueOf(34.2), "b", "c");
Of course, constructors can also be used directly:
Pair<String,Integer> pair = new Pair<String,Integer>("hello", Integer.valueOf(23));
...
Quintet<String,Integer,Double,String,String> quintet =
new Quintet<String,Integer,Double,String,String>("a", Integer.valueOf(3), Double.valueOf(34.2), "b", "c");
You can also create tuples from collections or --more generally--, any iterable:
Quintet<String,String,String,String,String> quintet = Quintet.fromCollection(myCollectionWith5Elements);
...
// Retrieve three values from an iterable starting at a specific index
Triplet<Integer,Integer,Integer> triplet = Triplet.fromIterable(lotsOfInts, 7);
Values can be retrieved from a tuple by using the specific method for its position:
Triplet<String,Integer,Double> triplet = ...
...
Integer intVal = triplet.getValue1();
Note that:
There is also a getValue(int pos) method, but its use is not recommended, because the compiler cannot know the type of the result beforehand and therefore you will need a cast:
Triplet<String,Integer,Double> triplet = ...
...
Integer intVal = (Integer) triplet.getValue(1);
Note that classes KeyValue and LabelValue have their getValue0()/getValue1() methods renamed as getKey()/getValue() and getLabel()/getValue(), respectively.
In order to set new values for specific positions of a tuple, you can use the setAtX(...) setter methods:
Triplet<String,Integer,Double> triplet = ...
...
triplet = triplet.setAt2(Double.valueOf(245.21));
Important: tuples are immutable. This means that you will have to collect the return value of your setAtX(...) calls, and also that you will be able to change the type of a position in the tuple by changing the object that lives in that position:
Triplet<String,Integer,Double> triplet = ...
...
Triplet<String,Integer,String> otherTriplet = triplet.setAt2("North Atlantic");
New elements can be added to a tuple, converting it in a different tuple.
For example, if you add a String to a Triplet<String,Integer,Double>, you will turn it into a Quartet<String,Integer,Double,String>:
Triplet<String,Integer,Double> triplet = ...
...
Quartet<String,Integer,Double,String> quartet = triplet.add("South Pacific");
By default, new elements are added at the end of the tuple. But you can also add elements in other positions of the tuple by using the addAtX(...) methods:
Triplet<String,Integer,Double> triplet = ...
...
Quartet<String,Integer,String,Double> quartet = triplet.addAt2("Mediterranean");
You can also add more than one element...
Triplet<String,Integer,Double> triplet = ...
...
Quintet<String,Integer,String,String,Double> quintet = triplet.addAt2("Red Sea", "Caspian");
...or even other tuples:
Triplet<String,Integer,Double> triplet1 = ...
Triplet<Byte,String[],String> triplet2 = ...
...
Sextet<String,Integer,Byte,String[],String,Double> sextet = triplet1.addAt2(triplet2);
Removing elements is just as easy, and it will also transform your tuple. If you remove an element from a Triplet, you will get a Pair:
Triplet<String,Integer,Double> triplet = ...
...
Pair<String,Double> pair = triplet.removeFrom1();
A tuple can be easily converted to a list or an array, but you will lose your type-safety and end up with a List<Object> or an Object[]:
Triplet<String,Integer,Double> triplet = ...
...
List<Object> list = triplet.toList();
...
Object[] array = triplet.toArray();
Inversely, you can obtain a tuple from both a collection or an array:
String[] array = ...
...
Quartet<String,String,String,String> quartet = Quartet.fromArray(array);
Note that your tuple will have all its elements set to the component type of the array (String, in this case). Also, note that...
String[] array = new String[] { "a", "b", "c", "d", "e" };
...
// Array has five elements: will raise an exception trying to create a quartet!!
Quartet<String,String,String,String> quartet = Quartet.fromArray(array);
...will raise the following exception:
java.lang.IllegalArgumentException: Array must have exactly 4 elements in order to create a Quartet. Size is 5
at ...
All tuple classes in javatuples implement the Iterable<Object> interface, so it can be iterated in the same way as collections or arrays:
Triplet<String,Integer,Double> triplet = ...
...
for (Object value : tuple) {
...
}
Tuples offer some utility methods, like contains(...), containsAll(...), indexOf(...) or lastIndexOf(...), which work in exactly the same way as they do in collections:
Quartet<String,Integer,String,Boolean> quartet = ...
...
if (quartet.contains(value)) {
...
}
...
if (quartet.containsAll(valueCollection)) {
...
}