001/*
002 * ============================================================================
003 *  Copyright © 2002-2025 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.internal;
019
020import static org.apiguardian.api.API.Status.STABLE;
021import static org.tquadrat.foundation.lang.Objects.requireNonNullArgument;
022
023import java.util.Comparator;
024
025import org.apiguardian.api.API;
026import org.tquadrat.foundation.annotation.ClassVersion;
027import org.tquadrat.foundation.annotation.NotRecord;
028import org.tquadrat.foundation.lang.StringConverter;
029
030/**
031 *  An implementation of
032 *  {@link Comparator}
033 *  that compares object instances based on their String representation.
034 *
035 *  @param  <T> The type of the objects to compare.
036 *
037 *  @version $Id: StringBasedComparator.java 1151 2025-10-01 21:32:15Z tquadrat $
038 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
039 *  @UMLGraph.link
040 *  @since 0.1.0
041 */
042@ClassVersion( sourceVersion = "$Id: StringBasedComparator.java 1151 2025-10-01 21:32:15Z tquadrat $" )
043@API( status = STABLE, since = "0.1.0" )
044@NotRecord
045public class StringBasedComparator<T> implements Comparator<T>
046{
047        /*------------*\
048    ====** Attributes **=======================================================
049        \*------------*/
050    /**
051     *  The instance of
052     *  {@link StringConverter}
053     *  that is used to translate the object instances to Strings.
054     */
055    private final StringConverter<T> m_StringConverter;
056
057        /*--------------*\
058    ====** Constructors **=====================================================
059        \*--------------*/
060    /**
061     *  Creates a new instance of {@code StringBasedComparator}.
062     *
063     *  @param  stringConverter The instance of
064     *      {@link StringConverter}
065     *      that is used to translate the object instances to Strings.
066     */
067    public StringBasedComparator( final StringConverter<T> stringConverter )
068    {
069        m_StringConverter = requireNonNullArgument( stringConverter, "stringConverter" );
070    }   //  StringBaseComparator()
071
072        /*---------*\
073    ====** Methods **==========================================================
074        \*---------*/
075    /**
076     *  {@inheritDoc}
077     */
078    @Override
079    public int compare( final T o1, final T o2 )
080    {
081        return Integer.signum( Comparator.<String>naturalOrder().compare( m_StringConverter.toString( o1 ), m_StringConverter.toString( o2 ) ) );
082    }   //  compare()
083}
084//  class StringBasedComparator
085
086/*
087 *  End of File
088 */