Introduction to Javatuples – Javatuples简介

最后修改: 2017年 3月 15日

中文/混合/英文(键盘快捷键：t)

1. Overview

1.概述

A tuple is a collection of several elements that may or may not be related to each other. In other words, tuples can be considered anonymous objects.

一个元组是若干元素的集合，这些元素之间可能有关系，也可能没有关系。换句话说，元组可以被认为是匿名的对象。

For example, [“RAM”, 16, “Astra”] is a tuple containing three elements.

例如，[“RAM”, 16, “Astra”]是一个包含三个元素的元组。

In this article, we will have a quick look at a really simple library that allows us to work with the tuple based data structures, named javatuples.

在这篇文章中，我们将快速浏览一个非常简单的库，它允许我们使用基于元组的数据结构，名为javatuples。

2. Built-in Javatuples Classes

2.内置Javatuples Classes

This library provides us ten different classes that would suffice most of our requirements related to tuples:

这个库为我们提供了十个不同的类，足以满足我们与图元有关的大部分要求。

  • Unit<A>
  • Pair<A,B>
  • Triplet<A,B,C>
  • Quartet<A,B,C,D>
  • Quintet<A,B,C,D,E>
  • Sextet<A,B,C,D,E,F>
  • Septet<A,B,C,D,E,F,G>
  • Octet<A,B,C,D,E,F,G,H>
  • Ennead<A,B,C,D,E,F,G,H,I>
  • Decade<A,B,C,D,E,F,G,H,I,J>

In addition to the classes above, there are two additional classes, KeyValue<A,B> and LabelValue<A,B>, which provide functionalities similar to Pair<A,B>, but differ in semantics.

除了上面的类，还有两个额外的类，KeyValue<A,B>和LabelValue<A,B>，它们提供的功能与Pair<A,B>相似，但在语义上有所不同。

As per the official site, all the classes in javatuples are typesafe and immutable. Each of the tuple class implements the Iterable, Serializable, and Comparable interface.

根据官方网站，javatuples中的所有类都是类型安全和不可变的。每个元组类都实现了Iterable、Serializable和Comparable接口。

3. Adding Maven Dependency

3.添加Maven的依赖性

Let’s add the Maven dependency to our pom.xml:

让我们把Maven的依赖性添加到pom.xml中。

<dependency>
    <groupId>org.javatuples</groupId>
    <artifactId>javatuples</artifactId>
    <version>1.2</version>
</dependency>

Please check the Central Maven repository for the latest version.

请检查中央Maven仓库，查看最新版本。

4. Creating Tuples

4.创建图元

Creating a tuple is really simple. We can use the corresponding constructors:

创建一个元组真的很简单。我们可以使用相应的构造函数。

Pair<String, Integer> pair = new Pair<String, Integer>("A pair", 55);

There is also a little less verbose and semantically elegant way of creating a tuple:

还有一种不那么啰嗦的、语义上优雅的创建元组的方法。

Triplet<String, Integer, Double> triplet = Triplet.with("hello", 23, 1.2);

We can also create tuples from an Iterable:

我们也可以从一个Iterable中创建图元。

List<String> listOfNames = Arrays.asList("john", "doe", "anne", "alex");
Quartet<String, String, String, String> quartet
  = Quartet.fromCollection(collectionOfNames);

Please note that the number of items in the collection should match the type of the tuple that we want to create. For example, we cannot create a Quintet using the above collection as it requires exactly five elements. Same is true for any other tuple class having a higher order than Quintet.

请注意，集合中的项目数量应该与我们想要创建的元组的类型相匹配。例如，我们不能用上述集合创建一个Quintet，因为它正好需要五个元素。对于任何其他比Quintet更高阶的元组类也是如此。

However, we can create a lower order tuple like Pair or a Triplet using the above collection, by specifying a starting index in the fromIterable() method:

然而，我们可以通过在fromIterable()方法中指定一个起始索引，使用上述集合创建一个低阶元组，如Pair或Triplet。

Pair<String, String> pairFromList = Pair.fromIterable(listOfNames, 2);

The above code will result in creating a Pair containing “anne” and “alex“.

上述代码将导致创建一个Pair，其中包含”anne“和”alex“。

Tuples can be conveniently created from any array as well:

Tuples也可以方便地从任何数组中创建。

String[] names = new String[] {"john", "doe", "anne"};
Triplet<String, String, String> triplet2 = Triplet.fromArray(names);

5. Getting Values from Tuples

5.从图元中获取数值

Every class in javatuples has a getValueX() method for getting the values from tuples, where X specifies the order of the element inside the tuple. Like the indexes in arrays, the value of X starts from zero.

javatuples中的每个类都有一个getValueX()方法，用于从元组中获取值，其中X指定元组中元素的顺序。和数组中的索引一样，X的值从零开始。

Let’s create a new Quartet and fetch some values:

让我们创建一个新的Quartet并获取一些值。

Quartet<String, Double, Integer, String> quartet 
  = Quartet.with("john", 72.5, 32, "1051 SW");

String name = quartet.getValue0();
Integer age = quartet.getValue2();
 
assertThat(name).isEqualTo("john");
assertThat(age).isEqualTo(32);

As we can see, the position of “john” is zero, “72.5” is one, and so on.

我们可以看到，”john“的位置是0，”72.5“是1，以此类推。

Note that the getValueX() methods are type-safe. That means, no casting is required.

请注意，getValueX()方法是类型安全的。这意味着，不需要铸造。

An alternative to this is the getValue(int pos) method. It takes a zero-based position of the element to be fetched. This method is not type-safe and requires explicit casting:

一个替代方法是getValue(int pos)方法。它需要一个基于零的要获取的元素的位置。这个方法不是类型安全的，需要显式铸造。

Quartet<String, Double, Integer, String> quartet 
  = Quartet.with("john", 72.5, 32, "1051 SW");

String name = (String) quartet.getValue(0);
Integer age = (Integer) quartet.getValue(2);
 
assertThat(name).isEqualTo("john");
assertThat(age).isEqualTo(32);

Please note that the classes KeyValue and LabelValue have their corresponding methods getKey()/getValue() and getLabel()/getValue().

请注意，类KeyValue和LabelValue有其相应的方法getKey()/getValue()和getLabel()/getValue()。

6. Setting Values to Tuples

6.为图元设置数值

Similar to getValueX(), all classes in javatuples have setAtX() methods. Again, X is zero-based positions for the element that we want to set:

与getValueX()类似，javatuples的所有类都有setAtX()方法。同样，X是我们想要设置的元素的零基位置。

Pair<String, Integer> john = Pair.with("john", 32);
Pair<String, Integer> alex = john.setAt0("alex");

assertThat(john.toString()).isNotEqualTo(alex.toString());

The important thing here is that the return type of setAtX() method is the tuple type itself. This is because the javatuples are immutable. Setting any new value will leave the original instance intact.

这里重要的是，setAtX()方法的返回类型是元组类型本身。这是因为javatuples是不可变的。设置任何新的值都会使原来的实例保持不变。

7. Adding and Removing Elements from Tuples

7.从图元中添加和删除元素

We can conveniently add new elements to the tuples. However, this will result in a new tuple of one order higher being created:

我们可以方便地将新元素添加到图元中。然而，这将导致一个高一阶的新元组被创建。

Pair<String, Integer> pair1 = Pair.with("john", 32);
Triplet<String, Integer, String> triplet1 = pair1.add("1051 SW");

assertThat(triplet1.contains("john"));
assertThat(triplet1.contains(32));
assertThat(triplet1.contains("1051 SW"));

It is clear from the above example that adding one element to a Pair will create a new Triplet. Similarly, adding one element to a Triplet will create a new Quartet.

从上面的例子可以看出，向Pair添加一个元素将创建一个新的Triplet。同样，在一个Triplet中添加一个元素将创建一个新的Quartet。

The example above also demonstrates the use of contains() method provided by all the classes in javatuples. This is a really handy method for verifying if the tuple contains a given value.

上面的例子还演示了contains()方法的使用，该方法由javatuples中的所有类提供。这是一个非常方便的方法，用于验证元组是否包含一个给定的值。

It is also possible to add one tuple to another using the add() method:

也可以使用add()方法将一个元组添加到另一个元组。

Pair<String, Integer> pair1 = Pair.with("john", 32);
Pair<String, Integer> pair2 = Pair.with("alex", 45);
Quartet<String, Integer, String, Integer> quartet2 = pair1.add(pair2);

assertThat(quartet2.containsAll(pair1));
assertThat(quartet2.containsAll(pair2));

Note the use of containsAll() method. It will return true if all the elements of pair1 are present in quartet2.

注意使用containsAll()方法。如果pair1的所有元素都存在于quartet2中，它将返回true。

By default, the add() method adds the element as a last element of the tuple. However, it is possible to add the element at a given position using addAtX() method, where X is the zero-based position where we want to add the element:

默认情况下，add()方法将元素添加为元组的最后一个元素。然而，我们可以使用addAtX()方法在指定的位置添加元素，其中X是我们想要添加元素的基于零的位置。

Pair<String, Integer> pair1 = Pair.with("john", 32);
Triplet<String, String, Integer> triplet2 = pair1.addAt1("1051 SW");

assertThat(triplet2.indexOf("john")).isEqualTo(0);
assertThat(triplet2.indexOf("1051 SW")).isEqualTo(1);
assertThat(triplet2.indexOf(32)).isEqualTo(2);

This example adds the String at position 1, which is then verified by the indexOf() method. Please note the difference in order of the types for the Pair<String, Integer> and the Triplet<String, String, Integer> after the call to addAt1() method call.

这个例子在位置1添加了String，然后通过indexOf()方法进行验证。请注意在调用addAt1()方法后，Pair<String, Integer>和Triplet<String, String, Integer>的类型顺序不同。

We can also add multiple elements using any of add() or addAtX() methods:

我们还可以使用add()或addAtX()中的任何一个方法添加多个元素。

Pair<String, Integer> pair1 = Pair.with("john", 32);
Quartet<String, Integer, String, Integer> quartet1 = pair1.add("alex", 45);

assertThat(quartet1.containsAll("alex", "john", 32, 45));

In order to remove an element from the tuple, we can use the removeFromX() method. Again, X specifies the zero-based position of the element to be removed:

为了从元组中移除一个元素，我们可以使用removeFromX()方法。同样，X指定了要移除的元素的零基位置。

Pair<String, Integer> pair1 = Pair.with("john", 32);
Unit<Integer> unit = pair1.removeFrom0();

assertThat(unit.contains(32));

8. Converting Tuples to List/Array

8.将图元转换为List/Array

We have already seen how to convert a List to a tuple. Let’s now see hot to convert a tuple to a List:

我们已经看到了如何将一个List转换为一个元组。现在让我们看看如何将一个元组转换为List。

Quartet<String, Double, Integer, String> quartet
  = Quartet.with("john", 72.5, 32, "1051 SW");
List<Object> list = quartet.toList();

assertThat(list.size()).isEqualTo(4);

It is fairly simple. The only thing to note here is that we will always get a List<Object>, even if the tuple contains the same type of elements.

这是很简单的。这里唯一需要注意的是，我们将总是得到一个List<Object>,，即使元组包含相同类型的元素。

Finally, let’s convert the tuple to an array:

最后，让我们把元组转换为数组。

Quartet<String, Double, Integer, String> quartet
  = Quartet.with("john", 72.5, 32, "1051 SW");
Object[] array = quartet.toArray();

assertThat(array.length).isEqualTo(4);

Clear enough, the toArray() method always returns an Object[].

很清楚，toArray()方法总是返回一个Object[]。

9. Conclusion

9.结论

In this article, we have explored the javatuples library and observed it’s simplicity. It provides elegant semantics and is really easy to use.

在这篇文章中，我们探讨了javatuples库并观察了它的简单性。它提供了优雅的语义，而且真的很容易使用。

Make sure you check out the complete source code for this article over on GitHub. The complete source code contains a little more examples than the ones covered here. After reading this article, the additional examples should be easy enough to understand.

请确保您在GitHub上查看本文的完整源代码。完整的源代码包含比这里所涉及的更多的例子。在阅读本文后，其他的例子应该很容易理解。