001/*
002 * Units of Measurement API
003 * Copyright (c) 2014-2021, Jean-Marie Dautelle, Werner Keil, Otavio Santana.
004 *
005 * All rights reserved.
006 *
007 * Redistribution and use in source and binary forms, with or without modification,
008 * are permitted provided that the following conditions are met:
009 *
010 * 1. Redistributions of source code must retain the above copyright notice,
011 *    this list of conditions and the following disclaimer.
012 *
013 * 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions
014 *    and the following disclaimer in the documentation and/or other materials provided with the distribution.
015 *
016 * 3. Neither the name of JSR-385 nor the names of its contributors may be used to endorse or promote products
017 *    derived from this software without specific prior written permission.
018 *
019 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
020 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
021 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
022 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
023 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
024 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
025 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
026 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
027 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
028 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
029 */
030package javax.measure;
031
032/**
033 * Provides support for the 20 prefixes used in the metric system (decimal multiples and submultiples of units). For example:
034 *
035 * <pre>
036 * {@code
037 *     import static tech.units.indriya.unit.Units.*;  // Static import.
038 *     import static javax.measure.MetricPrefix.*; // Static import.
039 *     import javax.measure.*;
040 *     import javax.measure.quantity.*;
041 *     ...
042 *     Unit<Pressure> HECTOPASCAL = HECTO(PASCAL);
043 *     Unit<Length> KILOMETRE = KILO(METRE);}
044 * </pre>
045 *
046 * @see <a href="http://en.wikipedia.org/wiki/Metric_prefix">Wikipedia: Metric Prefix</a>
047 * @author <a href="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
048 * @author <a href="mailto:werner@units.tech">Werner Keil</a>
049 * @version 2.0, June 28, 2019
050 * @since 2.0
051 */
052public enum MetricPrefix implements Prefix {
053    /** Prefix for 10<sup>24</sup>. */
054    YOTTA("Y", 24),
055    /** Prefix for 10<sup>21</sup>. */
056    ZETTA("Z", 21),
057    /** Prefix for 10<sup>18</sup>. */
058    EXA("E", 18),
059    /** Prefix for 10<sup>15</sup>. */
060    PETA("P", 15),
061    /** Prefix for 10<sup>12</sup>. */
062    TERA("T", 12),
063    /** Prefix for 10<sup>9</sup>. */
064    GIGA("G", 9),
065    /** Prefix for 10<sup>6</sup>. */
066    MEGA("M", 6),
067    /** Prefix for 10<sup>3</sup>. */
068    KILO("k", 3),
069    /** Prefix for 10<sup>2</sup>. */
070    HECTO("h", 2),
071    /** Prefix for 10<sup>1</sup>. */
072    DEKA("da", 1),
073    /** Prefix for 10<sup>-1</sup>. */
074    DECI("d", -1),
075    /** Prefix for 10<sup>-2</sup>. */
076    CENTI("c", -2),
077    /** Prefix for 10<sup>-3</sup>. */
078    MILLI("m", -3),
079    /** Prefix for 10<sup>-6</sup>. */
080    MICRO("\u00b5", -6),
081    /** Prefix for 10<sup>-9</sup>. */
082    NANO("n", -9),
083    /** Prefix for 10<sup>-12</sup>. */
084    PICO("p", -12),
085    /** Prefix for 10<sup>-15</sup>. */
086    FEMTO("f", -15),
087    /** Prefix for 10<sup>-18</sup>. */
088    ATTO("a", -18),
089    /** Prefix for 10<sup>-21</sup>. */
090    ZEPTO("z", -21),
091    /** Prefix for 10<sup>-24</sup>. */
092    YOCTO("y", -24);
093
094    /**
095     * The symbol of this prefix, as returned by {@link #getSymbol}.
096     *
097     * @serial
098     * @see #getSymbol()
099     */
100    private final String symbol;
101
102    /**
103     * Exponent part of the associated factor in base^exponent representation.
104     */
105    private final int exponent;
106
107    /**
108     * Creates a new prefix.
109     *
110     * @param symbol
111     *          the symbol of this prefix.
112     * @param exponent
113     *          part of the associated factor in base^exponent representation.
114     */
115    private MetricPrefix(String symbol, int exponent) {
116        this.symbol = symbol;
117        this.exponent = exponent;
118    }
119
120    /**
121     * Returns the specified unit multiplied by the factor <code>10<sup>24</sup></code>
122     *
123     * @param <Q>
124     *          type of the quantity measured by the unit.
125     * @param unit
126     *          any unit.
127     * @return <code>unit.times(1e24)</code>.
128     */
129    public static <Q extends Quantity<Q>> Unit<Q> YOTTA(Unit<Q> unit) {
130        return unit.prefix(YOTTA);
131    }
132
133    /**
134     * Returns the specified unit multiplied by the factor <code>10<sup>21</sup></code>
135     *
136     * @param <Q>
137     *          type of the quantity measured by the unit.
138     * @param unit
139     *          any unit.
140     * @return <code>unit.times(1e21)</code>.
141     */
142    public static <Q extends Quantity<Q>> Unit<Q> ZETTA(Unit<Q> unit) {
143        return unit.prefix(ZETTA);
144    }
145
146    /**
147     * Returns the specified unit multiplied by the factor <code>10<sup>18</sup></code>
148     *
149     * @param <Q>
150     *          type of the quantity measured by the unit.
151     * @param unit
152     *          any unit.
153     * @return <code>unit.times(1e18)</code>.
154     */
155    public static <Q extends Quantity<Q>> Unit<Q> EXA(Unit<Q> unit) {
156        return unit.prefix(EXA);
157    }
158
159    /**
160     * Returns the specified unit multiplied by the factor <code>10<sup>15</sup></code>
161     *
162     * @param <Q>
163     *          type of the quantity measured by the unit.
164     * @param unit
165     *          any unit.
166     * @return <code>unit.times(1e15)</code>.
167     */
168    public static <Q extends Quantity<Q>> Unit<Q> PETA(Unit<Q> unit) {
169        return unit.prefix(PETA);
170    }
171
172    /**
173     * Returns the specified unit multiplied by the factor <code>10<sup>12</sup></code>
174     *
175     * @param <Q>
176     *          type of the quantity measured by the unit.
177     * @param unit
178     *          any unit.
179     * @return <code>unit.times(1e12)</code>.
180     */
181    public static <Q extends Quantity<Q>> Unit<Q> TERA(Unit<Q> unit) {
182        return unit.prefix(TERA);
183    }
184
185    /**
186     * Returns the specified unit multiplied by the factor <code>10<sup>9</sup></code>
187     *
188     * @param <Q>
189     *          type of the quantity measured by the unit.
190     * @param unit
191     *          any unit.
192     * @return <code>unit.times(1e9)</code>.
193     */
194    public static <Q extends Quantity<Q>> Unit<Q> GIGA(Unit<Q> unit) {
195        return unit.prefix(GIGA);
196    }
197
198    /**
199     * Returns the specified unit multiplied by the factor <code>10<sup>6</sup></code>
200     *
201     * @param <Q>
202     *          type of the quantity measured by the unit.
203     * @param unit
204     *          any unit.
205     * @return <code>unit.times(1e6)</code>.
206     */
207    public static <Q extends Quantity<Q>> Unit<Q> MEGA(Unit<Q> unit) {
208        return unit.prefix(MEGA);
209    }
210
211    /**
212     * Returns the specified unit multiplied by the factor <code>10<sup>3</sup></code>
213     *
214     * @param <Q>
215     *          type of the quantity measured by the unit.
216     * @param unit
217     *          any unit.
218     * @return <code>unit.times(1e3)</code>.
219     */
220    public static <Q extends Quantity<Q>> Unit<Q> KILO(Unit<Q> unit) {
221        return unit.prefix(KILO);
222    }
223
224    /**
225     * Returns the specified unit multiplied by the factor <code>10<sup>2</sup></code>
226     *
227     * @param <Q>
228     *          type of the quantity measured by the unit.
229     * @param unit
230     *          any unit.
231     * @return <code>unit.times(1e2)</code>.
232     */
233    public static <Q extends Quantity<Q>> Unit<Q> HECTO(Unit<Q> unit) {
234        return unit.prefix(HECTO);
235    }
236
237    /**
238     * Returns the specified unit multiplied by the factor <code>10<sup>1</sup></code>
239     *
240     * @param <Q>
241     *          type of the quantity measured by the unit.
242     * @param unit
243     *          any unit.
244     * @return <code>unit.times(1e1)</code>.
245     */
246    public static <Q extends Quantity<Q>> Unit<Q> DEKA(Unit<Q> unit) {
247        return unit.prefix(DEKA);
248    }
249
250    /**
251     * Returns the specified unit multiplied by the factor <code>10<sup>-1</sup></code>
252     *
253     * @param <Q>
254     *          type of the quantity measured by the unit.
255     * @param unit
256     *          any unit.
257     * @return <code>unit.times(1e-1)</code>.
258     */
259    public static <Q extends Quantity<Q>> Unit<Q> DECI(Unit<Q> unit) {
260        return unit.prefix(DECI);
261    }
262
263    /**
264     * Returns the specified unit multiplied by the factor <code>10<sup>-2</sup></code>
265     *
266     * @param <Q>
267     *          type of the quantity measured by the unit.
268     * @param unit
269     *          any unit.
270     * @return <code>unit.times(1e-2)</code>.
271     */
272    public static <Q extends Quantity<Q>> Unit<Q> CENTI(Unit<Q> unit) {
273        return unit.prefix(CENTI);
274    }
275
276    /**
277     * Returns the specified unit multiplied by the factor <code>10<sup>-3</sup></code>
278     *
279     * @param <Q>
280     *          type of the quantity measured by the unit.
281     * @param unit
282     *          any unit.
283     * @return <code>unit.times(1e-3)</code>.
284     */
285    public static <Q extends Quantity<Q>> Unit<Q> MILLI(Unit<Q> unit) {
286        return unit.prefix(MILLI);
287    }
288
289    /**
290     * Returns the specified unit multiplied by the factor <code>10<sup>-6</sup></code>
291     *
292     * @param <Q>
293     *          type of the quantity measured by the unit.
294     * @param unit
295     *          any unit.
296     * @return <code>unit.times(1e-6)</code>.
297     */
298    public static <Q extends Quantity<Q>> Unit<Q> MICRO(Unit<Q> unit) {
299        return unit.prefix(MICRO);
300    }
301
302    /**
303     * Returns the specified unit multiplied by the factor <code>10<sup>-9</sup></code>
304     *
305     * @param <Q>
306     *          type of the quantity measured by the unit.
307     * @param unit
308     *          any unit.
309     * @return <code>unit.times(1e-9)</code>.
310     */
311    public static <Q extends Quantity<Q>> Unit<Q> NANO(Unit<Q> unit) {
312        return unit.prefix(NANO);
313    }
314
315    /**
316     * Returns the specified unit multiplied by the factor <code>10<sup>-12</sup></code>
317     *
318     * @param <Q>
319     *          type of the quantity measured by the unit.
320     * @param unit
321     *          any unit.
322     * @return <code>unit.times(1e-12)</code>.
323     */
324    public static <Q extends Quantity<Q>> Unit<Q> PICO(Unit<Q> unit) {
325        return unit.prefix(PICO);
326    }
327
328    /**
329     * Returns the specified unit multiplied by the factor <code>10<sup>-15</sup></code>
330     *
331     * @param <Q>
332     *          type of the quantity measured by the unit.
333     * @param unit
334     *          any unit.
335     * @return <code>unit.times(1e-15)</code>.
336     */
337    public static <Q extends Quantity<Q>> Unit<Q> FEMTO(Unit<Q> unit) {
338        return unit.prefix(FEMTO);
339    }
340
341    /**
342     * Returns the specified unit multiplied by the factor <code>10<sup>-18</sup></code>
343     *
344     * @param <Q>
345     *          type of the quantity measured by the unit.
346     * @param unit
347     *          any unit.
348     * @return <code>unit.times(1e-18)</code>.
349     */
350    public static <Q extends Quantity<Q>> Unit<Q> ATTO(Unit<Q> unit) {
351        return unit.prefix(ATTO);
352    }
353
354    /**
355     * Returns the specified unit multiplied by the factor <code>10<sup>-21</sup></code>
356     *
357     * @param <Q>
358     *          type of the quantity measured by the unit.
359     * @param unit
360     *          any unit.
361     * @return <code>unit.times(1e-21)</code>.
362     */
363    public static <Q extends Quantity<Q>> Unit<Q> ZEPTO(Unit<Q> unit) {
364        return unit.prefix(ZEPTO);
365    }
366
367    /**
368     * Returns the specified unit multiplied by the factor <code>10<sup>-24</sup></code>
369     *
370     * @param <Q>
371     *          type of the quantity measured by the unit.
372     * @param unit
373     *          any unit.
374     * @return <code>unit.times(1e-24)</code>.
375     */
376    public static <Q extends Quantity<Q>> Unit<Q> YOCTO(Unit<Q> unit) {
377        return unit.prefix(YOCTO);
378    }
379
380    /**
381     * Returns the symbol of this prefix.
382     *
383     * @return this prefix symbol, not {@code null}.
384     */
385    @Override
386    public String getSymbol() {
387        return symbol;
388    }
389
390    /**
391     * Base part of the associated factor in {@code base^exponent} representation. For metric prefix, this is always 10.
392     */
393    @Override
394    public Integer getValue() {
395        return 10;
396    }
397
398    /**
399     * Exponent part of the associated factor in {@code base^exponent} representation.
400     */
401    @Override
402    public int getExponent() {
403        return exponent;
404    }
405
406    /**
407     * Returns the name of this prefix.
408     *
409     * @return this prefix name, not {@code null}.
410     */
411    @Override
412    public String getName() {
413        return name();
414    }
415}