14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.lang;
27
28 import java.lang.invoke.MethodHandles;
29 import java.lang.constant.Constable;
30 import java.lang.constant.ConstantDesc;
31 import java.util.Optional;
32
33 import jdk.internal.math.FloatingDecimal;
34 import jdk.internal.HotSpotIntrinsicCandidate;
35
36 /**
37 * The {@code Float} class wraps a value of primitive type
38 * {@code float} in an object. An object of type
39 * {@code Float} contains a single field whose type is
40 * {@code float}.
41 *
42 * <p>In addition, this class provides several methods for converting a
43 * {@code float} to a {@code String} and a
44 * {@code String} to a {@code float}, as well as other
45 * constants and methods useful when dealing with a
46 * {@code float}.
47 *
48 * @author Lee Boynton
49 * @author Arthur van Hoff
50 * @author Joseph D. Darcy
51 * @since 1.0
52 */
53 public final class Float extends Number
125 */
126 public static final int SIZE = 32;
127
128 /**
129 * The number of bytes used to represent a {@code float} value.
130 *
131 * @since 1.8
132 */
133 public static final int BYTES = SIZE / Byte.SIZE;
134
135 /**
136 * The {@code Class} instance representing the primitive type
137 * {@code float}.
138 *
139 * @since 1.1
140 */
141 @SuppressWarnings("unchecked")
142 public static final Class<Float> TYPE = (Class<Float>) Class.getPrimitiveClass("float");
143
144 /**
145 * Returns a string representation of the {@code float}
146 * argument. All characters mentioned below are ASCII characters.
147 * <ul>
148 * <li>If the argument is NaN, the result is the string
149 * "{@code NaN}".
150 * <li>Otherwise, the result is a string that represents the sign and
151 * magnitude (absolute value) of the argument. If the sign is
152 * negative, the first character of the result is
153 * '{@code -}' ({@code '\u005Cu002D'}); if the sign is
154 * positive, no sign character appears in the result. As for
155 * the magnitude <i>m</i>:
156 * <ul>
157 * <li>If <i>m</i> is infinity, it is represented by the characters
158 * {@code "Infinity"}; thus, positive infinity produces
159 * the result {@code "Infinity"} and negative infinity
160 * produces the result {@code "-Infinity"}.
161 * <li>If <i>m</i> is zero, it is represented by the characters
162 * {@code "0.0"}; thus, negative zero produces the result
163 * {@code "-0.0"} and positive zero produces the result
164 * {@code "0.0"}.
165 * <li> If <i>m</i> is greater than or equal to 10<sup>-3</sup> but
166 * less than 10<sup>7</sup>, then it is represented as the
167 * integer part of <i>m</i>, in decimal form with no leading
168 * zeroes, followed by '{@code .}'
169 * ({@code '\u005Cu002E'}), followed by one or more
170 * decimal digits representing the fractional part of
171 * <i>m</i>.
172 * <li> If <i>m</i> is less than 10<sup>-3</sup> or greater than or
173 * equal to 10<sup>7</sup>, then it is represented in
174 * so-called "computerized scientific notation." Let <i>n</i>
175 * be the unique integer such that 10<sup><i>n</i> </sup>≤
176 * <i>m</i> {@literal <} 10<sup><i>n</i>+1</sup>; then let <i>a</i>
177 * be the mathematically exact quotient of <i>m</i> and
178 * 10<sup><i>n</i></sup> so that 1 ≤ <i>a</i> {@literal <} 10.
179 * The magnitude is then represented as the integer part of
180 * <i>a</i>, as a single decimal digit, followed by
181 * '{@code .}' ({@code '\u005Cu002E'}), followed by
182 * decimal digits representing the fractional part of
183 * <i>a</i>, followed by the letter '{@code E}'
184 * ({@code '\u005Cu0045'}), followed by a representation
185 * of <i>n</i> as a decimal integer, as produced by the
186 * method {@link java.lang.Integer#toString(int)}.
187 *
188 * </ul>
189 * </ul>
190 * How many digits must be printed for the fractional part of
191 * <i>m</i> or <i>a</i>? There must be at least one digit
192 * to represent the fractional part, and beyond that as many, but
193 * only as many, more digits as are needed to uniquely distinguish
194 * the argument value from adjacent values of type
195 * {@code float}. That is, suppose that <i>x</i> is the
196 * exact mathematical value represented by the decimal
197 * representation produced by this method for a finite nonzero
198 * argument <i>f</i>. Then <i>f</i> must be the {@code float}
199 * value nearest to <i>x</i>; or, if two {@code float} values are
200 * equally close to <i>x</i>, then <i>f</i> must be one of
201 * them and the least significant bit of the significand of
202 * <i>f</i> must be {@code 0}.
203 *
204 * <p>To create localized string representations of a floating-point
205 * value, use subclasses of {@link java.text.NumberFormat}.
206 *
207 * @param f the float to be converted.
208 * @return a string representation of the argument.
209 */
210 public static String toString(float f) {
211 return FloatingDecimal.toJavaFormatString(f);
212 }
213
214 /**
215 * Returns a hexadecimal string representation of the
216 * {@code float} argument. All characters mentioned below are
217 * ASCII characters.
218 *
219 * <ul>
220 * <li>If the argument is NaN, the result is the string
221 * "{@code NaN}".
222 * <li>Otherwise, the result is a string that represents the sign and
223 * magnitude (absolute value) of the argument. If the sign is negative,
224 * the first character of the result is '{@code -}'
225 * ({@code '\u005Cu002D'}); if the sign is positive, no sign character
226 * appears in the result. As for the magnitude <i>m</i>:
227 *
228 * <ul>
229 * <li>If <i>m</i> is infinity, it is represented by the string
230 * {@code "Infinity"}; thus, positive infinity produces the
231 * result {@code "Infinity"} and negative infinity produces
|
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.lang;
27
28 import java.lang.invoke.MethodHandles;
29 import java.lang.constant.Constable;
30 import java.lang.constant.ConstantDesc;
31 import java.util.Optional;
32
33 import jdk.internal.math.FloatingDecimal;
34 import jdk.internal.math.FloatToDecimal;
35 import jdk.internal.HotSpotIntrinsicCandidate;
36
37 /**
38 * The {@code Float} class wraps a value of primitive type
39 * {@code float} in an object. An object of type
40 * {@code Float} contains a single field whose type is
41 * {@code float}.
42 *
43 * <p>In addition, this class provides several methods for converting a
44 * {@code float} to a {@code String} and a
45 * {@code String} to a {@code float}, as well as other
46 * constants and methods useful when dealing with a
47 * {@code float}.
48 *
49 * @author Lee Boynton
50 * @author Arthur van Hoff
51 * @author Joseph D. Darcy
52 * @since 1.0
53 */
54 public final class Float extends Number
126 */
127 public static final int SIZE = 32;
128
129 /**
130 * The number of bytes used to represent a {@code float} value.
131 *
132 * @since 1.8
133 */
134 public static final int BYTES = SIZE / Byte.SIZE;
135
136 /**
137 * The {@code Class} instance representing the primitive type
138 * {@code float}.
139 *
140 * @since 1.1
141 */
142 @SuppressWarnings("unchecked")
143 public static final Class<Float> TYPE = (Class<Float>) Class.getPrimitiveClass("float");
144
145 /**
146 * Returns a string rendering of the {@code float} argument.
147 *
148 * <p>The characters of the result are all drawn from the ASCII set.
149 * <ul>
150 * <li> Any NaN, whether quiet or signaling, is rendered as
151 * {@code "NaN"}, regardless of the sign bit.
152 * <li> The infinities +∞ and -∞ are rendered as
153 * {@code "Infinity"} and {@code "-Infinity"}, respectively.
154 * <li> The positive and negative zeroes are rendered as
155 * {@code "0.0"} and {@code "-0.0"}, respectively.
156 * <li> A finite negative {@code v} is rendered as the sign
157 * '{@code -}' followed by the rendering of the magnitude -{@code v}.
158 * <li> A finite positive {@code v} is rendered in two stages:
159 * <ul>
160 * <li> <em>Selection of a decimal</em>: A well-defined
161 * decimal <i>d</i><sub><code>v</code></sub> is selected
162 * to represent {@code v}.
163 * <li> <em>Formatting as a string</em>: The decimal
164 * <i>d</i><sub><code>v</code></sub> is formatted as a string,
165 * either in plain or in computerized scientific notation,
166 * depending on its value.
167 * </ul>
168 * </ul>
169 *
170 * <p>A <em>decimal</em> is a number of the form
171 * <i>d</i>×10<sup><i>i</i></sup>
172 * for some (unique) integers <i>d</i> > 0 and <i>i</i> such that
173 * <i>d</i> is not a multiple of 10.
174 * These integers are the <em>significand</em> and
175 * the <em>exponent</em>, respectively, of the decimal.
176 * The <em>length</em> of the decimal is the (unique)
177 * integer <i>n</i> meeting
178 * 10<sup><i>n</i>-1</sup> ≤ <i>d</i> < 10<sup><i>n</i></sup>.
179 *
180 * <p>The decimal <i>d</i><sub><code>v</code></sub>
181 * for a finite positive {@code v} is defined as follows:
182 * <ul>
183 * <li>Let <i>R</i> be the set of all decimals that round to {@code v}
184 * according to the usual round-to-closest rule of
185 * IEEE 754 floating-point arithmetic.
186 * <li>Let <i>m</i> be the minimal length over all decimals in <i>R</i>.
187 * <li>When <i>m</i> ≥ 2, let <i>T</i> be the set of all decimals
188 * in <i>R</i> with length <i>m</i>.
189 * Otherwise, let <i>T</i> be the set of all decimals
190 * in <i>R</i> with length 1 or 2.
191 * <li>Define <i>d</i><sub><code>v</code></sub> as
192 * the decimal in <i>T</i> that is closest to {@code v}.
193 * Or if there are two such decimals in <i>T</i>,
194 * select the one with the even significand (there is exactly one).
195 * </ul>
196 *
197 * <p>The (uniquely) selected decimal <i>d</i><sub><code>v</code></sub>
198 * is then formatted.
199 *
200 * <p>Let <i>d</i>, <i>i</i> and <i>n</i> be the significand, exponent and
201 * length of <i>d</i><sub><code>v</code></sub>, respectively.
202 * Further, let <i>e</i> = <i>n</i> + <i>i</i> - 1 and let
203 * <i>d</i><sub>1</sub>…<i>d</i><sub><i>n</i></sub>
204 * be the usual decimal expansion of the significand.
205 * Note that <i>d</i><sub>1</sub> ≠ 0 ≠ <i>d</i><sub><i>n</i></sub>.
206 * <ul>
207 * <li>Case -3 ≤ <i>e</i> < 0:
208 * <i>d</i><sub><code>v</code></sub> is formatted as
209 * <code>0.0</code>…<code>0</code><!--
210 * --><i>d</i><sub>1</sub>…<i>d</i><sub><i>n</i></sub>,
211 * where there are exactly -(<i>n</i> + <i>i</i>) zeroes between
212 * the decimal point and <i>d</i><sub>1</sub>.
213 * For example, 123 × 10<sup>-4</sup> is formatted as
214 * {@code 0.0123}.
215 * <li>Case 0 ≤ <i>e</i> < 7:
216 * <ul>
217 * <li>Subcase <i>i</i> ≥ 0:
218 * <i>d</i><sub><code>v</code></sub> is formatted as
219 * <i>d</i><sub>1</sub>…<i>d</i><sub><i>n</i></sub><!--
220 * --><code>0</code>…<code>0.0</code>,
221 * where there are exactly <i>i</i> zeroes
222 * between <i>d</i><sub><i>n</i></sub> and the decimal point.
223 * For example, 123 × 10<sup>2</sup> is formatted as
224 * {@code 12300.0}.
225 * <li>Subcase <i>i</i> < 0:
226 * <i>d</i><sub><code>v</code></sub> is formatted as
227 * <i>d</i><sub>1</sub>…<!--
228 * --><i>d</i><sub><i>n</i>+<i>i</i></sub>.<!--
229 * --><i>d</i><sub><i>n</i>+<i>i</i>+1</sub>…<!--
230 * --><i>d</i><sub><i>n</i></sub>.
231 * There are exactly -<i>i</i> digits to the right of
232 * the decimal point.
233 * For example, 123 × 10<sup>-1</sup> is formatted as
234 * {@code 12.3}.
235 * </ul>
236 * <li>Case <i>e</i> < -3 or <i>e</i> ≥ 7:
237 * computerized scientific notation is used to format
238 * <i>d</i><sub><code>v</code></sub>.
239 * Here <i>e</i> is formatted as by {@link Integer#toString(int)}.
240 * <ul>
241 * <li>Subcase <i>n</i> = 1:
242 * <i>d</i><sub><code>v</code></sub> is formatted as
243 * <i>d</i><sub>1</sub><code>.0E</code><i>e</i>.
244 * For example, 1 × 10<sup>23</sup> is formatted as
245 * {@code 1.0E23}.
246 * <li>Subcase <i>n</i> > 1:
247 * <i>d</i><sub><code>v</code></sub> is formatted as
248 * <i>d</i><sub>1</sub><code>.</code><i>d</i><sub>2</sub><!--
249 * -->…<i>d</i><sub><i>n</i></sub><code>E</code><i>e</i>.
250 * For example, 123 × 10<sup>-21</sup> is formatted as
251 * {@code 1.23E-19}.
252 * </ul>
253 * </ul>
254 *
255 * @param v the {@code float} to be rendered.
256 * @return a string rendering of the argument.
257 */
258 public static String toString(float v) {
259 return FloatToDecimal.toString(v);
260 }
261
262 /**
263 * Returns a hexadecimal string representation of the
264 * {@code float} argument. All characters mentioned below are
265 * ASCII characters.
266 *
267 * <ul>
268 * <li>If the argument is NaN, the result is the string
269 * "{@code NaN}".
270 * <li>Otherwise, the result is a string that represents the sign and
271 * magnitude (absolute value) of the argument. If the sign is negative,
272 * the first character of the result is '{@code -}'
273 * ({@code '\u005Cu002D'}); if the sign is positive, no sign character
274 * appears in the result. As for the magnitude <i>m</i>:
275 *
276 * <ul>
277 * <li>If <i>m</i> is infinity, it is represented by the string
278 * {@code "Infinity"}; thus, positive infinity produces the
279 * result {@code "Infinity"} and negative infinity produces
|