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.Acceleration;
008
009/**
010 * A generic unit of acceleration.
011 *
012 * <p><strong>NOTE:</strong> This type is not compatible with unit-specific accelerations like
013 * {@link edu.wpi.first.units.measure.LinearAcceleration}. Authors of APIs that need to interact
014 * with all types should consider using a generic {@code Measure<? extends PerUnit<? extends
015 * PerUnit<[dimension>], TimeUnit>, TimeUnit>}. Bounded wildcards are necessary in order to
016 * interoperate with <i>any</i> subclass of the {@link edu.wpi.first.units.measure.Per} measurement
017 * type.
018 *
019 * @param <D> the unit of the accelerating quantity
020 */
021public final class AccelerationUnit<D extends Unit> extends PerUnit<VelocityUnit<D>, TimeUnit> {
022  @SuppressWarnings({"rawtypes", "unchecked"})
023  private static final CombinatoryUnitCache<VelocityUnit, TimeUnit, AccelerationUnit> cache =
024      new CombinatoryUnitCache<>(AccelerationUnit::new);
025
026  AccelerationUnit(VelocityUnit<D> velocity, TimeUnit period) {
027    super(
028        velocity.isBaseUnit() && period.isBaseUnit()
029            ? null
030            : combine(velocity.getBaseUnit(), period.getBaseUnit()),
031        velocity,
032        period);
033  }
034
035  AccelerationUnit(
036      AccelerationUnit<D> baseUnit,
037      UnaryFunction toBaseConverter,
038      UnaryFunction fromBaseConverter,
039      String name,
040      String symbol) {
041    super(baseUnit, toBaseConverter, fromBaseConverter, name, symbol);
042  }
043
044  @Override
045  public Acceleration<D> of(double magnitude) {
046    return new Acceleration<>(magnitude, toBaseUnits(magnitude), this);
047  }
048
049  @Override
050  public Acceleration<D> ofBaseUnits(double baseUnitMagnitude) {
051    return new Acceleration<>(fromBaseUnits(baseUnitMagnitude), baseUnitMagnitude, this);
052  }
053
054  @Override
055  @SuppressWarnings({"unchecked", "rawtypes"})
056  public Acceleration<D> zero() {
057    return (Acceleration<D>) (Acceleration) super.zero();
058  }
059
060  @Override
061  @SuppressWarnings({"unchecked", "rawtypes"})
062  public Acceleration<D> one() {
063    return (Acceleration<D>) (Acceleration) super.one();
064  }
065
066  @Override
067  public VelocityUnit<AccelerationUnit<D>> per(TimeUnit time) {
068    return VelocityUnit.combine(this, time);
069  }
070
071  /**
072   * Creates a ratio unit between this unit and an arbitrary other unit.
073   *
074   * @param other the other unit
075   * @param <U> the type of the other unit
076   * @return the ratio unit
077   */
078  public <U extends Unit> PerUnit<AccelerationUnit<D>, U> per(U other) {
079    return PerUnit.combine(this, other);
080  }
081
082  /**
083   * Converts a measurement value in terms of another time unit to this unit.
084   *
085   * @param magnitude the magnitude of the measurement in terms of the other time unit
086   * @param otherUnit the other time unit
087   * @return the value of the measurement in terms of this unit
088   */
089  public double convertFrom(double magnitude, AccelerationUnit<D> otherUnit) {
090    return fromBaseUnits(otherUnit.toBaseUnits(magnitude));
091  }
092
093  /**
094   * Combines a generic velocity and time period into a unit of acceleration.
095   *
096   * @param velocity the unit of velocity
097   * @param period the unit of the time period of acceleration
098   * @param <D> the unit of the accelerating quantity
099   * @return the combined acceleration unit
100   */
101  @SuppressWarnings("unchecked")
102  public static <D extends Unit> AccelerationUnit<D> combine(
103      VelocityUnit<D> velocity, TimeUnit period) {
104    return cache.combine(velocity, period);
105  }
106}