001/** An Interface representing the Type of a Token.
002
003 Copyright (c) 1997-2014 The Regents of the University of California.
004 All rights reserved.
005 Permission is hereby granted, without written agreement and without
006 license or royalty fees, to use, copy, modify, and distribute this
007 software and its documentation for any purpose, provided that the above
008 copyright notice and the following two paragraphs appear in all copies
009 of this software.
010
011 IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
012 FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
013 ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
014 THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
015 SUCH DAMAGE.
016
017 THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
018 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
019 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
020 PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
021 CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
022 ENHANCEMENTS, OR MODIFICATIONS.
023
024 PT_COPYRIGHT_VERSION_2
025 COPYRIGHTENDKEY
026
027
028 */
029package ptolemy.data.type;
030
031import ptolemy.data.Token;
032import ptolemy.kernel.util.IllegalActionException;
033
034///////////////////////////////////////////////////////////////////
035//// Type
036
037/**
038 An interface representing the type of a Token.
039
040 @author Yuhong Xiong, Steve Neuendorffer
041 @version $Id$
042 @since Ptolemy II 0.4
043 @Pt.ProposedRating Red (neuendor)
044 @Pt.AcceptedRating Red (cxh)
045 */
046public interface Type {
047
048    /** Return a new type which represents the type that results from
049     *  adding a token of this type and a token of the given argument
050     *  type.
051     *  @param rightArgumentType The type to add to this type.
052     *  @return A new type, or BaseType.GENERAL, if the operation does
053     *  not make sense for the given types.
054     */
055    public Type add(Type rightArgumentType);
056
057    /** Return a deep clone of this type.
058     *  @return A Type.
059     *  @exception CloneNotSupportedException If an instance cannot be cloned.
060     */
061    public Object clone() throws CloneNotSupportedException;
062
063    /** Convert the specified token into a token having the type
064     *  represented by this object.
065     *  @param token a token.
066     *  @return a token.
067     *  @exception IllegalActionException If lossless conversion
068     *   cannot be done.
069     */
070    public Token convert(Token token) throws IllegalActionException;
071
072    /** Return a new type which represents the type that results from
073     *  dividing a token of this type and a token of the given
074     *  argument type.
075     *  @param rightArgumentType The type to add to this type.
076     *  @return A new type, or BaseType.GENERAL, if the operation does
077     *  not make sense for the given types.
078     */
079    public Type divide(Type rightArgumentType);
080
081    /** Determine if the argument represents the same type as this object.
082     *  @param object A Type.
083     *  @return True if the argument represents the same type as this
084     *   object; false otherwise.
085     */
086    @Override
087    public boolean equals(Object object);
088
089    /** Return a perfect hash for this type.  This number corresponds
090     *  uniquely to a particular type, and is used to improve
091     *  performance of certain operations in the TypeLattice class.
092     *  All instances of a particular type (e.g. integer array) must
093     *  return the same number.  Types that return HASH_INVALID will
094     *  not have results in TypeLattice cached.  Note that it is safer
095     *  to return HASH_INVALID, than to return a number that is not
096     *  unique, or different number for the same type from different
097     *  instances.
098     *  @return A number greater than or equal to 0, or HASH_INVALID.
099     */
100    public int getTypeHash();
101
102    /** Return the class for tokens that this type represents.
103     *  @return The class for tokens that this type represents.
104     */
105    public Class getTokenClass();
106
107    /** Return true if this type does not correspond to a single token
108     *  class.  This occurs if the type is not instantiable, or it
109     *  represents either an abstract base class or an interface.
110     *  @return True if this type does not correspond to a single token
111     *  class.
112     */
113    public boolean isAbstract();
114
115    /** Test if the argument type is compatible with this type.
116     *  Compatible is defined as follows: If this type is a constant, the
117     *  argument is compatible if it is the same or less than this type in
118     *  the type lattice; If this type is a variable, the argument is
119     *  compatible if it is a substitution instance of this type.
120     *  @param type An instance of Type.
121     *  @return True if the argument is compatible with this type.
122     */
123    public boolean isCompatible(Type type);
124
125    /** Test if this Type is a constant. A Type is a constant if it
126     *  does not contain BaseType.UNKNOWN in any level within it.
127     *  @return True if this type is a constant.
128     */
129    public boolean isConstant();
130
131    /** Determine if this Type corresponds to an instantiable token
132     *  class.
133     *  @return True if this type corresponds to an instantiable
134     *   token class.
135     */
136    public boolean isInstantiable();
137
138    /** Return true if the specified type is a substitution instance of this
139     *  type. For the argument to be a substitution instance, it must be
140     *  either the same as this type, or it must be a type that can be
141     *  obtained by replacing the BaseType.UNKNOWN component of this type by
142     *  another type.
143     *  @param type A Type.
144     *  @return True if the argument is a substitution instance of this type.
145     */
146    public boolean isSubstitutionInstance(Type type);
147
148    /** Return a new type which represents the type that results from
149     *  moduloing a token of this type and a token of the given
150     *  argument type.
151     *  @param rightArgumentType The type to add to this type.
152     *  @return A new type, or BaseType.GENERAL, if the operation does
153     *  not make sense for the given types.
154     */
155    public Type modulo(Type rightArgumentType);
156
157    /** Return a new type which represents the type that results from
158     *  multiplying a token of this type and a token of the given
159     *  argument type.
160     *  @param rightArgumentType The type to add to this type.
161     *  @return A new type, or BaseType.GENERAL, if the operation does
162     *  not make sense for the given types.
163     */
164    public Type multiply(Type rightArgumentType);
165
166    /** Return the type of the multiplicative identity for elements of
167     *  this type.
168     *  @return A new type, or BaseType.GENERAL, if the operation does
169     *  not make sense for the given types.
170     */
171    public Type one();
172
173    /** Return a new type which represents the type that results from
174     *  subtracting a token of this type and a token of the given
175     *  argument type.
176     *  @param rightArgumentType The type to add to this type.
177     *  @return A new type, or BaseType.GENERAL, if the operation does
178     *  not make sense for the given types.
179     */
180    public Type subtract(Type rightArgumentType);
181
182    /** Return the string representation of this type.
183     *  @return A String.
184     */
185    @Override
186    public String toString();
187
188    /** Return the type of the additive identity for elements of
189     *  this type.
190     *  @return A new type, or BaseType.GENERAL, if the operation does
191     *  not make sense for the given types.
192     */
193    public Type zero();
194
195    ///////////////////////////////////////////////////////////////////
196    ////                         public variables                  ////
197
198    /** Used to indicate that the type comparison cache is invalid.
199     *  @since Ptolemy II 2.1
200     */
201    public static final int HASH_INVALID = Integer.MIN_VALUE;
202
203    // The maximum size of the type hash.
204    // HASH_MAX was used in TypeLattice but as of r66807 is no longer used.
205    //public static final int HASH_MAX = 16;
206}