001/*
002 * ============================================================================
003 *  Copyright © 2002-2025 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 static org.apiguardian.api.API.Status.STABLE;
021
022import java.util.Map;
023import java.util.Map.Entry;
024
025import org.apiguardian.api.API;
026import org.tquadrat.foundation.annotation.ClassVersion;
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 1151 2025-10-01 21:32:15Z 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 1151 2025-10-01 21:32:15Z 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    public final Map.Entry<L,R> asEntry()
064    {
065        @SuppressWarnings( "AnonymousInnerClass" )
066        final var retValue = new Entry<L,R>()
067        {
068            /**
069             *  {@inheritDoc}
070             */
071            @Override
072            public final L getKey() { return left(); }
073
074            /**
075             *  {@inheritDoc}
076             */
077            @Override
078            public final R getValue() { return right(); }
079
080            /**
081             *  {@inheritDoc}
082             */
083            @Override
084            public final R setValue( final R value ) { throw new UnsupportedOperationException( "setValue()" ); }
085        };
086
087        //---* Done *----------------------------------------------------------
088        return retValue;
089    }   //  asEntry()
090
091    /**
092     *  Creates a new instance of {@code Pair} with the right value from this
093     *  one and the given new left value.
094     *
095     *  @param  newLeft The new left value; can be {@code null}.
096     *  @return A new instance of {@code Pair}.
097     */
098    public final Pair<L,R> left(final L newLeft ) { return new Pair<>( newLeft, right ); }
099
100    /**
101     *  Creates a new instance of {@code Pair} with the left value from this
102     *  one and the given new right value.
103     *
104     *  @param  newRight The new right value; can be {@code null}.
105     *  @return A new instance of {@code Pair}.
106     */
107    public final Pair<L,R> right(final R newRight ) { return new Pair<>( left, newRight ); }
108}
109//  record Pair
110
111/*
112 *  End of File
113 */