package org.checkerframework.framework.type;

import org.checkerframework.framework.util.AnnotatedTypes;

/** Compares AnnotatedTypeMirrors for subtype relationships. See also {@link QualifierHierarchy}. */
public interface TypeHierarchy {

  /**
   * Returns true if {@code subtype} is a subtype of or convertible to {@code supertype} for all
   * hierarchies present. If the underlying Java type of {@code subtype} is not a subtype of or
   * convertible to the underlying Java type of {@code supertype}, then the behavior of this method
   * is undefined.
   *
   * <p>Ideally, types that require conversions would be converted before isSubtype is called, but
   * instead, isSubtype performs some of these conversions.
   *
   * <p>JLS 5.1 specifies 13 categories of conversions.
   *
   * <p>4 categories are converted in isSubtype:
   *
   * <ul>
   *   <li>Boxing conversions: isSubtype calls {@link AnnotatedTypes#asSuper( AnnotatedTypeFactory,
   *       AnnotatedTypeMirror, AnnotatedTypeMirror)} which calls {@link
   *       AnnotatedTypeFactory#getBoxedType}
   *   <li>Unboxing conversions: isSubtype calls {@link AnnotatedTypes#asSuper(
   *       AnnotatedTypeFactory, AnnotatedTypeMirror, AnnotatedTypeMirror)} which calls {@link
   *       AnnotatedTypeFactory#getUnboxedType}
   *   <li>Capture conversions: Wildcards are treated as though they were converted to type
   *       variables
   *   <li>String conversions: Any type to String. isSubtype calls {@link AnnotatedTypes#asSuper}
   *       which calls {@link AnnotatedTypeFactory#getStringType(AnnotatedTypeMirror)}
   * </ul>
   *
   * 1 happens elsewhere:
   *
   * <ul>
   *   <li>Unchecked conversions: Generic type to raw type. Raw types are instantiated with bounds
   *       in AnnotatedTypeFactory#fromTypeTree before is subtype is called
   * </ul>
   *
   * 7 are not explicitly converted and are treated as though the types are actually subtypes.
   *
   * <ul>
   *   <li>Identity conversions: type to same type
   *   <li>Widening primitive conversions: primitive to primitive (no loss of information, byte to
   *       short for example)
   *   <li>Narrowing primitive conversions: primitive to primitive (possibly loss of information,
   *       short to byte for example)
   *   <li>Widening and Narrowing Primitive Conversion: byte to char
   *   <li>Widening reference conversions: Upcast
   *   <li>Narrowing reference conversions: Downcast
   *   <li>Value set conversions: floating-point value from one value set to another without
   *       changing its type.
   * </ul>
   *
   * @param subtype possible subtype
   * @param supertype possible supertype
   * @return true if {@code subtype} is a subtype of {@code supertype} for all hierarchies present.
   */
  boolean isSubtype(AnnotatedTypeMirror subtype, AnnotatedTypeMirror supertype);
}