001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.commons.lang3.tuple; 018 019import java.io.Serializable; 020import java.util.Map; 021import java.util.Objects; 022 023import org.apache.commons.lang3.builder.CompareToBuilder; 024import org.apache.commons.lang3.function.FailableBiConsumer; 025import org.apache.commons.lang3.function.FailableBiFunction; 026 027/** 028 * A pair consisting of two elements. 029 * 030 * <p>This class is an abstract implementation defining the basic API. 031 * It refers to the elements as 'left' and 'right'. It also implements the 032 * {@code Map.Entry} interface where the key is 'left' and the value is 'right'.</p> 033 * 034 * <p>Subclass implementations may be mutable or immutable. 035 * However, there is no restriction on the type of the stored objects that may be stored. 036 * If mutable objects are stored in the pair, then the pair itself effectively becomes mutable.</p> 037 * 038 * @param <L> the left element type 039 * @param <R> the right element type 040 * 041 * @since 3.0 042 */ 043public abstract class Pair<L, R> implements Map.Entry<L, R>, Comparable<Pair<L, R>>, Serializable { 044 045 /** Serialization version */ 046 private static final long serialVersionUID = 4954918890077093841L; 047 048 /** 049 * An empty array. 050 * <p> 051 * Consider using {@link #emptyArray()} to avoid generics warnings. 052 * </p> 053 * 054 * @since 3.10. 055 */ 056 public static final Pair<?, ?>[] EMPTY_ARRAY = {}; 057 058 /** 059 * Returns the empty array singleton that can be assigned without compiler warning. 060 * 061 * @param <L> the left element type 062 * @param <R> the right element type 063 * @return the empty array singleton that can be assigned without compiler warning. 064 * 065 * @since 3.10. 066 */ 067 @SuppressWarnings("unchecked") 068 public static <L, R> Pair<L, R>[] emptyArray() { 069 return (Pair<L, R>[]) EMPTY_ARRAY; 070 } 071 072 /** 073 * Creates an immutable pair of two objects inferring the generic types. 074 * 075 * <p>This factory allows the pair to be created using inference to 076 * obtain the generic types.</p> 077 * 078 * @param <L> the left element type 079 * @param <R> the right element type 080 * @param left the left element, may be null 081 * @param right the right element, may be null 082 * @return a pair formed from the two parameters, not null 083 */ 084 public static <L, R> Pair<L, R> of(final L left, final R right) { 085 return ImmutablePair.of(left, right); 086 } 087 088 /** 089 * Creates an immutable pair from a map entry. 090 * 091 * <p>This factory allows the pair to be created using inference to 092 * obtain the generic types.</p> 093 * 094 * @param <L> the left element type 095 * @param <R> the right element type 096 * @param pair the map entry. 097 * @return a pair formed from the map entry 098 * @since 3.10 099 */ 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}