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 * http://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 * 41 * @since 3.0 42 */ 43 public abstract class Pair<L, R> implements Map.Entry<L, R>, Comparable<Pair<L, R>>, Serializable { 44 45 /** Serialization version */ 46 private static final long serialVersionUID = 4954918890077093841L; 47 48 /** 49 * An empty array. 50 * <p> 51 * Consider using {@link #emptyArray()} to avoid generics warnings. 52 * </p> 53 * 54 * @since 3.10. 55 */ 56 public static final Pair<?, ?>[] EMPTY_ARRAY = {}; 57 58 /** 59 * Returns the empty array singleton that can be assigned without compiler warning. 60 * 61 * @param <L> the left element type 62 * @param <R> the right element type 63 * @return the empty array singleton that can be assigned without compiler warning. 64 * 65 * @since 3.10. 66 */ 67 @SuppressWarnings("unchecked") 68 public static <L, R> Pair<L, R>[] emptyArray() { 69 return (Pair<L, R>[]) EMPTY_ARRAY; 70 } 71 72 /** 73 * Creates an immutable pair of two objects inferring the generic types. 74 * 75 * <p>This factory allows the pair to be created using inference to 76 * obtain the generic types.</p> 77 * 78 * @param <L> the left element type 79 * @param <R> the right element type 80 * @param left the left element, may be null 81 * @param right the right element, may be null 82 * @return a pair formed from the two parameters, not null 83 */ 84 public static <L, R> Pair<L, R> of(final L left, final R right) { 85 return ImmutablePair.of(left, right); 86 } 87 88 /** 89 * Creates an immutable pair from a map entry. 90 * 91 * <p>This factory allows the pair to be created using inference to 92 * obtain the generic types.</p> 93 * 94 * @param <L> the left element type 95 * @param <R> the right element type 96 * @param pair the map entry. 97 * @return a pair formed from the map entry 98 * @since 3.10 99 */ 100 public static <L, R> Pair<L, R> of(final Map.Entry<L, R> pair) { 101 return ImmutablePair.of(pair); 102 } 103 104 /** 105 * Creates an immutable pair of two non-null objects inferring the generic types. 106 * 107 * <p>This factory allows the pair to be created using inference to 108 * obtain the generic types.</p> 109 * 110 * @param <L> the left element type 111 * @param <R> the right element type 112 * @param left the left element, may not be null 113 * @param right the right element, may not be null 114 * @return a pair formed from the two parameters, not null 115 * @throws NullPointerException if any input is null 116 * @since 3.13.0 117 */ 118 public static <L, R> Pair<L, R> ofNonNull(final L left, final R right) { 119 return ImmutablePair.ofNonNull(left, right); 120 } 121 122 /** 123 * Accepts this key and value as arguments to the given consumer. 124 * 125 * @param <E> The kind of thrown exception or error. 126 * @param consumer the consumer to call. 127 * @throws E Thrown when the consumer fails. 128 * @since 3.13.0 129 */ 130 public <E extends Throwable> void accept(final FailableBiConsumer<L, R, E> consumer) throws E { 131 consumer.accept(getKey(), getValue()); 132 } 133 134 /** 135 * Applies this key and value as arguments to the given function. 136 * 137 * @param <V> The function return type. 138 * @param <E> The kind of thrown exception or error. 139 * @param function the consumer to call. 140 * @return the function's return value. 141 * @throws E Thrown when the consumer fails. 142 * @since 3.13.0 143 */ 144 public <V, E extends Throwable> V apply(final FailableBiFunction<L, R, V, E> function) throws E { 145 return function.apply(getKey(), getValue()); 146 } 147 148 /** 149 * Compares the pair based on the left element followed by the right element. 150 * The types must be {@link Comparable}. 151 * 152 * @param other the other pair, not null 153 * @return negative if this is less, zero if equal, positive if greater 154 */ 155 @Override 156 public int compareTo(final Pair<L, R> other) { 157 return new CompareToBuilder().append(getLeft(), other.getLeft()) 158 .append(getRight(), other.getRight()).toComparison(); 159 } 160 161 /** 162 * Compares this pair to another based on the two elements. 163 * 164 * @param obj the object to compare to, null returns false 165 * @return true if the elements of the pair are equal 166 */ 167 @Override 168 public boolean equals(final Object obj) { 169 if (obj == this) { 170 return true; 171 } 172 if (obj instanceof Map.Entry<?, ?>) { 173 final Map.Entry<?, ?> other = (Map.Entry<?, ?>) obj; 174 return Objects.equals(getKey(), other.getKey()) 175 && Objects.equals(getValue(), other.getValue()); 176 } 177 return false; 178 } 179 180 /** 181 * Gets the key from this pair. 182 * 183 * <p>This method implements the {@code Map.Entry} interface returning the 184 * left element as the key.</p> 185 * 186 * @return the left element as the key, may be null 187 */ 188 @Override 189 public final L getKey() { 190 return getLeft(); 191 } 192 193 /** 194 * Gets the left element from this pair. 195 * 196 * <p>When treated as a key-value pair, this is the key.</p> 197 * 198 * @return the left element, may be null 199 */ 200 public abstract L getLeft(); 201 202 /** 203 * Gets the right element from this pair. 204 * 205 * <p>When treated as a key-value pair, this is the value.</p> 206 * 207 * @return the right element, may be null 208 */ 209 public abstract R getRight(); 210 211 /** 212 * Gets the value from this pair. 213 * 214 * <p>This method implements the {@code Map.Entry} interface returning the 215 * right element as the value.</p> 216 * 217 * @return the right element as the value, may be null 218 */ 219 @Override 220 public R getValue() { 221 return getRight(); 222 } 223 224 /** 225 * Returns a suitable hash code. 226 * The hash code follows the definition in {@code Map.Entry}. 227 * 228 * @return the hash code 229 */ 230 @Override 231 public int hashCode() { 232 // see Map.Entry API specification 233 return Objects.hashCode(getKey()) ^ Objects.hashCode(getValue()); 234 } 235 236 /** 237 * Returns a String representation of this pair using the format {@code ($left,$right)}. 238 * 239 * @return a string describing this object, not null 240 */ 241 @Override 242 public String toString() { 243 return "(" + getLeft() + ',' + getRight() + ')'; 244 } 245 246 /** 247 * Formats the receiver using the given format. 248 * 249 * <p>This uses {@link java.util.Formattable} to perform the formatting. Two variables may 250 * be used to embed the left and right elements. Use {@code %1$s} for the left 251 * element (key) and {@code %2$s} for the right element (value). 252 * The default format used by {@code toString()} is {@code (%1$s,%2$s)}.</p> 253 * 254 * @param format the format string, optionally containing {@code %1$s} and {@code %2$s}, not null 255 * @return the formatted string, not null 256 */ 257 public String toString(final String format) { 258 return String.format(format, getLeft(), getRight()); 259 } 260 261 }