001/*
002 * ============================================================================
003 *  Copyright © 2002-2024 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.Entry;
024
025import static org.apiguardian.api.API.Status.STABLE;
026import static org.tquadrat.foundation.lang.Objects.requireNonNullArgument;
027import static org.tquadrat.foundation.lang.Objects.requireNotEmptyArgument;
028
029/**
030 *  An implementation of a name-value-pair.
031 *
032 *  @param  <V> The type of the value.
033 *  @param  name    The name; may not be {@code null}, and it may not be
034 *      empty.
035 *  @param  value   The value; can be {@code null}.
036 *
037 *  @version $Id: NameValuePair.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@ClassVersion( sourceVersion = "$Id: NameValuePair.java 1119 2024-03-16 09:03:57Z tquadrat $" )
043@API( status = STABLE, since = "0.1.0" )
044public record NameValuePair<V>( String name, V value )
045{
046        /*--------------*\
047    ====** Constructors **=====================================================
048        \*--------------*/
049    /**
050     *  Creates a new instance of {@code NameValuePair}.
051     *
052     *  @param  name    The name; may not be {@code null}, and it may not be
053     *      empty.
054     *  @param  value   The value; can be {@code null}.
055     */
056    public NameValuePair
057    {
058        requireNotEmptyArgument( name, "name" );
059    }   //  NameValuePair()
060
061    /**
062     *  Creates a new instance of {@code NameValuePair} from the given
063     *  {@link java.util.Map.Entry}
064     *  instance.
065     *
066     *  @param  entry   The entry.
067     */
068    public NameValuePair( final Entry<String, ? extends V> entry )
069    {
070        this( requireNonNullArgument( entry, "entry" ).getKey(), entry.getValue() );
071    }   //  NameValuePair()
072
073        /*---------*\
074    ====** Methods **==========================================================
075        \*---------*/
076    /**
077     *  Creates a new instance of {@code NameValuePair} that takes the name
078     *  from this instance and assigns the given new value.
079     *
080     *  @param  newValue    The new value; may be {@code null}.
081     *  @return The new instance.
082     */
083    @SuppressWarnings("PublicMethodNotExposedInInterface")
084    public final NameValuePair<V> newValue(final V newValue ) { return new NameValuePair<>( name, newValue ); }
085}
086//  record NameValuePair
087
088/*
089 *  End of File
090 */