/*
 *    Geotoolkit.org - An Open Source Java GIS Toolkit
 *    http://www.geotoolkit.org
 *
 *    (C) 2010-2012, Open Source Geospatial Foundation (OSGeo)
 *    (C) 2010-2012, Geomatys
 *
 *    This library is free software; you can redistribute it and/or
 *    modify it under the terms of the GNU Lesser General Public
 *    License as published by the Free Software Foundation;
 *    version 2.1 of the License.
 *
 *    This library is distributed in the hope that it will be useful,
 *    but WITHOUT ANY WARRANTY; without even the implied warranty of
 *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *    Lesser General Public License for more details.
 */
package org.geotoolkit.referencing.cs;

import org.apache.sis.measure.Range;
import org.apache.sis.util.collection.CheckedContainer;


/**
 * Interface for coordinate systems axes having a finite number of discrete ordinate values.
 * This interface is sometime used for axes associated to a grid coverage, for example in the
 * NetCDF file format. Instances can be created by {@link DiscreteReferencingFactory}.
 *
 * {@note The services provided by <code>DiscreteCoordinateSystemAxis</code> are redundant with
 * the service provided by the <cite>grid to CRS</cite> transform associated with grid geometries.
 * However this interface is defined as a more convenient way to access irregular ordinate values
 * on independent axes, for example a list of time instants on the temporal axis.}
 *
 * @param  <T> The type of axis ordinates. This is typically {@link Integer}, {@link Float},
 *         {@link Double}, {@link java.util.Date} or {@link String}.
 *
 * @author Martin Desruisseaux (Geomatys)
 * @version 3.20
 *
 * @see org.opengis.referencing.cs.CoordinateSystemAxis
 * @see org.opengis.coverage.grid.GridGeometry#getGridToCRS()
 *
 * @since 3.15
 * @module
 */
public interface DiscreteCoordinateSystemAxis<T extends Comparable<? super T>> extends CheckedContainer<T> {
    /**
     * Returns the type of values in this discrete axis.
     */
    @Override
    Class<T> getElementType();

    /**
     * Returns the number of ordinate values.
     *
     * @return The number of ordinate values.
     */
    int length();

    /**
     * Returns the ordinate value at the given index. The returned value is typically
     * an instance of {@link Number} or {@link java.util.Date}.
     *
     * @param  index The index at which to return the ordinate value.
     * @return The ordinate value at the given index as a {@link Number},
     *         {@link java.util.Date} or {@link String}.
     * @throws IndexOutOfBoundsException If the given index is outside the
     *         [0 … {@linkplain #length() length}-1] range.
     */
    Comparable<T> getOrdinateAt(int index) throws IndexOutOfBoundsException;

    /**
     * Returns the range of ordinate values at the given index. The {@linkplain Range#getMinValue()
     * range minimum} and {@linkplain Range#getMaxValue() range maximum} are the values where the
     * underlying grid element switches from "belonging to" the ordinate value referenced by
     * <code>index±1</code> to "belonging to" the ordinate value referenced by {@code index}.
     * <p>
     * The value returned by {@link #getOrdinateAt(int)} is typically in the middle of the range
     * returned by this method for the same index, but not necessarily.
     *
     * @param  index The index at which to return the range of ordinate values.
     * @return The range of ordinate values at the given index.
     * @throws IndexOutOfBoundsException If the given index is outside the
     *         [0 … {@linkplain #length() length}-1] range.
     * @throws UnsupportedOperationException if the axis is not numeric.
     */
    Range<T> getOrdinateRangeAt(int index) throws IndexOutOfBoundsException, UnsupportedOperationException;
}