-
Notifications
You must be signed in to change notification settings - Fork 1
/
using.html
executable file
·180 lines (169 loc) · 13.2 KB
/
using.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!-- Generated by Apache Maven Doxia Site Renderer 1.3 at May 18, 2012 -->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>javatuples - Using javatuples</title>
<style type="text/css" media="all">
@import url("./css/maven-base.css");
@import url("./css/maven-theme.css");
@import url("./css/site.css");
</style>
<link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
<meta name="Date-Revision-yyyymmdd" content="20120518" />
<meta http-equiv="Content-Language" content="en" />
</head>
<body class="composite">
<div id="banner">
<a href="./" id="bannerLeft">
<img src="images/javatuples_logo.png" alt="javatuples" />
</a>
<div class="clear">
<hr/>
</div>
</div>
<div id="breadcrumbs">
<div class="xleft">
<span id="publishDate">Last Published: 18 May 2012</span>
| <span id="projectVersion">Version: 1.2</span>
</div>
<div class="xright"> <a href="index.html" title="Main">Main</a>
|
<a href="download.html" title="Download">Download</a>
|
<a href="apidocs/index.html" title="Javadoc">Javadoc</a>
|
<a href="https://github.com/javatuples/javatuples" class="externalLink" title="Github Repository">Github Repository</a>
</div>
<div class="clear">
<hr/>
</div>
</div>
<div id="leftColumn">
<div id="navcolumn">
<h5>The javatuples Project</h5>
<ul>
<li class="none">
<a href="index.html" title="· Main">· Main</a>
</li>
<li class="none">
<a href="download.html" title="· Download">· Download</a>
</li>
<li class="none">
<a href="maveninfo.html" title="· Maven Info">· Maven Info</a>
</li>
<li class="none">
<a href="dependencies.html" title="· Dependencies">· Dependencies</a>
</li>
<li class="none">
<strong>· Using javatuples</strong>
</li>
<li class="none">
<a href="https://github.com/javatuples/javatuples" class="externalLink" title="· Github Repository">· Github Repository</a>
</li>
<li class="none">
<a href="license.html" title="· License">· License</a>
</li>
<li class="none">
<a href="team.html" title="· Team">· Team</a>
</li>
<li class="none">
<a href="apidocs/index.html" title="· Javadoc">· Javadoc</a>
</li>
<li class="none">
<a href="faq.html" title="· FAQ">· FAQ</a>
</li>
</ul>
<a href="https://maven.apache.org" title="Built with Maven 2" class="poweredBy">
<img class="poweredBy" alt="Built with Maven 2" src="https://maven.apache.org/images/logos/maven-feather.png" />
</a>
</div>
</div>
<div id="bodyColumn">
<div id="contentBox">
<div class="section"><h2>Using javatuples<a name="Using_javatuples"></a></h2><div class="section"><h3>The tuple classes<a name="The_tuple_classes"></a></h3><p>There are ten tuple classes in javatuples:</p><ul><li><tt>Unit<A</tt>> (1 element)</li><li><tt>Pair<A,B</tt>> (2 elements)</li><li><tt>Triplet<A,B,C</tt>> (3 elements)</li><li><tt>Quartet<A,B,C,D</tt>> (4 elements)</li><li><tt>Quintet<A,B,C,D,E</tt>> (5 elements)</li><li><tt>Sextet<A,B,C,D,E,F</tt>> (6 elements)</li><li><tt>Septet<A,B,C,D,E,F,G</tt>> (7 elements)</li><li><tt>Octet<A,B,C,D,E,F,G,H</tt>> (8 elements)</li><li><tt>Ennead<A,B,C,D,E,F,G,H,I</tt>> (9 elements)</li><li><tt>Decade<A,B,C,D,E,F,G,H,I,J</tt>> (10 elements)</li></ul><p>Plus a couple of very common 2-element tuple classes equivalent to <tt>Pair</tt>, just for the sake of code semantics:</p><ul><li><tt>KeyValue<A,B</tt>></li><li><tt>LabelValue<A,B</tt>></li></ul><p>All tuple classes are:</p><ul><li>Typesafe</li><li>Immutable</li><li>Iterable</li><li>Serializable</li><li>Comparable (implements <tt>Comparable<Tuple</tt>>)</li><li>Implementing <tt>equals(...)</tt> and <tt>hashCode()</tt></li><li>Implementing <tt>toString()</tt></li></ul></div><div class="section"><h3>Creating tuples<a name="Creating_tuples"></a></h3><p>Tuples can be instanced in a semantically elegant way, using the <tt>with(...)</tt> methods from each of the tuple classes:</p><div><pre> 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");
</pre></div><p>Of course, constructors can also be used directly:</p><div><pre> 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");
</pre></div><p>You can also create tuples from collections or --more generally--, any iterable:</p><div><pre> 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);
</pre></div></div><div class="section"><h3>Getting values<a name="Getting_values"></a></h3><p>Values can be retrieved from a tuple by using the specific method for its position:</p><div><pre> Triplet<String,Integer,Double> triplet = ...
...
Integer intVal = triplet.getValue1();
</pre></div><p>Note that:</p><ul><li>Value numbering starts with 0, so the getter for the first position will always be <tt>getValue0()</tt>.</li><li>A tuple object will only offer you methods for the specific number of positions it holds (e.g. <tt>Quartet</tt> does not have a <tt>getValue4()</tt> method).</li><li>All <tt>getValueX()</tt> getters are typesafe, no cast needed. Thanks to the type parameterization of the tuple classes (the "<tt><A,B,C,D</tt>>" in <tt>Quartet<A,B,C,D</tt>>) the compiler will know that <i>value0</i> is of type <tt>A</tt>, <i>value1</i> of type <tt>B</tt>, and so on.</li></ul><p>There is also a <tt>getValue(int pos)</tt> 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:</p><div><pre> Triplet<String,Integer,Double> triplet = ...
...
Integer intVal = (Integer) triplet.getValue(1);
</pre></div><p>Note that classes <b>KeyValue</b> and <b>LabelValue</b> have their <tt>getValue0()</tt>/<tt>getValue1()</tt> methods renamed as <tt>getKey()</tt>/<tt>getValue()</tt> and <tt>getLabel()</tt>/<tt>getValue()</tt>, respectively.</p></div><div class="section"><h3>Setting new values<a name="Setting_new_values"></a></h3><p>In order to set new values for specific positions of a tuple, you can use the <tt>setAtX(...)</tt> setter methods:</p><div><pre> Triplet<String,Integer,Double> triplet = ...
...
triplet = triplet.setAt2(Double.valueOf(245.21));
</pre></div><p><b>Important: tuples are immutable</b>. This means that you will have to collect the return value of your <tt>setAtX(...)</tt> 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:</p><div><pre> Triplet<String,Integer,Double> triplet = ...
...
Triplet<String,Integer,String> otherTriplet = triplet.setAt2("North Atlantic");
</pre></div></div><div class="section"><h3>Adding or removing elements<a name="Adding_or_removing_elements"></a></h3><p>New elements can be added to a tuple, converting it in a different tuple. </p><p>For example, if you add a <tt>String</tt> to a <tt>Triplet<String,Integer,Double</tt>>, you will turn it into a <tt>Quartet<String,Integer,Double,String</tt>>:</p><div><pre> Triplet<String,Integer,Double> triplet = ...
...
Quartet<String,Integer,Double,String> quartet = triplet.add("South Pacific");
</pre></div><p>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 <tt>addAtX(...)</tt> methods:</p><div><pre> Triplet<String,Integer,Double> triplet = ...
...
Quartet<String,Integer,String,Double> quartet = triplet.addAt2("Mediterranean");
</pre></div><p>You can also add more than one element...</p><div><pre> Triplet<String,Integer,Double> triplet = ...
...
Quintet<String,Integer,String,String,Double> quintet = triplet.addAt2("Red Sea", "Caspian");
</pre></div><p>...or even other tuples:</p><div><pre> Triplet<String,Integer,Double> triplet1 = ...
Triplet<Byte,String[],String> triplet2 = ...
...
Sextet<String,Integer,Byte,String[],String,Double> sextet = triplet1.addAt2(triplet2);
</pre></div><p>Removing elements is just as easy, and it will also transform your tuple. If you remove an element from a <tt>Triplet</tt>, you will get a <tt>Pair</tt>:</p><div><pre> Triplet<String,Integer,Double> triplet = ...
...
Pair<String,Double> pair = triplet.removeFrom1();
</pre></div></div><div class="section"><h3>Converting to/from collections or arrays<a name="Converting_tofrom_collections_or_arrays"></a></h3><p>A tuple can be easily converted to a list or an array, but you will lose your type-safety and end up with a <tt>List<Object</tt>> or an <tt>Object[]</tt>:</p><div><pre> Triplet<String,Integer,Double> triplet = ...
...
List<Object> list = triplet.toList();
...
Object[] array = triplet.toArray();
</pre></div><p>Inversely, you can obtain a tuple from both a collection or an array:</p><div><pre> String[] array = ...
...
Quartet<String,String,String,String> quartet = Quartet.fromArray(array);
</pre></div><p>Note that your tuple will have all its elements set to the component type of the array (<tt>String</tt>, in this case). Also, note that...</p><div><pre> 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);
</pre></div><p>...will raise the following exception:</p><div><pre> java.lang.IllegalArgumentException: Array must have exactly 4 elements in order to create a Quartet. Size is 5
at ...
</pre></div></div><div class="section"><h3>Iterating<a name="Iterating"></a></h3><p>All tuple classes in javatuples implement the <tt>Iterable<Object</tt>> interface, so it can be iterated in the same way as collections or arrays:</p><div><pre> Triplet<String,Integer,Double> triplet = ...
...
for (Object value : tuple) {
...
}
</pre></div></div><div class="section"><h3>Checking contents<a name="Checking_contents"></a></h3><p>Tuples offer some utility methods, like <tt>contains(...)</tt>, <tt>containsAll(...)</tt>, <tt>indexOf(...)</tt> or <tt>lastIndexOf(...)</tt>, which work in exactly the same way as they do in collections:</p><div><pre> Quartet<String,Integer,String,Boolean> quartet = ...
...
if (quartet.contains(value)) {
...
}
...
if (quartet.containsAll(valueCollection)) {
...
}
</pre></div></div></div>
</div>
</div>
<div class="clear">
<hr/>
</div>
<div id="footer">
<div class="xright">
Copyright © 2012
<a href="https://www.javatuples.org">The JAVATUPLES team</a>.
All Rights Reserved.
</div>
<div class="clear">
<hr/>
</div>
</div>
</body>
</html>