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.measure.Distance;
008import edu.wpi.first.units.measure.ImmutableDistance;
009import edu.wpi.first.units.measure.MutDistance;
010
011/**
012 * Unit of linear dimension.
013 *
014 * <p>This is the base type for units of linear dimension. It is also used to specify the dimension
015 * for {@link Measure}: <code>Measure&lt;DistanceUnit&gt;</code>.
016 *
017 * <p>Actual units (such as {@link Units#Meters} and {@link Units#Inches}) can be found in the
018 * {@link Units} class.
019 */
020public final class DistanceUnit extends Unit {
021  DistanceUnit(DistanceUnit baseUnit, double baseUnitEquivalent, String name, String symbol) {
022    super(baseUnit, baseUnitEquivalent, name, symbol);
023  }
024
025  DistanceUnit(
026      DistanceUnit baseUnit,
027      UnaryFunction toBaseConverter,
028      UnaryFunction fromBaseConverter,
029      String name,
030      String symbol) {
031    super(baseUnit, toBaseConverter, fromBaseConverter, name, symbol);
032  }
033
034  @Override
035  public DistanceUnit getBaseUnit() {
036    return (DistanceUnit) super.getBaseUnit();
037  }
038
039  @Override
040  public LinearVelocityUnit per(TimeUnit period) {
041    return LinearVelocityUnit.combine(this, period);
042  }
043
044  /**
045   * Creates a ratio unit between this unit and an arbitrary other unit.
046   *
047   * @param other the other unit
048   * @param <U> the type of the other unit
049   * @return the ratio unit
050   */
051  public <U extends Unit> PerUnit<DistanceUnit, U> per(U other) {
052    return PerUnit.combine(this, other);
053  }
054
055  /**
056   * Converts a measurement value in terms of another distance unit to this unit.
057   *
058   * @param magnitude the magnitude of the measurement in terms of the other distance unit
059   * @param otherUnit the other distance unit
060   * @return the value of the measurement in terms of this unit
061   */
062  public double convertFrom(double magnitude, DistanceUnit otherUnit) {
063    return fromBaseUnits(otherUnit.toBaseUnits(magnitude));
064  }
065
066  @Override
067  public Distance of(double magnitude) {
068    return new ImmutableDistance(magnitude, toBaseUnits(magnitude), this);
069  }
070
071  @Override
072  public Distance ofBaseUnits(double baseUnitMagnitude) {
073    return new ImmutableDistance(fromBaseUnits(baseUnitMagnitude), baseUnitMagnitude, this);
074  }
075
076  @Override
077  public Distance zero() {
078    return (Distance) super.zero();
079  }
080
081  @Override
082  public Distance one() {
083    return (Distance) super.one();
084  }
085
086  @Override
087  public MutDistance mutable(double initialMagnitude) {
088    return new MutDistance(initialMagnitude, toBaseUnits(initialMagnitude), this);
089  }
090
091  /**
092   * Multiplies this distance unit by a unit of force to create a unit of torque.
093   *
094   * @param force the unit of force
095   * @return the combined torque unit
096   */
097  public TorqueUnit multAsTorque(ForceUnit force) {
098    return TorqueUnit.combine(this, force);
099  }
100
101  // TODO: Add a multAsEnergy equivalent
102}