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 java.time.format.DateTimeFormatter.ISO_OFFSET_DATE_TIME;
022import static org.apiguardian.api.API.Status.STABLE;
023
024import java.io.Serial;
025import java.time.OffsetDateTime;
026import java.time.format.DateTimeFormatter;
027import java.time.format.DateTimeParseException;
028import java.util.Optional;
029
030import org.apiguardian.api.API;
031import org.tquadrat.foundation.annotation.ClassVersion;
032
033/**
034 *  The implementation of
035 *  {@link TimeDateStringConverter}
036 *  for {@code java.time.OffsetDateTime}.
037 *
038 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
039 *  @version $Id: OffsetDateTimeStringConverter.java 1130 2024-05-05 16:16:09Z tquadrat $
040 *  @since 0.4.5
041 *
042 *  @UMLGraph.link
043 */
044@ClassVersion( sourceVersion = "$Id: OffsetDateTimeStringConverter.java 1130 2024-05-05 16:16:09Z tquadrat $" )
045@API( status = STABLE, since = "0.4.5" )
046public class OffsetDateTimeStringConverter extends TimeDateStringConverter<OffsetDateTime>
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 OffsetDateTimeStringConverter INSTANCE = new OffsetDateTimeStringConverter();
063
064        /*--------------*\
065    ====** Constructors **=====================================================
066        \*--------------*/
067    /**
068     *  Creates a new {@code OffsetDateTimeStringConverter} instance that uses
069     *  {@link DateTimeFormatter#ISO_OFFSET_DATE_TIME}
070     *  to format/parse the date.
071     */
072    public OffsetDateTimeStringConverter() { super(OffsetDateTime.class ); }
073
074    /**
075     *  Creates a new {@code OffsetDateTimeStringConverter} instance.
076     *
077     *  @note The formatter may not drop any part of the offset date time,
078     *      otherwise {@code fromString()} may fail. This means that the
079     *      formatter is only allowed to re-order the temporal fields.
080     *
081     *  @param  formatter   The formatter for the temporal accessor.
082     */
083    public OffsetDateTimeStringConverter( final DateTimeFormatter formatter )
084    {
085        super( OffsetDateTime.class, formatter );
086    }   //  OffsetDateTimeStringConverter()
087
088        /*---------*\
089    ====** Methods **==========================================================
090        \*---------*/
091    /**
092     *  {@inheritDoc}
093     */
094    @Override
095    protected final OffsetDateTime parseDateTime( final CharSequence source, final Optional<DateTimeFormatter> formatter ) throws DateTimeParseException
096    {
097        final var retValue = OffsetDateTime.from( formatter.orElse( ISO_OFFSET_DATE_TIME ).parse( source ) );
098
099        //---* Done *----------------------------------------------------------
100        return retValue;
101    }   //  parseDateTime()
102
103    /**
104     *  This method is used by the
105     *  {@link java.util.ServiceLoader}
106     *  to obtain the instance for this
107     *  {@link org.tquadrat.foundation.lang.StringConverter}
108     *  implementation.
109     *
110     *  @return The instance for this {@code StringConverter} implementation.
111     */
112    public static final OffsetDateTimeStringConverter provider() { return INSTANCE; }
113}
114//  class OffsetDateTimeStringConverter
115
116/*
117 *  End of File
118 */