/*		 
 * Copyright (C) 2010-2014 Sebastiano Vigna 
 *
 * Licensed 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 PACKAGE;

import java.util.List;
import it.unimi.dsi.fastutil.BigList;

#if ! #keyclass(Reference)

/** A type-specific {@link BigList}; provides some additional methods that use polymorphism to avoid (un)boxing. 
 *
 * <P>Additionally, this interface strengthens {@link #iterator()}, {@link #listIterator()},
 * {@link #listIterator(long)} and {@link #subList(long,long)}.
 *
 * <P>Besides polymorphic methods, this interfaces specifies methods to copy into an array or remove contiguous
 * sublists. Although the abstract implementation of this interface provides simple, one-by-one implementations
 * of these methods, it is expected that concrete implementation override them with optimized versions.
 *
 * @see List
 */

public interface BIG_LIST KEY_GENERIC extends BigList<KEY_GENERIC_CLASS>, COLLECTION KEY_GENERIC, Comparable<BigList<? extends KEY_GENERIC_CLASS>> {
#else

/** A type-specific {@link BigList}; provides some additional methods that use polymorphism to avoid (un)boxing. 
 *
 * <P>Additionally, this interface strengthens {@link #iterator()}, {@link #listIterator()},
 * {@link #listIterator(long)} and {@link #subList(long,long)}.
 *
 * <P>Besides polymorphic methods, this interfaces specifies methods to copy into an array or remove contiguous
 * sublists. Although the abstract implementation of this interface provides simple, one-by-one implementations
 * of these methods, it is expected that concrete implementation override them with optimized versions.
 *
 * @see List
 */

public interface BIG_LIST KEY_GENERIC extends BigList<KEY_GENERIC_CLASS>, COLLECTION KEY_GENERIC {
#endif

	/** Returns a type-specific big-list iterator on this type-specific big list.
	 *
	 * @see List#iterator()
	 */
	KEY_BIG_LIST_ITERATOR KEY_GENERIC iterator();

	/** Returns a type-specific big-list iterator on this type-specific big list.
	 *
	 * @see List#listIterator()
	 */
	KEY_BIG_LIST_ITERATOR KEY_GENERIC listIterator();

	/** Returns a type-specific list iterator on this type-specific big list starting at a given index.
	 *
	 * @see BigList#listIterator(long)
	 */
	KEY_BIG_LIST_ITERATOR KEY_GENERIC listIterator( long index );

	/** Returns a type-specific view of the portion of this type-specific big list from the index <code>from</code>, inclusive, to the index <code>to</code>, exclusive.
	 *
	 * <P>Note that this specification strengthens the one given in {@link BigList#subList(long,long)}.
	 *
	 * @see BigList#subList(long,long)
	 */
	BIG_LIST KEY_GENERIC subList( long from, long to );

	/** Copies (hopefully quickly) elements of this type-specific big list into the given big array.
	 *
	 * @param from the start index (inclusive).
	 * @param a the destination big array.
	 * @param offset the offset into the destination big array where to store the first element copied.
	 * @param length the number of elements to be copied.
	 */
	void getElements( long from, KEY_TYPE a[][], long offset, long length );

	/** Removes (hopefully quickly) elements of this type-specific big list.
	 *
	 * @param from the start index (inclusive).
	 * @param to the end index (exclusive).
	 */
	void removeElements( long from, long to );

	/** Add (hopefully quickly) elements to this type-specific big list.
	 *
	 * @param index the index at which to add elements.
	 * @param a the big array containing the elements.
	 */
	void addElements( long index, KEY_GENERIC_TYPE a[][] );

	/** Add (hopefully quickly) elements to this type-specific big list.
	 *
	 * @param index the index at which to add elements.
	 * @param a the big array containing the elements.
	 * @param offset the offset of the first element to add.
	 * @param length the number of elements to add.
	 */
	void addElements( long index, KEY_GENERIC_TYPE a[][], long offset, long length );

#if #keys(primitive)

	/**
	 * @see List#add(int,Object)
	 */
	void add( long index, KEY_TYPE key );

	/**
	 * @see List#addAll(int,java.util.Collection)
	 */
	boolean addAll( long index, COLLECTION c );

	/**
	 * @see List#addAll(int,java.util.Collection)
	 */
	boolean addAll( long index, BIG_LIST c );

	/**
	 * @see List#addAll(int,java.util.Collection)
	 */
	boolean addAll( BIG_LIST c );

	/**
	 * @see BigList#get(long)
	 */
	KEY_TYPE GET_KEY( long index );

	/**
	 * @see BigList#indexOf(Object)
	 */
	long indexOf( KEY_TYPE k );

	/**
	 * @see BigList#lastIndexOf(Object)
	 */
	long lastIndexOf( KEY_TYPE k );

	/**
	 * @see BigList#remove(long)
	 */
	KEY_TYPE REMOVE_KEY( long index );

	/**
	 * @see BigList#set(long,Object)
	 */
	KEY_TYPE set( long index, KEY_TYPE k );

#endif

}