https://github.com/arxila/javatuples
A complete implementation of tuple data structures for Java.
https://github.com/arxila/javatuples
data-structures java tuples
Last synced: about 1 month ago
JSON representation
A complete implementation of tuple data structures for Java.
- Host: GitHub
- URL: https://github.com/arxila/javatuples
- Owner: arxila
- License: apache-2.0
- Created: 2025-08-12T17:51:38.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-09-04T20:51:10.000Z (6 months ago)
- Last Synced: 2025-12-01T23:51:59.207Z (3 months ago)
- Topics: data-structures, java, tuples
- Language: Java
- Homepage: https://javatuples.arxila.io
- Size: 257 KB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
- Notice: NOTICE.txt
Awesome Lists containing this project
- useful-java-links - javatuples - javatuples is one of the simplest java libraries ever made. Its aim is to provide a set of java classes that allow you to work with tuples.A tuple is just a sequence of objects that do not necessarily relate to each other in any way. For example: [23, "Saturn", java.sql.Connection@li734s] can be considered a tuple of three elements (a triplet) containing an Integer, a String, and a JDBC Connection object. License: [Apache 2](http://www.apache.org/licenses/LICENSE-2.0).  (I. Development / 6. Useful libraries)
README
JavaTuples
==========
JavaTuples is a simple Java library that provides a set of tuple classes. It includes:
* A general tuple interface: `io.arxila.javatuples.Tuple`
* A set of _named_ tuple classes: `Empty`, `Solo`, `Pair`, `Trio`, `Quartet`, `Quintet`, `Sextet`, `Septet`, `Octet`, `Nonet`, `Decet`
* A set of _numbered_ tuple classes: `Tuple0`, `Tuple1`, `Tuple2`, `Tuple3`, `Tuple4`, `Tuple5`, `Tuple6`, `Tuple7`, `Tuple8`, `Tuple9`, `Tuple10`
* Some common tuple-shaped utility classes: `KeyValue`, `LabelValue`, `MapEntry`
All tuples are **immutable**, and therefore **thread-safe**. They are also **iterable**
and **serializable**. Tuples are implemented as Java [records](https://docs.oracle.com/en/java/javase/17/language/records.html).
JavaTuples is open-source and distributed under the **Apache License 2.0**.
> [!NOTE]
> This library is a new incarnation of the previous `org.javatuples` library which could be previously found
> at [javatuples](https://github.com/javatuples/javatuples). This new library starts at version 2.x, it is a
> complete rewrite of the previous one and it is not backward compatible.
Requirements
------------
JavaTuples requires **Java 17**.
Maven Info
----------
Library dependency: `io.arxila.javatuples:javatuples:{version}`
From Maven:
```xml
io.arxila.javatuples
javatuples
{version}
```
Tuples
------
A tuple is just a sequence of objects that do not necessarily relate to each other in any way. For
example, `[23, "Saturn", java.sql.Connection@li734s]` can be considered a tuple of three elements (a triple,
or _trio_) containing an `Integer`, a `String`, and a JDBC `Connection` object.
JavaTuples offers two types of tuples: **named** and **numbered**. Named tuples have names that represent
their arity (e.g. `Trio`), while numbered tuples include arity in their names (e.g. `Tuple3`). All
tuple implementations reside in the `io.arxila.javatuples` package, and they all implement
the `io.arxila.javatuples.Tuple` interface.
Named tuples are:
* `Empty` (0 elements)
* `Solo` (1 element)
* `Pair` (2 elements)
* `Trio` (3 elements)
* `Quartet` (4 elements)
* `Quintet` (5 elements)
* `Sextet` (6 elements)
* `Septet` (7 elements)
* `Octet` (8 elements)
* `Nonet` (9 elements)
* `Decet` (10 elements)
Numbered tuples are:
* `Tuple0` (0 elements)
* `Tuple1` (1 element)
* `Tuple2` (2 elements)
* `Tuple3` (3 elements)
* `Tuple4` (4 elements)
* `Tuple5` (5 elements)
* `Tuple6` (6 elements)
* `Tuple7` (7 elements)
* `Tuple8` (8 elements)
* `Tuple9` (9 elements)
* `Tuple10` (10 elements)
Additionally, JavaTuples provides a small set of tuple-shaped utility classes:
* `KeyValue`
* `LabelValue`
* `MapEntry` (implements the `java.util.Map.Entry` interface)
Usage
-----
### Creating Tuples
Tuples are easy to create using constructors:
```java
// Named tuples
var pair = new Pair<>("Hello", 42); // pair : Pair
var trio = new Trio<>("A", "B", "C"); // trio : Trio
// Numbered tuples
var tuple2 = new Tuple2<>("Hello", 42); // tuple2 : Tuple2
```
Or using static `of(...)` factory methods:
```java
// Named tuples
var pair = Pair.of("Hello", 42); // pair : Pair
var trio = Trio.of("A", "B", "C"); // trio : Trio
// Numbered tuples
var tuple2 = Tuple2.of("Hello", 42); // tuple2 : Tuple2
```
They can also be created from arrays or lists of the exact size, though in that case, all elements of
the tuple are treated as the same type (the component type of the array or list):
```java
var valuesList = List.of("Hello", 42); // valuesList: List (effectively)
var valuesArray = new String[] {"A", "B", "C"}; // valuesArray: String[]
// ...
var pair = Pair.of(valuesList); // pair : Pair
var trio = Trio.of(valuesArray); // trio : Trio
```
### Accessing Values
Values in tuples are numbered from 0 to N-1, and can be accessed using the `valueN()` methods:
```java
// Direct access
String value0 = pair.value0();
Integer value1 = pair.value1();
Long value9 = decet.value9();
// All values as a list
var values = tuple.values(); // values: List
```
Tuples are also iterable and provide several useful `contains*` methods:
```java
// Iteration
for (final Object value : tuple) {
// ...do things
}
// Contains methods
if (tuple.contains("Hello")) {...} // true if a single value is contained in the tuple
if (tuple.containsAll("Hello", 42)) {...} // true if all specified values are contained in the tuple
if (tuple.containsAny(41,4 2)) {...} // true if any of the specified values are contained in the tuple
```
An `equalsIgnoreOrder()` method is also provided to compare tuples ignoring the order of their values:
```java
if (tuple.equalsIgnoreOrder(otherTuple)) {...} // true if tuples contain the same values in any order
```
### Modifying Values
Tuples are immutable, but you can create new instances with modified contents using _wither_ methods
(methods that return a new tuple with one value replaced):
```java
var pair = Pair.of("Hello", 42); // Pair("Hello", 42)
var newPair = pair.withValue1("World"); // Pair("Hello", "World")
```
### Growing and Shrinking
Adding a new element at index N (`withValueN(...)`) will grow the tuple: a new tuple one element
larger is created, with the new element appended.
Removing an element from any index (`withoutValueX(...)`) will shrink the tuple: a new tuple one
element smaller is created, with that element removed.
```java
var pair = Pair.of("Hello", 42); // Pair
var trio = pair.withValue2("!"); // Grow to Trio
var solo = pair.withoutValue1(); // Shrink to Solo
```