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 CharSequence}
037 *  values.}</p>
038 *  <p>Although a conversion from {@code CharSequence} to String is redundant
039 *  (at best), this implementation exists for cases where a string converter is
040 *  retrieved based on the data type; it can simplify the code when no special
041 *  case must be considered for {@code CharSequence}.</p>
042 *  <p>Obviously, the method
043 *  {@link #fromString(CharSequence) fromString()}
044 *  will not necessarily return an instance of the exact type that may have
045 *  been used with
046 *  {@link #toString(CharSequence) toString()};
047 *  it will return an instance of
048 *  {@link String},
049 *  as that is the best matching implementation of {@code CharSequence} for
050 *  this purpose.</p>
051 *
052 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
053 *  @version $Id: CharSequenceStringConverter.java 1060 2023-09-24 19:21:40Z tquadrat $
054 *  @since 0.1.0
055 *
056 *  @UMLGraph.link
057 */
058@ClassVersion( sourceVersion = "$Id: CharSequenceStringConverter.java 1060 2023-09-24 19:21:40Z tquadrat $" )
059@API( status = STABLE, since = "0.0.6" )
060public final class CharSequenceStringConverter implements StringConverter<CharSequence>
061{
062        /*------------------------*\
063    ====** Static Initialisations **===========================================
064        \*------------------------*/
065    /**
066     *  The serial version UID for objects of this class: {@value}.
067     *
068     *  @hidden
069     */
070    @Serial
071    private static final long serialVersionUID = 1L;
072
073    /**
074     *  An instance of this class.
075     */
076    public static final CharSequenceStringConverter INSTANCE = new CharSequenceStringConverter();
077
078        /*--------------*\
079    ====** Constructors **=====================================================
080        \*--------------*/
081    /**
082     *  Creates a new instance of {@code CharSequenceStringConverter}.
083     */
084    public CharSequenceStringConverter() {}
085
086        /*---------*\
087    ====** Methods **==========================================================
088        \*---------*/
089    /**
090     *  {@inheritDoc}
091     */
092    @Override
093    public final CharSequence fromString( final CharSequence source ) throws IllegalArgumentException
094    {
095        final var retValue = isNull( source ) ? null : source.toString();
096
097        //---* Done *----------------------------------------------------------
098        return retValue;
099    }   //  fromString()
100
101    /**
102     *  Provides the subject class for this converter.
103     *
104     * @return The subject class.
105     */
106    @SuppressWarnings( "PublicMethodNotExposedInInterface" )
107    public final Collection<Class<CharSequence>> getSubjectClass() { return List.of( CharSequence.class ); }
108
109    /**
110     *  This method is used by the
111     *  {@link java.util.ServiceLoader}
112     *  to obtain the instance for this
113     *  {@link StringConverter}
114     *  implementation.
115     *
116     *  @return The instance for this {@code StringConverter} implementation.
117     */
118    public static final CharSequenceStringConverter provider() { return INSTANCE; }
119
120    /**
121     *  {@inheritDoc}
122     */
123    @Override
124    public final String toString( final CharSequence source )
125    {
126        final var retValue = isNull( source ) ? null : source.toString();
127
128        //---* Done *----------------------------------------------------------
129        return retValue;
130    }   //  toString()
131}
132//  class StringStringConverter
133
134/*
135 *  End of File
136 */