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.util.Map;
020
021/**
022 * <p>A mutable pair consisting of two {@code Object} elements.</p>
023 *
024 * <p>Not #ThreadSafe#</p>
025 *
026 * @param <L> the left element type
027 * @param <R> the right element type
028 *
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 = new MutablePair[0];
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     *
053     * @since 3.10.
054     */
055    @SuppressWarnings("unchecked")
056    public static <L, R> MutablePair<L, R>[] emptyArray() {
057        return (MutablePair<L, R>[]) EMPTY_ARRAY;
058    }
059
060    /**
061     * <p>Creates a mutable pair of two objects inferring the generic types.</p>
062     *
063     * <p>This factory allows the pair to be created using inference to
064     * obtain the generic types.</p>
065     *
066     * @param <L> the left element type
067     * @param <R> the right element type
068     * @param left  the left element, may be null
069     * @param right  the right element, may be null
070     * @return a pair formed from the two parameters, not null
071     */
072    public static <L, R> MutablePair<L, R> of(final L left, final R right) {
073        return new MutablePair<>(left, right);
074    }
075
076    /**
077     * <p>Creates a mutable pair from an existing pair.</p>
078     *
079     * <p>This factory allows the pair to be created using inference to
080     * obtain the generic types.</p>
081     *
082     * @param <L> the left element type
083     * @param <R> the right element type
084     * @param pair the existing pair.
085     * @return a pair formed from the two parameters, not null
086     */
087    public static <L, R> MutablePair<L, R> of(final Map.Entry<L, R> pair) {
088        final L left;
089        final R right;
090        if (pair != null) {
091            left = pair.getKey();
092            right = pair.getValue();
093        } else {
094            left = null;
095            right = null;
096        }
097        return new MutablePair<>(left, right);
098    }
099
100    /** Left object */
101    public L left;
102
103    /** Right object */
104    public R right;
105
106    /**
107     * Create a new pair instance of two nulls.
108     */
109    public MutablePair() {
110    }
111
112    /**
113     * Create a new pair instance.
114     *
115     * @param left  the left value, may be null
116     * @param right  the right value, may be null
117     */
118    public MutablePair(final L left, final R right) {
119        this.left = left;
120        this.right = right;
121    }
122
123    //-----------------------------------------------------------------------
124    /**
125     * {@inheritDoc}
126     */
127    @Override
128    public L getLeft() {
129        return left;
130    }
131
132    /**
133     * {@inheritDoc}
134     */
135    @Override
136    public R getRight() {
137        return right;
138    }
139
140    /**
141     * Sets the left element of the pair.
142     *
143     * @param left  the new value of the left element, may be null
144     */
145    public void setLeft(final L left) {
146        this.left = left;
147    }
148
149    /**
150     * Sets the right element of the pair.
151     *
152     * @param right  the new value of the right element, may be null
153     */
154    public void setRight(final R right) {
155        this.right = right;
156    }
157
158    /**
159     * Sets the {@code Map.Entry} value.
160     * This sets the right element of the pair.
161     *
162     * @param value  the right value to set, not null
163     * @return the old value for the right element
164     */
165    @Override
166    public R setValue(final R value) {
167        final R result = getRight();
168        setRight(value);
169        return result;
170    }
171
172}