source: josm/trunk/src/javax/json/JsonNumber.java@ 15724

Last change on this file since 15724 was 13231, checked in by Don-vip, 7 years ago

see #15682 - upgrade to JSR 374 (JSON Processing) API 1.1.2

File size: 7.7 KB
Line 
1/*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright (c) 2011-2017 Oracle and/or its affiliates. All rights reserved.
5 *
6 * The contents of this file are subject to the terms of either the GNU
7 * General Public License Version 2 only ("GPL") or the Common Development
8 * and Distribution License("CDDL") (collectively, the "License"). You
9 * may not use this file except in compliance with the License. You can
10 * obtain a copy of the License at
11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
12 * or LICENSE.txt. See the License for the specific
13 * language governing permissions and limitations under the License.
14 *
15 * When distributing the software, include this License Header Notice in each
16 * file and include the License file at LICENSE.txt.
17 *
18 * GPL Classpath Exception:
19 * Oracle designates this particular file as subject to the "Classpath"
20 * exception as provided by Oracle in the GPL Version 2 section of the License
21 * file that accompanied this code.
22 *
23 * Modifications:
24 * If applicable, add the following below the License Header, with the fields
25 * enclosed by brackets [] replaced by your own identifying information:
26 * "Portions Copyright [year] [name of copyright owner]"
27 *
28 * Contributor(s):
29 * If you wish your version of this file to be governed by only the CDDL or
30 * only the GPL Version 2, indicate your decision by adding "[Contributor]
31 * elects to include this software in this distribution under the [CDDL or GPL
32 * Version 2] license." If you don't indicate a single choice of license, a
33 * recipient has the option to distribute your version of this file under
34 * either the CDDL, the GPL Version 2 or to extend the choice of license to
35 * its licensees as provided above. However, if you add GPL Version 2 code
36 * and therefore, elected the GPL Version 2 license, then the option applies
37 * only if the new code is made subject to such option by the copyright
38 * holder.
39 */
40
41package javax.json;
42
43import java.math.BigDecimal;
44import java.math.BigInteger;
45
46/**
47 * An immutable JSON number value.
48 *
49 * <p>
50 * Implementations may use a {@link BigDecimal} object to store the numeric
51 * value internally.
52 * The {@code BigDecimal} object can be constructed from the following types:
53 * <code>int</code> {@link BigDecimal#BigDecimal(int)},
54 * <code>long</code> {@link BigDecimal#BigDecimal(long)},
55 * <code>BigInteger</code> {@link BigDecimal#BigDecimal(BigInteger)},
56 * <code>double</code> {@link BigDecimal#valueOf(double)}, and
57 * <code>String</code> {@link BigDecimal#BigDecimal(String)}.
58 * Some of the method semantics in this class are defined using the
59 * {@code BigDecimal} semantics.
60 */
61public interface JsonNumber extends JsonValue {
62
63 /**
64 * Returns true if this JSON number is a integral number. This method
65 * semantics are defined using {@code bigDecimalValue().scale()}. If the
66 * scale is zero, then it is considered integral type. This integral type
67 * information can be used to invoke an appropriate accessor method to
68 * obtain a numeric value as in the following example:
69 *
70 * <pre>
71 * <code>
72 * JsonNumber num = ...
73 * if (num.isIntegral()) {
74 * num.longValue(); // or other methods to get integral value
75 * } else {
76 * num.doubleValue(); // or other methods to get decimal number value
77 * }
78 * </code>
79 * </pre>
80 *
81 * @return true if this number is a integral number, otherwise false
82 */
83 boolean isIntegral();
84
85 /**
86 * Returns this JSON number as an {@code int}. Note that this conversion
87 * can lose information about the overall magnitude and precision of the
88 * number value as well as return a result with the opposite sign.
89 *
90 * @return an {@code int} representation of the JSON number
91 * @see java.math.BigDecimal#intValue()
92 */
93 int intValue();
94
95 /**
96 * Returns this JSON number as an {@code int}.
97 *
98 * @return an {@code int} representation of the JSON number
99 * @throws ArithmeticException if the number has a nonzero fractional
100 * part or if it does not fit in an {@code int}
101 * @see java.math.BigDecimal#intValueExact()
102 */
103 int intValueExact();
104
105 /**
106 * Returns this JSON number as a {@code long}. Note that this conversion
107 * can lose information about the overall magnitude and precision of the
108 * number value as well as return a result with the opposite sign.
109 *
110 * @return a {@code long} representation of the JSON number.
111 * @see java.math.BigDecimal#longValue()
112 */
113 long longValue();
114
115 /**
116 * Returns this JSON number as a {@code long}.
117 *
118 * @return a {@code long} representation of the JSON number
119 * @throws ArithmeticException if the number has a non-zero fractional
120 * part or if it does not fit in a {@code long}
121 * @see java.math.BigDecimal#longValueExact()
122 */
123 long longValueExact();
124
125 /**
126 * Returns this JSON number as a {@link BigInteger} object. This is a
127 * a convenience method for {@code bigDecimalValue().toBigInteger()}.
128 * Note that this conversion can lose information about the overall
129 * magnitude and precision of the number value as well as return a result
130 * with the opposite sign.
131 *
132 * @return a {@code BigInteger} representation of the JSON number.
133 * @see java.math.BigDecimal#toBigInteger()
134 */
135 BigInteger bigIntegerValue();
136
137 /**
138 * Returns this JSON number as a {@link BigInteger} object. This is a
139 * convenience method for {@code bigDecimalValue().toBigIntegerExact()}.
140 *
141 * @return a {@link BigInteger} representation of the JSON number
142 * @throws ArithmeticException if the number has a nonzero fractional part
143 * @see java.math.BigDecimal#toBigIntegerExact()
144 */
145 BigInteger bigIntegerValueExact();
146
147 /**
148 * Returns this JSON number as a {@code double}. This is a
149 * a convenience method for {@code bigDecimalValue().doubleValue()}.
150 * Note that this conversion can lose information about the overall
151 * magnitude and precision of the number value as well as return a result
152 * with the opposite sign.
153 *
154 * @return a {@code double} representation of the JSON number
155 * @see java.math.BigDecimal#doubleValue()
156 */
157 double doubleValue();
158
159 /**
160 * Returns this JSON number as a {@link BigDecimal} object.
161 *
162 * @return a {@link BigDecimal} representation of the JSON number
163 */
164 BigDecimal bigDecimalValue();
165
166 /**
167 * Returns this JSON number as a {@link Number} object.
168 *
169 * @return a {@link Number} representation of the JSON number
170 *
171 * @since 1.1
172 */
173 default Number numberValue() {
174 throw new UnsupportedOperationException();
175 }
176
177 /**
178 * Returns a JSON text representation of the JSON number. The
179 * representation is equivalent to {@link BigDecimal#toString()}.
180 *
181 * @return JSON text representation of the number
182 */
183 @Override
184 String toString();
185
186 /**
187 * Compares the specified object with this {@code JsonNumber} object for
188 * equality. Returns {@code true} if and only if the type of the specified
189 * object is also {@code JsonNumber} and their {@link #bigDecimalValue()}
190 * objects are <i>equal</i>
191 *
192 * @param obj the object to be compared for equality with
193 * this {@code JsonNumber}
194 * @return {@code true} if the specified object is equal to this
195 * {@code JsonNumber}
196 */
197 @Override
198 boolean equals(Object obj);
199
200 /**
201 * Returns the hash code value for this {@code JsonNumber} object. The
202 * hash code of a {@code JsonNumber} object is defined as the hash code of
203 * its {@link #bigDecimalValue()} object.
204 *
205 * @return the hash code value for this {@code JsonNumber} object
206 */
207 @Override
208 int hashCode();
209
210}
Note: See TracBrowser for help on using the repository browser.