1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * https://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.lang3.tuple;
18
19 import java.io.Serializable;
20 import java.util.Map;
21 import java.util.Objects;
22
23 import org.apache.commons.lang3.builder.CompareToBuilder;
24 import org.apache.commons.lang3.function.FailableBiConsumer;
25 import org.apache.commons.lang3.function.FailableBiFunction;
26
27 /**
28 * A pair consisting of two elements.
29 *
30 * <p>This class is an abstract implementation defining the basic API.
31 * It refers to the elements as 'left' and 'right'. It also implements the
32 * {@code Map.Entry} interface where the key is 'left' and the value is 'right'.</p>
33 *
34 * <p>Subclass implementations may be mutable or immutable.
35 * However, there is no restriction on the type of the stored objects that may be stored.
36 * If mutable objects are stored in the pair, then the pair itself effectively becomes mutable.</p>
37 *
38 * @param <L> the left element type.
39 * @param <R> the right element type.
40 * @since 3.0
41 */
42 public abstract class Pair<L, R> implements Map.Entry<L, R>, Comparable<Pair<L, R>>, Serializable {
43
44 /** Serialization version */
45 private static final long serialVersionUID = 4954918890077093841L;
46
47 /**
48 * An empty array.
49 * <p>
50 * Consider using {@link #emptyArray()} to avoid generics warnings.
51 * </p>
52 *
53 * @since 3.10
54 */
55 public static final Pair<?, ?>[] EMPTY_ARRAY = {};
56
57 /**
58 * Returns the empty array singleton that can be assigned without compiler warning.
59 *
60 * @param <L> the left element type.
61 * @param <R> the right element type.
62 * @return the empty array singleton that can be assigned without compiler warning.
63 * @since 3.10
64 */
65 @SuppressWarnings("unchecked")
66 public static <L, R> Pair<L, R>[] emptyArray() {
67 return (Pair<L, R>[]) EMPTY_ARRAY;
68 }
69
70 /**
71 * Creates an immutable pair of two objects inferring the generic types.
72 *
73 * <p>This factory allows the pair to be created using inference to
74 * obtain the generic types.</p>
75 *
76 * @param <L> the left element type.
77 * @param <R> the right element type.
78 * @param left the left element, may be null.
79 * @param right the right element, may be null.
80 * @return a pair formed from the two parameters, not null.
81 */
82 public static <L, R> Pair<L, R> of(final L left, final R right) {
83 return ImmutablePair.of(left, right);
84 }
85
86 /**
87 * Creates an immutable pair from a map entry.
88 *
89 * <p>This factory allows the pair to be created using inference to
90 * obtain the generic types.</p>
91 *
92 * @param <L> the left element type.
93 * @param <R> the right element type.
94 * @param pair the map entry.
95 * @return a pair formed from the map entry.
96 * @since 3.10
97 */
98 public static <L, R> Pair<L, R> of(final Map.Entry<L, R> pair) {
99 return ImmutablePair.of(pair);
100 }
101
102 /**
103 * Creates an immutable pair of two non-null objects inferring the generic types.
104 *
105 * <p>This factory allows the pair to be created using inference to
106 * obtain the generic types.</p>
107 *
108 * @param <L> the left element type.
109 * @param <R> the right element type.
110 * @param left the left element, may not be null.
111 * @param right the right element, may not be null.
112 * @return a pair formed from the two parameters, not null.
113 * @throws NullPointerException if any input is null.
114 * @since 3.13.0
115 */
116 public static <L, R> Pair<L, R> ofNonNull(final L left, final R right) {
117 return ImmutablePair.ofNonNull(left, right);
118 }
119
120 /**
121 * Constructs a new instance.
122 */
123 public Pair() {
124 // empty
125 }
126
127 /**
128 * Accepts this key and value as arguments to the given consumer.
129 *
130 * @param <E> The kind of thrown exception or error.
131 * @param consumer the consumer to call.
132 * @throws E Thrown when the consumer fails.
133 * @since 3.13.0
134 */
135 public <E extends Throwable> void accept(final FailableBiConsumer<L, R, E> consumer) throws E {
136 consumer.accept(getKey(), getValue());
137 }
138
139 /**
140 * Applies this key and value as arguments to the given function.
141 *
142 * @param <V> The function return type.
143 * @param <E> The kind of thrown exception or error.
144 * @param function the consumer to call.
145 * @return the function's return value.
146 * @throws E Thrown when the consumer fails.
147 * @since 3.13.0
148 */
149 public <V, E extends Throwable> V apply(final FailableBiFunction<L, R, V, E> function) throws E {
150 return function.apply(getKey(), getValue());
151 }
152
153 /**
154 * Compares the pair based on the left element followed by the right element.
155 * The types must be {@link Comparable}.
156 *
157 * @param other the other pair, not null.
158 * @return negative if this is less, zero if equal, positive if greater.
159 */
160 @Override
161 public int compareTo(final Pair<L, R> other) {
162 // @formatter:off
163 return new CompareToBuilder()
164 .append(getLeft(), other.getLeft())
165 .append(getRight(), other.getRight())
166 .toComparison();
167 // @formatter:on
168 }
169
170 /**
171 * Compares this pair to another based on the two elements.
172 *
173 * @param obj the object to compare to, null returns false.
174 * @return true if the elements of the pair are equal.
175 */
176 @Override
177 public boolean equals(final Object obj) {
178 if (obj == this) {
179 return true;
180 }
181 if (obj instanceof Map.Entry<?, ?>) {
182 final Map.Entry<?, ?> other = (Map.Entry<?, ?>) obj;
183 return Objects.equals(getKey(), other.getKey())
184 && Objects.equals(getValue(), other.getValue());
185 }
186 return false;
187 }
188
189 /**
190 * Gets the key from this pair.
191 *
192 * <p>This method implements the {@code Map.Entry} interface returning the
193 * left element as the key.</p>
194 *
195 * @return the left element as the key, may be null.
196 */
197 @Override
198 public final L getKey() {
199 return getLeft();
200 }
201
202 /**
203 * Gets the left element from this pair.
204 *
205 * <p>When treated as a key-value pair, this is the key.</p>
206 *
207 * @return the left element, may be null.
208 */
209 public abstract L getLeft();
210
211 /**
212 * Gets the right element from this pair.
213 *
214 * <p>When treated as a key-value pair, this is the value.</p>
215 *
216 * @return the right element, may be null.
217 */
218 public abstract R getRight();
219
220 /**
221 * Gets the value from this pair.
222 *
223 * <p>This method implements the {@code Map.Entry} interface returning the
224 * right element as the value.</p>
225 *
226 * @return the right element as the value, may be null.
227 */
228 @Override
229 public R getValue() {
230 return getRight();
231 }
232
233 /**
234 * Returns a suitable hash code.
235 * <p>
236 * The hash code follows the definition in {@code Map.Entry}.
237 * </p>
238 *
239 * @return the hash code.
240 */
241 @Override
242 public int hashCode() {
243 // See Map.Entry API specification
244 return Objects.hashCode(getKey()) ^ Objects.hashCode(getValue());
245 }
246
247 /**
248 * Returns a String representation of this pair using the format {@code (left,right)}.
249 *
250 * @return a string describing this object, not null.
251 */
252 @Override
253 public String toString() {
254 return "(" + getLeft() + ',' + getRight() + ')';
255 }
256
257 /**
258 * Formats the receiver using the given format.
259 *
260 * <p>
261 * This uses {@link String#format(String, Object...)} to the format. Two variables may be used to embed the left and right elements. Use {@code %1$s} for
262 * the left element (key) and {@code %2$s} for the right element (value).
263 * </p>
264 *
265 * @param format the format string, optionally containing {@code %1$s} and {@code %2$s}, not null.
266 * @return the formatted string, not null.
267 * @see String#format(String, Object...)
268 */
269 public String toString(final String format) {
270 return String.format(format, getLeft(), getRight());
271 }
272
273 }