ptolemy.data

Class RecordToken

java.lang.Object

ptolemy.data.Token

ptolemy.data.AbstractNotConvertibleToken

ptolemy.data.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: RecordToken.java 70398 2014-10-22 23:44:32Z cxh $

Author:

Yuhong Xiong, Steve Neuendorffer, Elaine Cheong, Edward Lee; contributors: J. S. Senecal, Marten Lohstroh

Accepted Rating:

Yellow (cxh)

Proposed Rating:

Green (neuendor)

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.Map<java.lang.String,Token>	_fields The map of fields that has keys of type String and values of type token.
static RecordToken	EMPTY_RECORD Empty Record.

Fields inherited from class ptolemy.data.Token

NIL

Constructor Summary

Constructors

Constructor and Description
RecordToken() Construct a RecordToken with no fields.
RecordToken(java.util.Map<java.lang.String,Token> fieldMap) Construct a RecordToken with the labels and values specified by a given Map object.
RecordToken(java.lang.String init) Construct a RecordToken from the specified string.
RecordToken(java.lang.String[] labels, Token[] values) Construct a RecordToken with the specified labels and values.

Method Summary

Modifier and Type	Method and Description
protected Token	_add(Token rightArgument) Return a new token whose value is the field-wise addition of this token and the argument.
protected RecordToken	_createRecordToken(java.lang.String[] labels, Token[] values) Create a new RecordToken.
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.
protected Token	_divide(Token rightArgument) Return a new token whose value is the field-wise division of this token and the argument.
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.
protected BooleanToken	_isCloseTo(Token rightArgument, double epsilon) 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.
protected BooleanToken	_isEqualTo(Token rightArgument) Return true if the specified token is equal to this one.
protected Token	_modulo(Token rightArgument) Return a new token whose value is the field-wise modulo of this token and the argument.
protected Token	_multiply(Token rightArgument) Return a new token whose value is the field-wise multiplication of this token and the argument.
protected Token	_subtract(Token rightArgument) Return a new token whose value is the field-wise subtraction of this token and the argument.
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.
Token	get(java.lang.String label) Return the token with the specified label.
Type	getType() Return the type of this token.
int	hashCode() Return a hash code value for this token.
java.util.Set<java.lang.String>	labelSet() Return the labels of this token as a Set.
int	length() Return the length of this token.
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.
static Type	mergeReturnType(Type type1, Type type2) Return the (exact) return type of the merge function above.
Token	one() Returns a new RecordToken representing the multiplicative identity.
java.lang.String	toString() Return the value of this token as a string.
Token	zero() Returns a new RecordToken representing the additive identity.

Methods inherited from class ptolemy.data.AbstractNotConvertibleToken

add, addReverse, divide, divideReverse, isCloseTo, isEqualTo, modulo, moduloReverse, multiply, multiplyReverse, notSupportedDifferentClassesMessage, subtract, subtractReverse

Methods inherited from class ptolemy.data.Token

isCloseTo, isNil, notSupportedConversionMessage, notSupportedIncomparableConversionMessage, notSupportedIncomparableMessage, notSupportedMessage, notSupportedNullNilStringMessage, pow, zeroReturnType

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

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 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.