001/*
002 * ============================================================================
003 *  Copyright © 2002-2022 by Thomas Thrien.
004 *  All Rights Reserved.
005 * ============================================================================
006 *  Licensed to the public under the agreements of the GNU Lesser General Public
007 *  License, version 3.0 (the "License"). You may obtain a copy of the License at
008 *
009 *       http://www.gnu.org/licenses/lgpl.html
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, WITHOUT
013 *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
014 *  License for the specific language governing permissions and limitations
015 *  under the License.
016 */
017
018package org.tquadrat.foundation.lang;
019
020import org.apiguardian.api.API;
021import org.tquadrat.foundation.annotation.ClassVersion;
022
023import java.util.Map;
024import java.util.Map.Entry;
025
026import static org.apiguardian.api.API.Status.STABLE;
027
028/**
029 *  <p>{@summary The implementation of a tupel.}</p>
030 *  <p>Both values are allowed to be {@code null}.</p>
031 *
032 *  @param  <L> The type for the left value.
033 *  @param  <R> The type for the right value.
034 *  @param  left    The left value of the pair.
035 *  @param  right   The right value of the pair.
036 *
037 *  @version $Id: Pair.java 1119 2024-03-16 09:03:57Z tquadrat $
038 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
039 *  @UMLGraph.link
040 *  @since 0.1.0
041 */
042@SuppressWarnings( "NewClassNamingConvention" )
043@ClassVersion( sourceVersion = "$Id: Pair.java 1119 2024-03-16 09:03:57Z tquadrat $" )
044@API( status = STABLE, since = "0.1.0" )
045public record Pair<L,R>( L left, R right )
046{
047        /*---------*\
048    ====** Methods **==========================================================
049        \*---------*/
050    /**
051     *  <p>{@summary Returns this instance of {@code Pair} as an instance of
052     *  {@link Entry}.}
053     *  The left value is the
054     *  {@link Entry#getKey() key},
055     *  the right value is the
056     *  {@link Entry#getValue() value}.</p>
057     *  <p>The method
058     *  {@link Entry#setValue(Object)}
059     *  is not implemented and will throw an exception when called.</p>
060     *
061     *  @return A reference to this instance as an {@code Entry}.
062     */
063    @SuppressWarnings("PublicMethodNotExposedInInterface")
064    public final Map.Entry<L,R> asEntry()
065    {
066        @SuppressWarnings( "AnonymousInnerClass" )
067        final var retValue = new Entry<L,R>()
068        {
069            /**
070             *  {@inheritDoc}
071             */
072            @Override
073            public final L getKey() { return left(); }
074
075            /**
076             *  {@inheritDoc}
077             */
078            @Override
079            public final R getValue() { return right(); }
080
081            /**
082             *  {@inheritDoc}
083             */
084            @Override
085            public final R setValue( final R value ) { throw new UnsupportedOperationException( "setValue()" ); }
086        };
087
088        //---* Done *----------------------------------------------------------
089        return retValue;
090    }   //  asEntry()
091
092    /**
093     *  Creates a new instance of {@code Pair} with the right value from this
094     *  one and the given new left value.
095     *
096     *  @param  newLeft The new left value; can be {@code null}.
097     *  @return A new instance of {@code Pair}.
098     */
099    @SuppressWarnings("PublicMethodNotExposedInInterface")
100    public final Pair<L,R> left(final L newLeft ) { return new Pair<>( newLeft, right ); }
101
102    /**
103     *  Creates a new instance of {@code Pair} with the left value from this
104     *  one and the given new right value.
105     *
106     *  @param  newRight The new right value; can be {@code null}.
107     *  @return A new instance of {@code Pair}.
108     */
109    @SuppressWarnings("PublicMethodNotExposedInInterface")
110    public final Pair<L,R> right(final R newRight ) { return new Pair<>( left, newRight ); }
111}
112//  record Pair
113
114/*
115 *  End of File
116 */