DS_Indexable.java

/* --------------------------------------------------------- *
 *    __________    D E L T A S C R I P T                    *
 *   (_________()                                            *
 *    /  ===   /   - A fast, dynamic scripting language      *
 *   |  ==    |    - Version 4.13.11.0                       *
 *   /  ===   /    - Developed by Adam R. Nelson             *
 *  |  =  =  |     - 2011-2013                               *
 *  /  ===   /     - Distributed under GNU LGPL v3           *
 * (________()     - http://github.com/ar-nelson/deltascript *
 *                                                           *
 * --------------------------------------------------------- */

package com.sector91.delta.script.objects;

import com.sector91.delta.script.DScriptErr;

/**
 * <p>A DeltaScript object that supports the indexing (<code>[]</code>)
 * operator. Usually, this means some sort of collection.</p>
 * 
 * @author Adam R. Nelson
 */
public interface DS_Indexable extends DS_Object
{
    /**
     * <p>Returns a member of this object, specified by an index value (which
     * may be anything, but is usually a {@link DS_Integer}).</p>
     * 
     * <p>This method is called whenever the indexing operator is used (e.g.,
     * <code>seq[1]</code>), except for assignments (<code>seq[1] = q</code>),
     * which are handled by {@link #setIndex(DS_Object, DS_Object)}. If the
     * index is out of bounds or of a type not supported by this object, this
     * method should throw an error.</p>
     * 
     * @param index The index value to retrieve a member from.
     * @return The member at the given index.
     * @throws DScriptErr If the index is out of bounds or of an invalid type, or
     *                  another error occurs.
     */
    public DS_Object getIndex(DS_Object index) throws DScriptErr;
    
    /**
     * <p>Assigns to a member of this object, specified by an index value
     * (which may be anything, but is usually a {@link DS_Integer}).</p>
     * 
     * <p>This method is called whenever a member accessed with the indexing
     * operator is assigned to with the <code>=</code> operator (e.g.,
     * <code>seq[1] = q</code>). If the index if out of bounds or of a type
     * not supported by this object, or if the value is of a type that this
     * object cannot contain, this method should throw an error.</p>
     * 
     * @param index The index value to assign to.
     * @param value The value to assign to the member at the given index.
     * @return The member previously contained at this index, or null if no
     *         member previously existed at this index.
     * @throws DScriptErr If the index is out of bounds or of an invalid type,
     *                  the value is of an invalid type, or another error
     *                  occurs.
     */
    public DS_Object setIndex(DS_Object index, DS_Object value)
            throws DScriptErr;
    
    /**
     * <p>Returns the number of valid indexable values contained in this
     * object. May return 0 if this number is indefinite.</p>
     * 
     * @return The number of valid indexable values contained in this object.
     */
    public int size();
}