Package 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

Modifier and Type
Method
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, forceResolve, 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 Details

### 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 &#8744; *` = `*`
- `number &#8744; Object` = `(number, Object)`
- `Number &#8744; Object` = `Object`

Overrides:
  `getLeastSupertype` in class `JSType`
Returns:
  `this &#8744; 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 &lt;: 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 &isin; 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 &lt;: 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, 3rd 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`
Parameters:
  `constraint` -

### hasAnyTemplateTypesInternal

public boolean hasAnyTemplateTypesInternal()