001/*
002 * ============================================================================
003 * Copyright © 2002-2023 by Thomas Thrien.
004 * All Rights Reserved.
005 * ============================================================================
006 *
007 * Licensed to the public under the agreements of the GNU Lesser General Public
008 * License, version 3.0 (the "License"). You may obtain a copy of the License at
009 *
010 *      http://www.gnu.org/licenses/lgpl.html
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
014 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
015 * License for the specific language governing permissions and limitations
016 * under the License.
017 */
018
019package org.tquadrat.foundation.util.stringconverter;
020
021import static org.apiguardian.api.API.Status.STABLE;
022import static org.tquadrat.foundation.lang.Objects.isNull;
023
024import java.io.Serial;
025import java.util.Collection;
026import java.util.List;
027
028import org.apiguardian.api.API;
029import org.tquadrat.foundation.annotation.ClassVersion;
030import org.tquadrat.foundation.lang.StringConverter;
031
032/**
033 *  <p>{@summary The implementation of
034 *  {@link StringConverter}
035 *  for
036 *  {@link String}
037 *  values.}</p>
038 *  <p>Although a conversion from String to String is redundant (at best),
039 *  this implementation exists for cases where a string converter is retrieved
040 *  based on the data type; it can simplify the code when no special case must
041 *  be considered for String.</p>
042 *
043 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
044 *  @version $Id: StringStringConverter.java 1060 2023-09-24 19:21:40Z tquadrat $
045 *  @since 0.0.6
046 *
047 *  @UMLGraph.link
048 */
049@ClassVersion( sourceVersion = "$Id: StringStringConverter.java 1060 2023-09-24 19:21:40Z tquadrat $" )
050@API( status = STABLE, since = "0.0.6" )
051public final class StringStringConverter implements StringConverter<String>
052{
053        /*------------------------*\
054    ====** Static Initialisations **===========================================
055        \*------------------------*/
056    /**
057     *  The serial version UID for objects of this class: {@value}.
058     *
059     *  @hidden
060     */
061    @Serial
062    private static final long serialVersionUID = 1L;
063
064    /**
065     *  An instance of this class.
066     */
067    public static final StringStringConverter INSTANCE = new StringStringConverter();
068
069        /*--------------*\
070    ====** Constructors **=====================================================
071        \*--------------*/
072    /**
073     *  Creates a new instance of {@code StringStringConverter}.
074     */
075    public StringStringConverter() {}
076
077        /*---------*\
078    ====** Methods **==========================================================
079        \*---------*/
080    /**
081     *  {@inheritDoc}
082     */
083    @Override
084    public final String fromString( final CharSequence source ) throws IllegalArgumentException
085    {
086        final var retValue = isNull( source ) ? null : source.toString();
087
088        //---* Done *----------------------------------------------------------
089        return retValue;
090    }   //  fromString()
091
092    /**
093     *  Provides the subject class for this converter.
094     *
095     * @return The subject class.
096     */
097    @SuppressWarnings( "PublicMethodNotExposedInInterface" )
098    public final Collection<Class<String>> getSubjectClass() { return List.of( String.class ); }
099
100    /**
101     *  This method is used by the
102     *  {@link java.util.ServiceLoader}
103     *  to obtain the instance for this
104     *  {@link org.tquadrat.foundation.lang.StringConverter}
105     *  implementation.
106     *
107     *  @return The instance for this {@code StringConverter} implementation.
108     */
109    public static final StringStringConverter provider() { return INSTANCE; }
110
111    /**
112     *  {@inheritDoc}
113     */
114    @Override
115    public final String toString( final String source ) { return source; }
116}
117//  class StringStringConverter
118
119/*
120 *  End of File
121 */