32 /**
33 * The {@code Long} class wraps a value of the primitive type {@code
34 * long} in an object. An object of type {@code Long} contains a
35 * single field whose type is {@code long}.
36 *
37 * <p> In addition, this class provides several methods for converting
38 * a {@code long} to a {@code String} and a {@code String} to a {@code
39 * long}, as well as other constants and methods useful when dealing
40 * with a {@code long}.
41 *
42 * <p>Implementation note: The implementations of the "bit twiddling"
43 * methods (such as {@link #highestOneBit(long) highestOneBit} and
44 * {@link #numberOfTrailingZeros(long) numberOfTrailingZeros}) are
45 * based on material from Henry S. Warren, Jr.'s <i>Hacker's
46 * Delight</i>, (Addison Wesley, 2002).
47 *
48 * @author Lee Boynton
49 * @author Arthur van Hoff
50 * @author Josh Bloch
51 * @author Joseph D. Darcy
52 * @since JDK1.0
53 */
54 public final class Long extends Number implements Comparable<Long> {
55 /**
56 * A constant holding the minimum value a {@code long} can
57 * have, -2<sup>63</sup>.
58 */
59 @Native public static final long MIN_VALUE = 0x8000000000000000L;
60
61 /**
62 * A constant holding the maximum value a {@code long} can
63 * have, 2<sup>63</sup>-1.
64 */
65 @Native public static final long MAX_VALUE = 0x7fffffffffffffffL;
66
67 /**
68 * The {@code Class} instance representing the primitive type
69 * {@code long}.
70 *
71 * @since JDK1.1
72 */
73 @SuppressWarnings("unchecked")
74 public static final Class<Long> TYPE = (Class<Long>) Class.getPrimitiveClass("long");
75
76 /**
77 * Returns a string representation of the first argument in the
78 * radix specified by the second argument.
79 *
80 * <p>If the radix is smaller than {@code Character.MIN_RADIX}
81 * or larger than {@code Character.MAX_RADIX}, then the radix
82 * {@code 10} is used instead.
83 *
84 * <p>If the first argument is negative, the first element of the
85 * result is the ASCII minus sign {@code '-'}
86 * ({@code '\u005Cu002d'}). If the first argument is not
87 * negative, no sign character appears in the result.
88 *
89 * <p>The remaining characters of the result represent the magnitude
90 * of the first argument. If the magnitude is zero, it is
91 * represented by a single zero character {@code '0'}
249 * <blockquote>
250 * {@code 0123456789abcdef}
251 * </blockquote>
252 *
253 * These are the characters {@code '\u005Cu0030'} through
254 * {@code '\u005Cu0039'} and {@code '\u005Cu0061'} through
255 * {@code '\u005Cu0066'}. If uppercase letters are desired,
256 * the {@link java.lang.String#toUpperCase()} method may be called
257 * on the result:
258 *
259 * <blockquote>
260 * {@code Long.toHexString(n).toUpperCase()}
261 * </blockquote>
262 *
263 * @param i a {@code long} to be converted to a string.
264 * @return the string representation of the unsigned {@code long}
265 * value represented by the argument in hexadecimal
266 * (base 16).
267 * @see #parseUnsignedLong(String, int)
268 * @see #toUnsignedString(long, int)
269 * @since JDK 1.0.2
270 */
271 public static String toHexString(long i) {
272 return toUnsignedString0(i, 4);
273 }
274
275 /**
276 * Returns a string representation of the {@code long}
277 * argument as an unsigned integer in base 8.
278 *
279 * <p>The unsigned {@code long} value is the argument plus
280 * 2<sup>64</sup> if the argument is negative; otherwise, it is
281 * equal to the argument. This value is converted to a string of
282 * ASCII digits in octal (base 8) with no extra leading
283 * {@code 0}s.
284 *
285 * <p>The value of the argument can be recovered from the returned
286 * string {@code s} by calling {@link
287 * Long#parseUnsignedLong(String, int) Long.parseUnsignedLong(s,
288 * 8)}.
289 *
290 * <p>If the unsigned magnitude is zero, it is represented by a
291 * single zero character {@code '0'} ({@code '\u005Cu0030'});
292 * otherwise, the first character of the representation of the
293 * unsigned magnitude will not be the zero character. The
294 * following characters are used as octal digits:
295 *
296 * <blockquote>
297 * {@code 01234567}
298 * </blockquote>
299 *
300 * These are the characters {@code '\u005Cu0030'} through
301 * {@code '\u005Cu0037'}.
302 *
303 * @param i a {@code long} to be converted to a string.
304 * @return the string representation of the unsigned {@code long}
305 * value represented by the argument in octal (base 8).
306 * @see #parseUnsignedLong(String, int)
307 * @see #toUnsignedString(long, int)
308 * @since JDK 1.0.2
309 */
310 public static String toOctalString(long i) {
311 return toUnsignedString0(i, 3);
312 }
313
314 /**
315 * Returns a string representation of the {@code long}
316 * argument as an unsigned integer in base 2.
317 *
318 * <p>The unsigned {@code long} value is the argument plus
319 * 2<sup>64</sup> if the argument is negative; otherwise, it is
320 * equal to the argument. This value is converted to a string of
321 * ASCII digits in binary (base 2) with no extra leading
322 * {@code 0}s.
323 *
324 * <p>The value of the argument can be recovered from the returned
325 * string {@code s} by calling {@link
326 * Long#parseUnsignedLong(String, int) Long.parseUnsignedLong(s,
327 * 2)}.
328 *
329 * <p>If the unsigned magnitude is zero, it is represented by a
330 * single zero character {@code '0'} ({@code '\u005Cu0030'});
331 * otherwise, the first character of the representation of the
332 * unsigned magnitude will not be the zero character. The
333 * characters {@code '0'} ({@code '\u005Cu0030'}) and {@code
334 * '1'} ({@code '\u005Cu0031'}) are used as binary digits.
335 *
336 * @param i a {@code long} to be converted to a string.
337 * @return the string representation of the unsigned {@code long}
338 * value represented by the argument in binary (base 2).
339 * @see #parseUnsignedLong(String, int)
340 * @see #toUnsignedString(long, int)
341 * @since JDK 1.0.2
342 */
343 public static String toBinaryString(long i) {
344 return toUnsignedString0(i, 1);
345 }
346
347 /**
348 * Format a long (treated as unsigned) into a String.
349 * @param val the value to format
350 * @param shift the log2 of the base to format in (4 for hex, 3 for octal, 1 for binary)
351 */
352 static String toUnsignedString0(long val, int shift) {
353 // assert shift > 0 && shift <=5 : "Illegal shift value";
354 int mag = Long.SIZE - Long.numberOfLeadingZeros(val);
355 int chars = Math.max(((mag + (shift - 1)) / shift), 1);
356 char[] buf = new char[chars];
357
358 formatUnsignedLong(val, shift, buf, 0, chars);
359 return new String(buf, true);
360 }
361
|
32 /**
33 * The {@code Long} class wraps a value of the primitive type {@code
34 * long} in an object. An object of type {@code Long} contains a
35 * single field whose type is {@code long}.
36 *
37 * <p> In addition, this class provides several methods for converting
38 * a {@code long} to a {@code String} and a {@code String} to a {@code
39 * long}, as well as other constants and methods useful when dealing
40 * with a {@code long}.
41 *
42 * <p>Implementation note: The implementations of the "bit twiddling"
43 * methods (such as {@link #highestOneBit(long) highestOneBit} and
44 * {@link #numberOfTrailingZeros(long) numberOfTrailingZeros}) are
45 * based on material from Henry S. Warren, Jr.'s <i>Hacker's
46 * Delight</i>, (Addison Wesley, 2002).
47 *
48 * @author Lee Boynton
49 * @author Arthur van Hoff
50 * @author Josh Bloch
51 * @author Joseph D. Darcy
52 * @since 1.0
53 */
54 public final class Long extends Number implements Comparable<Long> {
55 /**
56 * A constant holding the minimum value a {@code long} can
57 * have, -2<sup>63</sup>.
58 */
59 @Native public static final long MIN_VALUE = 0x8000000000000000L;
60
61 /**
62 * A constant holding the maximum value a {@code long} can
63 * have, 2<sup>63</sup>-1.
64 */
65 @Native public static final long MAX_VALUE = 0x7fffffffffffffffL;
66
67 /**
68 * The {@code Class} instance representing the primitive type
69 * {@code long}.
70 *
71 * @since 1.1
72 */
73 @SuppressWarnings("unchecked")
74 public static final Class<Long> TYPE = (Class<Long>) Class.getPrimitiveClass("long");
75
76 /**
77 * Returns a string representation of the first argument in the
78 * radix specified by the second argument.
79 *
80 * <p>If the radix is smaller than {@code Character.MIN_RADIX}
81 * or larger than {@code Character.MAX_RADIX}, then the radix
82 * {@code 10} is used instead.
83 *
84 * <p>If the first argument is negative, the first element of the
85 * result is the ASCII minus sign {@code '-'}
86 * ({@code '\u005Cu002d'}). If the first argument is not
87 * negative, no sign character appears in the result.
88 *
89 * <p>The remaining characters of the result represent the magnitude
90 * of the first argument. If the magnitude is zero, it is
91 * represented by a single zero character {@code '0'}
249 * <blockquote>
250 * {@code 0123456789abcdef}
251 * </blockquote>
252 *
253 * These are the characters {@code '\u005Cu0030'} through
254 * {@code '\u005Cu0039'} and {@code '\u005Cu0061'} through
255 * {@code '\u005Cu0066'}. If uppercase letters are desired,
256 * the {@link java.lang.String#toUpperCase()} method may be called
257 * on the result:
258 *
259 * <blockquote>
260 * {@code Long.toHexString(n).toUpperCase()}
261 * </blockquote>
262 *
263 * @param i a {@code long} to be converted to a string.
264 * @return the string representation of the unsigned {@code long}
265 * value represented by the argument in hexadecimal
266 * (base 16).
267 * @see #parseUnsignedLong(String, int)
268 * @see #toUnsignedString(long, int)
269 * @since 1.0.2
270 */
271 public static String toHexString(long i) {
272 return toUnsignedString0(i, 4);
273 }
274
275 /**
276 * Returns a string representation of the {@code long}
277 * argument as an unsigned integer in base 8.
278 *
279 * <p>The unsigned {@code long} value is the argument plus
280 * 2<sup>64</sup> if the argument is negative; otherwise, it is
281 * equal to the argument. This value is converted to a string of
282 * ASCII digits in octal (base 8) with no extra leading
283 * {@code 0}s.
284 *
285 * <p>The value of the argument can be recovered from the returned
286 * string {@code s} by calling {@link
287 * Long#parseUnsignedLong(String, int) Long.parseUnsignedLong(s,
288 * 8)}.
289 *
290 * <p>If the unsigned magnitude is zero, it is represented by a
291 * single zero character {@code '0'} ({@code '\u005Cu0030'});
292 * otherwise, the first character of the representation of the
293 * unsigned magnitude will not be the zero character. The
294 * following characters are used as octal digits:
295 *
296 * <blockquote>
297 * {@code 01234567}
298 * </blockquote>
299 *
300 * These are the characters {@code '\u005Cu0030'} through
301 * {@code '\u005Cu0037'}.
302 *
303 * @param i a {@code long} to be converted to a string.
304 * @return the string representation of the unsigned {@code long}
305 * value represented by the argument in octal (base 8).
306 * @see #parseUnsignedLong(String, int)
307 * @see #toUnsignedString(long, int)
308 * @since 1.0.2
309 */
310 public static String toOctalString(long i) {
311 return toUnsignedString0(i, 3);
312 }
313
314 /**
315 * Returns a string representation of the {@code long}
316 * argument as an unsigned integer in base 2.
317 *
318 * <p>The unsigned {@code long} value is the argument plus
319 * 2<sup>64</sup> if the argument is negative; otherwise, it is
320 * equal to the argument. This value is converted to a string of
321 * ASCII digits in binary (base 2) with no extra leading
322 * {@code 0}s.
323 *
324 * <p>The value of the argument can be recovered from the returned
325 * string {@code s} by calling {@link
326 * Long#parseUnsignedLong(String, int) Long.parseUnsignedLong(s,
327 * 2)}.
328 *
329 * <p>If the unsigned magnitude is zero, it is represented by a
330 * single zero character {@code '0'} ({@code '\u005Cu0030'});
331 * otherwise, the first character of the representation of the
332 * unsigned magnitude will not be the zero character. The
333 * characters {@code '0'} ({@code '\u005Cu0030'}) and {@code
334 * '1'} ({@code '\u005Cu0031'}) are used as binary digits.
335 *
336 * @param i a {@code long} to be converted to a string.
337 * @return the string representation of the unsigned {@code long}
338 * value represented by the argument in binary (base 2).
339 * @see #parseUnsignedLong(String, int)
340 * @see #toUnsignedString(long, int)
341 * @since 1.0.2
342 */
343 public static String toBinaryString(long i) {
344 return toUnsignedString0(i, 1);
345 }
346
347 /**
348 * Format a long (treated as unsigned) into a String.
349 * @param val the value to format
350 * @param shift the log2 of the base to format in (4 for hex, 3 for octal, 1 for binary)
351 */
352 static String toUnsignedString0(long val, int shift) {
353 // assert shift > 0 && shift <=5 : "Illegal shift value";
354 int mag = Long.SIZE - Long.numberOfLeadingZeros(val);
355 int chars = Math.max(((mag + (shift - 1)) / shift), 1);
356 char[] buf = new char[chars];
357
358 formatUnsignedLong(val, shift, buf, 0, chars);
359 return new String(buf, true);
360 }
361
|