001/*
002 * ============================================================================
003 * Copyright © 2002-2023 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.util.stringconverter;
019
020import static java.lang.String.format;
021import static org.apiguardian.api.API.Status.STABLE;
022import static org.tquadrat.foundation.lang.Objects.isNull;
023import static org.tquadrat.foundation.lang.Objects.nonNull;
024
025import java.io.Serial;
026import java.util.Collection;
027import java.util.List;
028
029import org.apiguardian.api.API;
030import org.tquadrat.foundation.annotation.ClassVersion;
031import org.tquadrat.foundation.lang.StringConverter;
032
033/**
034 *  An implementation of
035 *  {@link StringConverter}
036 *  for
037 *  {@link Character}
038 *  values.<br>
039 *  <br>Calling
040 *  {@link #fromString(CharSequence)}
041 *  with an empty String will cause an
042 *  {@link IllegalArgumentException}.
043 *
044 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
045 *  @version $Id: CharacterStringConverter.java 1060 2023-09-24 19:21:40Z tquadrat $
046 *  @since 0.0.6
047 *
048 *  @UMLGraph.link
049 */
050@ClassVersion( sourceVersion = "$Id: CharacterStringConverter.java 1060 2023-09-24 19:21:40Z tquadrat $" )
051@API( status = STABLE, since = "0.0.6" )
052public final class CharacterStringConverter implements StringConverter<Character>
053{
054        /*-----------*\
055    ====** Constants **========================================================
056        \*-----------*/
057    /**
058     *  The error message for an invalid character on the command line:
059     *  {@value}.
060     */
061    public static final String MSG_InvalidCharacter = "Not a valid Character: '%s'";
062
063        /*------------------------*\
064    ====** Static Initialisations **===========================================
065        \*------------------------*/
066    /**
067     *  The serial version UID for objects of this class: {@value}.
068     *
069     *  @hidden
070     */
071    @Serial
072    private static final long serialVersionUID = 1L;
073
074    /**
075     *  An instance of this class.
076     */
077    public static final CharacterStringConverter INSTANCE = new CharacterStringConverter();
078
079        /*--------------*\
080    ====** Constructors **=====================================================
081        \*--------------*/
082    /**
083     *  Creates a new instance of {@code CharacterStringConverter}.
084     */
085    public CharacterStringConverter() {}
086
087        /*---------*\
088    ====** Methods **==========================================================
089        \*---------*/
090    /**
091     *  {@inheritDoc}
092     */
093    @Override
094    public final Character fromString( final CharSequence source ) throws IllegalArgumentException
095    {
096        Character retValue = null;
097        if( nonNull( source ) )
098        {
099            if( source.length() != 1 ) throw new IllegalArgumentException( format( MSG_InvalidCharacter, source ) );
100            retValue = source.charAt( 0 );
101        }
102
103        //---* Done *----------------------------------------------------------
104        return retValue;
105    }   //  fromString()
106
107    /**
108     *  Provides the subject class for this converter.
109     *
110     * @return The subject class.
111     */
112    @SuppressWarnings( "PublicMethodNotExposedInInterface" )
113    public final Collection<Class<?>> getSubjectClass() { return List.of( char.class, Character.class ); }
114
115    /**
116     *  This method is used by the
117     *  {@link java.util.ServiceLoader}
118     *  to obtain the instance for this
119     *  {@link org.tquadrat.foundation.lang.StringConverter}
120     *  implementation.
121     *
122     *  @return The instance for this {@code StringConverter} implementation.
123     */
124    public static final CharacterStringConverter provider() { return INSTANCE; }
125
126    /**
127     *  {@inheritDoc}
128     */
129    @Override
130    public final String toString( final Character source )
131    {
132        final var retValue = isNull( source ) ? null : source.toString();
133
134        //---* Done *----------------------------------------------------------
135        return retValue;
136    }   //  toString()
137}
138//  class CharacterValueHandler
139
140/*
141 *  End of File
142 */