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.util.Map;
20 import java.util.Objects;
21
22 /**
23 * A mutable pair consisting of two {@link Object} elements.
24 *
25 * <p>Not #ThreadSafe#</p>
26 *
27 * @param <L> the left element type.
28 * @param <R> the right element type.
29 * @since 3.0
30 */
31 public class MutablePair<L, R> extends Pair<L, R> {
32
33 /**
34 * An empty array.
35 * <p>
36 * Consider using {@link #emptyArray()} to avoid generics warnings.
37 * </p>
38 *
39 * @since 3.10
40 */
41 public static final MutablePair<?, ?>[] EMPTY_ARRAY = {};
42
43 /** Serialization version */
44 private static final long serialVersionUID = 4954918890077093841L;
45
46 /**
47 * Returns the empty array singleton that can be assigned without compiler warning.
48 *
49 * @param <L> the left element type.
50 * @param <R> the right element type.
51 * @return the empty array singleton that can be assigned without compiler warning.
52 * @since 3.10
53 */
54 @SuppressWarnings("unchecked")
55 public static <L, R> MutablePair<L, R>[] emptyArray() {
56 return (MutablePair<L, R>[]) EMPTY_ARRAY;
57 }
58
59 /**
60 * Creates a mutable pair of two objects inferring the generic types.
61 *
62 * <p>This factory allows the pair to be created using inference to
63 * obtain the generic types.</p>
64 *
65 * @param <L> the left element type.
66 * @param <R> the right element type.
67 * @param left the left element, may be null.
68 * @param right the right element, may be null.
69 * @return a pair formed from the two parameters, not null.
70 */
71 public static <L, R> MutablePair<L, R> of(final L left, final R right) {
72 return new MutablePair<>(left, right);
73 }
74
75 /**
76 * Creates a mutable pair from a map entry.
77 *
78 * <p>This factory allows the pair to be created using inference to
79 * obtain the generic types.</p>
80 *
81 * @param <L> the left element type.
82 * @param <R> the right element type.
83 * @param pair the existing map entry.
84 * @return a pair formed from the map entry.
85 */
86 public static <L, R> MutablePair<L, R> of(final Map.Entry<L, R> pair) {
87 final L left;
88 final R right;
89 if (pair != null) {
90 left = pair.getKey();
91 right = pair.getValue();
92 } else {
93 left = null;
94 right = null;
95 }
96 return new MutablePair<>(left, right);
97 }
98
99 /**
100 * Creates a mutable pair of two non-null objects inferring the generic types.
101 *
102 * <p>This factory allows the pair to be created using inference to
103 * obtain the generic types.</p>
104 *
105 * @param <L> the left element type.
106 * @param <R> the right element type.
107 * @param left the left element, may not be null.
108 * @param right the right element, may not be null.
109 * @return a pair formed from the two parameters, not null.
110 * @throws NullPointerException if any input is null.
111 * @since 3.13.0
112 */
113 public static <L, R> MutablePair<L, R> ofNonNull(final L left, final R right) {
114 return of(Objects.requireNonNull(left, "left"), Objects.requireNonNull(right, "right"));
115 }
116
117 /** Left object. */
118 public L left;
119
120 /** Right object. */
121 public R right;
122
123 /**
124 * Create a new pair instance of two nulls.
125 */
126 public MutablePair() {
127 }
128
129 /**
130 * Create a new pair instance.
131 *
132 * @param left the left value, may be null.
133 * @param right the right value, may be null.
134 */
135 public MutablePair(final L left, final R right) {
136 this.left = left;
137 this.right = right;
138 }
139
140 /**
141 * {@inheritDoc}
142 */
143 @Override
144 public L getLeft() {
145 return left;
146 }
147
148 /**
149 * {@inheritDoc}
150 */
151 @Override
152 public R getRight() {
153 return right;
154 }
155
156 /**
157 * Sets the left element of the pair.
158 *
159 * @param left the new value of the left element, may be null.
160 */
161 public void setLeft(final L left) {
162 this.left = left;
163 }
164
165 /**
166 * Sets the right element of the pair.
167 *
168 * @param right the new value of the right element, may be null.
169 */
170 public void setRight(final R right) {
171 this.right = right;
172 }
173
174 /**
175 * Sets the {@code Map.Entry} value.
176 * This sets the right element of the pair.
177 *
178 * @param value the right value to set, not null.
179 * @return the old value for the right element.
180 */
181 @Override
182 public R setValue(final R value) {
183 final R result = getRight();
184 setRight(value);
185 return result;
186 }
187
188 }