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 *      https://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.util.Map;
020import java.util.Objects;
021
022/**
023 * A mutable pair consisting of two {@link Object} elements.
024 *
025 * <p>Not #ThreadSafe#</p>
026 *
027 * @param <L> the left element type.
028 * @param <R> the right element type.
029 * @since 3.0
030 */
031public class MutablePair<L, R> extends Pair<L, R> {
032
033    /**
034     * An empty array.
035     * <p>
036     * Consider using {@link #emptyArray()} to avoid generics warnings.
037     * </p>
038     *
039     * @since 3.10
040     */
041    public static final MutablePair<?, ?>[] EMPTY_ARRAY = {};
042
043    /** Serialization version */
044    private static final long serialVersionUID = 4954918890077093841L;
045
046    /**
047     * Returns the empty array singleton that can be assigned without compiler warning.
048     *
049     * @param <L> the left element type.
050     * @param <R> the right element type.
051     * @return the empty array singleton that can be assigned without compiler warning.
052     * @since 3.10
053     */
054    @SuppressWarnings("unchecked")
055    public static <L, R> MutablePair<L, R>[] emptyArray() {
056        return (MutablePair<L, R>[]) EMPTY_ARRAY;
057    }
058
059    /**
060     * Creates a mutable pair of two objects inferring the generic types.
061     *
062     * <p>This factory allows the pair to be created using inference to
063     * obtain the generic types.</p>
064     *
065     * @param <L> the left element type.
066     * @param <R> the right element type.
067     * @param left  the left element, may be null.
068     * @param right  the right element, may be null.
069     * @return a pair formed from the two parameters, not null.
070     */
071    public static <L, R> MutablePair<L, R> of(final L left, final R right) {
072        return new MutablePair<>(left, right);
073    }
074
075    /**
076     * Creates a mutable pair from a map entry.
077     *
078     * <p>This factory allows the pair to be created using inference to
079     * obtain the generic types.</p>
080     *
081     * @param <L> the left element type.
082     * @param <R> the right element type.
083     * @param pair the existing map entry.
084     * @return a pair formed from the map entry.
085     */
086    public static <L, R> MutablePair<L, R> of(final Map.Entry<L, R> pair) {
087        final L left;
088        final R right;
089        if (pair != null) {
090            left = pair.getKey();
091            right = pair.getValue();
092        } else {
093            left = null;
094            right = null;
095        }
096        return new MutablePair<>(left, right);
097    }
098
099    /**
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}