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 org.apiguardian.api.API.Status.STABLE;
021import static org.tquadrat.foundation.lang.Objects.isNull;
022
023import java.io.Serial;
024import java.util.Collection;
025import java.util.List;
026
027import org.apiguardian.api.API;
028import org.tquadrat.foundation.annotation.ClassVersion;
029import org.tquadrat.foundation.annotation.MountPoint;
030import org.tquadrat.foundation.lang.StringConverter;
031
032/**
033 *  An implementation of
034 *  {@link StringConverter}
035 *  for {@code boolean} and
036 *  {@link Boolean}
037 *  values.<br>
038 *  <br>The method
039 *  {@link #fromString(CharSequence)}
040 *  will accept the String &quot;true&quot;, irrespective of case, for the
041 *  value {@code true}, and any other String for {@code false} (including the
042 *  empty String!), while
043 *  {@link #toString()}
044 *  will only return &quot;true&quot; or &quot;false&quot; (or {@code null} if
045 *  the input is {@code null}). This behaviour can be changed by providing
046 *  different implementations for
047 *  {@link #translate(CharSequence)}
048 *  and
049 *  {@link #toString(Boolean)}.
050 *
051 *  @see Boolean#valueOf(String)
052 *
053 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
054 *  @version $Id: BooleanStringConverter.java 1060 2023-09-24 19:21:40Z tquadrat $
055 *  @since 0.0.6
056 *
057 *  @UMLGraph.link
058 */
059@ClassVersion( sourceVersion = "$Id: BooleanStringConverter.java 1060 2023-09-24 19:21:40Z tquadrat $" )
060@API( status = STABLE, since = "0.0.6" )
061public class BooleanStringConverter implements StringConverter<Boolean>
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 BooleanStringConverter INSTANCE = new BooleanStringConverter();
078
079        /*--------------*\
080    ====** Constructors **=====================================================
081        \*--------------*/
082    /**
083     *  Creates a new instance of {@code BooleanStringConverter}.
084     */
085    public BooleanStringConverter() {}
086
087        /*---------*\
088    ====** Methods **==========================================================
089        \*---------*/
090    /**
091     *  {@inheritDoc}
092     */
093    @Override
094    public Boolean fromString( final CharSequence source )
095    {
096        final var translated = translate( source );
097        final var retValue = isNull( translated ) ? null : Boolean.valueOf( translated.toString() );
098
099        //---* Done *----------------------------------------------------------
100        return retValue;
101    }   //  fromString()
102
103    /**
104     *  Provides the subject class for this converter.
105     *
106     * @return The subject class.
107     */
108    @SuppressWarnings( "PublicMethodNotExposedInInterface" )
109    public final Collection<Class<?>> getSubjectClass() { return List.of( boolean.class, Boolean.class ); }
110
111    /**
112     *  This method is used by the
113     *  {@link java.util.ServiceLoader}
114     *  to obtain the instance for this
115     *  {@link org.tquadrat.foundation.lang.StringConverter}
116     *  implementation.
117     *
118     *  @return The instance for this {@code StringConverter} implementation.
119     */
120    public static final BooleanStringConverter provider() { return INSTANCE; }
121
122    /**
123     * {@inheritDoc}
124     */
125    @MountPoint
126    @Override
127    public String toString( final Boolean source )
128    {
129        final var retValue = isNull( source ) ? null : source.toString();
130
131        //---* Done *----------------------------------------------------------
132        return retValue;
133    }   //  toString()
134
135    /**
136     *  Translates the given String to either &quot;true&quot; or
137     *  &quot;false&quot;. The default implementation just returns the
138     *  argument.<br>
139     *  <br>If this method will be implemented differently, it is no longer
140     *  guaranteed that
141     *  <pre><code>toString( fromString( s ) ) == s</code></pre>
142     *  yields {@code true} for all {@code s}.
143     *
144     *  @param  source  The original text; can be {@code null}.
145     *  @return The translated source; can be {@code null} if {@code source}
146     *      was already {@code null}.
147     */
148    @SuppressWarnings( "static-method" )
149    @MountPoint
150    protected CharSequence translate( final CharSequence source ) { return source; }
151}
152//  class BooleanStringConverter
153
154/*
155 *  End of File
156 */