JavaTuples | Introduction

Tuple

The word “tuple” means “a data structure consisting of multiple parts”. Hence Tuples can be defined as a data structure that can hold multiple values and these values may/may not be related to each other. Example:

[Geeks, 123, *@]

In this example, the values in the tuple are not at all related to each other. “Geeks” is a word that has a meaning. “123” are numbers. While “&#*@” are just some bunch of special characters. Hence the values in a tuple might or might not be related to each other.

JavaTuple

JavaTuples is a Java library that offers classes, functions and data structures to work with tuples. It is one of the simplest java library ever made. JavaTuples offers following classes to work with :

• JavaTuples allows maximum of 10 tuples. The classes for each are:

  For 1 element   - Unit<A>
  For 2 elements  - Pair<A, B> 
  For 3 elements  - Triplet<A, B, C> 
  For 4 elements  - Quartet<A, B, C, D> 
  For 5 elements  - Quintet<A, B, C, D, E>
  For 6 elements  - Sextet<A, B, C, D, E, F> 
  For 7 elements  - Septet<A, B, C, D, E, F, G>
  For 8 elements  - Octet<A, B, C, D, E, F, G, H>
  For 9 elements  - Ennead<A, B, C, D, E, F, G, H, I>
  For 10 elements - Decade<A, B, C, D, E, F, G, H, I, J>
  

• JavaTuples also gives the 2 very common 2-element tuple classes equivalent to Pair:

  KeyValue<A, B>
  LabelValue<A, B>
  

Note: To run the JavaTuples program, org.javatuples library needs to be added in the IDE. The IDE can be Netbeans, Eclipse, etc. Download JavaTuples Jar library here. To add a library in Netbeans, refer this. The basic characteristics of JavaTuples are:

• They are Typesafe
• They are Immutable
• They are Iterable
• They are Serializable
• They are Comparable (implements Comparable<Tuple>)
• They implement equals() and hashCode()
• They also implement toString()

Why to prefer JavaTuples over Lists/Arrays?

Think of a scenario where you want to store the details of a student in just one entity, like Name, Roll Number, Father’s Name, Contact Number. Now the most common approach that strikes the mind is to construct a data structure that would take the fields as required. This is where Tuples come into play. With Tuples, any separate data structure need not to be created. Instead, for this scenario, a Quartet<A, B, C, D> can be simply used. Therefore, common data structures like List, Array :

• Can be of a specific type only.
• Can be of infinite elements.

Whereas, Tuples :

• Can be of any type, yet they are typesafe
• Can be of limited number only, from 1-10

Methods in JavaTuples

JavaTuples library has many functions that help with the easy working of them. These are:

fromArray()	fromCollection()	fromIterable()	with()	addAtX()	add()
compareTo()	equals()	contains()	containsAll()	getSize()	hashCode()
toString()	toArray()	indexOf()	lastIndexOf()	getValueX()	getValue()
setAtX()	removeFromX()	getKey()	setKey()	getLabel()	setLabel()
setValue()

Creating JavaTuples

Note: Below examples are shown to be as a generic approach. They can be used for any of the JavaTuple by replacing with the number of parameters and the corresponding Tuple class with values, as required.
• From Constructor: Syntax:

  NthTuple<type 1, type 2, .., type n> nthTuple = new NthTuple
                  <type 1, type 2, .., type n>(value 1, value 2, .., value n);
  

  Example:

  Pair<Integer, String> pair = new Pair<Integer, String>(
                                Integer.valurOf(1), "Geeks");
  
  Sextet<Integer, String, Integer, String, Integer, String> sextet
                             = new Sextet<Integer, String, Integer,
                                           String, Integer, String>(
                                               Integer.valueOf(1), "Geeks",
                                               Integer.valueOf(2), "For",
                                               Integer.valueOf(3), "Geeks"
                                               );
• Using with() method: Syntax:

  NthTuple<type 1, type 2, .., type n> nthTuple 
      = NthTuple.with(value 1, value 2, .., value n);
  

  Example:

  Pair<Integer, String> pair = Pair.with(Integer.valurOf(1), "Geeks");
  
  Sextet<Integer, String, Integer, String, Integer, String> sextet
      = Sextet.with(Integer.valueOf(1), "Geeks",
                    Integer.valueOf(2), "For",
                    Integer.valueOf(3), "Geeks");
• From other collections: Syntax:

  NthTuple<type, type, .., type> nthTuple 
           = NthTuple.fromCollection(collectionWith_n_values);
  

  Example:

  Pair<String, String> pair = Pair.fromCollection(collectionWith2Values);
  
  Sextet<Integer, String, Integer, String, Integer, String> sextet
      = Sextet.fromCollection(collectionWith6Values);

Getting JavaTuples values

• Syntax:

  NthTuple<type 1, type 2, .., type n> nthTuple = new NthTuple
                  <type 1, type 2, .., type n>(value 1, value 2, .., value n);
  typeX valX = nthTuple.getValueX-1();
  

• Example:

  Pair < Integer, String >
  pair = new Pair<Integer, String>(Integer.valurOf(1), "Geeks");
  
  // This will set val2 = "Geeks"
  String val2 = pair.getValue1();
  
  Sextet<Integer, String, Integer, String, Integer, String> sextet
      = new Sextet<Integer, String, Integer, String, Integer, String>(
                                          Integer.valueOf(1), "Geeks",
                                          Integer.valueOf(2), "For",
                                          Integer.valueOf(3), "Geeks"
                                          );
  
  // This will set val5 = 3
  Integer val5 = sextet.getValue4();
  Note:
  • Value numbering starts with index 0. Hence for nth value, the getter will be getValuen-1()
  • NthTuple object can only have getValue0() to getValuen-1() valid getters (e.g. Sextet does not have a getValue6() method).
  • All getValueX() getters are typesafe, i.e. no cast needed. It is because of the type parameterization of the tuple classes (the “” in Triplet) the compiler will know that value0 is of type A, value1 of type B, and so on.
  • 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 a cast will be needed: Triplet<String, Integer, Double> triplet = … … Integer intVal = (Integer) triplet.getValue(1);
• Classes KeyValue and LabelValue have their getValue0()/getValue1() methods renamed as getKey()/getValue() and getLabel()/getValue(), respectively.

Setting JavaTuples values

Since the JavaTuples are immutable, it means that modifying a value at any index is not possible. Hence JavaTuples offer setAtX(value) which creates a copy of the Tuple with a new value at index X, and returns that Tuple. Syntax:

NthTuple<type 1, type 2, .., type n> nthTuple = new NthTuple
                <type 1, type 2, .., type n>(value 1, value 2, .., value n);
nthTuple = nthTuple.setAtX(val);

Example:

Pair<Integer, String> pair = new Pair<Integer, String>(
                            Integer.valueOf(1), "Geeks");

pair = pair.setAt1("For"); // This will return a pair (1, "For")

Sextet<Integer, String, Integer, String, Integer, String> sextet
    = new Sextet<Integer, String, Integer, String, Integer, String>(
                                        Integer.valueOf(1), "Geeks",
                                        Integer.valueOf(2), "For",
                                        Integer.valueOf(3), "Geeks"
                                        );

// This will return sextet (1, "Geeks", 2, "For", 3, "Everyone")
Sextet<Integer, String, Integer, String, Integer, String> otherSextet
    = sextet.setAt5("Everyone");

Iterating JavaTuple values

All tuple classes in javatuples implement the Iterable<Object> interface. It means that they can be iterated in the same way as collections or arrays. Example:

Triplet<String, Integer, Double> triplet = ......

for (Object value : tuple)
{
    ...
}