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 */
016 package org.joda.primitives.list;
017
018 import java.util.List;
019
020 import 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 */
033 public 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 }