/*		 
 * Copyright (C) 2002-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.Iterator;
import java.util.ListIterator;
import java.util.NoSuchElementException;

/** A class providing static methods and objects that do useful things with type-specific iterators.
 *
 * @see Iterator
 */

public class ITERATORS {

	private ITERATORS() {}
	
	/** A class returning no elements and a type-specific iterator interface.
	 *
	 * <P>This class may be useful to implement your own in case you subclass
	 * a type-specific iterator.
	 */

	public static class EmptyIterator KEY_GENERIC extends KEY_ABSTRACT_LIST_ITERATOR KEY_GENERIC implements java.io.Serializable, Cloneable {

		private static final long serialVersionUID = -7046029254386353129L;

		protected EmptyIterator() {}

		public boolean hasNext() { return false; }
		public boolean hasPrevious() { return false; }
		public KEY_GENERIC_TYPE NEXT_KEY() { throw new NoSuchElementException(); }
		public KEY_GENERIC_TYPE PREV_KEY() { throw new NoSuchElementException(); }
		public int nextIndex() { return 0; }
		public int previousIndex() { return -1; }
		public int skip( int n ) { return 0; };
		public int back( int n ) { return 0; };
		public Object clone() { return EMPTY_ITERATOR; }
        private Object readResolve() { return EMPTY_ITERATOR; }
	}

	/** An empty iterator (immutable). It is serializable and cloneable.
	 *
	 * <P>The class of this objects represent an abstract empty iterator
	 * that can iterate as a type-specific (list) iterator.
	 */

	SUPPRESS_WARNINGS_KEY_RAWTYPES
	public final static EmptyIterator EMPTY_ITERATOR = new EmptyIterator();


	/** An iterator returning a single element. */

	private static class SingletonIterator KEY_GENERIC extends KEY_ABSTRACT_LIST_ITERATOR KEY_GENERIC {
		private final KEY_GENERIC_TYPE element;
		private int curr;

		public SingletonIterator( final KEY_GENERIC_TYPE element ) {
			this.element = element;
		}
	
		public boolean hasNext() { return curr == 0; }
		public boolean hasPrevious() { return curr == 1; }

		public KEY_GENERIC_TYPE NEXT_KEY() {
			if ( ! hasNext() ) throw new NoSuchElementException();
			curr = 1;
			return element;
		}

		public KEY_GENERIC_TYPE PREV_KEY() {
			if ( ! hasPrevious() ) throw new NoSuchElementException();
			curr = 0;
			return element;
		}

		public int nextIndex() {
			return curr;
		}

		public int previousIndex() {
			return curr - 1;
		}
	}


	/** Returns an iterator that iterates just over the given element.
	 *
	 * @param element the only element to be returned by a type-specific list iterator.
	 * @return  an iterator that iterates just over <code>element</code>.
	 */
	public static KEY_GENERIC KEY_LIST_ITERATOR KEY_GENERIC singleton( final KEY_GENERIC_TYPE element ) {
		return new SingletonIterator KEY_GENERIC( element );
	}


	/** A class to wrap arrays in iterators. */

	private static class ArrayIterator KEY_GENERIC extends KEY_ABSTRACT_LIST_ITERATOR KEY_GENERIC {
		private final KEY_GENERIC_TYPE[] array;
		private final int offset, length;
		private int curr;

		public ArrayIterator( final KEY_GENERIC_TYPE[] array, final int offset, final int length ) {
			this.array = array;
			this.offset = offset;
			this.length = length;
		}
	
		public boolean hasNext() { return curr < length; }
		public boolean hasPrevious() { return curr > 0; }

		public KEY_GENERIC_TYPE NEXT_KEY() {
			if ( ! hasNext() ) throw new NoSuchElementException();
			return array[ offset + curr++ ];
		}

		public KEY_GENERIC_TYPE PREV_KEY() {
			if ( ! hasPrevious() ) throw new NoSuchElementException();
			return array[ offset + --curr ];
		}

		public int skip( int n ) {
			if ( n <= length - curr ) {
				curr += n;
				return n;
			}
			n = length - curr;
			curr = length;
			return n;
		}

		public int back( int n ) {
			if ( n <= curr ) {
				curr -= n;
				return n;
			}
			n = curr;
			curr = 0;
			return n;
		}

		public int nextIndex() {
			return curr;
		}

		public int previousIndex() {
			return curr - 1;
		}
	}


	/** Wraps the given part of an array into a type-specific list iterator.
	 *
	 * <P>The type-specific list iterator returned by this method will iterate
	 * <code>length</code> times, returning consecutive elements of the given
	 * array starting from the one with index <code>offset</code>.
	 *
	 * @param array an array to wrap into a type-specific list iterator.
	 * @param offset the first element of the array to be returned.
	 * @param length the number of elements to return.
	 * @return an iterator that will return <code>length</code> elements of <code>array</code> starting at position <code>offset</code>.
	 */
	public static KEY_GENERIC KEY_LIST_ITERATOR KEY_GENERIC wrap( final KEY_GENERIC_TYPE[] array, final int offset, final int length ) {
		ARRAYS.ensureOffsetLength( array, offset, length );
		return new ArrayIterator KEY_GENERIC( array, offset, length );
	}

	/** Wraps the given array into a type-specific list iterator.
	 *
	 * <P>The type-specific list iterator returned by this method will return
	 * all elements of the given array.
	 *
	 * @param array an array to wrap into a type-specific list iterator.
	 * @return an iterator that will the elements of <code>array</code>.
	 */
	public static KEY_GENERIC KEY_LIST_ITERATOR KEY_GENERIC wrap( final KEY_GENERIC_TYPE[] array ) {
		return new ArrayIterator KEY_GENERIC( array, 0, array.length );
	}


	/** Unwraps an iterator into an array starting at a given offset for a given number of elements.
	 *
	 * <P>This method iterates over the given type-specific iterator and stores the elements
	 * returned, up to a maximum of <code>length</code>, in the given array starting at <code>offset</code>.
	 * The number of actually unwrapped elements is returned (it may be less than <code>max</code> if
	 * the iterator emits less than <code>max</code> elements).
	 *
	 * @param i a type-specific iterator.
	 * @param array an array to contain the output of the iterator.
	 * @param offset the first element of the array to be returned.
	 * @param max the maximum number of elements to unwrap.
	 * @return the number of elements unwrapped.
	 */
	public static KEY_GENERIC int unwrap( final STD_KEY_ITERATOR KEY_EXTENDS_GENERIC i, final KEY_GENERIC_TYPE array[], int offset, final int max ) {
		if ( max < 0 ) throw new IllegalArgumentException( "The maximum number of elements (" + max + ") is negative" );
		if ( offset < 0 || offset + max > array.length ) throw new IllegalArgumentException();
		int j = max;
		while( j-- != 0 && i.hasNext() ) array[ offset++ ] = i.NEXT_KEY();
		return max - j - 1;
	}

	/** Unwraps an iterator into an array.
	 *
	 * <P>This method iterates over the given type-specific iterator and stores the
	 * elements returned in the given array. The iteration will stop when the
	 * iterator has no more elements or when the end of the array has been reached.
	 *
	 * @param i a type-specific iterator.
	 * @param array an array to contain the output of the iterator.
	 * @return the number of elements unwrapped.
	 */
	public static KEY_GENERIC int unwrap( final STD_KEY_ITERATOR KEY_EXTENDS_GENERIC i, final KEY_GENERIC_TYPE array[] ) {
		return unwrap( i, array, 0, array.length );
	}

	/** Unwraps an iterator, returning an array, with a limit on the number of elements.
	 *
	 * <P>This method iterates over the given type-specific iterator and returns an array
	 * containing the elements returned by the iterator. At most <code>max</code> elements
	 * will be returned.
	 *
	 * @param i a type-specific iterator.
	 * @param max the maximum number of elements to be unwrapped.
	 * @return an array containing the elements returned by the iterator (at most <code>max</code>).
	 */
	SUPPRESS_WARNINGS_KEY_UNCHECKED
	public static KEY_GENERIC KEY_GENERIC_TYPE[] unwrap( final STD_KEY_ITERATOR KEY_EXTENDS_GENERIC i, int max ) {
		if ( max < 0 ) throw new IllegalArgumentException( "The maximum number of elements (" + max + ") is negative" );
		KEY_GENERIC_TYPE array[] = KEY_GENERIC_ARRAY_CAST new KEY_TYPE[ 16 ];
		int j = 0;

		while( max-- != 0 && i.hasNext() ) {
			if ( j == array.length ) array = ARRAYS.grow( array, j + 1 );
			array[ j++ ] = i.NEXT_KEY();
		}

		return ARRAYS.trim( array, j );
	}


	/** Unwraps an iterator, returning an array.
	 *
	 * <P>This method iterates over the given type-specific iterator and returns an array
	 * containing the elements returned by the iterator.
	 *
	 * @param i a type-specific iterator.
	 * @return an array containing the elements returned by the iterator.
	 */

	public static KEY_GENERIC KEY_GENERIC_TYPE[] unwrap( final STD_KEY_ITERATOR KEY_EXTENDS_GENERIC i ) {
		return unwrap( i, Integer.MAX_VALUE );
	}


	/** Unwraps an iterator into a type-specific collection,  with a limit on the number of elements.
	 *
	 * <P>This method iterates over the given type-specific iterator and stores the elements
	 * returned, up to a maximum of <code>max</code>, in the given type-specific collection.
	 * The number of actually unwrapped elements is returned (it may be less than <code>max</code> if
	 * the iterator emits less than <code>max</code> elements).
	 *
	 * @param i a type-specific iterator.
	 * @param c a type-specific collection array to contain the output of the iterator.
	 * @param max the maximum number of elements to unwrap.
	 * @return the number of elements unwrapped. Note that
	 * this is the number of elements returned by the iterator, which is not necessarily the number
	 * of elements that have been added to the collection (because of duplicates).
	 */
	public static KEY_GENERIC int unwrap( final STD_KEY_ITERATOR KEY_GENERIC i, final COLLECTION KEY_SUPER_GENERIC c, final int max ) {
		if ( max < 0 ) throw new IllegalArgumentException( "The maximum number of elements (" + max + ") is negative" );
		int j = max;
		while( j-- != 0 && i.hasNext() ) c.add( i.NEXT_KEY() );
		return max - j - 1;
	}

	/** Unwraps an iterator into a type-specific collection.
	 *
	 * <P>This method iterates over the given type-specific iterator and stores the
	 * elements returned in the given type-specific collection. The returned count on the number
	 * unwrapped elements is a long, so that it will work also with very large collections.
	 *
	 * @param i a type-specific iterator.
	 * @param c a type-specific collection to contain the output of the iterator.
	 * @return the number of elements unwrapped. Note that
	 * this is the number of elements returned by the iterator, which is not necessarily the number
	 * of elements that have been added to the collection (because of duplicates).
	 */
	public static KEY_GENERIC long unwrap( final STD_KEY_ITERATOR KEY_GENERIC i, final COLLECTION KEY_SUPER_GENERIC c ) {
		long n = 0;
		while( i.hasNext() ) {
			c.add( i.NEXT_KEY() );
			n++;
		}
		return n;
	}


	/** Pours an iterator into a type-specific collection, with a limit on the number of elements.
	 *
	 * <P>This method iterates over the given type-specific iterator and adds
	 * the returned elements to the given collection (up to <code>max</code>).
	 *
	 * @param i a type-specific iterator.
	 * @param s a type-specific collection.
	 * @param max the maximum number of elements to be poured.
	 * @return the number of elements poured. Note that
	 * this is the number of elements returned by the iterator, which is not necessarily the number
	 * of elements that have been added to the collection (because of duplicates).
	 */

	public static KEY_GENERIC int pour( final STD_KEY_ITERATOR KEY_GENERIC i, final COLLECTION KEY_SUPER_GENERIC s, final int max ) {
		if ( max < 0 ) throw new IllegalArgumentException( "The maximum number of elements (" + max + ") is negative" );
		int j = max;
		while( j-- != 0 && i.hasNext() ) s.add( i.NEXT_KEY() );
		return max - j - 1;
	}

	/** Pours an iterator into a type-specific collection.
	 *
	 * <P>This method iterates over the given type-specific iterator and adds
	 * the returned elements to the given collection.
	 *
	 * @param i a type-specific iterator.
	 * @param s a type-specific collection.
	 * @return the number of elements poured. Note that
	 * this is the number of elements returned by the iterator, which is not necessarily the number
	 * of elements that have been added to the collection (because of duplicates).
	 */

	public static KEY_GENERIC int pour( final STD_KEY_ITERATOR KEY_GENERIC i, final COLLECTION KEY_SUPER_GENERIC s ) {
		return pour( i, s, Integer.MAX_VALUE );
	}

	/** Pours an iterator, returning a type-specific list, with a limit on the number of elements.
	 *
	 * <P>This method iterates over the given type-specific iterator and returns
	 * a type-specific list containing the returned elements (up to <code>max</code>). Iteration
	 * on the returned list is guaranteed to produce the elements in the same order
	 * in which they appeared in the iterator.
	 *
	 *
	 * @param i a type-specific iterator.
	 * @param max the maximum number of elements to be poured.
	 * @return a type-specific list containing the returned elements, up to <code>max</code>.
	 */

	public static KEY_GENERIC LIST KEY_GENERIC pour( final STD_KEY_ITERATOR KEY_GENERIC i, int max ) {
		final ARRAY_LIST KEY_GENERIC l = new ARRAY_LIST KEY_GENERIC();
		pour( i, l, max );
		l.trim();
		return l;
	}

	/** Pours an iterator, returning a type-specific list.
	 *
	 * <P>This method iterates over the given type-specific iterator and returns
	 * a list containing the returned elements. Iteration
	 * on the returned list is guaranteed to produce the elements in the same order
	 * in which they appeared in the iterator.
	 *
	 * @param i a type-specific iterator.
	 * @return a type-specific list containing the returned elements.
	 */

	public static KEY_GENERIC LIST KEY_GENERIC pour( final STD_KEY_ITERATOR KEY_GENERIC i ) {
		return pour( i, Integer.MAX_VALUE );
	}

	private static class IteratorWrapper KEY_GENERIC extends KEY_ABSTRACT_ITERATOR KEY_GENERIC {
		final Iterator<KEY_GENERIC_CLASS> i;

		public IteratorWrapper( final Iterator<KEY_GENERIC_CLASS> i ) {
			this.i = i;
		}

		public boolean hasNext() { return i.hasNext(); }
		public void remove() { i.remove(); }

		public KEY_GENERIC_TYPE NEXT_KEY() { return KEY_CLASS2TYPE( i.next() ); }
	}

	/** Wraps a standard iterator into a type-specific iterator.
	 *
	 * <P>This method wraps a standard iterator into a type-specific one which will handle the
	 * type conversions for you. Of course, any attempt to wrap an iterator returning the
	 * instances of the wrong class will generate a {@link ClassCastException}. The
	 * returned iterator is backed by <code>i</code>: changes to one of the iterators
	 * will affect the other, too.
	 *
	 * <P>If <code>i</code> is already type-specific, it will returned and no new object
	 * will be generated.
	 *
	 * @param i an iterator.
	 * @return a type-specific iterator  backed by <code>i</code>.
	 */
#if #keys(primitive)
	@SuppressWarnings({"unchecked","rawtypes"})
#endif
 	public static KEY_GENERIC KEY_ITERATOR KEY_GENERIC AS_KEY_ITERATOR( final Iterator KEY_GENERIC i ) {
		if ( i instanceof KEY_ITERATOR ) return (KEY_ITERATOR KEY_GENERIC)i;
		return new IteratorWrapper KEY_GENERIC( i );
	}


	private static class ListIteratorWrapper KEY_GENERIC extends KEY_ABSTRACT_LIST_ITERATOR KEY_GENERIC {
		final ListIterator<KEY_GENERIC_CLASS> i;

		public ListIteratorWrapper( final ListIterator<KEY_GENERIC_CLASS> i ) {
			this.i = i;
		}

		public boolean hasNext() { return i.hasNext(); }
		public boolean hasPrevious() { return i.hasPrevious(); }
		public int nextIndex() { return i.nextIndex(); }
		public int previousIndex() { return i.previousIndex(); }
		public void set( KEY_GENERIC_TYPE k ) { i.set( KEY2OBJ( k ) ); }
		public void add( KEY_GENERIC_TYPE k ) { i.add( KEY2OBJ( k ) ); }
		public void remove() { i.remove(); }

		public KEY_GENERIC_TYPE NEXT_KEY() { return KEY_CLASS2TYPE( i.next() ); }
		public KEY_GENERIC_TYPE PREV_KEY() { return KEY_CLASS2TYPE( i.previous() ); }
	}

	/** Wraps a standard list iterator into a type-specific list iterator.
	 *
	 * <P>This method wraps a standard list iterator into a type-specific one
	 * which will handle the type conversions for you. Of course, any attempt
	 * to wrap an iterator returning the instances of the wrong class will
	 * generate a {@link ClassCastException}. The
	 * returned iterator is backed by <code>i</code>: changes to one of the iterators
	 * will affect the other, too.
	 *
	 * <P>If <code>i</code> is already type-specific, it will returned and no new object
	 * will be generated.
	 *
	 * @param i a list iterator.
	 * @return a type-specific list iterator backed by <code>i</code>.
	 */
#if #keys(primitive)
	@SuppressWarnings({"unchecked","rawtypes"})
#endif
 	public static KEY_GENERIC KEY_LIST_ITERATOR KEY_GENERIC AS_KEY_ITERATOR( final ListIterator KEY_GENERIC i ) {
		if ( i instanceof KEY_LIST_ITERATOR ) return (KEY_LIST_ITERATOR KEY_GENERIC)i;
		return new ListIteratorWrapper KEY_GENERIC( i );
	}


#if #keyclass(Integer) || #keyclass(Byte) || #keyclass(Short) || #keyclass(Character) || #keyclass(Long)

#if #keyclass(Long)
	private static class IntervalIterator extends KEY_ABSTRACT_BIDI_ITERATOR {
#else
	private static class IntervalIterator extends KEY_ABSTRACT_LIST_ITERATOR {
#endif
		private final KEY_TYPE from, to;
		KEY_TYPE curr;

		public IntervalIterator( final KEY_TYPE from, final KEY_TYPE to ) {
			this.from = this.curr = from;
			this.to = to;
		}

		public boolean hasNext() { return curr < to; }
		public boolean hasPrevious() { return curr > from; }

		public KEY_TYPE NEXT_KEY() { 
			if ( ! hasNext() ) throw new NoSuchElementException();
			return curr++; 
		}
		public KEY_TYPE PREV_KEY() { 
			if ( ! hasPrevious() ) throw new NoSuchElementException();
			return --curr; 
		}

#if ! #keyclass(Long)
		public int nextIndex() { return curr - from; }
		public int previousIndex() { return curr - from - 1; }
#endif

		public int skip( int n ) {
			if ( curr + n <= to ) {
				curr += n;
				return n;
			}
#if ! #keyclass(Long)
			n = to - curr;
#else
			n = (int)( to - curr );
#endif
			curr = to;
			return n;
		}

		public int back( int n ) {
			if ( curr - n >= from ) {
				curr -= n;
				return n;
			}
#if ! #keyclass(Long)
			n = curr - from ;
#else
			n = (int)( curr - from );
#endif
			curr = from;
			return n;
		}
	}
		
#if #keyclass(Long)
	/** Creates a type-specific bidirectional iterator over an interval.
	 *
	 * <P>The type-specific bidirectional iterator returned by this method will return the
	 * elements <code>from</code>, <code>from+1</code>,&hellip;, <code>to-1</code>.
	 *
	 * <P>Note that all other type-specific interval iterator are <em>list</em>
	 * iterators. Of course, this is not possible with longs as the index
	 * returned by {@link java.util.ListIterator#nextIndex() nextIndex()}/{@link
	 * java.util.ListIterator#previousIndex() previousIndex()} would exceed an integer.
	 *
	 * @param from the starting element (inclusive).
	 * @param to the ending element (exclusive).
	 * @return a type-specific bidirectional iterator enumerating the elements from <code>from</code> to <code>to</code>.
	 */
	public static KEY_BIDI_ITERATOR fromTo( final KEY_TYPE from, final KEY_TYPE to ) {
		return new IntervalIterator( from, to );
	}
#else

	/** Creates a type-specific list iterator over an interval.
	 *
	 * <P>The type-specific list iterator returned by this method will return the
	 * elements <code>from</code>, <code>from+1</code>,&hellip;, <code>to-1</code>.
	 *
	 * @param from the starting element (inclusive).
	 * @param to the ending element (exclusive).
	 * @return a type-specific list iterator enumerating the elements from <code>from</code> to <code>to</code>.
	 */
	public static KEY_LIST_ITERATOR fromTo( final KEY_TYPE from, final KEY_TYPE to ) {
		return new IntervalIterator( from, to );
	}

#endif

#endif

	private static class IteratorConcatenator KEY_GENERIC extends KEY_ABSTRACT_ITERATOR KEY_GENERIC {
		final KEY_ITERATOR KEY_EXTENDS_GENERIC a[];
		int offset, length, lastOffset = -1;

		public IteratorConcatenator( final KEY_ITERATOR KEY_EXTENDS_GENERIC a[], int offset, int length ) {
			this.a = a;
			this.offset = offset;
			this.length = length;
			advance();
		}

		private void advance() {
			while( length != 0 ) {
				if ( a[ offset ].hasNext() ) break;
				length--;
				offset++;
			}

			return;
		}

		public boolean hasNext() {
			return length > 0;
		}

		public KEY_GENERIC_TYPE NEXT_KEY() {
			if ( ! hasNext() ) throw new NoSuchElementException();
			KEY_GENERIC_TYPE next = a[ lastOffset = offset ].NEXT_KEY();
			advance();
			return next;
		}

		public void remove() {
			if ( lastOffset == -1 ) throw new IllegalStateException();
			a[ lastOffset ].remove();
		}

		public int skip( int n ) {
			lastOffset = -1;

			int skipped = 0;

			while( skipped < n && length != 0 ) {
				skipped += a[ offset ].skip( n - skipped );
				if ( a[ offset ].hasNext() ) break;
				length--;
				offset++;
			}
			
			return skipped;
		}

	}


	/** Concatenates all iterators contained in an array.
	 *
	 * <P>This method returns an iterator that will enumerate in order the elements returned
	 * by all iterators contained in the given array.
	 *
	 * @param a an array of iterators.
	 * @return an iterator obtained by concatenation.
	 */

	public static KEY_GENERIC KEY_ITERATOR KEY_GENERIC concat( final KEY_ITERATOR KEY_EXTENDS_GENERIC a[] ) {
		return concat( a, 0, a.length );
	}


	/** Concatenates a sequence of iterators contained in an array.
	 *
	 * <P>This method returns an iterator that will enumerate in order the elements returned
	 * by <code>a[ offset ]</code>, then those returned 
	 * by <code>a[ offset + 1 ]</code>, and so on up to 
	 * <code>a[ offset + length - 1 ]</code>. 
	 *
	 * @param a an array of iterators.
	 * @param offset the index of the first iterator to concatenate.
	 * @param length the number of iterators to concatenate.
	 * @return an iterator obtained by concatenation of <code>length</code> elements of <code>a</code> starting at <code>offset</code>.
	 */

	public static KEY_GENERIC KEY_ITERATOR KEY_GENERIC concat( final KEY_ITERATOR KEY_EXTENDS_GENERIC a[], final int offset, final int length ) {
		return new IteratorConcatenator KEY_GENERIC( a, offset, length );
	}


  	/** An unmodifiable wrapper class for iterators. */


	public static class UnmodifiableIterator KEY_GENERIC extends KEY_ABSTRACT_ITERATOR KEY_GENERIC {
		final protected KEY_ITERATOR KEY_GENERIC i;

		public UnmodifiableIterator( final KEY_ITERATOR KEY_GENERIC i ) {
			this.i = i;
		}

		public boolean hasNext() { return i.hasNext(); }

		public KEY_GENERIC_TYPE NEXT_KEY() { return i.NEXT_KEY(); }
#if #keys(primitive)
		public KEY_GENERIC_CLASS next() { return i.next(); }
#endif
	}


	/** Returns an unmodifiable iterator backed by the specified iterator.
	 *
	 * @param i the iterator to be wrapped in an unmodifiable iterator.
	 * @return an unmodifiable view of the specified iterator.
	 */
	public static KEY_GENERIC KEY_ITERATOR KEY_GENERIC unmodifiable( final KEY_ITERATOR KEY_GENERIC i ) { return new UnmodifiableIterator KEY_GENERIC( i ); }



  	/** An unmodifiable wrapper class for bidirectional iterators. */

	public static class UnmodifiableBidirectionalIterator KEY_GENERIC extends KEY_ABSTRACT_BIDI_ITERATOR KEY_GENERIC {
		final protected KEY_BIDI_ITERATOR KEY_GENERIC i;

		public UnmodifiableBidirectionalIterator( final KEY_BIDI_ITERATOR KEY_GENERIC i ) {
			this.i = i;
		}

		public boolean hasNext() { return i.hasNext(); }
		public boolean hasPrevious() { return i.hasPrevious(); }
		public KEY_GENERIC_TYPE NEXT_KEY() { return i.NEXT_KEY(); }
		public KEY_GENERIC_TYPE PREV_KEY() { return i.PREV_KEY(); }
#if #keys(primitive)
		public KEY_GENERIC_CLASS next() { return i.next(); }
		public KEY_GENERIC_CLASS previous() { return i.previous(); }
#endif
	}


	/** Returns an unmodifiable bidirectional iterator backed by the specified bidirectional iterator.
	 *
	 * @param i the bidirectional iterator to be wrapped in an unmodifiable bidirectional iterator.
	 * @return an unmodifiable view of the specified bidirectional iterator.
	 */
	public static KEY_GENERIC KEY_BIDI_ITERATOR KEY_GENERIC unmodifiable( final KEY_BIDI_ITERATOR KEY_GENERIC i ) { return new UnmodifiableBidirectionalIterator KEY_GENERIC( i ); }


  	/** An unmodifiable wrapper class for list iterators. */

	public static class UnmodifiableListIterator KEY_GENERIC extends KEY_ABSTRACT_LIST_ITERATOR KEY_GENERIC {
		final protected KEY_LIST_ITERATOR KEY_GENERIC i;

		public UnmodifiableListIterator( final KEY_LIST_ITERATOR KEY_GENERIC i ) {
			this.i = i;
		}

		public boolean hasNext() { return i.hasNext(); }
		public boolean hasPrevious() { return i.hasPrevious(); }
		public KEY_GENERIC_TYPE NEXT_KEY() { return i.NEXT_KEY(); }
		public KEY_GENERIC_TYPE PREV_KEY() { return i.PREV_KEY(); }
		public int nextIndex() { return i.nextIndex(); }
		public int previousIndex() { return i.previousIndex(); }
#if #keys(primitive)
		public KEY_GENERIC_CLASS next() { return i.next(); }
		public KEY_GENERIC_CLASS previous() { return i.previous(); }
#endif
	}

	/** Returns an unmodifiable list iterator backed by the specified list iterator.
	 *
	 * @param i the list iterator to be wrapped in an unmodifiable list iterator.
	 * @return an unmodifiable view of the specified list iterator.
	 */
	public static KEY_GENERIC KEY_LIST_ITERATOR KEY_GENERIC unmodifiable( final KEY_LIST_ITERATOR KEY_GENERIC i ) { return new UnmodifiableListIterator KEY_GENERIC( i ); }

#if #keyclass(Short) || #keyclass(Integer) || #keyclass(Long) || #keyclass(Float) || #keyclass(Double)

  	/** A wrapper promoting the results of a ByteIterator. */

	protected static class ByteIteratorWrapper implements KEY_ITERATOR {
		final it.unimi.dsi.fastutil.bytes.ByteIterator iterator;
		
		public ByteIteratorWrapper( final it.unimi.dsi.fastutil.bytes.ByteIterator iterator ) {
			this.iterator = iterator;
		}
	
		public boolean hasNext() { return iterator.hasNext(); }
		public KEY_GENERIC_CLASS next() { return KEY_GENERIC_CLASS.valueOf( iterator.nextByte() ); }
		public KEY_TYPE NEXT_KEY() { return iterator.nextByte(); }
		public void remove() { iterator.remove(); }
		public int skip( final int n ) { return iterator.skip( n ); }
	}

	/** Returns an iterator backed by the specified byte iterator. 
	 * @return an iterator backed by the specified byte iterator. 
	 */
	public static KEY_ITERATOR wrap( final it.unimi.dsi.fastutil.bytes.ByteIterator iterator ) {
		return new ByteIteratorWrapper( iterator );
	}
#endif

#if #keyclass(Integer) || #keyclass(Long) || #keyclass(Float) || #keyclass(Double)

  	/** A wrapper promoting the results of a ShortIterator. */

	protected static class ShortIteratorWrapper implements KEY_ITERATOR {
		final it.unimi.dsi.fastutil.shorts.ShortIterator iterator;
		
		public ShortIteratorWrapper( final it.unimi.dsi.fastutil.shorts.ShortIterator iterator ) {
			this.iterator = iterator;
		}
	
		public boolean hasNext() { return iterator.hasNext(); }
		public KEY_GENERIC_CLASS next() { return KEY_GENERIC_CLASS.valueOf( iterator.nextShort() ); }
		public KEY_TYPE NEXT_KEY() { return iterator.nextShort(); }
		public void remove() { iterator.remove(); }
		public int skip( final int n ) { return iterator.skip( n ); }
	}

	/** Returns an iterator backed by the specified short iterator. 
	 * @return an iterator backed by the specified short iterator. 
	 */
	public static KEY_ITERATOR wrap( final it.unimi.dsi.fastutil.shorts.ShortIterator iterator ) {
		return new ShortIteratorWrapper( iterator );
	}

#endif

#if #keyclass(Long) || #keyclass(Double)

  	/** A wrapper promoting the results of an IntIterator. */

	protected static class IntIteratorWrapper implements KEY_ITERATOR {
		final it.unimi.dsi.fastutil.ints.IntIterator iterator;
		
		public IntIteratorWrapper( final it.unimi.dsi.fastutil.ints.IntIterator iterator ) {
			this.iterator = iterator;
		}
	
		public boolean hasNext() { return iterator.hasNext(); }
		public KEY_GENERIC_CLASS next() { return KEY_GENERIC_CLASS.valueOf( iterator.nextInt() ); }
		public KEY_TYPE NEXT_KEY() { return iterator.nextInt(); }
		public void remove() { iterator.remove(); }
		public int skip( final int n ) { return iterator.skip( n ); }
	}

	/** Returns an iterator backed by the specified integer iterator. 
	 * @return an iterator backed by the specified integer iterator. 
	 */

	public static KEY_ITERATOR wrap( final it.unimi.dsi.fastutil.ints.IntIterator iterator ) {
		return new IntIteratorWrapper( iterator );
	}

#endif

#if #keyclass(Double)

  	/** A wrapper promoting the results of a FloatIterator. */

	protected static class FloatIteratorWrapper implements KEY_ITERATOR {
		final it.unimi.dsi.fastutil.floats.FloatIterator iterator;
		
		public FloatIteratorWrapper( final it.unimi.dsi.fastutil.floats.FloatIterator iterator ) {
			this.iterator = iterator;
		}
	
		public boolean hasNext() { return iterator.hasNext(); }
		public KEY_GENERIC_CLASS next() { return KEY_GENERIC_CLASS.valueOf( iterator.nextFloat() ); }
		public KEY_TYPE NEXT_KEY() { return iterator.nextFloat(); }
		public void remove() { iterator.remove(); }
		public int skip( final int n ) { return iterator.skip( n ); }
	}

	/** Returns an iterator backed by the specified float iterator. 
	 * @return an iterator backed by the specified float iterator. 
	 */
	public static KEY_ITERATOR wrap( final it.unimi.dsi.fastutil.floats.FloatIterator iterator ) {
		return new FloatIteratorWrapper( iterator );
	}
#endif
}
