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 java.lang.String.format;
022import static org.apiguardian.api.API.Status.STABLE;
023import static org.tquadrat.foundation.lang.Objects.isNull;
024import static org.tquadrat.foundation.util.SystemUtils.retrieveLocale;
025
026import java.io.Serial;
027import java.util.Locale;
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 Locale}
038 *  values.<br>
039 *  <br>The method
040 *  {@link #fromString(CharSequence)}
041 *  will use
042 *  {@link org.tquadrat.foundation.util.SystemUtils#retrieveLocale(CharSequence)}
043 *  to obtain an instance of {@code Locale} based on the given value.
044 *
045 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
046 *  @version $Id: LocaleStringConverter.java 1060 2023-09-24 19:21:40Z tquadrat $
047 *  @since 0.0.6
048 *
049 *  @UMLGraph.link
050 */
051@ClassVersion( sourceVersion = "$Id: LocaleStringConverter.java 1060 2023-09-24 19:21:40Z tquadrat $" )
052@API( status = STABLE, since = "0.0.6" )
053public final class LocaleStringConverter implements StringConverter<Locale>
054{
055        /*-----------*\
056    ====** Constants **========================================================
057        \*-----------*/
058    /**
059     *  The error message for an invalid locale: {@value}.
060     */
061    public static final String MSG_InvalidLocaleFormat = "'%s' cannot be parsed as a valid locale";
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 LocaleStringConverter INSTANCE = new LocaleStringConverter();
078
079        /*--------------*\
080    ====** Constructors **=====================================================
081        \*--------------*/
082    /**
083     *  Creates a new instance of {@code LocaleStringConverter}.
084     */
085    public LocaleStringConverter() {}
086
087        /*---------*\
088    ====** Methods **==========================================================
089        \*---------*/
090    /**
091     *  {@inheritDoc}
092     */
093    @Override
094    public final Locale fromString( final CharSequence source ) throws IllegalArgumentException
095    {
096        final var retValue = isNull( source ) ? null : retrieveLocale( source ).orElseThrow( () -> new IllegalArgumentException( format( MSG_InvalidLocaleFormat, source ) ) );
097
098        //---* Done *----------------------------------------------------------
099        return retValue;
100    }   //  fromString()
101
102    /**
103     *  This method is used by the
104     *  {@link java.util.ServiceLoader}
105     *  to obtain the instance for this
106     *  {@link org.tquadrat.foundation.lang.StringConverter}
107     *  implementation.
108     *
109     *  @return The instance for this {@code StringConverter} implementation.
110     */
111    public static final LocaleStringConverter provider() { return INSTANCE; }
112}
113//  class LocaleStringConverter
114
115/*
116 *  End of File
117 */