org.microbean.assign.SpecializationComparator Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of microbean-assign Show documentation
microBean™ Assign: Utility classes for implementing Java type assignment.
There is a newer version: 0.0.1
/* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
 *
 * Copyright © 2025 microBean™.
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
 * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
 * specific language governing permissions and limitations under the License.
 */
package org.microbean.assign;

import java.util.Comparator;
import java.util.Objects;

import javax.lang.model.type.TypeMirror;

import org.microbean.construct.Domain;

/**
 * A {@link Comparator} of {@link TypeMirror}s that establishes a partial order on its arguments, enforcing
 * only that more specialized types precede less specialized ones.
 *
 * Instances of this class are (deliberately) not consistent with equals.
 *
 * @author Laird Nelson
 *
 * @see #compare(TypeMirror, TypeMirror)
 */
public final class SpecializationComparator implements Comparator {

  private final Domain domain;

  /**
   * Creates a new {@link SpecializationComparator}.
   *
   * @param domain a {@link Domain}; must not be {@code null}
   *
   * @exception NullPointerException if {@code domain} is {@code null}
   */
  public SpecializationComparator(final Domain domain) {
    super();
    this.domain = Objects.requireNonNull(domain, "domain");
  }

  /**
   * Compares two {@link TypeMirror}s and returns the result.
   *
   * The following rules are evaluated in order to calculate the returned result:
   *
   * If {@code t} {@code ==} {@code s}, or {@linkplain Domain#sameType(TypeMirror, TypeMirror) t and
   * s are the same time}, returns {@code 0}.
   *
   * If {@code t} is {@code null} and {@code s} is not, returns a positive value.
   *
   * If {@code s} is {@code null} and {@code t} is not, returns a negative value.
   *
   * If {@code t} {@linkplain Domain#subtype(TypeMirror, TypeMirror) is a subtype of} {@code s}, returns a negative
   * value.
   *
   * If {@code s} {@linkplain Domain#subtype(TypeMirror, TypeMirror) is a subtype of} {@code t}, returns a positive
   * value.
   *
   * In all other cases {@code 0} is returned..
   *
   * @param t a {@link TypeMirror}; may be {@code null}
   *
   * @param s a {@link TypeMirror}; may be {@code null}
   *
   * @return a comparison result
   *
   * @see Domain#sameType(TypeMirror, TypeMirror)
   *
   * @see Domain#subtype(TypeMirror, TypeMirror)
   */
  @Override // Comparator
  public final int compare(final TypeMirror t, final TypeMirror s) {
    if (t == s) {
      return 0;
    } else if (t == null) {
      return 1; // nulls right
    } else if (s == null) {
      return -1; // nulls right
    } else if (domain.sameType(t, s)) {
      return 0;
    } else if (domain.subtype(t, s)) {
      // t is a subtype of s; s is a proper supertype of t
      return -1;
    } else if (domain.subtype(s, t)) {
      // s is a subtype of t; t is a proper supertype of s
      return 1;
    } else {
      return 0;
    }
  }

}