001// Copyright (c) FIRST and other WPILib contributors.
002// Open Source Software; you can modify and/or share it under the terms of
003// the WPILib BSD license file in the root directory of this project.
004
005package edu.wpi.first.units;
006
007import edu.wpi.first.units.collections.LongToObjectHashMap;
008import java.util.Objects;
009
010/**
011 * Generic combinatory unit type that represents the proportion of one unit to another, such as
012 * Meters per Second or Radians per Celsius.
013 *
014 * <p>Note: {@link Velocity} is used to represent the velocity dimension, rather than {@code
015 * Per<Distance, Time>}.
016 *
017 * @param <N> the type of the numerator unit
018 * @param <D> the type of the denominator unit
019 */
020public class Per<N extends Unit<N>, D extends Unit<D>> extends Unit<Per<N, D>> {
021  private final N m_numerator;
022  private final D m_denominator;
023
024  /**
025   * Keep a cache of created instances so expressions like Volts.per(Meter) don't do any allocations
026   * after the first.
027   */
028  @SuppressWarnings("rawtypes")
029  private static final LongToObjectHashMap<Per> cache = new LongToObjectHashMap<>();
030
031  /**
032   * Creates a new proportional unit derived from the ratio of one unit to another. Consider using
033   * {@link #combine} instead of manually calling this constructor.
034   *
035   * @param baseType the base type representing the unit ratio
036   * @param numerator the numerator unit
037   * @param denominator the denominator unit
038   */
039  protected Per(Class<Per<N, D>> baseType, N numerator, D denominator) {
040    super(
041        baseType,
042        numerator.toBaseUnits(1) / denominator.toBaseUnits(1),
043        numerator.name() + " per " + denominator.name(),
044        numerator.symbol() + "/" + denominator.symbol());
045    m_numerator = numerator;
046    m_denominator = denominator;
047  }
048
049  /**
050   * Creates a new Per unit derived from an arbitrary numerator and time denominator units. Using a
051   * denominator with a unit of time is discouraged; use {@link Velocity} instead.
052   *
053   * <pre>
054   *   Per.combine(Volts, Meters) // possible PID constant
055   * </pre>
056   *
057   * <p>It's recommended to use the convenience function {@link Unit#per(Unit)} instead of calling
058   * this factory directly.
059   *
060   * @param <N> the type of the numerator unit
061   * @param <D> the type of the denominator unit
062   * @param numerator the numerator unit
063   * @param denominator the denominator for unit time
064   * @return the combined unit
065   */
066  @SuppressWarnings({"unchecked", "rawtypes"})
067  public static <N extends Unit<N>, D extends Unit<D>> Per<N, D> combine(
068      N numerator, D denominator) {
069    final long key =
070        ((long) numerator.hashCode()) << 32L | (((long) denominator.hashCode()) & 0xFFFFFFFFL);
071
072    var existing = cache.get(key);
073    if (existing != null) {
074      return existing;
075    }
076
077    var newUnit = new Per<N, D>((Class) Per.class, numerator, denominator);
078    cache.put(key, newUnit);
079    return newUnit;
080  }
081
082  /**
083   * Gets the numerator unit. For a {@code Per<A, B>}, this will return the {@code A} unit.
084   *
085   * @return the numerator unit
086   */
087  public N numerator() {
088    return m_numerator;
089  }
090
091  /**
092   * Gets the denominator unit. For a {@code Per<A, B>}, this will return the {@code B} unit.
093   *
094   * @return the denominator unit
095   */
096  public D denominator() {
097    return m_denominator;
098  }
099
100  @Override
101  public boolean equals(Object o) {
102    if (this == o) {
103      return true;
104    }
105    if (o == null || getClass() != o.getClass()) {
106      return false;
107    }
108    if (!super.equals(o)) {
109      return false;
110    }
111    Per<?, ?> per = (Per<?, ?>) o;
112    return Objects.equals(m_numerator, per.m_numerator)
113        && Objects.equals(m_denominator, per.m_denominator);
114  }
115
116  @Override
117  public int hashCode() {
118    return Objects.hash(super.hashCode(), m_numerator, m_denominator);
119  }
120}