001/*
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003 *
004 * Copyright (c) 2011-2017 Oracle and/or its affiliates. All rights reserved.
005 *
006 * The contents of this file are subject to the terms of either the GNU
007 * General Public License Version 2 only ("GPL") or the Common Development
008 * and Distribution License("CDDL") (collectively, the "License").  You
009 * may not use this file except in compliance with the License.  You can
010 * obtain a copy of the License at
011 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
012 * or LICENSE.txt.  See the License for the specific
013 * language governing permissions and limitations under the License.
014 *
015 * When distributing the software, include this License Header Notice in each
016 * file and include the License file at LICENSE.txt.
017 *
018 * GPL Classpath Exception:
019 * Oracle designates this particular file as subject to the "Classpath"
020 * exception as provided by Oracle in the GPL Version 2 section of the License
021 * file that accompanied this code.
022 *
023 * Modifications:
024 * If applicable, add the following below the License Header, with the fields
025 * enclosed by brackets [] replaced by your own identifying information:
026 * "Portions Copyright [year] [name of copyright owner]"
027 *
028 * Contributor(s):
029 * If you wish your version of this file to be governed by only the CDDL or
030 * only the GPL Version 2, indicate your decision by adding "[Contributor]
031 * elects to include this software in this distribution under the [CDDL or GPL
032 * Version 2] license."  If you don't indicate a single choice of license, a
033 * recipient has the option to distribute your version of this file under
034 * either the CDDL, the GPL Version 2 or to extend the choice of license to
035 * its licensees as provided above.  However, if you add GPL Version 2 code
036 * and therefore, elected the GPL Version 2 license, then the option applies
037 * only if the new code is made subject to such option by the copyright
038 * holder.
039 */
040
041package javax.json;
042
043import java.math.BigDecimal;
044import java.math.BigInteger;
045
046/**
047 * An immutable JSON number value.
048 *
049 * <EMBED CLASS='external-html' DATA-FILE-ID=LICENSE DATA-CIETName=JsonNumber>
050 * 
051 * <BR /><BR />Implementations may use a {@link BigDecimal} object to store the numeric
052 * value internally.
053 * The {@code BigDecimal} object can be constructed from the following types:
054 * 
055 * <BR /><BR /><UL CLASS=JDUL>
056 *  <LI><code>int</code> {@link BigDecimal#BigDecimal(int)}</LI>
057 *  <LI><code>long</code> {@link BigDecimal#BigDecimal(long)}</LI>
058 *  <LI><code>BigInteger</code> {@link BigDecimal#BigDecimal(BigInteger)}</LI>
059 *  <LI><code>double</code> {@link BigDecimal#valueOf(double)}</LI>
060 *  <LI><code>String</code> {@link BigDecimal#BigDecimal(String)}.</LI>
061 * </UL>
062 * 
063 * <BR />Some of the method semantics in this class are defined using the
064 * {@code BigDecimal} semantics.
065 */
066public interface JsonNumber extends JsonValue {
067
068    /**
069     * Returns true if this JSON number is a integral number. This method
070     * semantics are defined using {@code bigDecimalValue().scale()}. If the
071     * scale is zero, then it is considered integral type. This integral type
072     * information can be used to invoke an appropriate accessor method to
073     * obtain a numeric value as in the following example:
074     *
075     * <DIV CLASS=EXAMPLE>{@code
076     * JsonNumber num = ...
077     * 
078     * if (num.isIntegral())
079     *     num.longValue();     // or other methods to get integral value
080     * else
081     *     num.doubleValue();   // or other methods to get decimal number value
082     * }</DIV>
083     *
084     * @return true if this number is a integral number, otherwise false
085     */
086    boolean isIntegral();
087
088    /**
089     * Returns this JSON number as an {@code int}. Note that this conversion
090     * can lose information about the overall magnitude and precision of the
091     * number value as well as return a result with the opposite sign.
092     *
093     * @return an {@code int} representation of the JSON number
094     * @see java.math.BigDecimal#intValue()
095     */
096    int intValue();
097
098    /**
099     * Returns this JSON number as an {@code int}.
100     *
101     * @return an {@code int} representation of the JSON number
102     * @throws ArithmeticException if the number has a nonzero fractional
103     *         part or if it does not fit in an {@code int}
104     * @see java.math.BigDecimal#intValueExact()
105     */
106    int intValueExact();
107
108    /**
109     * Returns this JSON number as a {@code long}. Note that this conversion
110     * can lose information about the overall magnitude and precision of the
111     * number value as well as return a result with the opposite sign.
112     *
113     * @return a {@code long} representation of the JSON number.
114     * @see java.math.BigDecimal#longValue()
115     */
116    long longValue();
117
118    /**
119     * Returns this JSON number as a {@code long}.
120     *
121     * @return a {@code long} representation of the JSON number
122     * @throws ArithmeticException if the number has a non-zero fractional
123     *         part or if it does not fit in a {@code long}
124     * @see java.math.BigDecimal#longValueExact()
125     */
126    long longValueExact();
127
128    /**
129     * Returns this JSON number as a {@link BigInteger} object. This is a
130     * a convenience method for {@code bigDecimalValue().toBigInteger()}.
131     * Note that this conversion can lose information about the overall
132     * magnitude and precision of the number value as well as return a result
133     * with the opposite sign.
134     *
135     * @return a {@code BigInteger} representation of the JSON number.
136     * @see java.math.BigDecimal#toBigInteger()
137     */
138    BigInteger bigIntegerValue();
139
140    /**
141     * Returns this JSON number as a {@link BigInteger} object. This is a
142     * convenience method for {@code bigDecimalValue().toBigIntegerExact()}.
143     *
144     * @return a {@link BigInteger} representation of the JSON number
145     * @throws ArithmeticException if the number has a nonzero fractional part
146     * @see java.math.BigDecimal#toBigIntegerExact()
147     */
148    BigInteger bigIntegerValueExact();
149
150    /**
151     * Returns this JSON number as a {@code double}. This is a
152     * a convenience method for {@code bigDecimalValue().doubleValue()}.
153     * Note that this conversion can lose information about the overall
154     * magnitude and precision of the number value as well as return a result
155     * with the opposite sign.
156     *
157     * @return a {@code double} representation of the JSON number
158     * @see java.math.BigDecimal#doubleValue()
159     */
160    double doubleValue();
161
162    /**
163     * Returns this JSON number as a {@link BigDecimal} object.
164     *
165     * @return a {@link BigDecimal} representation of the JSON number
166     */
167    BigDecimal bigDecimalValue();
168
169    /**
170     * Returns this JSON number as a {@link Number} object.
171     *
172     * @return a {@link Number} representation of the JSON number
173     *
174     * @since 1.1
175     */
176    default Number numberValue() {
177        throw new UnsupportedOperationException();
178    }
179
180    /**
181     * Returns a JSON text representation of the JSON number. The
182     * representation is equivalent to {@link BigDecimal#toString()}.
183     *
184     * @return JSON text representation of the number
185     */
186    @Override
187    String toString();
188
189    /**
190     * Compares the specified object with this {@code JsonNumber} object for
191     * equality. Returns {@code true} if and only if the type of the specified
192     * object is also {@code JsonNumber} and their {@link #bigDecimalValue()}
193     * objects are <i>equal</i>
194     *
195     * @param obj the object to be compared for equality with
196     *      this {@code JsonNumber}
197     * @return {@code true} if the specified object is equal to this
198     *      {@code JsonNumber}
199     */
200    @Override
201    boolean equals(Object obj);
202
203    /**
204     * Returns the hash code value for this {@code JsonNumber} object.  The
205     * hash code of a {@code JsonNumber} object is defined as the hash code of
206     * its {@link #bigDecimalValue()} object.
207     *
208     * @return the hash code value for this {@code JsonNumber} object
209     */
210    @Override
211    int hashCode();
212
213}