001/*
002 * ============================================================================
003 * Copyright © 2002-2023 by Thomas Thrien.
004 * All Rights Reserved.
005 * ============================================================================
006 * Licensed to the public under the agreements of the GNU Lesser General Public
007 * License, version 3.0 (the "License"). You may obtain a copy of the License at
008 *
009 *      http://www.gnu.org/licenses/lgpl.html
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
013 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
014 * License for the specific language governing permissions and limitations
015 * under the License.
016 */
017
018package org.tquadrat.foundation.value;
019
020import static java.lang.String.format;
021import static java.util.Arrays.stream;
022import static org.apiguardian.api.API.Status.STABLE;
023import static org.tquadrat.foundation.lang.Objects.requireNotEmptyArgument;
024
025import java.math.BigDecimal;
026
027import org.apiguardian.api.API;
028import org.tquadrat.foundation.annotation.ClassVersion;
029import org.tquadrat.foundation.value.api.DimensionWithLinearConversion;
030
031/**
032 *  The various instances of data sizes (for files or free disk space or
033 *  capacities of memory sticks …).
034 *
035 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
036 *  @version $Id: DataSize.java 1072 2023-09-30 20:44:38Z tquadrat $
037 *  @since 0.1.0
038 *
039 *  @UMLGraph.link
040 */
041@ClassVersion( sourceVersion = "$Id: DataSize.java 1072 2023-09-30 20:44:38Z tquadrat $" )
042@API( status = STABLE, since = "0.1.0" )
043public enum DataSize implements DimensionWithLinearConversion
044{
045        /*------------------*\
046    ====** Enum Declaration **=================================================
047        \*------------------*/
048    /**
049     *  A single byte.
050     */
051    BYTE( BigDecimal.ONE, "Byte" ),
052
053    /**
054     *  A Kilobyte (with 1000 bytes).
055     */
056    KILOBYTE( new BigDecimal( "1000.0" ), "kB" ),
057
058    /**
059     *  A Kilobyte with 1024 bytes.
060     */
061    KIBIBYTE( new BigDecimal( "1024.0" ), "KiB" ),
062
063    /**
064     *  A megabyte (the decimal form).
065     */
066    MEGABYTE( new BigDecimal( "1000000.0" ), "MB" ),
067
068    /**
069     *  A megabyte in the binary form.
070     */
071    MEBIBYTE( new BigDecimal( "1048576.0" ), "MiB" ),
072
073    /**
074     *  A gigabyte (the decimal form).
075     */
076    GIGABYTE( new BigDecimal( "1000000000.0" ), "GB" ),
077
078    /**
079     *  A gigabyte in the binary form.
080     */
081    GIBIBYTE( new BigDecimal( "1073741824.0" ), "GiB" ),
082
083    /**
084     *  A terabyte (the decimal form).
085     */
086    TERABYTE( new BigDecimal( "1000000000000.0" ), "TB" ),
087
088    /**
089     *  A terabyte in the binary form.
090     */
091    TEBIBYTE( new BigDecimal( "1099511627776.0" ), "TiB" );
092
093        /*------------*\
094    ====** Attributes **=======================================================
095        \*------------*/
096    /**
097     *  The factor.
098     */
099    private final BigDecimal m_Factor;
100
101    /**
102     *  The default precision.
103     */
104    private final int m_Precision;
105
106    /**
107     *  The unit string.
108     */
109    private final String m_UnitSymbol;
110
111        /*--------------*\
112    ====** Constructors **=====================================================
113        \*--------------*/
114    /**
115     *  Creates a new {@code DataSize} instance.
116     *
117     *  @param  factor  The factor.
118     *  @param  unitSymbol    The unit string.
119     *  @param  precision   The default precision.
120     */
121    private DataSize( final BigDecimal factor, final String unitSymbol, final int precision )
122    {
123        m_Factor = factor.stripTrailingZeros();
124        m_UnitSymbol = unitSymbol;
125        m_Precision = precision;
126    }   //  DataSize()
127
128    /**
129     *  Creates a new {@code DataSize} instance, with a default precision of
130     *  zero mantissa digits.
131     *
132     *  @param  factor  The factor.
133     *  @param  unitSymbol    The unit string.
134     */
135    private DataSize( final BigDecimal factor, final String unitSymbol )
136    {
137        this( factor, unitSymbol, 0 );
138    }   //  DataSize()
139
140        /*---------*\
141    ====** Methods **==========================================================
142        \*---------*/
143    /**
144     *  {@inheritDoc}
145     */
146    @Override
147    @SuppressWarnings( "unchecked" )
148    public final DataSize baseUnit() { return BYTE; }
149
150    /**
151     *  {@inheritDoc}
152     */
153    @Override
154    public final BigDecimal factor() { return m_Factor; }
155
156    /**
157     *  Returns the {@code DataSize} instance for the given unit.
158     *
159     *  @param  unit    The unit.
160     *  @return The respective instance.
161     *  @throws IllegalArgumentException    The given unit is unknown.
162     */
163    public static final DataSize forUnit( final String unit ) throws IllegalArgumentException
164    {
165        requireNotEmptyArgument( unit, "unit" );
166
167        final var retValue = stream( values() )
168            .filter( v -> v.unitSymbol().equals( unit ) )
169            .findFirst()
170            .orElseThrow( () -> new IllegalArgumentException( format( MSG_UnknownUnit, unit ) ) );
171
172        //---* Done *----------------------------------------------------------
173        return retValue;
174    }   //  forUnit()
175
176    /**
177     *  {@inheritDoc}
178     */
179    @Override
180    public final int getPrecision() { return m_Precision; }
181
182    /**
183     *  {@inheritDoc}
184     */
185    @Override
186    public final String unitSymbol() { return m_UnitSymbol; }
187}
188//  enum DataSize
189
190/*
191 *  End of File
192 */