/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.commons.collections.primitives;

/**
 * An ordered collection of <code>byte</code> values.
 *
 * @see org.apache.commons.collections.primitives.adapters.ByteListList
 * @see org.apache.commons.collections.primitives.adapters.ListByteList
 *
 * @since Commons Primitives 1.0
 * @version $Revision: 480460 $ $Date: 2006-11-29 03:14:21 -0500 (Wed, 29 Nov 2006) $
 * 
 * @author Rodney Waldhoff 
 */
public interface ByteList extends ByteCollection {
    /** 
     * Appends the specified element to the end of me
     * (optional operation).  Returns <code>true</code>
     * iff I changed as a result of this call.
     * <p/>
     * If a collection refuses to add the specified
     * element for any reason other than that it already contains
     * the element, it <i>must</i> throw an exception (rather than
     * simply returning <tt>false</tt>).  This preserves the invariant
     * that a collection always contains the specified element after 
     * this call returns. 
     * 
     * @param element the value whose presence within me is to be ensured
     * @return <code>true</code> iff I changed as a result of this call
     * 
     * @throws UnsupportedOperationException when this operation is not 
     *         supported
     * @throws IllegalArgumentException may be thrown if some aspect of the 
     *         specified element prevents it from being added to me
     */
    boolean add(byte element);
       
    /** 
     * Inserts the specified element at the specified position 
     * (optional operation). Shifts the element currently 
     * at that position (if any) and any subsequent elements to the 
     * right, increasing their indices.
     * 
     * @param index the index at which to insert the element
     * @param element the value to insert
     * 
     * @throws UnsupportedOperationException when this operation is not 
     *         supported
     * @throws IllegalArgumentException if some aspect of the specified element 
     *         prevents it from being added to me
     * @throws IndexOutOfBoundsException if the specified index is out of range
     */
    void add(int index, byte element);
          
    /** 
     * Inserts all of the elements in the specified collection into me,
     * at the specified position (optional operation).  Shifts the 
     * element currently at that position (if any) and any subsequent 
     * elements to the right, increasing their indices.  The new elements 
     * will appear in the order that they are returned by the given 
     * collection's {@link ByteCollection#iterator iterator}.
     * 
     * @param index the index at which to insert the first element from 
     *        the specified collection
     * @param collection the {@link ByteCollection ByteCollection} of elements to add 
     * @return <code>true</code> iff I changed as a result of this call
     * 
     * @throws UnsupportedOperationException when this operation is not 
     *         supported
     * @throws IndexOutOfBoundsException if the specified index is out of range
     */
    boolean addAll(int index, ByteCollection collection);
    
    /**
     * Returns <code>true</code> iff <i>that</i> is an <code>ByteList</code>
     * that contains the same elements in the same order as me.
     * In other words, returns <code>true</code> iff <i>that</i> is
     * a <code>ByteList</code> that has the same {@link #size() size} as me,
     * and for which the elements returned by its 
     * {@link ByteList#iterator iterator} are equal (<code>==</code>) to
     * the corresponding elements within me.
     * (This contract ensures that this method works properly across 
     * different implementations of the <code>ByteList</code> interface.)
     * 
     * @param that the object to compare to me
     * @return <code>true</code> iff <i>that</i> is an <code>ByteList</code>
     *         that contains the same elements in the same order as me
     */
    boolean equals(Object that);
    
    /** 
     * Returns the value of the element at the specified position 
     * within me. 
     * 
     * @param index the index of the element to return
     * @return the value of the element at the specified position
     * @throws IndexOutOfBoundsException if the specified index is out of range
     */
    byte get(int index);
        
    /**
     * Returns my hash code.
     * <p />
     * The hash code of an <code>ByteList</code> is defined to be the
     * result of the following calculation:
     * <pre> int hash = 1;
     * for(ByteIterator iter = iterator(); iter.hasNext(); ) {
     *   byte value = iter.next();
     *   hash = 31*hash + (int)(value ^ (value >>> 32));
     * }</pre>
     * <p />
     * This contract ensures that this method is consistent with 
     * {@link #equals equals} and with the 
     * {@link java.util.List#hashCode hashCode}
     * method of a {@link java.util.List List} of {@link Byte}s. 
     * 
     * @return my hash code
     */
    int hashCode();

    /** 
     * Returns the index of the first occurrence 
     * of the specified element within me, 
     * or <code>-1</code> if I do not contain 
     * the element. 
     * 
     * @param element the element to search for
     * @return the smallest index of an element matching the specified value,
     *         or <code>-1</code> if no such matching element can be found 
     */
    int indexOf(byte element);
     
    /** 
     * Returns an {@link ByteIterator iterator} over all my elements,
     * in the appropriate sequence.
     * @return an {@link ByteIterator iterator} over all my elements.
     */
    ByteIterator iterator();

    /** 
     * Returns the index of the last occurrence 
     * of the specified element within me, 
     * or -1 if I do not contain the element. 
     * 
     * @param element the element to search for
     * @return the largest index of an element matching the specified value,
     *         or <code>-1</code> if no such matching element can be found 
     */
    int lastIndexOf(byte element);
    
    /** 
     * Returns a 
     * {@link ByteListIterator bidirectional iterator}
     * over all my elements, in the appropriate sequence.
     */
    ByteListIterator listIterator();
    
    /** 
     * Returns a 
     * {@link ByteListIterator bidirectional iterator}
     * over all my elements, in the appropriate sequence, 
     * starting at the specified position. The 
     * specified <i>index</i> indicates the first 
     * element that would be returned by an initial 
     * call to the 
     * {@link ByteListIterator#next next} 
     * method. An initial call to the 
     * {@link ByteListIterator#previous previous}
     * method would return the element with the specified 
     * <i>index</i> minus one.
     * 
     * @throws IndexOutOfBoundsException if the specified index is out of range
     */
    ByteListIterator listIterator(int index);
    
    /** 
     * Removes the element at the specified position in 
     * (optional operation).  Any subsequent elements 
     * are shifted to the left, subtracting one from their 
     * indices.  Returns the element that was removed.
     * 
     * @param index the index of the element to remove
     * @return the value of the element that was removed
     * 
     * @throws UnsupportedOperationException when this operation is not 
     *         supported
     * @throws IndexOutOfBoundsException if the specified index is out of range
     */
    byte removeElementAt(int index);
   
    /** 
     * Replaces the element at the specified 
     * position in me with the specified element
     * (optional operation). 
     * 
     * @param index the index of the element to change
     * @param element the value to be stored at the specified position
     * @return the value previously stored at the specified position
     * 
     * @throws UnsupportedOperationException when this operation is not 
     *         supported
     * @throws IndexOutOfBoundsException if the specified index is out of range
     */
    byte set(int index, byte element);
    
    /** 
     * Returns a view of the elements within me 
     * between the specified <i>fromIndex</i>, inclusive, and 
     * <i>toIndex</i>, exclusive.  The returned <code>ByteList</code>
     * is backed by me, so that any changes in 
     * the returned list are reflected in me, and vice-versa.
     * The returned list supports all of the optional operations
     * that I support.
     * <p/>
     * Note that when <code><i>fromIndex</i> == <i>toIndex</i></code>,
     * the returned list is initially empty, and when 
     * <code><i>fromIndex</i> == 0 && <i>toIndex</i> == {@link #size() size()}</code>
     * the returned list is my "improper" sublist, containing all my elements.
     * <p/>
     * The semantics of the returned list become undefined
     * if I am structurally modified in any way other than 
     * via the returned list.
     * 
     * @param fromIndex the smallest index (inclusive) in me that appears in 
     *        the returned list
     * @param toIndex the largest index (exclusive) in me that appears in the 
     *        returned list
     * @return a view of this list from <i>fromIndex</i> (inclusive) to 
     *         <i>toIndex</i> (exclusive)
     * 
     * @throws IndexOutOfBoundsException if either specified index is out of range
     */
    ByteList subList(int fromIndex, int toIndex);

}