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.Dimensionless;
008import edu.wpi.first.units.measure.ImmutableDimensionless;
009import edu.wpi.first.units.measure.MutDimensionless;
010
011/**
012 * A type of unit that corresponds to raw values and not any physical dimension, such as percentage.
013 */
014public final class DimensionlessUnit extends Unit {
015  /**
016   * Creates a new unit with the given name and multiplier to the base unit.
017   *
018   * @param baseUnitEquivalent the multiplier to convert this unit to the base unit of this type.
019   * @param name the name of the unit
020   * @param symbol the symbol of the unit
021   */
022  DimensionlessUnit(
023      DimensionlessUnit baseUnit, double baseUnitEquivalent, String name, String symbol) {
024    super(baseUnit, baseUnitEquivalent, name, symbol);
025  }
026
027  DimensionlessUnit(
028      DimensionlessUnit baseUnit,
029      UnaryFunction toBaseConverter,
030      UnaryFunction fromBaseConverter,
031      String name,
032      String symbol) {
033    super(baseUnit, toBaseConverter, fromBaseConverter, name, symbol);
034  }
035
036  @Override
037  public DimensionlessUnit getBaseUnit() {
038    return (DimensionlessUnit) super.getBaseUnit();
039  }
040
041  @Override
042  public Dimensionless of(double magnitude) {
043    return new ImmutableDimensionless(magnitude, toBaseUnits(magnitude), this);
044  }
045
046  @Override
047  public Dimensionless ofBaseUnits(double baseUnitMagnitude) {
048    return new ImmutableDimensionless(fromBaseUnits(baseUnitMagnitude), baseUnitMagnitude, this);
049  }
050
051  @Override
052  public Dimensionless zero() {
053    return (Dimensionless) super.zero();
054  }
055
056  @Override
057  public Dimensionless one() {
058    return (Dimensionless) super.one();
059  }
060
061  @Override
062  public MutDimensionless mutable(double initialMagnitude) {
063    return new MutDimensionless(initialMagnitude, toBaseUnits(initialMagnitude), this);
064  }
065
066  /**
067   * Converts a measurement value in terms of another dimensionless unit to this unit.
068   *
069   * @param magnitude the magnitude of the measurement in terms of the other dimensionless unit
070   * @param otherUnit the other dimensionless unit
071   * @return the value of the measurement in terms of this unit
072   */
073  public double convertFrom(double magnitude, DimensionlessUnit otherUnit) {
074    return fromBaseUnits(otherUnit.toBaseUnits(magnitude));
075  }
076
077  /**
078   * Creates a frequency unit as the ratio of this dimensionless unit to the period of time in which
079   * a single cycle is made.
080   *
081   * @param period the cycle period
082   * @return the combined frequency unit
083   */
084  @Override
085  public FrequencyUnit per(TimeUnit period) {
086    return FrequencyUnit.combine(this, period);
087  }
088
089  /**
090   * Creates a ratio unit between this unit and an arbitrary other unit.
091   *
092   * @param other the other unit
093   * @param <U> the type of the other unit
094   * @return the ratio unit
095   */
096  public <U extends Unit> PerUnit<DimensionlessUnit, U> per(U other) {
097    return PerUnit.combine(this, other);
098  }
099}