001/*
002 *  Copyright 2001-2010 Stephen Colebourne
003 *
004 *  Licensed under the Apache License, Version 2.0 (the "License");
005 *  you may not use this file except in compliance with the License.
006 *  You may obtain a copy of the License at
007 *
008 *      http://www.apache.org/licenses/LICENSE-2.0
009 *
010 *  Unless required by applicable law or agreed to in writing, software
011 *  distributed under the License is distributed on an "AS IS" BASIS,
012 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 *  See the License for the specific language governing permissions and
014 *  limitations under the License.
015 */
016package org.joda.primitives.list;
017
018import java.util.List;
019
020import org.joda.primitives.collection.PrimitiveCollection;
021
022/**
023 * Base interface for all primitive list interfaces.
024 * <p>
025 * This interface extends {@link List} allowing seamless integration with other APIs.
026 * All List methods can be used, using the primitive wrapper class.
027 * However, it will be <em>much</em> more efficient to use the direct primitive methods
028 * in the subinterface.
029 * 
030 * @author Stephen Colebourne
031 * @since 1.0
032 */
033public interface PrimitiveList<E> extends PrimitiveCollection<E>, List<E> {
034
035    // Mandatory operations
036    //-----------------------------------------------------------------------
037    /**
038     * Gets the first list value.
039     *
040     * @return value at index zero, or null if the size is zero
041     */
042    E first();
043
044    /**
045     * Gets the last list value.
046     *
047     * @return value at index <code>size() - 1</code> or null if the size is zero
048     */
049    E last();
050
051    // Optional operations
052    //-----------------------------------------------------------------------
053    /**
054     * Removes a range of values from the list (optional operation).
055     * <p>
056     * This method is optional, throwing an UnsupportedOperationException if the
057     * list cannot be modified.
058     *
059     * @param fromIndexInclusive  the start of the range to remove, inclusive
060     * @param toIndexExclusive  the end of the range to remove, exclusive
061     * @return <code>true</code> if the collection was modified
062     * @throws IndexOutOfBoundsException if the index is invalid
063     * @throws UnsupportedOperationException if remove is not supported
064     */
065    boolean removeRange(int fromIndexInclusive, int toIndexExclusive);
066
067}