Package ptolemy.data

Class RecordToken

  • Direct Known Subclasses:
    OrderedRecordToken
    public class RecordToken
extends AbstractNotConvertibleToken
    A token that contains a set of label/token pairs. Record labels may be arbitrary strings. Operations on record tokens result in new record tokens containing only the common fields, where the operation specifies how to combine the data in the common fields. Thus, for example, if two record tokens are added or subtracted, then common records (those with the same labels) will be added or subtracted, and the disjoint records will not appear in the result.
    Since:
    Ptolemy II 1.0
    Version:
    $Id$
    Author:
    Yuhong Xiong, Steve Neuendorffer, Elaine Cheong, Edward Lee; contributors: J. S. Senecal, Marten Lohstroh
    Pt.AcceptedRating:
    Yellow (cxh)
    Pt.ProposedRating:
    Green (neuendor)

    • Field Detail

      • EMPTY_RECORD

        public static final RecordToken EMPTY_RECORD
        Empty Record.

      • _fields

        protected java.util.Map<java.lang.String,​Token> _fields
        The map of fields that has keys of type String and values of type token. Subclasses can use alternative Map implementations (for ordering).

    • Constructor Detail

      • RecordToken

        public RecordToken()
        Construct a RecordToken with no fields.

      • RecordToken

        public RecordToken​(java.lang.String[] labels,
                   Token[] values)
            throws IllegalActionException
        Construct a RecordToken with the specified labels and values. The labels and values arrays must have the same length, and have one to one correspondence with each other. That is, the i'th entry in the labels array is the label for the i'th value in the values array. If both arrays are empty, this creates an empty record token.
        Parameters:
        labels - An array of labels.
        values - An array of Tokens.
        Throws:
        IllegalActionException - If the labels or the values array do not have the same length, or contains null element, or the labels array contains duplicate elements.

      • RecordToken

        public RecordToken​(java.lang.String init)
            throws IllegalActionException
        Construct a RecordToken from the specified string.

        Record labels that contain any non-Java identifier characters must be presented as a string i.e., surrounded with single or double quotes. Quotes within label strings must be escaped using a backslash.

        Parameters:
        init - A string expression of a record.
        Throws:
        IllegalActionException - If the string does not contain a parsable record.

      • RecordToken

        public RecordToken​(java.util.Map<java.lang.String,​Token> fieldMap)
            throws IllegalActionException
        Construct a RecordToken with the labels and values specified by a given Map object. The object cannot contain any null keys or values.
        Parameters:
        fieldMap - A Map that has keys of type String and values of type Token.
        Throws:
        IllegalActionException - If the map contains null keys or values, or if it contains non-String keys or non-Token values.

    • Method Detail

      • equals

        public boolean equals​(java.lang.Object object)
        Return true if the class of the argument is RecordToken, and the argument has the same set of labels as this token and the corresponding fields are equal, as determined by the equals method of the contained tokens.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        object - An instance of Object.
        Returns:
        True if the argument is equal to this token.
        See Also:
        hashCode()

      • get

        public Token get​(java.lang.String label)
        Return the token with the specified label. If this token does not contain the specified label, return null.
        Parameters:
        label - A String label.
        Returns:
        A Token.

      • getType

        public Type getType()
        Return the type of this token.
        Overrides:
        getType in class Token
        Returns:
        An instance of RecordType.

      • hashCode

        public int hashCode()
        Return a hash code value for this token. This method returns the sum of the hash codes of the element tokens.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        A hash code value for this token.

      • labelSet

        public java.util.Set<java.lang.String> labelSet()
        Return the labels of this token as a Set.
        Returns:
        A Set containing labels.

      • length

        public int length()
        Return the length of this token.
        Returns:
        The length of this token, which is greater than or equal to zero.

      • merge

        public static RecordToken merge​(RecordToken token1,
                                RecordToken token2)
        Return a new token created by merging the two specified tokens, where preference is given to the first token when field labels are the same.
        Parameters:
        token1 - The higher priority record token.
        token2 - The lower priority record token.
        Returns:
        A new RecordToken.

      • mergeReturnType

        public static Type mergeReturnType​(Type type1,
                                   Type type2)
        Return the (exact) return type of the merge function above. If the arguments are both record type, then return a record type that contains all of the fields (and types) of the first record, and all of the fields of the second record that are not in the first record, otherwise return BaseType.UNKNOWN.
        Parameters:
        type1 - The type of the first argument to the corresponding function.
        type2 - The type of the second argument to the corresponding function.
        Returns:
        The type of the value returned from the corresponding function.

      • one

        public Token one()
          throws IllegalActionException
        Returns a new RecordToken representing the multiplicative identity. The returned token has the same set of labels as this one, and each field contains the multiplicative identity of the corresponding field of this token.
        Overrides:
        one in class Token
        Returns:
        A RecordToken.
        Throws:
        IllegalActionException - If multiplicative identity is not supported by any element token.

      • toString

        public java.lang.String toString()
        Return the value of this token as a string. The syntax is similar to the ML record: {label = value, label = value, ...} The record fields are listed in the lexicographical order of the labels determined by the java.lang.String.compareTo() method.

        Record labels that contain any non-Java identifier characters or contain only numbers are surrounded with double quotes. Quotes within label strings are escaped using a backslash.

        Overrides:
        toString in class Token
        Returns:
        A String beginning with "{" that contains label and value pairs separated by commas, ending with "}".

      • zero

        public Token zero()
           throws IllegalActionException
        Returns a new RecordToken representing the additive identity. The returned token has the same set of labels as this one, and each field contains the additive identity of the corresponding field of this token.
        Overrides:
        zero in class Token
        Returns:
        A RecordToken.
        Throws:
        IllegalActionException - If additive identity is not supported by any element token.

      • _add

        protected Token _add​(Token rightArgument)
              throws IllegalActionException
        Return a new token whose value is the field-wise addition of this token and the argument. It is assumed that the class of the argument is RecordToken.
        Specified by:
        _add in class AbstractNotConvertibleToken
        Parameters:
        rightArgument - The token to add to this token.
        Returns:
        A new RecordToken.
        Throws:
        IllegalActionException - If calling the add method on one of the record fields throws it.

      • _divide

        protected Token _divide​(Token rightArgument)
                 throws IllegalActionException
        Return a new token whose value is the field-wise division of this token and the argument. It is assumed that the class of the argument is RecordToken.
        Specified by:
        _divide in class AbstractNotConvertibleToken
        Parameters:
        rightArgument - The token to divide this token by.
        Returns:
        A new RecordToken.
        Throws:
        IllegalActionException - If calling the divide method on one of the record fields throws it.

      • _isCloseTo

        protected BooleanToken _isCloseTo​(Token rightArgument,
                                  double epsilon)
                           throws IllegalActionException
        Test whether the value of this token is close to the first argument, where "close" means that the distance between them is less than or equal to the second argument. This method only makes sense for tokens where the distance between them is reasonably represented as a double. It is assumed that the argument is an RecordToken, and the isCloseTo() method of the fields is used. If the fields do not match, then the return value is false.
        Specified by:
        _isCloseTo in class AbstractNotConvertibleToken
        Parameters:
        rightArgument - The token to compare to this token.
        epsilon - The value that we use to determine whether two tokens are close.
        Returns:
        A token containing true if the value of the first argument is close to the value of this token.
        Throws:
        IllegalActionException - If throw while checking the closeness of an element of the record.

      • _isEqualTo

        protected BooleanToken _isEqualTo​(Token rightArgument)
                           throws IllegalActionException
        Return true if the specified token is equal to this one. Equal means that both tokens have the same labels with the same values. This method is different from equals() in that _isEqualTo() looks for equalities of values irrespective of their types. It is assumed that the type of the argument is RecordToken.
        Overrides:
        _isEqualTo in class AbstractNotConvertibleToken
        Parameters:
        rightArgument - The token to compare to this token.
        Returns:
        True if the argument is equal to this.
        Throws:
        IllegalActionException - If this method is not supported by the derived class.

      • _modulo

        protected Token _modulo​(Token rightArgument)
                 throws IllegalActionException
        Return a new token whose value is the field-wise modulo of this token and the argument. It is assumed that the class of the argument is RecordToken.
        Specified by:
        _modulo in class AbstractNotConvertibleToken
        Parameters:
        rightArgument - The token to modulo this token by.
        Returns:
        A new RecordToken.
        Throws:
        IllegalActionException - If calling the modulo method on one of the record fields throws it.

      • _multiply

        protected Token _multiply​(Token rightArgument)
                   throws IllegalActionException
        Return a new token whose value is the field-wise multiplication of this token and the argument. It is assumed that the class of the argument is RecordToken.
        Specified by:
        _multiply in class AbstractNotConvertibleToken
        Parameters:
        rightArgument - The token to multiply this token by.
        Returns:
        A new RecordToken.
        Throws:
        IllegalActionException - If calling the multiply method on one of the record fields throws it.

      • _subtract

        protected Token _subtract​(Token rightArgument)
                   throws IllegalActionException
        Return a new token whose value is the field-wise subtraction of this token and the argument. It is assumed that the class of the argument is RecordToken.
        Specified by:
        _subtract in class AbstractNotConvertibleToken
        Parameters:
        rightArgument - The token to subtract from this token.
        Returns:
        A new RecordToken.
        Throws:
        IllegalActionException - If calling the subtract method on one of the record fields throws it.

      • _initializeStorage

        protected void _initializeStorage()
        Subclasses of RecordToken may choose a different Map implementation TreeMap is used in the base class to provide naturally-ordered labels This may not be desired in some applications.

      • _createRecordToken

        protected RecordToken _createRecordToken​(java.lang.String[] labels,
                                         Token[] values)
                                  throws IllegalActionException
        Create a new RecordToken. Subclasses of RecordToken may return a different subclass instance.
        Parameters:
        labels - An array of String labels for the RecordToken to be created.
        values - An array of Token values for the RecordToken to be created.
        Returns:
        a new RecordToken.
        Throws:
        IllegalActionException - If thrown while constructing the RecordToken

      • _createSet

        protected java.util.Set<java.lang.String> _createSet()
        Create a Set implementation appropriate for operations on this RecordToken Subclasses of RecordToken may return a different implementation.
        Returns:
        a new Set.