com.google.javascript.rhino.jstype

Class UnionType

java.lang.Object

com.google.javascript.rhino.jstype.JSType

com.google.javascript.rhino.jstype.UnionType

All Implemented Interfaces:

Serializable

public class UnionType
extends JSType

The UnionType implements a common JavaScript idiom in which the code is specifically designed to work with multiple input types. Because JavaScript always knows the run-time type of an object value, this is safer than a C union.

For instance, values of the union type (String,boolean) can be of type String or of type boolean. The commutativity of the statement is captured by making (String,boolean) and (boolean,String) equal.

The implementation of this class prevents the creation of nested unions.

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class com.google.javascript.rhino.jstype.JSType

JSType.TypePair

Field Summary

Fields inherited from class com.google.javascript.rhino.jstype.JSType

EMPTY_TYPE_COMPONENT, ENUMDECL, NOT_A_CLASS, NOT_A_TYPE, NOT_ENUMDECL, templateTypeMap, UNKNOWN_NAME

Method Summary

Methods

Modifier and Type	Method and Description
JSType	autobox() Dereference a type for property access.
boolean	canBeCalled() This predicate is used to test whether a given type can be used as the 'function' in a function call.
JSType	collapseUnion() Gets the least supertype of this that's not a union.
boolean	contains(JSType type) A UnionType contains a given type (alternate) iff the member vector contains it.
JSType	findPropertyType(String propertyName) Coerces this type to an Object type, then gets the type of the property whose name is given.
Collection<JSType>	getAlternates() Gets the alternate types of this union type.
JSType	getLeastSupertype(JSType that) Gets the least supertype of this and that.
BooleanLiteralSet	getPossibleToBooleanOutcomes() Computes the set of possible outcomes of the ToBoolean predicate for this type.
JSType	getRestrictedTypeGivenToBooleanOutcome(boolean outcome) Computes the restricted type of this type knowing that the ToBoolean predicate has a specific value.
JSType	getRestrictedUnion(JSType type) Returns a more restricted union type than this one, in which all subtypes of type have been removed.
JSType.TypePair	getTypesUnderEquality(JSType that) Computes the subset of this and that types if equality is observed.
JSType.TypePair	getTypesUnderInequality(JSType that) Computes the subset of this and that types if inequality is observed.
JSType.TypePair	getTypesUnderShallowInequality(JSType that) Computes the subset of this and that types under shallow inequality.
boolean	hasAnyTemplateTypesInternal()
int	hashCode()
boolean	hasProperty(String pname) Checks whether the property is present on the object.
boolean	isDict() Returns true iff this can be a dict.
boolean	isNullable() This predicate determines whether objects of this type can have the null value, and therefore can appear in contexts where null is expected.
boolean	isObject() Tests whether this type is an Object, or any subtype thereof.
boolean	isStruct() Returns true iff this can be a struct.
boolean	isSubtype(JSType that) Checks whether this is a subtype of that.
boolean	isUnknownType()
void	matchConstraint(JSType constraint) Modify this type so that it matches the specified type.
boolean	matchesNumberContext() This predicate is used to test whether a given type can appear in a numeric context, such as an operand of a multiply operator.
boolean	matchesObjectContext() This predicate is used to test whether a given type can appear in an Object context, such as the expression in a with statement.
boolean	matchesStringContext() This predicate is used to test whether a given type can appear in a String context, such as an operand of a string concat (+) operator.
JSType	restrictByNotNullOrUndefined() If this is a union type, returns a union type that does not include the null or undefined type.
boolean	setValidator(com.google.common.base.Predicate<JSType> validator) Certain types have constraints on them at resolution-time.
TernaryValue	testForEquality(JSType that) Compares this and that.
String	toDebugHashCodeString() A hash code function for diagnosing complicated issues around type-identity.
UnionType	toMaybeUnionType() Downcasts this to a UnionType, or returns null if this is not a UnionType.
<T> T	visit(Visitor<T> visitor) Visit this type with the given visitor.

Methods inherited from class com.google.javascript.rhino.jstype.JSType

autoboxesTo, canCastTo, canTestForEqualityWith, canTestForShallowEqualityWith, clearResolved, dereference, differsFrom, equals, extendTemplateTypeMap, getDisplayName, getGreatestSubtype, getJSDocInfo, getTemplateTypeMap, getTypesUnderShallowEquality, hasAnyTemplateTypes, hasDisplayName, isAllType, isArrayType, isBooleanObjectType, isBooleanValueType, isCheckedUnknownType, isConstructor, isDateType, isEmptyType, isEnumElementType, isEnumType, isEquivalent, isEquivalentTo, isFunctionPrototypeType, isFunctionType, isGlobalThisType, isInstanceType, isInterface, isInvariant, isNominalConstructor, isNominalType, isNoObjectType, isNoResolvedType, isNoType, isNullType, isNumber, isNumberObjectType, isNumberValueType, isOrdinaryFunction, isRecordType, isRegexpType, isResolved, isString, isStringObjectType, isStringValueType, isTemplateType, isTemplatizedType, isUnionType, isVoidType, matchesInt32Context, matchesUint32Context, resolve, toAnnotationString, toMaybeEnumElementType, toMaybeEnumType, toMaybeFunctionType, toMaybeFunctionType, toMaybeTemplateType, toMaybeTemplateType, toMaybeTemplatizedType, toMaybeTemplatizedType, toObjectType, toString, unboxesTo

Methods inherited from class java.lang.Object

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

Method Detail

getAlternates

public Collection<JSType> getAlternates()

Gets the alternate types of this union type.

Returns:

The alternate types of this union type. The returned set is immutable.

matchesNumberContext

public boolean matchesNumberContext()

This predicate is used to test whether a given type can appear in a numeric context, such as an operand of a multiply operator.

Overrides:

matchesNumberContext in class JSType

Returns:

true if the type can appear in a numeric context.

matchesStringContext

public boolean matchesStringContext()

This predicate is used to test whether a given type can appear in a String context, such as an operand of a string concat (+) operator.

All types have at least the potential for converting to String. When we add externally defined types, such as a browser OM, we may choose to add types that do not automatically convert to String.

Overrides:

matchesStringContext in class JSType

Returns:

true if not VoidType

matchesObjectContext

public boolean matchesObjectContext()

This predicate is used to test whether a given type can appear in an Object context, such as the expression in a with statement.

Most types we will encounter, except notably null, have at least the potential for converting to Object. Host defined objects can get peculiar.

VOID type is included here because while it is not part of the JavaScript language, functions returning 'void' type can't be used as operands of any operator or statement.

Overrides:

matchesObjectContext in class JSType

Returns:

true if the type is not NullType or VoidType

findPropertyType

public JSType findPropertyType(String propertyName)

Description copied from class: JSType

Coerces this type to an Object type, then gets the type of the property whose name is given. Unlike ObjectType.getPropertyType(java.lang.String), returns null if the property is not found.

Overrides:

findPropertyType in class JSType

Returns:

The property's type. null if the current type cannot have properties, or if the type is not found.

canBeCalled

public boolean canBeCalled()

Description copied from class: JSType

This predicate is used to test whether a given type can be used as the 'function' in a function call.

Overrides:

canBeCalled in class JSType

Returns:

true if this type might be callable.

autobox

public JSType autobox()

Description copied from class: JSType

Dereference a type for property access. Filters null/undefined and autoboxes the resulting type. Never returns null.

Overrides:

autobox in class JSType

restrictByNotNullOrUndefined

public JSType restrictByNotNullOrUndefined()

Description copied from class: JSType

If this is a union type, returns a union type that does not include the null or undefined type.

Overrides:

restrictByNotNullOrUndefined in class JSType

testForEquality

public TernaryValue testForEquality(JSType that)

Description copied from class: JSType

Compares this and that.

Overrides:

testForEquality in class JSType

Returns:

• TernaryValue.TRUE if the comparison of values of this type and that always succeed (such as undefined compared to null)
• TernaryValue.FALSE if the comparison of values of this type and that always fails (such as undefined compared to number)
• TernaryValue.UNKNOWN if the comparison can succeed or fail depending on the concrete values

isNullable

public boolean isNullable()

This predicate determines whether objects of this type can have the null value, and therefore can appear in contexts where null is expected.

Overrides:

isNullable in class JSType

Returns:

true for everything but Number and Boolean types.

isUnknownType

public boolean isUnknownType()

Overrides:

isUnknownType in class JSType

isStruct

public boolean isStruct()

Description copied from class: JSType

Returns true iff this can be a struct. UnionType overrides the method, assume this is not a union here.

Overrides:

isStruct in class JSType

isDict

public boolean isDict()

Description copied from class: JSType

Returns true iff this can be a dict. UnionType overrides the method, assume this is not a union here.

Overrides:

isDict in class JSType

getLeastSupertype

public JSType getLeastSupertype(JSType that)

Description copied from class: JSType

Gets the least supertype of this and that. The least supertype is the join (∨) or supremum of both types in the type lattice.

Examples:

• number ∨ * = *
• number ∨ Object = (number, Object)
• Number ∨ Object = Object

Overrides:

getLeastSupertype in class JSType

Returns:

this ∨ that

hasProperty

public boolean hasProperty(String pname)

Description copied from class: JSType

Checks whether the property is present on the object.

Overrides:

hasProperty in class JSType

Parameters:

pname - The property name.

hashCode

public int hashCode()

Overrides:

hashCode in class JSType

toMaybeUnionType

public UnionType toMaybeUnionType()

Description copied from class: JSType

Downcasts this to a UnionType, or returns null if this is not a UnionType. Named in honor of Haskell's Maybe type constructor.

Overrides:

toMaybeUnionType in class JSType

isObject

public boolean isObject()

Description copied from class: JSType

Tests whether this type is an Object, or any subtype thereof.

Overrides:

isObject in class JSType

Returns:

this <: Object

contains

public boolean contains(JSType type)

A UnionType contains a given type (alternate) iff the member vector contains it.

Parameters:

type - The alternate which might be in this union.

Returns:

true if the alternate is in the union

getRestrictedUnion

public JSType getRestrictedUnion(JSType type)

Returns a more restricted union type than this one, in which all subtypes of type have been removed.

Examples:

• (number,string) restricted by number is string
• (null, EvalError, URIError) restricted by Error is null

Parameters:

type - the supertype of the types to remove from this union type

isSubtype

public boolean isSubtype(JSType that)

Description copied from class: JSType

Checks whether this is a subtype of that.

Subtyping rules:

• (unknown) — every type is a subtype of the Unknown type.
• (no) — the No type is a subtype of every type.
• (no-object) — the NoObject type is a subtype of every object type (i.e. subtypes of the Object type).
• (ref) — a type is a subtype of itself.
• (union-l) — A union type is a subtype of a type U if all the union type's constituents are a subtype of U. Formally
  (T<sub>1</sub>, &hellip;, T<sub>n</sub>) &lt;: U if and only T<sub>k</sub> &lt;: U for all k ∈ 1..n.
• (union-r) — A type U is a subtype of a union type if it is a subtype of one of the union type's constituents. Formally
  U &lt;: (T<sub>1</sub>, &hellip;, T<sub>n</sub>) if and only if U &lt;: T<sub>k</sub> for some index k.
• (objects) — an Object O<sub>1</sub> is a subtype of an object O<sub>2</sub> if it has more properties than O<sub>2</sub> and all common properties are pairwise subtypes.

Overrides:

isSubtype in class JSType

Returns:

this <: that

getRestrictedTypeGivenToBooleanOutcome

public JSType getRestrictedTypeGivenToBooleanOutcome(boolean outcome)

Description copied from class: JSType

Computes the restricted type of this type knowing that the ToBoolean predicate has a specific value. For more information about the ToBoolean predicate, see JSType.getPossibleToBooleanOutcomes().

Overrides:

getRestrictedTypeGivenToBooleanOutcome in class JSType

Parameters:

outcome - the value of the ToBoolean predicate

Returns:

the restricted type, or the Any Type if the underlying type could not have yielded this ToBoolean value TODO(user): Move this method to the SemanticRAI and use the visit method of types to get the restricted type.

getPossibleToBooleanOutcomes

public BooleanLiteralSet getPossibleToBooleanOutcomes()

Description copied from class: JSType

Computes the set of possible outcomes of the ToBoolean predicate for this type. The ToBoolean predicate is defined by the ECMA-262 standard, 3^rd edition. Its behavior for simple types can be summarized by the following table:

type	result
undefined	{false}
null	{false}
boolean	{true, false}
number	{true, false}
string	{true, false}
Object	{true}

Specified by:

getPossibleToBooleanOutcomes in class JSType

Returns:

the set of boolean literals for this type

getTypesUnderEquality

public JSType.TypePair getTypesUnderEquality(JSType that)

Description copied from class: JSType

Computes the subset of this and that types if equality is observed. If a value v1 of type null is equal to a value v2 of type (undefined,number), we can infer that the type of v1 is null and the type of v2 is undefined.

Overrides:

getTypesUnderEquality in class JSType

Returns:

a pair containing the restricted type of this as the first component and the restricted type of that as the second element. The returned pair is never null even though its components may be null

getTypesUnderInequality

public JSType.TypePair getTypesUnderInequality(JSType that)

Description copied from class: JSType

Computes the subset of this and that types if inequality is observed. If a value v1 of type number is not equal to a value v2 of type (undefined,number), we can infer that the type of v1 is number and the type of v2 is number as well.

Overrides:

getTypesUnderInequality in class JSType

Returns:

a pair containing the restricted type of this as the first component and the restricted type of that as the second element. The returned pair is never null even though its components may be null

getTypesUnderShallowInequality

public JSType.TypePair getTypesUnderShallowInequality(JSType that)

Description copied from class: JSType

Computes the subset of this and that types under shallow inequality.

Overrides:

getTypesUnderShallowInequality in class JSType

Returns:

A pair containing the restricted type of this as the first component and the restricted type of that as the second element. The returned pair is never null even though its components may be null

visit

public <T> T visit(Visitor<T> visitor)

Description copied from class: JSType

Visit this type with the given visitor.

Specified by:

visit in class JSType

Returns:

the value returned by the visitor

See Also:

Visitor

toDebugHashCodeString

public String toDebugHashCodeString()

Description copied from class: JSType

A hash code function for diagnosing complicated issues around type-identity.

Overrides:

toDebugHashCodeString in class JSType

setValidator

public boolean setValidator(com.google.common.base.Predicate<JSType> validator)

Description copied from class: JSType

Certain types have constraints on them at resolution-time. For example, a type in an @extends annotation must be an object. Clients should inject a validator that emits a warning if the type does not validate, and return false.

Overrides:

setValidator in class JSType

collapseUnion

public JSType collapseUnion()

Description copied from class: JSType

Gets the least supertype of this that's not a union.

Overrides:

collapseUnion in class JSType

matchConstraint

public void matchConstraint(JSType constraint)

Description copied from class: JSType

Modify this type so that it matches the specified type. This is useful for reverse type-inference, where we want to infer that an object literal matches its constraint (much like how the java compiler does reverse-inference to figure out generics).

Overrides:

matchConstraint in class JSType

hasAnyTemplateTypesInternal

public boolean hasAnyTemplateTypesInternal()