001    // Copyright 2008 Regents of the University of California.  May be used 
002    // under the terms of the revised BSD license.  See LICENSING for details.
003    package org.joe_e.array;
004    
005    /**
006     * A builder of ConstArrays.  Each type of ConstArray has a nested class that
007     * implements this interface, e.g. <code>ConstArray.Builder</code>.
008     * 
009     * @author Adrian Mettler
010     *
011     * @param <E> the component type of the Array to build
012     */
013    public interface ArrayBuilder<E> {
014        /** 
015         * Appends an element to the Array
016         * @param element the element to append
017         */
018        void append(E element);
019    
020        /** 
021         * Appends all elements from a Java array to the Array
022         * @param elements the element to append
023         */
024        void append(E[] elements);
025    
026        /** 
027         * Appends a range of elements from a Java array to the Array
028         * @param elements the source array
029         * @param off   the index of the first element to append
030         * @param len   the number of elements to append
031         */
032        void append(E[] elements, int off, int len);
033        
034        /** 
035         * Gets the current number of elements in the Array
036         * @return the number of elements that have been appended
037         */
038        int length();
039        
040        /**
041         * Create a snapshot of the current content.
042         * @return a <code>ConstArray<E></code> containing the elements written
043         *         so far
044         */
045        ConstArray<E> snapshot();
046    }