ptolemy.data

Class StringToken

java.lang.Object

ptolemy.data.Token

ptolemy.data.AbstractConvertibleToken

ptolemy.data.StringToken

public class StringToken
extends AbstractConvertibleToken

A token that contains a string, or more specifically, a reference to an instance of String. The reference is never null, although it may be an empty string (""). Note that when this token is cloned, the clone will refer to exactly the same String object. However, a String object in Java is immutable, so there is no risk when two tokens refer to the same string that one of the strings will be changed.

Since:

Ptolemy II 0.2

Version:

$Id$

Author:

Edward A. Lee, Neil Smyth, Steve Neuendorffer, contributor: Christopher Brooks

Pt.AcceptedRating:

Red (cxh) nil token code

Pt.ProposedRating:

Yellow (cxh)

Field Summary

Fields

Modifier and Type	Field and Description
static StringToken	NIL A token that represents a missing value.

Constructor Summary

Constructors

Constructor and Description
StringToken() Construct a token with an empty string.
StringToken(java.lang.String value) Construct a token with the specified string.

Method Summary

Modifier and Type	Method and Description
protected Token	_add(Token rightArgument) Return a new token whose value is the value of the argument Token added to the value of this Token.
protected Token	_divide(Token rightArgument) Return a new token whose value is the value of this token divided by the value of the argument token.
protected BooleanToken	_isCloseTo(Token rightArgument, double epsilon) Test for closeness of the values of this Token and the argument Token.
protected BooleanToken	_isEqualTo(Token rightArgument) Test for equality of the values of this Token and the argument Token.
protected Token	_modulo(Token rightArgument) Return a new token whose value is the value of this token modulo the value of the argument token.
protected Token	_multiply(Token rightArgument) Return a new token whose value is the value of this token multiplied by the value of the argument token.
protected Token	_subtract(Token rightArgument) Return a new token whose value is the value of the argument token subtracted from the value of this token.
static StringToken	convert(Token token) Convert the specified token into an instance of StringToken.
boolean	equals(java.lang.Object object) Return true if the argument is an instance of StringToken with the same value.
Type	getType() Return the type of this token.
int	hashCode() Return a hash code value for this token.
boolean	isNil() Return true if the token is nil, (aka null or missing).
java.lang.String	stringValue() Return the string that this token contains.
java.lang.String	toString() Return the value of this Token as a string.
Token	zero() Return a StringToken containing an empty string, which is considered as the additive identity of string.

Methods inherited from class ptolemy.data.AbstractConvertibleToken

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

Methods inherited from class ptolemy.data.Token

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

Methods inherited from class java.lang.Object

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

Field Detail

NIL

public static final StringToken NIL

A token that represents a missing value. Null or missing tokens are common in analytical systems like R and SAS where they are used to handle sparsely populated data sources. In database parlance, missing tokens are sometimes called null tokens. Since null is a Java keyword, we use the term "nil". The toString() method on a nil token returns the string "nil".

Constructor Detail

StringToken

public StringToken()

Construct a token with an empty string.

StringToken

public StringToken(java.lang.String value)

Construct a token with the specified string. If the value argument is null then the empty string is created. If the value argument is the string "nil", then the Token is not a nil token it is the string "nil".

Parameters:

value - The specified string.

Method Detail

convert

public static StringToken convert(Token token)
                           throws IllegalActionException

Convert the specified token into an instance of StringToken. This method does lossless conversion. If the argument is already an instance of StringToken, it is returned without any change. If the argument is a nil token, then NIL is returned. Otherwise, if the argument is below StringToken in the type hierarchy, it is converted to an instance of StringToken or one of the subclasses of StringToken and returned. If none of the above condition is met, an exception is thrown.

Parameters:

token - The token to be converted to a StringToken.

Returns:

A StringToken

Throws:

IllegalActionException - If the conversion cannot be carried out.

equals

public boolean equals(java.lang.Object object)

Return true if the argument is an instance of StringToken with the same value.

Overrides:

equals in class java.lang.Object

Parameters:

object - An instance of Object.

Returns:

True if the argument is an IntToken with the same value. If either this object or the argument is nil, return false.

getType

public Type getType()

Return the type of this token.

Overrides:

getType in class Token

Returns:

BaseType.STRING

hashCode

public int hashCode()

Return a hash code value for this token. This method returns the hash code of the contained string.

Overrides:

hashCode in class java.lang.Object

Returns:

A hash code value for this token.

isNil

public boolean isNil()

Return true if the token is nil, (aka null or missing). Nil or missing tokens occur when a data source is sparsely populated.

Overrides:

isNil in class Token

Returns:

True if the token is the NIL token.

stringValue

public java.lang.String stringValue()

Return the string that this token contains. Note that this is different than the toString method, which returns a string expression that has double quotes around it.

Returns:

The contained string.

toString

public java.lang.String toString()

Return the value of this Token as a string. If the value of the Token contains double quotes, then a backslash is inserted before each double quote and then double quotes are added to the beginning and the end, indicating a string constant in the expression language.

Overrides:

toString in class Token

Returns:

A String.

zero

public Token zero()

Return a StringToken containing an empty string, which is considered as the additive identity of string.

Overrides:

zero in class Token

Returns:

A new StringToken containing an empty string.

_add

protected Token _add(Token rightArgument)
              throws IllegalActionException

Return a new token whose value is the value of the argument Token added to the value of this Token. It is assumed that the type of the argument is StringToken.

Specified by:

_add in class AbstractConvertibleToken

Parameters:

rightArgument - The token whose value we add to the value of this token.

Returns:

A new Token containing the result.

Throws:

IllegalActionException - If this method is not supported by the derived class.

_divide

protected Token _divide(Token rightArgument)
                 throws IllegalActionException

Return a new token whose value is the value of this token divided by the value of the argument token. It is assumed that the type of the argument is StringToken.

Specified by:

_divide in class AbstractConvertibleToken

Parameters:

rightArgument - The token to divide this token by.

Returns:

A new Token containing the result that is of the same class as this token.

Throws:

IllegalActionException - If this method is not supported by the derived class.

_isCloseTo

protected BooleanToken _isCloseTo(Token rightArgument,
                                  double epsilon)
                           throws IllegalActionException

Test for closeness of the values of this Token and the argument Token. It is assumed that the type of the argument is StringToken.

Specified by:

_isCloseTo in class AbstractConvertibleToken

Parameters:

rightArgument - The token to add to this token.

epsilon - The value that we use to determine whether two tokens are close. This parameter is ignored by this class.

Returns:

A BooleanToken containing the result.

Throws:

IllegalActionException - If this method is not supported by the derived class.

_isEqualTo

protected BooleanToken _isEqualTo(Token rightArgument)
                           throws IllegalActionException

Test for equality of the values of this Token and the argument Token. It is assumed that the type of the argument is StringToken.

Specified by:

_isEqualTo in class AbstractConvertibleToken

Parameters:

rightArgument - The token to add to this token.

Returns:

A BooleanToken containing the result.

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 value of this token modulo the value of the argument token. It is assumed that the type of the argument is StringToken.

Specified by:

_modulo in class AbstractConvertibleToken

Parameters:

rightArgument - The token to modulo this token by.

Returns:

A new Token containing the result that is of the same class as this token.

Throws:

IllegalActionException - If this method is not supported by the derived class.

_multiply

protected Token _multiply(Token rightArgument)
                   throws IllegalActionException

Return a new token whose value is the value of this token multiplied by the value of the argument token. It is assumed that the type of the argument is StringToken. classes to provide type specific actions for multiply.

Specified by:

_multiply in class AbstractConvertibleToken

Parameters:

rightArgument - The token to multiply this token by.

Returns:

A new Token containing the result that is of the same class as this token.

Throws:

IllegalActionException - If this method is not supported by the derived class.

_subtract

protected Token _subtract(Token rightArgument)
                   throws IllegalActionException

Return a new token whose value is the value of the argument token subtracted from the value of this token. It is assumed that the type of the argument is StringToken.

Specified by:

_subtract in class AbstractConvertibleToken

Parameters:

rightArgument - The token to subtract from this token.

Returns:

A new Token containing the result that is of the same class as this token.

Throws:

IllegalActionException - If this method is not supported by the derived class.