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 common binary prefixes to be used by units.
034 *
035 * @author <a href="mailto:werner@units.tech">Werner Keil</a>
036 * @version 2.0, June 28, 2019
037 * @see <a href="https://en.wikipedia.org/wiki/Binary_prefix">Wikipedia: Binary Prefix</a>
038 * @since 2.0
039 */
040public enum BinaryPrefix implements Prefix {
041    /** Prefix for 1024. */
042    KIBI("Ki", 1),
043    /** Prefix for 1024<sup>2</sup>. */
044    MEBI("Mi", 2),
045    /** Prefix for 1024<sup>3</sup>. */
046    GIBI("Gi", 3),
047    /** Prefix for 1024<sup>4</sup>. */
048    TEBI("Ti", 4),
049    /** Prefix for 1024<sup>5</sup>. */
050    PEBI("Pi", 5),
051    /** Prefix for 1024<sup>6</sup>. */
052    EXBI("Ei", 6),
053    /** Prefix for 1024<sup>7</sup>. */
054    ZEBI("Zi", 7),
055    /** Prefix for 1024<sup>8</sup>. */
056    YOBI("Yi", 8);
057
058    /**
059     * The symbol of this prefix, as returned by {@link #getSymbol}.
060     *
061     * @serial
062     * @see #getSymbol()
063     */
064    private final String symbol;
065
066    /**
067     * Exponent part of the associated factor in base^exponent representation.
068     */
069    private final int exponent;
070
071    /**
072     * Creates a new prefix.
073     *
074     * @param symbol
075     *          the symbol of this prefix.
076     * @param exponent
077     *          part of the associated factor in base^exponent representation.
078     */
079    private BinaryPrefix(String symbol, int exponent) {
080        this.symbol = symbol;
081        this.exponent = exponent;
082    }
083
084    /**
085     * Returns the specified unit multiplied by the factor <code>1024</code> (binary prefix).
086     *
087     * @param <Q>
088     *          type of the quantity measured by the unit.
089     * @param unit
090     *          any unit.
091     * @return <code>unit.multiply(1024)</code>.
092     */
093    public static <Q extends Quantity<Q>> Unit<Q> KIBI(Unit<Q> unit) {
094        return unit.prefix(KIBI);
095    }
096
097    /**
098     * Returns the specified unit multiplied by the factor <code>1024<sup>2</sup></code> (binary prefix).
099     *
100     * @param <Q>
101     *          type of the quantity measured by the unit.
102     * @param unit
103     *          any unit.
104     * @return <code>unit.multiply(1048576)</code>.
105     */
106    public static <Q extends Quantity<Q>> Unit<Q> MEBI(Unit<Q> unit) {
107        return unit.prefix(MEBI);
108    }
109
110    /**
111     * Returns the specified unit multiplied by the factor <code>1024<sup>3</sup></code> (binary prefix).
112     *
113     * @param <Q>
114     *          type of the quantity measured by the unit.
115     * @param unit
116     *          any unit.
117     * @return <code>unit.multiply(1073741824)</code>.
118     */
119    public static <Q extends Quantity<Q>> Unit<Q> GIBI(Unit<Q> unit) {
120        return unit.prefix(GIBI);
121    }
122
123    /**
124     * Returns the specified unit multiplied by the factor <code>1024<sup>4</sup></code> (binary prefix).
125     *
126     * @param <Q>
127     *          type of the quantity measured by the unit.
128     * @param unit
129     *          any unit.
130     * @return <code>unit.multiply(1099511627776L)</code>.
131     */
132    public static <Q extends Quantity<Q>> Unit<Q> TEBI(Unit<Q> unit) {
133        return unit.prefix(TEBI);
134    }
135
136    /**
137     * Returns the specified unit multiplied by the factor <code>1024<sup>5</sup></code> (binary prefix).
138     *
139     * @param <Q>
140     *          type of the quantity measured by the unit.
141     * @param unit
142     *          any unit.
143     * @return <code>unit.multiply(1125899906842624L)</code>.
144     */
145    public static <Q extends Quantity<Q>> Unit<Q> PEBI(Unit<Q> unit) {
146        return unit.prefix(PEBI);
147    }
148
149    /**
150     * Returns the specified unit multiplied by the factor <code>1024<sup>6</sup></code> (binary prefix).
151     *
152     * @param <Q>
153     *          type of the quantity measured by the unit.
154     * @param unit
155     *          any unit.
156     * @return <code>unit.multiply(1152921504606846976L)</code>.
157     */
158    public static <Q extends Quantity<Q>> Unit<Q> EXBI(Unit<Q> unit) {
159        return unit.prefix(EXBI);
160    }
161
162    /**
163     * Returns the specified unit multiplied by the factor <code>1024<sup>7</sup></code> (binary prefix).
164     *
165     * @param <Q>
166     *          type of the quantity measured by the unit.
167     * @param unit
168     *          any unit.
169     * @return <code>unit.multiply(1152921504606846976d)</code>.
170     */
171    public static <Q extends Quantity<Q>> Unit<Q> ZEBI(Unit<Q> unit) {
172        return unit.prefix(ZEBI);
173    }
174
175    /**
176     * Returns the specified unit multiplied by the factor <code>1024<sup>8</sup></code> (binary prefix).
177     *
178     * @param <Q>
179     *          type of the quantity measured by the unit.
180     * @param unit
181     *          any unit.
182     * @return <code>unit.multiply(1208925819614629174706176d)</code>.
183     */
184    public static <Q extends Quantity<Q>> Unit<Q> YOBI(Unit<Q> unit) {
185        return unit.prefix(YOBI);
186    }
187
188    /**
189     * Returns the symbol of this prefix.
190     *
191     * @return this prefix symbol, not {@code null}.
192     */
193    @Override
194    public String getSymbol() {
195        return symbol;
196    }
197
198    /**
199     * Base part of the associated factor in {@code base^exponent} representation. For binary prefix, this is always 1024.
200     */
201    @Override
202    public Integer getValue() {
203        return 1024;
204    }
205
206    /**
207     * Exponent part of the associated factor in {@code base^exponent} representation.
208     */
209    @Override
210    public int getExponent() {
211        return exponent;
212    }
213
214    /**
215     * Returns the name of this prefix.
216     *
217     * @return this prefix name, not {@code null}.
218     */
219    @Override
220    public String getName() {
221        return name();
222    }
223}