001: /*=============================================================================
002: * Copyright Texas Instruments 2003. All Rights Reserved.
003: *
004: * This program is free software; you can redistribute it and/or
005: * modify it under the terms of the GNU Lesser General Public
006: * License as published by the Free Software Foundation; either
007: * version 2 of the License, or (at your option) any later version.
008: *
009: * This program is distributed in the hope that it will be useful,
010: * but WITHOUT ANY WARRANTY; without even the implied warranty of
011: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012: * Lesser General Public License for more details.
013: *
014: * You should have received a copy of the GNU Lesser General Public
015: * License along with this library; if not, write to the Free Software
016: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
017: *
018: * $ProjectHeader: OSCRIPT 0.155 Fri, 20 Dec 2002 18:34:22 -0800 rclark $
019: */
020:
021: package oscript.util;
022:
023: import oscript.exceptions.*;
024:
025: /**
026: * This defines the interface for a table that maps a symbol (integer id) to
027: * an array index. This is similar to a hashtable, except that allows for
028: * a couple domain specific interface level optimizations:
029: * <ul>
030: * <li> the value that a symbol maps to is an int <code>idx</code> where
031: * <code>0 <= idx <= Integer.MAX_VALUE</code>. This means that an
032: * <code>idx</code> value of <code>-1</code> can be (and is) used by
033: * {@link #get} to indicate that the table doesn't contain the specified
034: * symbol.
035: * <li> since the table knows that the value of the next entry created
036: * is equal to the last plus one (ie. the next successive array index)
037: * the act of checking for the existance of a mapping (get), and
038: * creating a new mapping if one doesn't already exist (put) can be
039: * combined int a single {@link #create} operation.
040: * </ul>
041: *
042: * @author Rob Clark (rob@ti.com)
043: * @version 1.0
044: * @see SymbolMap
045: */
046: public interface SymbolTable {
047: /**
048: * Currently the symbol id of zero is reserved for use by the symbol table
049: * implementation, and in the future could (hypothetically, at least) add
050: * more, therefore the minimum symbol id must be <code>MIN_SYMBOL_ID</code>.
051: */
052: public static int MIN_SYMBOL_ID = 1;
053:
054: /**
055: * Get the index that the specified symbol maps to.
056: *
057: * @param id the id of the symbol to get a mapping for
058: * @return an index, or <code>-1</code> if no mapping exists for the
059: * specified symbol
060: */
061: public int get(int id);
062:
063: /**
064: * Get the index that the specified symbol maps to, and create a new one
065: * if a mapping does not already exist. If a new mapping is created,
066: * it's value is the next successive array index, ie. the the previous
067: * array index plus one. The first mapping created has the value zero.
068: *
069: * @param id the id of the symbol to get a mapping for
070: * @return an index
071: */
072: public int create(int id);
073:
074: /**
075: * The number of mappings that exist in this table.
076: *
077: * @return the number of mappings in the table
078: */
079: public int size();
080:
081: /**
082: * Return an iteration of the keys (symbols) into this table. To conform to
083: * the {@link java.util.Iterator} interface, each symbol is wrapped (boxed)
084: * in a {@link Integer}.
085: *
086: * @return an iteration of symbols that are keys into this table
087: */
088: public java.util.Iterator symbols();
089: }
090:
091: /*
092: * Local Variables:
093: * tab-width: 2
094: * indent-tabs-mode: nil
095: * mode: java
096: * c-indentation-style: java
097: * c-basic-offset: 2
098: * eval: (c-set-offset 'substatement-open '0)
099: * eval: (c-set-offset 'case-label '+)
100: * eval: (c-set-offset 'inclass '+)
101: * eval: (c-set-offset 'inline-open '0)
102: * End:
103: */
|