Type (API documentation of hlt.language packages)
Date: 2013-01-30

hlt.language.design.types

## Class Type

- java.lang.Object
- - hlt.language.design.types.Type

- All Implemented Interfaces:
    Valuable
  Direct Known Subclasses:
    ProtoType, StaticType

      public abstract class Type
      extends java.lang.Object
      implements Valuable

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static byte` | `ARRAY`
    `static byte` | `BAG`
    `static TypeConstant` | `BOOLEAN`
    `static byte` | `BOXABLE`
    `static TypeConstant` | `CHAR`
    `static byte` | `CLASS`
    `static byte` | `COLLECTION`
    `static byte` | `CONSTANT`
    `static byte` | `DEFINED`
    `static byte` | `FUNCTION`
    `static TypeConstant` | `INT`
    `static TypeConstant` | `INT_RANGE`
    `static byte` | `INT_SORT`
    `static byte` | `LIST`
    `static byte` | `NAMED_TUPLE`
    `static byte` | `OBJECT_SORT`
    `static byte` | `PARAMETER`
    `static TypeConstant` | `REAL`
    `static TypeConstant` | `REAL_RANGE`
    `static byte` | `REAL_SORT`
    `static byte` | `SET`
    `static TypeConstant` | `STRING`
    `static byte` | `TUPLE`
    `static TypeConstant` | `VOID`
    `static byte` | `VOID_SORT`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Type()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Type` | `actualType()` Returns the value of this when this does not have a defining type; or that of its defining type otherwise.
    `ArrayType` | `array(Expression[] dimension)` Returns an array type of the specified dimension with this type as base type.
    `ArrayType` | `array(int dimension)` Returns an array type of the specified dimension number (with unspecified dimension types) with this type as base type.
    `Type` | `baseType()` Returns the value of this when this does not have a base type; or that of its base type otherwise.
    `Type` | `baseTypeRef()` Returns this when this does not have a base type; or the (undereferenced) base type otherwise.
    `static BoxableTypeConstant` | `BOOLEAN()` This creates and returns a new type for boolean that may be boxed by the compiler as the situation dictates.
    `static BoxableTypeConstant` | `BOXED_BOOLEAN()` This creates and returns a new type for boolean that may be unboxed by the compiler as the situation dictates.
    `static BoxableTypeConstant` | `BOXED_CHAR()` This creates and returns a new type for integers that may be unboxed by the compiler as the situation dictates.
    `static BoxableTypeConstant` | `BOXED_INT()` This creates and returns a new type for integers that may be unboxed by the compiler as the situation dictates.
    `static BoxableTypeConstant` | `BOXED_REAL()` This creates and returns a new type for real numbers that may be unboxed by the compiler as the situation dictates.
    `byte` | `boxSort()` This returns the runtime sort for this type unless this type has been marked as boxed - in which case it returns `OBJECT_SORT`.
    `static BoxableTypeConstant` | `CHAR()` This creates and returns a new type for characters that may be boxed by the compiler as the situation dictates.
    `void` | `checkOccurrence(TypeParameter parameter, Type context, TypeChecker typeChecker)` Throws a `FailedUnificationException` if the specified type parameter occurs in this type.
    `Type` | `copy()` Returns a copy of this type with an empty renaming.
    `Type` | `copy(java.util.HashMap parameters)` Returns a copy of this type with a consistent renaming of all free type parameters, and identyfing bound type parameters with their values.
    `void` | `curry(int depth, TypeChecker typeChecker)` If this this a function type, transforms the type by splitting the domains at the specified depth, and records the old form in the appropriate trail of the specified type-checker for undoing purposes.
    `abstract int` | `eqCode()` Returns a hash code for this type - the reason for using the name `eqCode` (rather than overriding `hashCode`), is that it is important to preserve the implementation of `java.lang.Object.hashCode` for type parameters (to be compatible with `==`).
    `boolean` | `equals(java.lang.Object object)`
    `Type` | `findValue()` This returns the type value this is bound to and side-effects the binding chains by shortening them (i.e., like the FIND operation of the UNION/FIND algorithm (returns itself by default - overridden by `TypeParameter`).
    `Type` | `flatten()` Returns a flattened form of this type by uncurrying all the domains of all function types that occur in it.
    `java.util.HashSet` | `getParameters()` Returns the set of unbound type parameters that occur in this type.
    `java.util.HashSet` | `getParameters(java.util.HashSet set)` Returns the specified set augmented with all the unbound type parameters that occur in this type.
    `Valuable` | `getValue()` This is identical to the `value` method but returns a `Valuable` as mandated as it implements this interface.
    `Type` | `instantiate(java.util.HashMap substitution)` Returns a copy of this type with all free type parameters bound as per the specified type substitution.
    `static BoxableTypeConstant` | `INT()` This creates and returns a new type for integers that may be boxed by the compiler as the situation dictates.
    `boolean` | `is(Type type)`
    `boolean` | `isBag()`
    `boolean` | `isBoolean()`
    `boolean` | `isBoxedType()` This returns `true` iff this type has been marked as boxed (`true` by default - overridden by `TypeConstant`).
    `boolean` | `isChar()`
    `boolean` | `isCollection()`
    `abstract boolean` | `isEqualTo(Type type)` Returns true iff this type is structurally isomorphic to the specified type.
    `abstract boolean` | `isEqualTo(Type type, java.util.HashMap parameters)` Returns true iff this type is structurally isomorphic to the specified type, under the renaming of type parameters specified by the given HashMap.
    `boolean` | `isGlobalUnsafe()` Returns `true` iff this type has a structure that may be modified internally at a place that has a polymorphic type.
    `boolean` | `isInt()`
    `boolean` | `isList()`
    `boolean` | `isPolymorphic()`
    `boolean` | `isPrimitive()`
    `boolean` | `isReal()`
    `boolean` | `isSet()`
    `boolean` | `isString()`
    `boolean` | `isVoid()`
    `abstract byte` | `kind()` This returns the value identifying what kind of type this is.
    `java.lang.String` | `kindString()` This returns the string describing the identifying kind this type.
    `abstract int` | `numberOfTypeComponents()` Returns the number of type components making up this type.
    `int` | `rank()` Returns an integer measuring the collection rank of this type.
    `static BoxableTypeConstant` | `REAL()` This creates and returns a new type for real numbers that may be boxed by the compiler as the situation dictates.
    `static void` | `resetNames()` Clears the names of parameters.
    `Type` | `setBoxed(boolean flag)` With `true` (resp.
    `abstract void` | `setTypeRefComponent(int n, Type type)` Sets the `n`-th undereferenced type component of this type to the specified type; throws a `NoSuchTypeComponentException` otherwise.
    `Type` | `shadowType()` This is used in `Homomorphism` for typing irregular monoid operations in the absence of a real mechanism for subtyping.
    `byte` | `sort()` This returns the runtime sort for this type (`OBJECT_SORT` by default - overridden by `TypeConstant`).
    `Type` | `standardize()` Returns a standard form for this type by creating a flattened copy where all free type parameters, if any, are renamed.
    `java.lang.String` | `toFullString()` N.B.: The following definition specifies only the default behavior for this method.
    `java.lang.String` | `toQuantifiedString()`
    `java.lang.String` | `toQuantifiedString(boolean full)` Returns a string for this type with an explicit header for universally quantified type parameters if there are any in this type.
    `Type` | `typeComponent(int n)` Returns the `n`-th derefenced type component in this type, if any; throws a `NoSuchTypeComponentException` otherwise.
    `abstract Type` | `typeRefComponent(int n)` Returns the `n`-th undereferenced type component in this type, if any; throws a `NoSuchTypeComponentException` otherwise.
    `abstract boolean` | `unify(Type type)` This unifies this type with the specified type with no possibility of undoing any effects.
    `abstract void` | `unify(Type type, TypeChecker typeChecker)` This unifies this type with the specified type in the context of the specified `TypeChecker`.
    `Expression` | `unwrapper()` This returns the built-in function that is appropriate for turning a boxed value with primitive type into that value.
    `Type` | `value()` This returns the type value this is bound to (itself by default - overridden by `TypeParameter`).
    `Expression` | `wrapper()` This returns the built-in function that is appropriate for turning a value with primitive type into an object.

    - ### Methods inherited from class java.lang.Object

      `getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### CONSTANT

          public static final byte CONSTANT

      See Also:
        Constant Field Values

    - #### BOXABLE

          public static final byte BOXABLE

      See Also:
        Constant Field Values

    - #### PARAMETER

          public static final byte PARAMETER

      See Also:
        Constant Field Values

    - #### FUNCTION

          public static final byte FUNCTION

      See Also:
        Constant Field Values

    - #### ARRAY

          public static final byte ARRAY

      See Also:
        Constant Field Values

    - #### TUPLE

          public static final byte TUPLE

      See Also:
        Constant Field Values

    - #### NAMED_TUPLE

          public static final byte NAMED_TUPLE

      See Also:
        Constant Field Values

    - #### SET

          public static final byte SET

      See Also:
        Constant Field Values

    - #### BAG

          public static final byte BAG

      See Also:
        Constant Field Values

    - #### LIST

          public static final byte LIST

      See Also:
        Constant Field Values

    - #### CLASS

          public static final byte CLASS

      See Also:
        Constant Field Values

    - #### COLLECTION

          public static final byte COLLECTION

      See Also:
        Constant Field Values

    - #### DEFINED

          public static final byte DEFINED

      See Also:
        Constant Field Values

    - #### VOID_SORT

          public static final byte VOID_SORT

      See Also:
        Constant Field Values

    - #### INT_SORT

          public static final byte INT_SORT

      See Also:
        Constant Field Values

    - #### REAL_SORT

          public static final byte REAL_SORT

      See Also:
        Constant Field Values

    - #### OBJECT_SORT

          public static final byte OBJECT_SORT

      See Also:
        Constant Field Values

    - #### VOID

          public static final TypeConstant VOID

    - #### INT

          public static final TypeConstant INT

    - #### REAL

          public static final TypeConstant REAL

    - #### CHAR

          public static final TypeConstant CHAR

    - #### BOOLEAN

          public static final TypeConstant BOOLEAN

    - #### STRING

          public static final TypeConstant STRING

    - #### INT_RANGE

          public static final TypeConstant INT_RANGE

    - #### REAL_RANGE

          public static final TypeConstant REAL_RANGE

  - ### Constructor Detail

    - #### Type

          public Type()

  - ### Method Detail

    - #### numberOfTypeComponents

          public abstract int numberOfTypeComponents()

      Returns the number of type components making up this type.

    - #### typeRefComponent

          public abstract Type typeRefComponent(int n)
                                         throws NoSuchTypeComponentException

      Returns the `n`-th undereferenced type component in this type, if any; throws a `NoSuchTypeComponentException` otherwise.
      Throws:
        `NoSuchTypeComponentException`

    - #### setTypeRefComponent

          public abstract void setTypeRefComponent(int n,
                                 Type type)
                                            throws NoSuchTypeComponentException

      Sets the `n`-th undereferenced type component of this type to the specified type; throws a `NoSuchTypeComponentException` otherwise.
      Throws:
        `NoSuchTypeComponentException`

    - #### typeComponent

          public final Type typeComponent(int n)
                                   throws NoSuchTypeComponentException

      Returns the `n`-th derefenced type component in this type, if any; throws a `NoSuchTypeComponentException` otherwise.
      Throws:
        `NoSuchTypeComponentException`

    - #### BOOLEAN

          public static final BoxableTypeConstant BOOLEAN()

      This creates and returns a new type for boolean that may be boxed by the compiler as the situation dictates.

    - #### INT

          public static final BoxableTypeConstant INT()

      This creates and returns a new type for integers that may be boxed by the compiler as the situation dictates.

    - #### REAL

          public static final BoxableTypeConstant REAL()

      This creates and returns a new type for real numbers that may be boxed by the compiler as the situation dictates.

    - #### CHAR

          public static final BoxableTypeConstant CHAR()

      This creates and returns a new type for characters that may be boxed by the compiler as the situation dictates.

    - #### BOXED_BOOLEAN

          public static final BoxableTypeConstant BOXED_BOOLEAN()

      This creates and returns a new type for boolean that may be unboxed by the compiler as the situation dictates.

    - #### BOXED_INT

          public static final BoxableTypeConstant BOXED_INT()

      This creates and returns a new type for integers that may be unboxed by the compiler as the situation dictates.

    - #### BOXED_REAL

          public static final BoxableTypeConstant BOXED_REAL()

      This creates and returns a new type for real numbers that may be unboxed by the compiler as the situation dictates.

    - #### BOXED_CHAR

          public static final BoxableTypeConstant BOXED_CHAR()

      This creates and returns a new type for integers that may be unboxed by the compiler as the situation dictates.

    - #### isCollection

          public final boolean isCollection()

    - #### isPrimitive

          public final boolean isPrimitive()

    - #### is

          public final boolean is(Type type)

    - #### isVoid

          public final boolean isVoid()

    - #### isBoolean

          public final boolean isBoolean()

    - #### isInt

          public final boolean isInt()

    - #### isReal

          public final boolean isReal()

    - #### isChar

          public final boolean isChar()

    - #### isString

          public final boolean isString()

    - #### isSet

          public final boolean isSet()

    - #### isBag

          public final boolean isBag()

    - #### isList

          public final boolean isList()

    - #### baseTypeRef

          public Type baseTypeRef()

      Returns this when this does not have a base type; or the (undereferenced) base type otherwise.

    - #### baseType

          public Type baseType()

      Returns the value of this when this does not have a base type; or that of its base type otherwise.

    - #### actualType

          public Type actualType()

      Returns the value of this when this does not have a defining type; or that of its defining type otherwise. This is overriden in `DefinedType`.

    - #### shadowType

          public Type shadowType()

      This is used in `Homomorphism` for typing irregular monoid operations in the absence of a real mechanism for subtyping. Returns this type's value by default. Only a `TypeConstant` may redefine its shadow type.

    - #### rank

          public final int rank()

      Returns an integer measuring the collection rank of this type. It is defined inductively as follows: it is equal to `0` for non-collection types; for a collection type with base type `T`, it is equal to `1` plus the rank of `T`.

    - #### array

          public final ArrayType array(Expression[] dimension)

      Returns an array type of the specified dimension with this type as base type.

    - #### array

          public final ArrayType array(int dimension)

      Returns an array type of the specified dimension number (with unspecified dimension types) with this type as base type.

    - #### isGlobalUnsafe

          public final boolean isGlobalUnsafe()

      Returns `true` iff this type has a structure that may be modified internally at a place that has a polymorphic type. Objects of such types should not be allowed to be defined globally since this may lead to unsafe typing. For example, if `a` is a globally defined polymorphic array of type `forall A . A[]`, then the type checker has no way of disallowing certain illegal situations such as `a[0] = true; a[1] = "foo";` because the two occurrences of the global name `a` have two different instances of its type. Note however that this pathology does not arise when `a` is a local array name, because it then refers to the same entity, and thus to a single type instance. In other words, for a polymorphic local `a`, the example given can thus be flagged as a type clash.

      A type will be unsafe for global definitions if it is:

      - a non-functional polymorphic type;
      - an array type whose base type is polymorphic or itself unsafe;
      - a tuple that has at least one component type that is polymorphic or itself unsafe;
      - a class type that is either not yet declared or has at least one field whose value type is polymorphic or itself unsafe.
      Note that this last criterion entails that a polymorphic class type may be safe, and that a non-polymorphic class type may not be so.

    - #### isPolymorphic

          public boolean isPolymorphic()

    - #### value

          public Type value()

      This returns the type value this is bound to (itself by default - overridden by `TypeParameter`).

    - #### findValue

          public Type findValue()

      This returns the type value this is bound to and side-effects the binding chains by shortening them (i.e., like the FIND operation of the UNION/FIND algorithm (returns itself by default - overridden by `TypeParameter`).

    - #### getValue

          public final Valuable getValue()

      This is identical to the `value` method but returns a `Valuable` as mandated as it implements this interface. It is never used on `Type` objects - only `value()` or `findValue()` are.
      Specified by:
        `getValue` in interface `Valuable`

    - #### sort

          public byte sort()

      This returns the runtime sort for this type (`OBJECT_SORT` by default - overridden by `TypeConstant`).

      N.B.: The following definition specifies only the default behavior for this method. Specific subclasses are generally expected to override this method.

    - #### boxSort

          public final byte boxSort()

      This returns the runtime sort for this type unless this type has been marked as boxed - in which case it returns `OBJECT_SORT`.

      N.B.: The following definition specifies only the default behavior for this method. Specific subclasses are generally expected to override this method.

    - #### wrapper

          public final Expression wrapper()

      This returns the built-in function that is appropriate for turning a value with primitive type into an object.

    - #### unwrapper

          public final Expression unwrapper()

      This returns the built-in function that is appropriate for turning a boxed value with primitive type into that value.

    - #### isBoxedType

          public boolean isBoxedType()

      This returns `true` iff this type has been marked as boxed (`true` by default - overridden by `TypeConstant`).

      N.B.: The following definition specifies only the default behavior for this method. Specific subclasses are generally expected to override this method.

    - #### setBoxed

          public Type setBoxed(boolean flag)

      With `true` (resp. `false`), this marks this type as boxed (resp., unboxed), if it is boxable. Does nothing by default.

      N.B.: The following definition specifies only the default behavior for this method. Specific subclasses are generally expected to override this method.

    - #### kind

          public abstract byte kind()

      This returns the value identifying what kind of type this is.

    - #### kindString

          public final java.lang.String kindString()

      This returns the string describing the identifying kind this type.

    - #### unify

          public abstract void unify(Type type,
                   TypeChecker typeChecker)
                              throws FailedUnificationException

      This unifies this type with the specified type in the context of the specified `TypeChecker`.
      Throws:
        `FailedUnificationException`

    - #### unify

          public abstract boolean unify(Type type)

      This unifies this type with the specified type with no possibility of undoing any effects. This method is meant to be used on types that are fresh copies independent of any type-checker because it will side-effect the structures it traverses. It returns `true` iff unification succeeds. NB: This method does not perform the "occurs-check" test.

    - #### checkOccurrence

          public void checkOccurrence(TypeParameter parameter,
                             Type context,
                             TypeChecker typeChecker)
                               throws FailedUnificationException

      Throws a `FailedUnificationException` if the specified type parameter occurs in this type. The type `context` is the outermost type enclosing this.

      N.B.: The following definition specifies only the default behavior for this method. Specific subclasses are generally expected to override this method.

      Throws:
        `FailedUnificationException`

    - #### curry

          public void curry(int depth,
                   TypeChecker typeChecker)

      If this this a function type, transforms the type by splitting the domains at the specified depth, and records the old form in the appropriate trail of the specified type-checker for undoing purposes. For example, currying A[1],...,A[n]n -> A at depth k (A[k+1],...,A[n] -> A). If this type is a type parameter, this will curry its value if any. Otherwise, does nothing.

      N.B.: The following definition specifies only the default behavior for this method. Specific subclasses are generally expected to override this method.

    - #### flatten

          public Type flatten()

      Returns a flattened form of this type by uncurrying all the domains of all function types that occur in it. It also trims all binding chains of type parameters that may occur in it. The form returned is the canonical form used for all types of defined symbols and is assumed for type equality tests to work.

      N.B.: The following definition specifies only the default behavior for this method. Specific subclasses are generally expected to override this method.

    - #### copy

          public Type copy(java.util.HashMap parameters)

      Returns a copy of this type with a consistent renaming of all free type parameters, and identyfing bound type parameters with their values.

      N.B.: The following definition specifies only the default behavior for this method. Specific subclasses are generally expected to override this method.

    - #### copy

          public Type copy()

      Returns a copy of this type with an empty renaming.

      N.B.: The following definition specifies only the default behavior for this method. Specific subclasses are generally expected to override this method.

    - #### instantiate

          public Type instantiate(java.util.HashMap substitution)

      Returns a copy of this type with all free type parameters bound as per the specified type substitution.

      N.B.: The following definition specifies only the default behavior for this method. Specific subclasses are generally expected to override this method.

    - #### standardize

          public final Type standardize()

      Returns a standard form for this type by creating a flattened copy where all free type parameters, if any, are renamed.

    - #### getParameters

          public java.util.HashSet getParameters(java.util.HashSet set)

      Returns the specified set augmented with all the unbound type parameters that occur in this type.

    - #### getParameters

          public final java.util.HashSet getParameters()

      Returns the set of unbound type parameters that occur in this type.

    - #### eqCode

          public abstract int eqCode()

      Returns a hash code for this type - the reason for using the name `eqCode` (rather than overriding `hashCode`), is that it is important to preserve the implementation of `java.lang.Object.hashCode` for type parameters (to be compatible with `==`). All we require with this new code is that it be compatible with type equality as defined by `isEqualTo` - and it is! Incidentally, the same reason goes for preserving `equals` for type parameters to be compatible with `==` - and it is (see `TypeParameter`).

    - #### equals

          public boolean equals(java.lang.Object object)

      Overrides:
        `equals` in class `java.lang.Object`

    - #### isEqualTo

          public abstract boolean isEqualTo(Type type)

      Returns true iff this type is structurally isomorphic to the specified type. Two type parameters will be considered equal only if they are the same object (i.e., equal pointers).

    - #### isEqualTo

          public abstract boolean isEqualTo(Type type,
                          java.util.HashMap parameters)

      Returns true iff this type is structurally isomorphic to the specified type, under the renaming of type parameters specified by the given HashMap.

    - #### resetNames

          public static final void resetNames()

      Clears the names of parameters.

    - #### toFullString

          public java.lang.String toFullString()

      N.B.: The following definition specifies only the default behavior for this method. Specific subclasses are generally expected to override this method.

    - #### toQuantifiedString

          public final java.lang.String toQuantifiedString(boolean full)

      Returns a string for this type with an explicit header for universally quantified type parameters if there are any in this type. If the specified boolean is true, the full string is quantified. If this contains free type parameters, they are gathered in an array in the canonical order of their appearance in the depth-first traversal of the type.

    - #### toQuantifiedString

          public final java.lang.String toQuantifiedString()