001/*
002 * ============================================================================
003 * Copyright © 2002-2024 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;
022
023import java.io.Serial;
024import java.time.Instant;
025import java.time.format.DateTimeFormatter;
026import java.time.format.DateTimeParseException;
027import java.util.Optional;
028
029import org.apiguardian.api.API;
030import org.tquadrat.foundation.annotation.ClassVersion;
031
032/**
033 *  The implementation of
034 *  {@link TimeDateStringConverter}
035 *  for
036 *  {@link java.time.Instant}.
037 *
038 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
039 *  @version $Id: InstantStringConverter.java 1130 2024-05-05 16:16:09Z tquadrat $
040 *  @since 0.0.6
041 *
042 *  @UMLGraph.link
043 */
044@ClassVersion( sourceVersion = "$Id: InstantStringConverter.java 1130 2024-05-05 16:16:09Z tquadrat $" )
045@API( status = STABLE, since = "0.0.6" )
046public class InstantStringConverter extends TimeDateStringConverter<Instant>
047{
048        /*------------------------*\
049    ====** Static Initialisations **===========================================
050        \*------------------------*/
051    /**
052     *  The serial version UID for objects of this class: {@value}.
053     *
054     *  @hidden
055     */
056    @Serial
057    private static final long serialVersionUID = 1L;
058
059    /**
060     *  An instance of this class.
061     */
062    public static final InstantStringConverter INSTANCE = new InstantStringConverter();
063
064        /*--------------*\
065    ====** Constructors **=====================================================
066        \*--------------*/
067    /**
068     *  Creates a new {@code InstantStringConverter} instance.
069     */
070    public InstantStringConverter() { super( Instant.class ); }
071
072    /**
073     *  Creates a new {@code InstantStringConverter} instance that uses the
074     *  given formatter for the conversion back and forth.
075     *
076     *  @note The formatter may not drop any part of the instant, otherwise
077     *      {@code fromString()} may fail. This means that the formatter is
078     *      only allowed to re-order the temporal fields.
079     *
080     *  @param  formatter   The formatter for the temporal accessor.
081     */
082    public InstantStringConverter( final DateTimeFormatter formatter )
083    {
084        super( Instant.class, formatter );
085    }   //  InstantStringConverter()
086
087        /*---------*\
088    ====** Methods **==========================================================
089        \*---------*/
090    /**
091     *  {@inheritDoc}
092     */
093    @Override
094    protected final Instant parseDateTime( final CharSequence source, final Optional<DateTimeFormatter> formatter ) throws DateTimeParseException
095    {
096        final var retValue = formatter.map( dateTimeFormatter -> Instant.from( dateTimeFormatter.parse( source ) ) ).orElse( Instant.parse( source ) );
097
098        //---* Done *----------------------------------------------------------
099        return retValue;
100    }   //  parseDateTime()
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 InstantStringConverter provider() { return INSTANCE; }
112}
113//  class InstantStringConverter
114
115/*
116 *  End of File
117 */