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 25 /** 26 * A pair consisting of two elements. 27 * 28 * <p>This class is an abstract implementation defining the basic API. 29 * It refers to the elements as 'left' and 'right'. It also implements the 30 * {@code Map.Entry} interface where the key is 'left' and the value is 'right'.</p> 31 * 32 * <p>Subclass implementations may be mutable or immutable. 33 * However, there is no restriction on the type of the stored objects that may be stored. 34 * If mutable objects are stored in the pair, then the pair itself effectively becomes mutable.</p> 35 * 36 * @param <L> the left element type 37 * @param <R> the right element type 38 * 39 * @since 3.0 40 */ 41 public abstract class Pair<L, R> implements Map.Entry<L, R>, Comparable<Pair<L, R>>, Serializable { 42 43 /** Serialization version */ 44 private static final long serialVersionUID = 4954918890077093841L; 45 46 /** 47 * An empty array. 48 * <p> 49 * Consider using {@link #emptyArray()} to avoid generics warnings. 50 * </p> 51 * 52 * @since 3.10. 53 */ 54 public static final Pair<?, ?>[] EMPTY_ARRAY = {}; 55 56 /** 57 * Returns the empty array singleton that can be assigned without compiler warning. 58 * 59 * @param <L> the left element type 60 * @param <R> the right element type 61 * @return the empty array singleton that can be assigned without compiler warning. 62 * 63 * @since 3.10. 64 */ 65 @SuppressWarnings("unchecked") emptyArray()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 */ of(final L left, final R right)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 */ of(final Map.Entry<L, R> pair)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 */ ofNonNull(final L left, final R right)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 * Compares the pair based on the left element followed by the right element. 122 * The types must be {@link Comparable}. 123 * 124 * @param other the other pair, not null 125 * @return negative if this is less, zero if equal, positive if greater 126 */ 127 @Override compareTo(final Pair<L, R> other)128 public int compareTo(final Pair<L, R> other) { 129 return new CompareToBuilder().append(getLeft(), other.getLeft()) 130 .append(getRight(), other.getRight()).toComparison(); 131 } 132 133 /** 134 * Compares this pair to another based on the two elements. 135 * 136 * @param obj the object to compare to, null returns false 137 * @return true if the elements of the pair are equal 138 */ 139 @Override equals(final Object obj)140 public boolean equals(final Object obj) { 141 if (obj == this) { 142 return true; 143 } 144 if (obj instanceof Map.Entry<?, ?>) { 145 final Map.Entry<?, ?> other = (Map.Entry<?, ?>) obj; 146 return Objects.equals(getKey(), other.getKey()) 147 && Objects.equals(getValue(), other.getValue()); 148 } 149 return false; 150 } 151 152 /** 153 * Gets the key from this pair. 154 * 155 * <p>This method implements the {@code Map.Entry} interface returning the 156 * left element as the key.</p> 157 * 158 * @return the left element as the key, may be null 159 */ 160 @Override getKey()161 public final L getKey() { 162 return getLeft(); 163 } 164 165 /** 166 * Gets the left element from this pair. 167 * 168 * <p>When treated as a key-value pair, this is the key.</p> 169 * 170 * @return the left element, may be null 171 */ getLeft()172 public abstract L getLeft(); 173 174 /** 175 * Gets the right element from this pair. 176 * 177 * <p>When treated as a key-value pair, this is the value.</p> 178 * 179 * @return the right element, may be null 180 */ getRight()181 public abstract R getRight(); 182 183 /** 184 * Gets the value from this pair. 185 * 186 * <p>This method implements the {@code Map.Entry} interface returning the 187 * right element as the value.</p> 188 * 189 * @return the right element as the value, may be null 190 */ 191 @Override getValue()192 public R getValue() { 193 return getRight(); 194 } 195 196 /** 197 * Returns a suitable hash code. 198 * The hash code follows the definition in {@code Map.Entry}. 199 * 200 * @return the hash code 201 */ 202 @Override hashCode()203 public int hashCode() { 204 // see Map.Entry API specification 205 return Objects.hashCode(getKey()) ^ Objects.hashCode(getValue()); 206 } 207 208 /** 209 * Returns a String representation of this pair using the format {@code ($left,$right)}. 210 * 211 * @return a string describing this object, not null 212 */ 213 @Override toString()214 public String toString() { 215 return "(" + getLeft() + ',' + getRight() + ')'; 216 } 217 218 /** 219 * Formats the receiver using the given format. 220 * 221 * <p>This uses {@link java.util.Formattable} to perform the formatting. Two variables may 222 * be used to embed the left and right elements. Use {@code %1$s} for the left 223 * element (key) and {@code %2$s} for the right element (value). 224 * The default format used by {@code toString()} is {@code (%1$s,%2$s)}.</p> 225 * 226 * @param format the format string, optionally containing {@code %1$s} and {@code %2$s}, not null 227 * @return the formatted string, not null 228 */ toString(final String format)229 public String toString(final String format) { 230 return String.format(format, getLeft(), getRight()); 231 } 232 233 } 234