001/*
002 * ============================================================================
003 * Copyright © 2014 by Dominic Fox.
004 * All Rights Reserved.
005 * ============================================================================
006 * The MIT License (MIT)
007 *
008 * Permission is hereby granted, free of charge, to any person obtaining a copy
009 * of this software and associated documentation files (the "Software"), to
010 * deal in the Software without restriction, including without limitation the
011 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
012 * sell copies of the Software, and to permit persons to whom the Software is
013 * furnished to do so, subject to the following conditions:
014 *
015 * The above copyright notice and this permission notice shall be included in
016 * all copies or substantial portions of the Software.
017 *
018 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
019 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
020 * FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
021 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
022 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
023 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
024 * IN THE SOFTWARE.
025 */
026
027package org.tquadrat.foundation.stream;
028
029import static org.apiguardian.api.API.Status.STABLE;
030import static org.tquadrat.foundation.lang.Objects.nonNull;
031
032import java.io.Serial;
033import java.io.Serializable;
034import java.util.Map;
035import java.util.Objects;
036
037import org.apiguardian.api.API;
038import org.tquadrat.foundation.annotation.ClassVersion;
039
040/**
041 *  A value combined with an index, indicating its position in an ordered
042 *  sequence.
043 *
044 *  @param  <T> The type of the indexed value.
045 *
046 *  @author Dominic Fox
047 *  @modified Thomas Thrien - thomas.thrien@tquadrat.org
048 *  @version $Id: Indexed.java 1078 2023-10-19 14:39:47Z tquadrat $
049 *  @since 0.0.7
050 *
051 *  @UMLGraph.link
052 */
053@ClassVersion( sourceVersion = "$Id: Indexed.java 1078 2023-10-19 14:39:47Z tquadrat $" )
054@API( status = STABLE, since = "0.0.7" )
055public final class Indexed<T> implements Map.Entry<Long,T>, Serializable
056{
057        /*------------*\
058    ====** Attributes **=======================================================
059        \*------------*/
060    /**
061     *  The index.
062     *
063     *  @serial
064     */
065    private final long m_Index;
066
067    /**
068     *  The value.
069     *
070     *  @serial
071     */
072    private T m_Value;
073
074        /*--------------*\
075    ====** Constructors **=====================================================
076        \*--------------*/
077    /**
078     *  Creates a new {@code Indexed} instance.
079     *
080     *  @param  index   The index.
081     *  @param  value   The value.
082     */
083    private Indexed( final long index, final T value )
084    {
085        m_Index = index;
086        m_Value = value;
087    }   //  Indexed()
088
089        /*------------------------*\
090    ====** Static Initialisations **===========================================
091        \*------------------------*/
092    /**
093     *  The serial version UID for objects of this class: {@value}.
094     *
095     *  @hidden
096     */
097    @Serial
098    private static final long serialVersionUID = 1L;
099
100        /*---------*\
101    ====** Methods **==========================================================
102        \*---------*/
103    /**
104     *  Factory method for instances of {@code Indexed}; it combines an index
105     *  and a value into an indexed value.
106     *
107     *  @param  <T> The type of the value.
108     *  @param  index   The index of the value.
109     *  @param  value   The value indexed.
110     *  @return The indexed value.
111     */
112    public static <T> Indexed<T> index( final long index, final T value )
113    {
114        final var retValue = new Indexed<>( index, value );
115
116        //---* Done *----------------------------------------------------------
117        return retValue;
118    }   //  index()
119
120    /**
121     *  {@inheritDoc}
122     */
123    @Override
124    public final boolean equals( final Object obj )
125    {
126        var retValue = this == obj;
127        if( !retValue && nonNull( obj ) && (getClass() == obj.getClass()) )
128        {
129            @SuppressWarnings( "rawtypes" )
130            final var other = (Indexed) obj;
131            retValue = (getIndex() == other.getIndex()) && Objects.equals( getValue(), other.getValue() );
132        }
133
134        //---* Done *----------------------------------------------------------
135        return retValue;
136    }   //  equals()
137
138    /**
139     *  Returns the index.
140     *
141     *  @return The index.
142     */
143    public final long getIndex() { return m_Index; }
144
145    /**
146     *  {@inheritDoc}
147     */
148    @Override
149    public final Long getKey() { return Long.valueOf( m_Index ); }
150
151    /**
152     *  The indexed value.
153     *
154     *  @return The value.
155     */
156    @Override
157    public final T getValue() { return m_Value; }
158
159    /**
160     *  {@inheritDoc}
161     */
162    @Override
163    @SuppressWarnings( "NonFinalFieldReferencedInHashCode" )
164    public final int hashCode() { return Objects.hash( m_Index, m_Value ); }
165
166    /**
167     *  {@inheritDoc}
168     */
169    @Override
170    public final T setValue( final T value )
171    {
172        final var retValue = m_Value;
173        m_Value = value;
174
175        //---* Done *----------------------------------------------------------
176        return retValue;
177    }   //  setValue()
178}
179//  class Indexed
180
181/*
182 *  End of File
183 */