this.firstIndex = first;
            this.lastIndex = last;
        }

        /**
         * @see org.millscript.commons.util.list.AbstractIList#doGet(int)
         */
        @Override
        protected V doGet( final int pos ) {
            int i = this.firstBucket;
            int p = 1;
            HashMaplet< ?, ? > hmp = this.firstHashMaplet;
            while ( p <= this.size() && i < this.store.length ) {
                if ( p == pos ) {
                    return this.getAppropriateMapletPart( hmp );
                } else {
                    // Advance to the next bucketIndex/maplet
                    hmp = hmp.next;
                    while ( hmp == null && ++i < this.store.length ) {
                        hmp = this.store[ i ];
                    }
                    p++;
                }
            }
            throw new Fault(
                "Specified position is neither out of bounds or within the list!"
            ).culprit( "index", pos ).decorate( this ).mishap();
        }

        /**
         * @see org.millscript.commons.util.list.AbstractIList#doSlice(int, int, boolean)
         */
        @Override
        @SuppressWarnings( "unchecked" )
        protected IList< V > doSlice( final int first, final int last, final boolean share ) {
            if ( share ) {
                return this.sharedSlice( first, last );
            } else {
                // Return a copy of the slice of the list.
                final V[] objects = (V[]) new Object[ this.size() ];
                int i = this.firstBucket;
                int pos = 0;
                HashMaplet< ?, ? > hmp = this.firstHashMaplet;
                while ( pos < this.size() && i < this.store.length ) {
                    objects[ pos ] = this.getAppropriateMapletPart( hmp );
                    // Advance to the next bucketIndex/maplet
                    hmp = hmp.next;
                    while ( hmp == null && ++i < this.store.length ) {
                        hmp = this.store[ i ];
                    }
                    pos++;
                }
                return new IArrayList< V >( objects, true );
            }
        }

        /**
         * Returns the appropriate part of the specified maplet for this list.
         *
         * @param maplet    the maplet to get the appropriate part from
         * @return  the appropriate part of the specified maplet
         */
        abstract V getAppropriateMapletPart( Maplet< ?, ? > maplet );

        /**
         * @see org.millscript.commons.util.IList#indexOf(java.lang.Object)
         */
        public int indexOf( final V value ) {
            int i = this.firstBucket;
            int pos = 1;
            HashMaplet< ?, ? > hmp = this.firstHashMaplet;
            if ( value == null ) {
                while ( pos <= this.size() && i < this.store.length ) {
                    if ( this.getAppropriateMapletPart( hmp ) == null ) {
                        return pos;
                    } else {
                        // Advance to the next bucketIndex/maplet
                        hmp = hmp.next;
                        while ( hmp == null && ++i < this.store.length ) {
                            hmp = this.store[ i ];
                        }
                        pos++;
                    }
                }
            } else {
                while ( pos <= this.size() && i < this.store.length ) {
                    if ( value.equals( this.getAppropriateMapletPart( hmp ) ) ) {
                        return pos;
                    } else {
                        // Advance to the next bucketIndex/maplet
                        hmp = hmp.next;
                        while ( hmp == null && ++i < this.store.length ) {
                            hmp = this.store[ i ];
                        }
                        pos++;
                    }
                }
            }
            return 0;
        }

        /**
         * @see org.millscript.commons.util.IMap#iterator(boolean)
         */
        @SuppressWarnings( "unchecked" )
        public ListIterator< V > iterator( final boolean share ) {
            if ( share ) {
                return this.sharedIterator();
            } else {
                // We can do the generic copy here, as we can always access the
                // appropriate part of each maplet
                final V[] objects = (V[]) new Object[ this.size() ];
                for ( int i = 0, j = 0; i < this.store.length; i++ ) {
                    for ( HashMaplet< ?, ? > maplet = this.store[ i ]; maplet != null; maplet = maplet.next ) {
                        objects[ j++ ] = this.getAppropriateMapletPart( maplet );
                     }
                }
                return new ArrayListIterator< V >( objects, true );
            }
        }

        /**
         * Returns a map iterator which shares backing store with this list.
         *
         * @return  a map iterator which shares this lists backing store
         */
        abstract ListIterator< V > sharedIterator();

        /**
         * Returns a slice of this list which shares backing store with this
         * list.
         *
         * @param first the index(one based) of the first element in the slice
         * @param last  the index(one based) of the last element in the slice
         * @return  a slice of this list which shares this lists backing store
         */
        abstract IList< V > sharedSlice( int first, int last );

        /**
         * @see org.millscript.commons.util.IMap#size()
         */
        public int size() {
            return this.lastIndex <= this.firstIndex ? 0
                                                    : this.lastIndex - this.firstIndex + 1;
        }
        
    }

    /**
     * The number of mappings in this map.
     */
    private final int size;

        }

    }

    /**
     * This class implements a map iterator which iterates over an array
     * of hash map buckets, returning each maplet as the value.
     */
    public static class LinkedHashMapMapletIterator< K, V > extends LinkedHashMapXIterator< Maplet< K, V > > {

        /**
         * Constructs a new hash map iterator to iterate over the specified
         * array of hash map buckets returning the maplet as the value.
         *
         * @param start the first LinkedHashMaplet in the iteration
         * @param num   the number of elements in the iteration
         */
        public LinkedHashMapMapletIterator( final LinkedHashMaplet< ?, ? > start, final int num ) {
            super( start, num );
        }

        /**
         * @see org.millscript.commons.util.map.ILinkedHashMap.LinkedHashMapXIterator#getAppropriateMapletPart(org.millscript.commons.util.Maplet)
         */
        @Override
        @SuppressWarnings( "unchecked" )
        Maplet< K, V > getAppropriateMapletPart( final Maplet< ?, ? > maplet ) {
            return (Maplet< K, V >) maplet;
        }
        
    }

    /**
     * This class implements an immutable list which is backed by an array of
     * hash map buckets, but NOTE the values in the list are actually the
     * individual hash maplets themselves.
     */
    public static class LinkedHashMapMapletList< K, V > extends LinkedHashMapXList< Maplet< K, V > > {

        /**
         * Constructs a new hash maplet array list of the individual maplets.
         *
         * @param start the LinkedHashMap element with index 1
         * @param num   the number of elements in the list 
         */
        public LinkedHashMapMapletList( final LinkedHashMaplet< ?, ? > start, final int num ) {
            super( start, num );
        }

        /**
         * Constructs a new hash maplet array list of the individual maplets.
         *
         * @param start the LinkedHashMap element with index 1
         * @param first the index(one based, inclusive) of the first name
         * @param last  the index(one based, inclusive) of the last name 
         */
        public LinkedHashMapMapletList( final LinkedHashMaplet< ?, ? > start, final int first, final int last ) {
            super( start, first, last );
        }

        /**
         * @see org.millscript.commons.util.map.ILinkedHashMap.LinkedHashMapXList#getAppropriateMapletPart(org.millscript.commons.util.Maplet)
         */
        @Override
        @SuppressWarnings( "unchecked" )
        Maplet< K, V > getAppropriateMapletPart( final Maplet< ?, ? > maplet ) {
            return (Maplet< K, V >) maplet;
        }

        /**
         * @see org.millscript.commons.util.map.IHashMap.LinkedHashMapKeysIterator.LinkedHashMapXList#sharedIterator()
         */
        @Override
        ListIterator< Maplet< K, V > > sharedIterator() {
            return new LinkedHashMapMapletIterator< K, V >( this.firstHashMaplet, this.size );
        }

        /**
         * @see org.millscript.commons.util.map.ILinkedHashMap.LinkedHashMapXList#sharedSlice(int, int)
         */
        @Override
        IList< Maplet< K, V > > sharedSlice( final int first, final int last ) {
            return new LinkedHashMapMapletList< K, V >( this.firstHashMaplet, first, last );
        }

    }

    /**
     * This class implements a map iterator which iterates over an array
     * of hash map buckets, returning each maplet value.
     */
    public static class LinkedHashMapValuesIterator< V > extends LinkedHashMapXIterator< V > {

        /**
         * Constructs a new hash map iterator to iterate over the specified
         * array of hash map buckets returning the maplet values.
         *
         * @param start the first LinkedHashMaplet in the iteration
         * @param num   the number of elements in the iteration
         */
        public LinkedHashMapValuesIterator( final LinkedHashMaplet< ?, ? > start, final int num ) {
            super( start, num );
        }

        /**
         * @see org.millscript.commons.util.map.ILinkedHashMap.LinkedHashMapXIterator#getAppropriateMapletPart(org.millscript.commons.util.Maplet)
         */
        @Override
        @SuppressWarnings( "unchecked" )
        V getAppropriateMapletPart( final Maplet< ?, ? > maplet ) {
            return (V) maplet.getValue();
        }
        
    }

    /**
     * This class implements an immutable list which is backed by an array of
     * hash map buckets, but NOTE the values in the list are actually the
     * individual hash maplet values.
     */
    public static class LinkedHashMapValuesList< V > extends LinkedHashMapXList< V > {

        /**
         * Constructs a new hash maplet array list of the individual maplet
         * values.
         *
         * @param start the LinkedHashMap element with index 1
         * @param num   the number of elements in the list 
         */
        public LinkedHashMapValuesList( final LinkedHashMaplet< ?, ? > start, final int num ) {
            super( start, num );
        }

        /**
         * Constructs a new hash maplet array list of the individual maplet
         * values.
         *
         * @param start the LinkedHashMap element with index 1
         * @param first the index(one based, inclusive) of the first name
         * @param last  the index(one based, inclusive) of the last name 
         */
        public LinkedHashMapValuesList( final LinkedHashMaplet< ?, ? > start, final int first, final int last ) {
            super( start, first, last );
        }

        /**
         * @see org.millscript.commons.util.map.ILinkedHashMap.LinkedHashMapXList#getAppropriateMapletPart(org.millscript.commons.util.Maplet)
         */
        @Override
        @SuppressWarnings( "unchecked" )
        V getAppropriateMapletPart( final Maplet< ?, ? > maplet ) {
            return (V) maplet.getValue();
        }

        /**
         * @see org.millscript.commons.util.map.IHashMap.LinkedHashMapKeysIterator.LinkedHashMapXList#sharedIterator()
         */
        @Override
        ListIterator< V > sharedIterator() {
            return new LinkedHashMapValuesIterator< V >( this.firstHashMaplet, this.size );
        }

        /**
         * @see org.millscript.commons.util.map.ILinkedHashMap.LinkedHashMapXList#sharedSlice(int, int)
         */
        @Override
        IList< V > sharedSlice( final int first, final int last ) {
            return new LinkedHashMapValuesList< V >( this.firstHashMaplet, first, last );
        }

    }

    /**
     * This class implements a map iterator which iterates over an array
     * of hash map buckets, returning either the keys or values.
     */
    private static abstract class LinkedHashMapXIterator< V > extends AbstractListIterator< V > {

    }

    /**
     * @see org.millscript.commons.util.IMap#contains(java.lang.Object, java.lang.Object)
     */
    public boolean contains( final K key, final V value ) {
        final int pos = key == null ? 0 : ( key.hashCode() & 0x7FFFFFFF ) % this.store.length;
        for ( LinkedHashMaplet< K, V > hmp = this.store[ pos ]; hmp != null; hmp = hmp.next ) {
            if ( key == null ? hmp.getKey() == null : key.equals( hmp.getKey() ) ) {
                // The keys are equal, so return true if the values are both
                // null or equal and false otherwise
                return hmp.getValue() == null ? value == null
                                              : hmp.getValue().equals( value );
            }
        }
        return false;
    }

    /**
     * @see org.millscript.commons.util.IMap#containsKey(java.lang.Object)
     */
    public boolean containsKey( final K key ) {
        final int pos = key == null ? 0 : ( key.hashCode() & 0x7FFFFFFF ) % this.store.length;
        for ( LinkedHashMaplet< K, V > hmp = this.store[ pos ]; hmp != null; hmp = hmp.next ) {
            if ( key == null ? hmp.getKey() == null : key.equals( hmp.getKey() ) ) {
                return true;
            }
        }
        return false;
    }

    /**
     * @see org.millscript.commons.util.IMap#containsValue(java.lang.Object)
     */
    public boolean containsValue( final V value ) {
        // We can't do better than a linear search
        LinkedHashMaplet< K, V > current = this.firstElement;
        while ( current != null ) {
            if ( value == null ? current.getValue() == null : value.equals( current.getValue() ) ) {
                return true;
            } else {
                current = current.nextByInsertion;
            }
        }
        return false;
    }

    /**
     * @see org.millscript.commons.util.IMap#get(java.lang.Object)
     */
    public V get( final K key ) {
        final int pos = key == null ? 0 : ( key.hashCode() & 0x7FFFFFFF ) % this.store.length;
        for ( LinkedHashMaplet< K, V > hmp = this.store[ pos ]; hmp != null; hmp = hmp.next ) {
            if ( key == null ? hmp.getKey() == null : key.equals( hmp.getKey() ) ) {
                return hmp.getValue();
            }
        }
        return this.getDefault().get( this, key );
    }

        }

        /**
         * @see org.millscript.commons.util.iterator.AbstractMapIterator#getValue()
         */
        @Override
        protected V getValue() {
            return currentMaplet.getValue();
        }

        /**
         * @see org.millscript.commons.util.MapIterator#hasNext()
         */
        public boolean hasNext() {
            return this.nextMaplet != null;
        }

        /**
         * @see org.millscript.commons.util.iterator.AbstractMapIterator#outOfBounds()
         */
        @Override
        protected boolean outOfBounds() {
            return currentMaplet == null;
        }

    }

    /**
     * This class implements a map iterator which iterates over an array
     * of hash map buckets, returning each maplet key.
     */
    public static class LinkedHashMapKeysIterator< K > extends LinkedHashMapXIterator< K > {

        /**
         * Constructs a new hash map iterator to iterate over the specified
         * array of hash map buckets returning the maplet keys.
         *
         * @param start the first LinkedHashMaplet in the iteration
         * @param num   the number of elements in the iteration
         */
        public LinkedHashMapKeysIterator( final LinkedHashMaplet< ?, ? > start, final int num ) {
            super( start, num );
        }

        /**
         * @see org.millscript.commons.util.map.ILinkedHashMap.LinkedHashMapXIterator#getAppropriateMapletPart(org.millscript.commons.util.Maplet)
         */
        @Override
        @SuppressWarnings( "unchecked" )
        K getAppropriateMapletPart( final Maplet< ?, ? > maplet ) {
            return (K) maplet.getKey();
        }
        
    }

    /**
     * This class implements an immutable list which is backed by an array of
     * hash map buckets, but NOTE the values in the list are actually the
     * individual hash maplet keys.
     */
    public static class LinkedHashMapKeysList< K > extends LinkedHashMapXList< K > {

        /**
         * Constructs a new hash maplet array list of the individual maplet
         * keys.
         *
         * @param start the LinkedHashMap element with index 1
         * @param num   the number of elements in the list 
         */
        public LinkedHashMapKeysList( final LinkedHashMaplet< ?, ? > start, final int num ) {
            super( start, num );
        }

        /**
         * Constructs a new hash maplet array list of the individual maplet
         * keys.
         *
         * @param start the LinkedHashMap element with index 1
         * @param first the index(one based, inclusive) of the first name
         * @param last  the index(one based, inclusive) of the last name 
         */
        public LinkedHashMapKeysList( final LinkedHashMaplet< ?, ? > start, final int first, final int last ) {
            super( start, first, last );
        }

        /**
         * @see org.millscript.commons.util.map.ILinkedHashMap.LinkedHashMapXList#getAppropriateMapletPart(org.millscript.commons.util.Maplet)
         */
        @Override
        @SuppressWarnings( "unchecked" )
        K getAppropriateMapletPart( final Maplet< ?, ? > maplet ) {
            return (K) maplet.getKey();
        }

        /**
         * @see org.millscript.commons.util.map.IHashMap.LinkedHashMapKeysIterator.LinkedHashMapXList#sharedIterator()
         */
        @Override
        ListIterator< K > sharedIterator() {
            return new LinkedHashMapKeysIterator< K >( this.firstHashMaplet, this.size );
        }

        /**
         * @see org.millscript.commons.util.map.ILinkedHashMap.LinkedHashMapXList#sharedSlice(int, int)
         */
        @Override
        IList< K > sharedSlice( final int first, final int last ) {
            return new LinkedHashMapKeysList< K >( this.firstHashMaplet, first, last );
        }

    }

    /**
     * This class provides an immutable implementation of a <code>Maplet</code>
     * which also acts as a bucket in our hashmap.
     */
    private static class LinkedHashMaplet< K, V > extends IMaplet< K, V > {

                return new ISharedLinkedList< V >(
                    this.firstLink,
                    first,
                    last
                );
            } else {
                // Return a copy of the relevant slice of the list
                final V[] objects = (V[]) new Object[ first - last + 1 ];
                Link< V > link = this.firstLink;
                int outerListCount = 1;
                // Find the first link in the shared chain
                for ( ; outerListCount <= first; outerListCount++ ) {
                    link = link.next;
                }
                // Now copy each required link into the array
                int newArrayPos = 0;
                for ( ; link != null && outerListCount <= last; link = link.next, outerListCount++ ) {
                    objects[ newArrayPos++ ] = link.current;
                }
                return new IArrayList< V >( objects, true );
            }
        }

        /**
         * @see org.millscript.commons.util.IList#indexOf(java.lang.Object)
         */
        public int indexOf( final V value ) {
            int pos = 1;
            if ( value == null ) {
                for ( Link< V > link = this.firstLink; link != null && pos <= this.size; link = link.next, pos++ ) {
                    if ( link.current == null ) {
                        return pos;
                    }
                }
            } else {
                for ( Link< V > link = this.firstLink; link != null && pos <= this.size; link = link.next, pos++ ) {
                    if ( value.equals( link.current ) ) {
                        return pos;
                    }
                }
            }
            return 0;
        }

        /**
         * @see org.millscript.commons.util.IMap#iterator(boolean)
         */
        @SuppressWarnings( "unchecked" )
        public ListIterator< V > iterator( final boolean share ) {
            if ( share ) {
                return new ISharedLinkedListIterator< V >(

        public HashMapXIterator( final AbstractEReferenceHashMap< ?, ? > map, final int first, final int last ) {
            int fb = 0;
            HashMaplet< ?, ? > fm = null;
            int totalMaplets = 0;
            // Loop through the buckets to find the first maplet
            for ( int i = 0; i < map.store.length; i++ ) {
                // Loop through the maplets in this bucket
                for ( HashMaplet< ?, ? > hmp = map.store[ i ]; hmp != null; hmp = hmp.next ) {
                    // Have we found the first maplet?
                    if ( ++totalMaplets == first ) {
                        // Yes, we have so store it's details
                        fb = i;
                        fm = hmp;
                    }
                }
            }
            if ( first > last ) {
                this.currentMaplet = null;
                this.nextMaplet = null;
                this.bucketIndex = 0;
                this.size = 0;
                this.store = null;
            } else if ( first < 1 || first > totalMaplets ) {
                throw new ListIndexOutOfBoundsAlert(
                    "First index in slice must be between 1 and the number of entries in the map"
                ).culprit(
                    "index",
                    first
                ).decorate( map ).mishap();
            } else if ( last > totalMaplets ) {
                throw new ListIndexOutOfBoundsAlert(
                    "Last index in slice must not be greater than the number of entries in the map"
                ).culprit(
                    "index",
                    last
                ).decorate( map ).mishap();
            } else {
                this.currentMaplet = null;
                this.nextMaplet = fm;
                this.bucketIndex = fb;
                this.size = last - first + 1;
                this.store = map.store;
            }
        }

        /**
         * @see org.millscript.commons.util.iterator.AbstractMapIterator#advance()
         */
        @Override
        protected void advance() {
            // Increment the position
            super.advance();
            // Move to the next maplet
            this.currentMaplet = this.nextMaplet;

        public TwoArrayMapletList( final K[] k, final V[] v, final boolean share ) {
            // Validate the incoming arrays
            if ( k == null && v == null ) {
                this.keys = null;
                this.values = null;
            } else if ( k == null || v == null ) {
                throw new IllegalArgumentAlert(
                    "Backing store arrays should both be null or not null"
                ).culprit(
                    "keys array",
                    k
                ).culprit(
                    "values array",
                    v
                ).mishap();
            } else if ( k.length != v.length ) {
                throw new IllegalArgumentAlert(
                    "Backing store arrays must be the same length"
                ).culprit(
                    "keys array",
                    k
                ).culprit(
                    "keys array length",
                    k.length
                ).culprit(
                    "values array",
                    v
                ).culprit(
                    "values array length",
                    v.length
                ).mishap();
            } else if ( share ) {
                this.keys = k;
                this.values = v;
            } else {
                this.keys = (K[]) new Object[ k.length ];
                System.arraycopy( k, 0, this.keys, 0, k.length );
                this.values = (V[]) new Object[ v.length ];
                System.arraycopy( v, 0, this.values, 0, v.length );
            }
        }

        /**
         * @see org.millscript.commons.util.list.AbstractIList#doGet(int)
         */
        @Override
        protected Maplet< K, V > doGet( final int pos ) {

        private HashMapXList( final AbstractEReferenceHashMap< ?, ? > map, final int first, final int last ) {
            int fb = 0;
            HashMaplet< ?, ? > fm = null;
            int totalMaplets = 0;
            // Loop through the buckets to find the first maplet
            for ( int i = 0; i < map.store.length; i++ ) {
                // Loop through the maplets in this bucket
                for ( HashMaplet< ?, ? > hmp = map.store[ i ]; hmp != null; hmp = hmp.next ) {
                    // Have we found the first maplet?
                    if ( ++totalMaplets == first ) {
                        // Yes, we have so store it's details
                        fb = i;
                        fm = hmp;
                    }
                }
            }
            if ( first > last ) {
                this.firstBucket = 0;
                this.firstHashMaplet = null;
                this.store = null;
            } else if ( first < 1 || first > totalMaplets ) {
                throw new ListIndexOutOfBoundsAlert(
                    "First index in slice must be between 1 and the number of entries in the map"
                ).culprit(
                    "index",
                    first
                ).decorate( map ).mishap();
            } else if ( last > totalMaplets ) {
                throw new ListIndexOutOfBoundsAlert(
                    "Last index in slice must not be greater than the number of entries in the map"
                ).culprit(
                    "index",
                    last
                ).decorate( map ).mishap();
            } else {
                this.firstBucket = fb;
                this.firstHashMaplet = fm;
                this.store = map.store;
            }
            this.backingMap = map;
            this.firstIndex = first;
            this.lastIndex = last;
        }

        /**
         * @see org.millscript.commons.util.list.AbstractIList#doGet(int)
         */
        @Override
        protected V doGet( final int pos ) {

                        if ( hmp.getKey() == null ? hashMaplet.getKey() == null : hmp.getKey().equals( hashMaplet.getKey() ) ) {
                            hmp.value = hashMaplet.value;
                            break;
                        } else if ( hmp.next == null ) {
                            hmp.next = new HashMaplet< K, V >( hashMaplet );
                            break;
                        }
                    }
                }
                hashMaplet = hashMaplet.next;
            }
        }
        this.store = newStore;
        this.triggerRehashSize = (int) ( this.store.length * DEFAULT_LOAD_FACTOR );
        // Now we've re-hashed, insert the new mapping.
        this.insert( key, value );
    }

    /**
     * @see org.millscript.commons.util.IMap#iterator(boolean)
     */
    @SuppressWarnings( "unchecked" )
    public MapIterator< K, V > iterator( final boolean share ) {
        if ( share ) {
            return new HashMapIterator< K, V >( this, true );
        } else {
            // It's more efficient to copy the hash map backing store into a
            // fixed array of plain maplets, rather than copying the array of
            // buckets.
            final Maplet< K, V >[] maplets = new Maplet[ this.size() ];
            for ( int i = 0, j = 0; i < this.store.length; i++ ) {
                for ( HashMaplet< K, V > maplet = this.store[ i ]; maplet != null; maplet = maplet.next ) {
                    maplets[ j++ ] = new IMaplet< K, V >( maplet );
                 }
            }
            return new IMapletArrayMap.MapletArrayMapIterator< K, V >( maplets, true );
        }
    }

    private static abstract class LinkedHashMapXList< V > extends AbstractIList< V > {

        /**
         * The first link in the shared part of the maplet chain.
         */
        final LinkedHashMaplet< ?, ? > firstHashMaplet;

        /**
         * The number of values in the list.
         */
        final int size;

        /**
         * Constructs a new hash maplet array list of either the individual
         * maplet keys or values.
         *
         * @param start the LinkedHashMap element with index 1
         * @param num   the number of elements in the list 
         */
        private LinkedHashMapXList( final LinkedHashMaplet< ?, ? > start, final int num ) {
            this.firstHashMaplet = start;
            this.size = num;
        }

        /**
         * Constructs a new hash maplet array list of either the individual
         * maplet keys or values.
         *
         * @param start the LinkedHashMap element with index 1
         * @param first the index(one based, inclusive) of the first name
         * @param last  the index(one based, inclusive) of the last name 
         */
        private LinkedHashMapXList( final LinkedHashMaplet< ?, ? > start, final int first, final int last ) {
            LinkedHashMaplet< ?, ? > firstMaplet = null;
            int totalMaplets = 1;
            // Find the first link in the shared chain
            for ( LinkedHashMaplet< ?, ? > maplet = start; maplet != null; totalMaplets++, maplet = maplet.nextByInsertion ) {
                if ( totalMaplets == first ) {
                    firstMaplet = maplet;
                }
            }
            if ( first > last ) {
                this.firstHashMaplet = null;
                this.size = 0;
            } else if ( first < 1 || first > totalMaplets ) {
                throw new ListIndexOutOfBoundsAlert(
                    "First index in slice must be between 1 and the number of entries in the map"
                ).culprit(
                    "index",
                    first
                ).decorate( start ).mishap();
            } else if ( last > totalMaplets ) {
                throw new ListIndexOutOfBoundsAlert(
                    "Last index in slice must not be greater than the number of entries in the list"
                ).culprit(
                    "index",
                    last
                ).decorate( start ).mishap();
            } else {
                this.firstHashMaplet = firstMaplet;
                this.size = last - first + 1;
            }
        }

        /**
         * @see org.millscript.commons.util.list.AbstractIList#doGet(int)
         */
        @Override
        protected V doGet( final int pos ) {

                Node< X, Y > child = this.getLeft();
                if ( child == null ) {
                    // The child is a (black) leaf node
                    // First handle any tree adjustments. There is nothing else
                    // to do if we are deleting a red node
                    if ( ! this.isRed ) {
                        this.deleteCase1( map );
                    }
                    // and now delete this node
                    if ( this.getParent() == null ) {
                        map.setRootNode( null );
                    } else if ( this == this.getParent().getLeft() ) {
                        this.getParent().setLeft( null );
                    } else {
                        this.getParent().setRight( null );
                    }
                    // There is nothing else to do in the case where the child
                    // is a leaf node
                } else {
                    // Delete the node first
                    if ( this.getParent() == null ) {
                        map.setRootNode( child );
                    } else if ( this == this.getParent().getLeft() ) {
                        this.getParent().setLeft( child );
                    } else {
                        this.getParent().setRight( child );
                    }
                    if ( child != null ) {
                        child.setParent( this.getParent() );
                    }
                    // and now handle any tree adjustments. There is nothing
                    // else to do if we are deleting a red node
                    if ( ! this.isRed ) {
                        if ( child.isRed ) {
                            child.isRed = false;
                        } else {
                            // The child is a normal black node
                            child.deleteCase1( map );
                        }
                    }
                }
//            } else if ( Math.random() < 0.5d ) {
//                // Ok there is a left and right, so we've randomly
//                // chosen to delete from the right
//                // Find the minimum element in the right tree
//                Node< X, Y > minimum = this.getRight();
//                while ( minimum.getLeft() != null ) {
//                    minimum = minimum.getLeft();
//                }
//                // Copy the minimum value into this node
//                this.key = minimum.getKey();
//                this.value = minimum.getValue();
//                // and now delete the node we copied the value from
//                minimum.delete( map );
            } else {

        public int indexOf( final V value ) {
            int i = this.firstBucket;
            int pos = 1;
            HashMaplet< ?, ? > hmp = this.firstHashMaplet;
            if ( value == null ) {
                while ( pos <= this.size() && i < this.store.length ) {
                    if ( this.getAppropriateMapletPart( hmp ) == null ) {
                        return pos;
                    } else {
                        // Advance to the next bucketIndex/maplet
                        hmp = hmp.next;
                        while ( hmp == null && ++i < this.store.length ) {
                            hmp = this.store[ i ];
                        }
                        pos++;
                    }
                }
            } else {
                while ( pos <= this.size() && i < this.store.length ) {
                    if ( value.equals( this.getAppropriateMapletPart( hmp ) ) ) {
                        return pos;
                    } else {
                        // Advance to the next bucketIndex/maplet
                        hmp = hmp.next;
                        while ( hmp == null && ++i < this.store.length ) {
                            hmp = this.store[ i ];
                        }
                        pos++;
                    }
                }
            }
            return 0;
        }

        /**
         * @see org.millscript.commons.util.IMap#iterator(boolean)
         */
        @SuppressWarnings( "unchecked" )
        public ListIterator< V > iterator( final boolean share ) {

        public ISharedLinkedList( final Link< V > first, final int start, final int end ) {
            Link< V > link = first;
            int outerListCount = 1;
            // Find the first link in the shared chain
            for ( ; outerListCount < start; outerListCount++ ) {
                link = link.next;
            }
            this.firstLink = link;
            this.size = end - start + 1;
        }

        /**
         * @see org.millscript.commons.util.list.AbstractIList#doGet(int)
         */
        @Override
        protected V doGet( final int pos ) {
            int currentPos = 1;
            for ( Link< V > link = this.firstLink; link != null; link = link.next ) {
                if ( pos == currentPos++ ) {
                    return link.current;
                }
            }
            throw new Fault(
                "Specified position is neither out of bounds or within the list!"
            ).culprit( "index", pos ).decorate( this ).mishap();
        }

        /**
         * @see org.millscript.commons.util.list.AbstractIList#doSlice(int, int, boolean)
         */
        @Override
        @SuppressWarnings( "unchecked" )
        protected IList< V > doSlice( final int first, final int last, final boolean share ) {
            if ( share ) {
                return new ISharedLinkedList< V >(

        public ImmutableSharedMapletList( final Object[] objects, final int first, final int len ) {
            if ( len <= 0 ) {
                // We keep this test here to avoid problems with the array
                // length check below
                this.firstIndex = first - 1;
                this.size = len;
                this.store = null;
            } else if ( first < 0 || first > objects.length ) {
                throw new ListIndexOutOfBoundsAlert(
                    "First index in slice must be between 1 and the length of the array"
                ).culprit(
                    "index",
                    first
                ).decorate( objects ).mishap();
            } else if ( first + 2 * ( len - 1 ) > objects.length ) {
                throw new ListIndexOutOfBoundsAlert(
                    "Requested list exceeds bounds of specified array"
                ).culprit(
                    "first element index",
                    first
                ).culprit(
                    "requested size",
                    len
                ).decorate( objects ).mishap();
//            } else if ( ( first - len + 2 ) % 2 != 0 ) {
//                throw new IllegalArgumentAlert(
//                    "Backing store key-value array length must be a multiple of 2"
//                ).culprit(
//                    "array",
//                    objects
//                ).culprit(
//                    "array length",
//                    objects.length
//                ).culprit(
//                    "first name index",
//                    first
//                ).culprit(
//                    "last name index",
//                    len
//                ).mishap();
            } else {
                this.firstIndex = first - 1;
                this.size = len;
                this.store = objects;
            }
        }

        /**
         * @see org.millscript.commons.util.list.AbstractIList#doGet(int)
         */
        @Override
        @SuppressWarnings( "unchecked" )
        protected Maplet< K, V > doGet( final int pos ) {

        HashMapMapletList( final AbstractEReferenceHashMap< ?, ? > map, final int first, final int last ) {
            super( map, first, last );
        }

        /**
         * @see org.millscript.commons.util.map.IHashMap.HashMapXList#getAppropriateNodePart(org.millscript.commons.util.Maplet)
         */
        @Override
        @SuppressWarnings( "unchecked" )
        Maplet< K, V > getAppropriateMapletPart( final Maplet< ?, ? > maplet ) {
            return (Maplet< K, V >) maplet;
        }

        /**
         * @see org.millscript.commons.util.map.IHashMap.HashMapKeysIterator.HashMapXList#sharedIterator()
         */
        @Override
        ListIterator< Maplet< K, V > > sharedIterator() {
            return new HashMapMapletIterator< K, V >( this.backingMap, this.firstIndex, this.lastIndex );
        }

        /**
         * @see org.millscript.commons.util.map.IHashMap.HashMapXList#sharedSlice(int, int)
         */
        @Override
        IList< Maplet< K, V > > sharedSlice( final int first, final int last ) {
            return new HashMapMapletList< K, V >( this.backingMap, first, last );
        }

    }

    /**
     * This class implements a map iterator which iterates over an array
     * of hash map buckets, returning each maplet value, sharing the backing
     * store with it's enclosing mutable map.
     */
    public static class HashMapValuesIterator< V > extends HashMapXIterator< V > {

        /**
         * Constructs a new hash map iterator to iterate over the specified
         * mutable hash map returning the maplet values.
         *
         * @param map   the mutable hash map to iterate over 
         * @param first the index(one based, inclusive) of the first name
         * @param last  the index(one based, inclusive) of the last name
         */
        public HashMapValuesIterator( final AbstractEReferenceHashMap< ?, ? > map, final int first, final int last ) {

                        HashMaplet copy = new HashMaplet< K, V >( maplet );
                        this.store[ i ] = copy;
                        for ( maplet = maplet.next; maplet != null; maplet = maplet.next ) {
                            copy.next = new HashMaplet< K, V >( maplet );
                        }
                    }
                }
            }
        }

        /**
         * @see org.millscript.commons.util.iterator.AbstractMapIterator#advance()
         */
        @Override
        protected void advance() {
            // Ensure the next maplet is properly populated
            this.checkNext();
            // Move to the next maplet
            this.currentMaplet = this.nextMaplet;
            if ( this.nextMaplet != null ) {
                this.nextMaplet = this.nextMaplet.next;
            }
        }

        /**
         * Checks that the next maplet field is populated with the next maplet
         * if one is available.
         */
        private void checkNext() {
            if ( this.nextMaplet == null ) {
                // Must advance to the next bucket if available
                if ( ++pos < this.store.length ) {
                    this.nextMaplet = this.store[ pos ];
                    // Next bucket please
                    this.checkNext();
                }
            }
        }

        /**
         * @see org.millscript.commons.util.iterator.AbstractMapIterator#getKey()
         */
        @Override
        protected K getKey() {
            return currentMaplet.getKey();

        HashMapKeysList( final AbstractEReferenceHashMap< ?, ? > map, final int first, final int last ) {
            super( map, first, last );
        }

        /**
         * @see org.millscript.commons.util.map.IHashMap.HashMapXList#getAppropriateNodePart(org.millscript.commons.util.Maplet)
         */
        @Override
        @SuppressWarnings( "unchecked" )
        K getAppropriateMapletPart( final Maplet< ?, ? > maplet ) {
            return (K) maplet.getKey();
        }

        /**
         * @see org.millscript.commons.util.map.IHashMap.HashMapKeysIterator.HashMapXList#sharedIterator()
         */
        @Override
        ListIterator< K > sharedIterator() {
            return new HashMapKeysIterator< K >( this.backingMap, this.firstIndex, this.lastIndex );
        }

        /**
         * @see org.millscript.commons.util.map.AbstractEReferenceHashMap.HashMapXList#sharedSlice(int, int)
         */
        @Override
        IList< K > sharedSlice( final int first, final int last ) {
            return new HashMapKeysList< K >( this.backingMap, first, last );
        }

    }

    /**
     * This class provides a mutable implementation of a <code>Maplet</code>
     * which also acts as a bucket in our hashmap. This implementation only
     * supports mutating the maplet value, not the key.
     */
    private static class HashMaplet< K, V > implements Maplet< K, V > {

        /**
         * This maplets key.
         */
        final Reference< K > key;

                    this.size--;
                } else {
                    previousInChain = hmp;
                }
            }
        }
    }

    /**
     * @see org.millscript.commons.util.map.AbstractIMap#sharedKeyList()
     */
    @Override
    protected IList< K > sharedKeyList() {
        return new HashMapKeysList< K >( this, 1, this.size() );
    }

    /**
     * @see org.millscript.commons.util.map.AbstractIMap#sharedMapletList()
     */
    @Override
    protected IList< Maplet< K, V > > sharedMapletList() {
        return new HashMapMapletList< K, V >( this, 1, this.size() );
    }

    /**
     * @see org.millscript.commons.util.map.AbstractIMap#sharedValueList()
     */
    @Override
    protected IList< V > sharedValueList() {
        return new HashMapValuesList< V >( this, 1, this.size() );
    }

    /**
     * @see org.millscript.commons.util.IMap#size()
     */
    public int size() {
        return this.size;
    }

    /**
     * @see org.millscript.commons.util.UMap#update(java.lang.Object, java.lang.Object)
     */
    public void update( final K key, final V value ) {

        protected V doGet( final int pos ) {
            int i = this.firstBucket;
            int p = 1;
            HashMaplet< ?, ? > hmp = this.firstHashMaplet;
            while ( p <= this.size() && i < this.store.length ) {
                if ( p == pos ) {
                    return this.getAppropriateMapletPart( hmp );
                } else {
                    // Advance to the next bucketIndex/maplet
                    hmp = hmp.next;
                    while ( hmp == null && ++i < this.store.length ) {
                        hmp = this.store[ i ];
                    }
                    p++;
                }
            }
            throw new Fault(
                "Specified position is neither out of bounds or within the list!"
            ).culprit( "index", pos ).decorate( this ).mishap();
        }

        /**
         * @see org.millscript.commons.util.list.AbstractIList#doSlice(int, int, boolean)
         */
        @Override
        @SuppressWarnings( "unchecked" )
        protected IList< V > doSlice( final int first, final int last, final boolean share ) {

    }

    /**
     * Reads this object from the specified {@link ObjectInputStream}.
     *
     * @param stream    the {@link ObjectInputStream} to read the objects data
     * from
     * @serialData      Reads the default object, followed by the integer
     * number of mappings and then an alternating sequence of key-value pairs
     * @throws ClassNotFoundException   if a required class cannot be found
     * @throws IOException      if something goes wrong during the
     * deserialization process
     */
    @SuppressWarnings( "unchecked" )
    private void readObject( final ObjectInputStream stream ) throws ClassNotFoundException, IOException {
        // Write the default stuff
        stream.defaultReadObject();
        // Retrieve the number of mappings in the array.
        final int size = stream.readInt();
        // Allocate arrays to temporarily store the mappings in
        final K[] keys = (K[]) new Comparable[ size ];
        final V[] values = (V[]) new Comparable[ size ];
        for ( int i = 0; i < size; i++ ) {
            keys[ i ] = (K) stream.readObject();
            values[ i ] = (V) stream.readObject();
        }
        this.root = new Node< K, V >( null, keys, values, 1, size );
    }

    /**
     * @see org.millscript.commons.util.ETreeMap#setRootNode(N)
     */
    public void setRootNode( final ETreeMapNode< K, V > node ) {

        referenceQueue.setAccessible( false );
        // Retrieve the number of mappings in the array.
        this.size = stream.readInt();
        // Allocate the required number of buckets.
        this.store = new HashMaplet[ stream.readInt() ];
        // Set the rehash trigger size
        this.triggerRehashSize = (int) ( this.store.length * DEFAULT_LOAD_FACTOR );
        // Retrieve the mappings
        for ( int i = 0; i < size; i++ ) {
            final K key = (K) stream.readObject();
            final V value = (V) stream.readObject();
            final int pos = key == null ? 0 : ( key.hashCode() & 0x7FFFFFFF ) % this.store.length;
            if ( this.store[ pos ] == null ) {
                this.store[ pos ] = new HashMaplet< K, V >( this.makeReference( key ), value );

    }

    /**
     * @see org.millscript.commons.util.IMap#iterator(boolean)
     */
    @SuppressWarnings( "unchecked" )
    public MapIterator< K, V > iterator( final boolean share ) {
        if ( share ) {
            return new LinkedHashMapIterator< K, V >( this.firstElement, share );
        } else {
            // It's more efficient to copy the hash map backing store into a
            // fixed array of plain maplets, rather than copying the array of
            // buckets.
            final Maplet< K, V >[] maplets = new Maplet[ this.size() ];
            LinkedHashMaplet< K, V > current = this.firstElement;
            for ( int i = 0; current != null; current = current.nextByInsertion ) {
                maplets[ i++ ] = new IMaplet< K, V >( current );
            }
            return new IMapletArrayMap.MapletArrayMapIterator< K, V >( maplets, true );
        }
    }

    /**
     * @see org.millscript.commons.util.map.AbstractIMap#sharedKeyList()
     */
    @Override

        HashMapValuesList( final AbstractEReferenceHashMap< ?, ? > map, final int first, final int last ) {
            super( map, first, last );
        }

        /**
         * @see org.millscript.commons.util.map.IHashMap.HashMapXList#getAppropriateNodePart(org.millscript.commons.util.Maplet)
         */
        @Override
        @SuppressWarnings( "unchecked" )
        V getAppropriateMapletPart( final Maplet< ?, ? > maplet ) {
            return (V) maplet.getValue();
        }

        /**
         * @see org.millscript.commons.util.map.IHashMap.HashMapKeysIterator.HashMapXList#sharedIterator()
         */
        @Override
        ListIterator< V > sharedIterator() {
            return new HashMapValuesIterator< V >( this.backingMap, this.firstIndex, this.lastIndex );
        }

        /**
         * @see org.millscript.commons.util.map.AbstractEReferenceHashMap.HashMapXList#sharedSlice(int, int)
         */
        @Override
        IList< V > sharedSlice( final int first, final int last ) {
            return new HashMapValuesList< V >( this.backingMap, first, last );
        }

    }

    /**
     * This class implements a map iterator which iterates over an array
     * of hash map buckets, returning either the keys or values. The backing
     * store is shared with it's enclosing mutable map.
     */
    private static abstract class HashMapXIterator< V > extends AbstractListIterator< V > {

                return new JavaUtilCollectionListIterator< V >(
                    this.store,
                    this.firstIndex,
                    this.lastIndex
                );
            } else if ( this.size() == 0 ) {
                return new NullListIterator< V >();
            } else {
                final V[] objects = (V[]) new Object[ this.size() ];
                System.arraycopy( this.store, this.firstIndex - 1, objects, 0, objects.length );
                return new ArrayListIterator< V >( objects, true );
            }
        }

        /**
         * @see org.millscript.commons.util.IMap#size()
         */
        public int size() {
            return this.lastIndex < this.firstIndex ? 0
                                                    : this.lastIndex - this.firstIndex + 1;
        }

    }

    protected IList< V > doSlice( final int first, final int last, boolean share ) {
        if ( share ) {
            return new SharedLinkedListList< V >( this.firstLink, first, last );
        } else {
            // Return a copy of the relevant slice of the list
            final V[] objects = (V[]) new Object[ first - last + 1 ];
            Link< V > link = this.firstLink;
            int outerListCount = 1;
            // Find the first link in the shared chain
            for ( ; outerListCount <= first; outerListCount++ ) {
                link = link.next;
            }
            // Now copy each required link into the array
            int newArrayPos = 0;
            for ( ; link != null && outerListCount <= last; link = link.next, outerListCount++ ) {
                objects[ newArrayPos++ ] = link.current;
            }
            return new IArrayList< V >( objects, true );
        }
    }

            if ( hmp.getKey() == null ? key == null : hmp.getKey().equals( key ) ) {
                hmp.value = value;
                // As we've updated a mapping we must exit the function early,
                // otherwise we'll trigger the mishap below...
                return;
            }
        }
        // Error
        throw new NoSuchKeyInMapAlert(
            "Only pre-existing keys can have their values updated"
        ).culpritKey( key ).decorate( this ).mishap();
    }

    /**
     * Writes this object to the specified {@link ObjectOutputStream}.
     *
     * @param stream    the {@link ObjectOutputStream} to write this object to
     * @serialData      Writes the default object, followed by the integer
     * number of mappings, the integer number of buckets and then an
     * alternating sequence of key-value pairs
     * @throws IOException      if something goes wrong during the
     * serialization process
     */
    private void writeObject( final ObjectOutputStream stream ) throws IOException {
        // Write the default stuff
        stream.defaultWriteObject();
        // Save the number of mappings in the array.
        stream.writeInt( this.size() );
        // Save the number of buckets
        stream.writeInt( this.store.length );
        // Save the mappings in the array
        for ( MapIterator< K, V > it = this.iterator( true ); it.hasNext(); ) {
            stream.writeObject( it.nextKey() );
            stream.writeObject( it.currentValue() );
        }
    }

}

        public int indexOf( final V value ) {
            int pos = 1;
            LinkedHashMaplet< ?, ? > hmp = this.firstHashMaplet;
            if ( value == null ) {
                for ( ; hmp != null && pos <= this.size; hmp = hmp.nextByInsertion, pos++ ) {
                    if ( this.getAppropriateMapletPart( hmp ) == null ) {
                        return pos;
                    }
                }
            } else {
                for ( ; hmp != null && pos <= this.size; hmp = hmp.nextByInsertion, pos++ ) {
                    if ( value.equals( this.getAppropriateMapletPart( hmp ) ) ) {
                        return pos;
                    }
                }
            }
            return 0;
        }

        /**
         * @see org.millscript.commons.util.IMap#iterator(boolean)
         */
        @SuppressWarnings( "unchecked" )
        public ListIterator< V > iterator( final boolean share ) {

            if ( key == null ? hmp.getKey() == null : key.equals( hmp.getKey() ) ) {
                hmp.value = value;
                // As we've updated a mapping we must exit the function early,
                // otherwise we'll trigger the mishap below...
                return;
            }
        }
        // Error
        throw new NoSuchKeyInMapAlert(
            "Only pre-existing keys can have their values updated"
        ).culpritKey( key ).decorate( this ).mishap();
    }

    /**
     * Writes this object to the specified {@link ObjectOutputStream}.
     *
     * @param stream    the {@link ObjectOutputStream} to write this object to
     * @serialData      Writes the default object, followed by the integer
     * number of mappings, the integer number of buckets and then an
     * alternating sequence of key-value pairs
     * @throws IOException      if something goes wrong during the
     * serialization process
     */
    private void writeObject( final ObjectOutputStream stream ) throws IOException {
        // Write the default stuff
        stream.defaultWriteObject();
        // Save the number of mappings in the array.
        stream.writeInt( this.size() );
        // Save the number of buckets
        stream.writeInt( this.store.length );
        // Save the mappings in the array
        for ( MapIterator< K, V > it = this.iterator( true ); it.hasNext(); ) {
            stream.writeObject( it.nextKey() );
            stream.writeObject( it.currentValue() );
        }
    }

}

    public AbstractEReferenceHashMap( final IMap< K, V > map ) {
        final MapIterator< K, V > it = map.iterator( true );
        final HashMaplet< K, V >[] maplets = new HashMaplet[ map.size() * 2 + 1 ];
        while ( it.hasNext() ) {
            final int pos = it.nextKey() == null ? 0 : ( it.currentKey().hashCode() & 0x7FFFFFFF ) % maplets.length;
            if ( maplets[ pos ] == null ) {
                maplets[ pos ] = new HashMaplet< K, V >( this.makeReference( it.currentKey() ), it.currentValue() );

            }
        }

        /**
         * @see org.millscript.commons.util.iterator.AbstractMapIterator#advance()
         */
        @Override
        protected void advance() {
            // Increment the position
            super.advance();
            // Move to the next maplet
            this.currentMaplet = this.nextMaplet;
            if ( super.position >= this.size ) {
                this.nextMaplet = null;
            } else if ( this.nextMaplet != null ) {
                this.nextMaplet = this.nextMaplet.next;
            }
            // Ensure the next maplet is properly populated
            this.checkNext();
        }

        /**
         * Checks that the next maplet field is populated with the next maplet
         * if one is available.
         */
        private void checkNext() {
            if ( this.nextMaplet == null ) {
                // Must advance to the next bucket if available
                if ( ++bucketIndex < this.store.length ) {
                    this.nextMaplet = this.store[ bucketIndex ];
                    // Next bucket please
                    this.checkNext();
                }
            }
        }

        /**
         * Returns the appropriate part of the specified maplet for this list.
         *
         * @param maplet    the maplet to get the appropriate part from
         * @return  the appropriate part of the specified maplet
         */
        abstract V getAppropriateMapletPart( Maplet< ?, ? > maplet );

    }

    /**
     * @see org.millscript.commons.util.IList#toArray(null[])
     */
    @Override
    @SuppressWarnings( "unchecked" )
    public V[] toArray( final V[] target ) {
        if ( this.size() <= target.length ) {
            System.arraycopy( this.store, 0, target, 0, this.size() );
            return target;
        } else {
            final V[] dest = (V[]) Array.newInstance(
                target.getClass(),
                this.size()
            );
            System.arraycopy( this.store, 0, dest, 0, this.size() );
            return dest;
        }
    }

                return new ISharedLinkedList< V >(
                    this.firstLink,
                    first,
                    last
                );
            } else {
                // Return a copy of the relevant slice of the list
                final V[] objects = (V[]) new Object[ first - last + 1 ];
                Link< V > link = this.firstLink;
                int outerListCount = 1;
                // Find the first link in the shared chain
                for ( ; outerListCount <= first; outerListCount++ ) {
                    link = link.next;
                }
                // Now copy each required link into the array
                int newArrayPos = 0;
                for ( ; link != null && outerListCount <= last; link = link.next, outerListCount++ ) {
                    objects[ newArrayPos++ ] = link.current;
                }
                return new IArrayList< V >( objects, true );
            }
        }

    private static abstract class LinkedHashMapXIterator< V > extends AbstractListIterator< V > {

        /**
         * The maplet for the current point in the iteration.
         */
        private LinkedHashMaplet< ?, ? > currentMaplet;

        /**
         * The next maplet in the iteration. If this is <code>null</code> there
         * are no more elements in the iteration.
         */
        private LinkedHashMaplet< ?, ? > nextMaplet;

        /**
         * The number of elements this iterator will return.
         */
        private final int size;

        /**
         * Constructs a new hash map iterator to iterate over the specified
         * array of hash map buckets returning either the maplet keys or
         * values.
         *
         * @param start the first LinkedHashMaplet in the iteration
         * @param num   the number of elements in the iteration
         */
        public LinkedHashMapXIterator( final LinkedHashMaplet< ?, ? > start, final int num ) {
            this.nextMaplet = start;
            this.size = num;
        }

        /**
         * @see org.millscript.commons.util.iterator.AbstractMapIterator#advance()
         */
        @Override
        protected void advance() {
            // Increment the position
            super.advance();
            this.currentMaplet = this.nextMaplet;
            if ( super.position >= this.size ) {
                this.nextMaplet = null;
            } else if ( this.nextMaplet != null ) {
                this.nextMaplet = this.nextMaplet.nextByInsertion;
            }
        }

        /**
         * Returns the appropriate part of the specified maplet for this list.
         *
         * @param maplet    the maplet to get the appropriate part from
         * @return  the appropriate part of the specified maplet
         */
        abstract V getAppropriateMapletPart( Maplet< ?, ? > maplet );

                return new ISharedLinkedListIterator< V >(
                    this.firstLink,
                    this.size()
                );
            } else {
                final V[] objects = (V[]) new Object[ this.size() ];
                int i = 0;
                for ( Link< V > link = this.firstLink; link != null && i < objects.length; link = link.next, i++ ) {
                    objects[ i ] = link.current;
                }
                return new ArrayListIterator< V >( objects, true );
            }
        }

        /**
         * @see org.millscript.commons.util.IMap#size()
         */
        public int size() {
            return this.size;
        }
        
    }

    /**
     * This class provides a map interator implementation which iterates over
     * a shared poriton of the specified linked list.
     */
    public static class ISharedLinkedListIterator< V > extends AbstractListIterator< V > {

            if ( key == null ? currentInBucket.key == null : key.equals( currentInBucket.key ) ) {
                // The keys are equal, we should remove this link from the
                // bucket, but first we need to find the right entry in the
                // insertion order list, we can't do better than a linear
                // search unfortunately
                LinkedHashMaplet< K, V > previous = null;
                LinkedHashMaplet< K, V > current = this.firstElement;
                while ( current != null ) {
                    if ( current == currentInBucket ) {
                        // We've found the element to remove in both it's bucket
                        // and the insertion order chain, so remove it.
                        if ( prev == null ) {
                            // We're still at the begining of the bucket, so remove
                            // the first link from it.
                            this.store[ pos ] = currentInBucket.next;
                        } else {
                            // We're after the first link in the bucket, so remove
                            // the current link
                            prev.next = currentInBucket.next;
                        }
                        if ( previous == null )  {
                            // We've just removed the element inserted first
                            this.firstElement = current.nextByInsertion;
                        } else {
                            // We've removed an element that wasn't inserted first...
                            previous.nextByInsertion = current.nextByInsertion;
                        }
                        // We're done, so return from this function
                        this.size--;
                        return;
                    }
                    previous = current;
                    current = current.nextByInsertion;
                }
            }
        }
    }

            return new HashMapIterator< K, V >( this.store, share );
        } else {
            // It's more efficient to copy the hash map backing store into a
            // fixed array of plain maplets, rather than copying the array of
            // buckets.
            final Maplet< K, V >[] maplets = new Maplet[ this.size() ];
            for ( int i = 0, j = 0; i < this.store.length; i++ ) {
                for ( HashMaplet< K, V > maplet = this.store[ i ]; maplet != null; maplet = maplet.next ) {
                    maplets[ j++ ] = new IMaplet< K, V >( maplet );
                 }
            }
            return new IMapletArrayMap.MapletArrayMapIterator< K, V >( maplets, true );
        }
    }

    /**
     * @see org.millscript.commons.util.map.AbstractIMap#sharedKeyList()
     */
    @Override

    }

    /**
     * @see java.lang.Object#equals(java.lang.Object)
     */
    @Override
    public boolean equals( final Object obj ) {
        if ( this == obj ) {
            return true;
        } else if ( obj instanceof Maplet ) {
            // The key or the value are allowed to be null
            final Maplet< ?, ? > maplet = (Maplet) obj;
            if ( this.key == null ? maplet.getKey() == null : this.key.equals( maplet.getKey() ) ) {
                return this.value == null ? maplet.getValue() == null
                                          : this.value.equals( maplet.getValue() );
            }
        }
        return false;
    }

    /**
     * @see org.millscript.commons.util.Maplet#getKey()
     */
    public Integer getKey() {

            return new HashMapIterator< K, V >( this.store, share );
        } else {
            // It's more efficient to copy the hash map backing store into a
            // fixed array of plain maplets, rather than copying the array of
            // buckets.
            final Maplet< K, V >[] maplets = new Maplet[ this.size() ];
            for ( int i = 0, j = 0; i < this.store.length; i++ ) {
                for ( HashMaplet< K, V > maplet = this.store[ i ]; maplet != null; maplet = maplet.next ) {
                    maplets[ j++ ] = new IMaplet< K, V >( maplet );
                 }
            }
            return new IMapletArrayMap.MapletArrayMapIterator< K, V >( maplets, true );
        }
    }

    public ISharedArrayList( final V[] objects, final int start, final int end ) {
        if ( start > end ) {
            this.store = null;
        } else if ( start < 1 || start > objects.length ) {
            throw new ListIndexOutOfBoundsAlert(
                "First index in slice must be between 1 and the length of the array"
            ).culprit(
                "index",
                start
            ).decorate( objects ).mishap();
        } else if ( end > objects.length ) {
            throw new ListIndexOutOfBoundsAlert(
                "Last index in slice must not be greater than the length of the array"
            ).culprit(
                "index",
                end
            ).decorate( objects ).mishap();
        } else {
            this.store = objects;

        private HashMapXList( final AbstractEReferenceHashMap< ?, ? > map, final int first, final int last ) {
            int fb = 0;
            HashMaplet< ?, ? > fm = null;
            int totalMaplets = 0;
            // Loop through the buckets to find the first maplet
            for ( int i = 0; i < map.store.length; i++ ) {
                // Loop through the maplets in this bucket
                for ( HashMaplet< ?, ? > hmp = map.store[ i ]; hmp != null; hmp = hmp.next ) {
                    // Have we found the first maplet?
                    if ( ++totalMaplets == first ) {
                        // Yes, we have so store it's details
                        fb = i;
                        fm = hmp;
                    }
                }
            }
            if ( first > last ) {
                this.firstBucket = 0;

        private HashMapXList( final EHashMap< ?, ? > map, final int first, final int last ) {
            int fb = 0;
            HashMaplet< ?, ? > fm = null;
            int totalMaplets = 0;
            // Loop through the buckets to find the first maplet
            for ( int i = 0; i < map.store.length; i++ ) {
                // Loop through the maplets in this bucket
                for ( HashMaplet< ?, ? > hmp = map.store[ i ]; hmp != null; hmp = hmp.next ) {
                    // Have we found the first maplet?
                    if ( ++totalMaplets == first ) {
                        // Yes, we have so store it's details
                        fb = i;
                        fm = hmp;
                    }
                }
            }
            if ( first > last ) {
                this.firstBucket = 0;

    public void insert( final Maplet< ? extends K, ? extends V > entry ) {
        this.insert( entry.getKey(), entry.getValue() );
    }

    /**
     * @see org.millscript.commons.util.EMap#insertAll(org.millscript.commons.util.IMap)
     */
    public void insertAll( final IMap< ? extends K, ? extends V > map ) {
        // Iterate over all the mappings in the supplied map, inserting them
        // into this one. NOTE - we want the iterator to share backing store
        // here
        final MapIterator< ? extends K, ? extends V > it = map.iterator( true );
        while ( it.hasNext() ) {
            this.insert( it.nextKey(), it.currentValue() );
        }
    }

    /**
     * @see org.millscript.commons.util.EMap#remove(org.millscript.commons.util.Maplet)
     */
    public void remove( final Maplet< ? extends K, ? extends V > entry ) {

                } else {
                    for ( LinkedHashMaplet< K, V > hmp = this.store[ pos ]; hmp != null; hmp = hmp.next ) {
                        if ( hmp.getKey() == null ? it.currentKey() == null : hmp.getKey().equals( it.currentKey() ) ) {
                            throw new KeyAlreadyExistsAlert(
                                "Specified key is already present in this map"
                            ).culprit(
                                "existing maplet",
                                hmp
                            ).culprit(
                                "duplicate maplet",
                                it.currentMaplet()
                            ).mishap();
                        } else if ( hmp.next == null ) {

        private HashMapXList( final AbstractEReferenceHashMap< ?, ? > map, final int first, final int last ) {
            int fb = 0;
            HashMaplet< ?, ? > fm = null;
            int totalMaplets = 0;
            // Loop through the buckets to find the first maplet
            for ( int i = 0; i < map.store.length; i++ ) {
                // Loop through the maplets in this bucket
                for ( HashMaplet< ?, ? > hmp = map.store[ i ]; hmp != null; hmp = hmp.next ) {
                    // Have we found the first maplet?
                    if ( ++totalMaplets == first ) {
                        // Yes, we have so store it's details
                        fb = i;
                        fm = hmp;
                    }
                }
            }
            if ( first > last ) {
                this.firstBucket = 0;

    public Integer getKey() {
        return this.key;
    }

    /**
     * @see org.millscript.commons.util.Maplet#getValue()
     */
    public V getValue() {
        return this.value;
    }

    /**
     * @see java.lang.Object#hashCode()
     */
    @Override
    public int hashCode() {
        return MapletUtil.mapletHashCode( this.key, this.value );
    }

    /**
     * @see java.lang.Object#toString()
     */
    @Override
    public String toString() {
        final StringBuffer buffer = new StringBuffer( 128 );
        buffer.append( "( " );
        buffer.append( this.key );
        buffer.append( " ==> " );
        buffer.append( this.value );
        return buffer.append( " )" ).toString();
    }

}

    public void update( final Maplet< ? extends K, ? extends V > entry ) {
        this.update( entry.getKey(), entry.getValue() );
    }

    /**
     * @see org.millscript.commons.util.UMap#updateAll(org.millscript.commons.util.IMap)
     */
    public void updateAll( final IMap< ? extends K, ? extends V > map ) {
        final MapIterator< ? extends K, ? extends V > it = map.iterator( true );
        while ( it.hasNext() ) {
            this.update( it.nextKey(), it.currentValue() );
        }
    }

}

                final V[] objects = (V[]) new Object[ this.size() ];
                int i = this.firstBucket;
                int pos = 0;
                HashMaplet< ?, ? > hmp = this.firstHashMaplet;
                while ( pos < this.size() && i < this.store.length ) {
                    objects[ pos ] = this.getAppropriateMapletPart( hmp );
                    // Advance to the next bucketIndex/maplet
                    hmp = hmp.next;
                    while ( hmp == null && ++i < this.store.length ) {
                        hmp = this.store[ i ];
                    }
                    pos++;
                }
                return new IArrayList< V >( objects, true );