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