1 /* Long.java -- object wrapper for long 2 Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc. 3 4 This file is part of GNU Classpath. 5 6 GNU Classpath is free software; you can redistribute it and/or modify 7 it under the terms of the GNU General Public License as published by 8 the Free Software Foundation; either version 2, or (at your option) 9 any later version. 10 11 GNU Classpath is distributed in the hope that it will be useful, but 12 WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 General Public License for more details. 15 16 You should have received a copy of the GNU General Public License 17 along with GNU Classpath; see the file COPYING. If not, write to the 18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 19 02111-1307 USA. 20 21 Linking this library statically or dynamically with other modules is 22 making a combined work based on this library. Thus, the terms and 23 conditions of the GNU General Public License cover the whole 24 combination. 25 26 As a special exception, the copyright holders of this library give you 27 permission to link this library with independent modules to produce an 28 executable, regardless of the license terms of these independent 29 modules, and to copy and distribute the resulting executable under 30 terms of your choice, provided that you also meet, for each linked 31 independent module, the terms and conditions of the license of that 32 module. An independent module is a module which is not derived from 33 or based on this library. If you modify this library, you may extend 34 this exception to your version of the library, but you are not 35 obligated to do so. If you do not wish to do so, delete this 36 exception statement from your version. */ 37 38 39 package java.lang; 40 41 /** 42 * Instances of class <code>Long</code> represent primitive 43 * <code>long</code> values. 44 * 45 * Additionally, this class provides various helper functions and variables 46 * related to longs. 47 * 48 * @author Paul Fisher 49 * @author John Keiser 50 * @author Warren Levy 51 * @author Eric Blake <ebb9@email.byu.edu> 52 * @since 1.0 53 * @status updated to 1.4 54 */ 55 public final class Long extends Number implements Comparable 56 { 57 /** 58 * Compatible with JDK 1.0.2+. 59 */ 60 private static final long serialVersionUID = 4290774380558885855L; 61 62 /** 63 * The minimum value a <code>long</code> can represent is 64 * -9223372036854775808L (or -2<sup>63</sup>). 65 */ 66 public static final long MIN_VALUE = 0x8000000000000000L; 67 68 /** 69 * The maximum value a <code>long</code> can represent is 70 * 9223372036854775807 (or 2<sup>63</sup> - 1). 71 */ 72 public static final long MAX_VALUE = 0x7fffffffffffffffL; 73 74 /** 75 * The primitive type <code>long</code> is represented by this 76 * <code>Class</code> object. 77 * @since 1.1 78 */ 79 public static final Class TYPE = VMClassLoader.getPrimitiveClass ('J'); 80 81 /** 82 * The immutable value of this Long. 83 * 84 * @serial the wrapped long 85 */ 86 private final long value; 87 88 /** 89 * Create a <code>Long</code> object representing the value of the 90 * <code>long</code> argument. 91 * 92 * @param value the value to use 93 */ Long(long value)94 public Long(long value) 95 { 96 this.value = value; 97 } 98 99 /** 100 * Create a <code>Long</code> object representing the value of the 101 * argument after conversion to a <code>long</code>. 102 * 103 * @param s the string to convert 104 * @throws NumberFormatException if the String does not contain a long 105 * @see #valueOf(String) 106 */ Long(String s)107 public Long(String s) 108 { 109 value = parseLong(s, 10, false); 110 } 111 112 /** 113 * Converts the <code>long</code> to a <code>String</code> using 114 * the specified radix (base). If the radix exceeds 115 * <code>Character.MIN_RADIX</code> or <code>Character.MAX_RADIX</code>, 10 116 * is used instead. If the result is negative, the leading character is 117 * '-' ('\\u002D'). The remaining characters come from 118 * <code>Character.forDigit(digit, radix)</code> ('0'-'9','a'-'z'). 119 * 120 * @param num the <code>long</code> to convert to <code>String</code> 121 * @param radix the radix (base) to use in the conversion 122 * @return the <code>String</code> representation of the argument 123 */ toString(long num, int radix)124 public static String toString(long num, int radix) 125 { 126 // Use the Integer toString for efficiency if possible. 127 if ((int) num == num) 128 return Integer.toString((int) num, radix); 129 130 if (radix < Character.MIN_RADIX || radix > Character.MAX_RADIX) 131 radix = 10; 132 133 // For negative numbers, print out the absolute value w/ a leading '-'. 134 // Use an array large enough for a binary number. 135 char[] buffer = new char[65]; 136 int i = 65; 137 boolean isNeg = false; 138 if (num < 0) 139 { 140 isNeg = true; 141 num = -num; 142 143 // When the value is MIN_VALUE, it overflows when made positive 144 if (num < 0) 145 { 146 buffer[--i] = digits[(int) (-(num + radix) % radix)]; 147 num = -(num / radix); 148 } 149 } 150 151 do 152 { 153 buffer[--i] = digits[(int) (num % radix)]; 154 num /= radix; 155 } 156 while (num > 0); 157 158 if (isNeg) 159 buffer[--i] = '-'; 160 161 // Package constructor avoids an array copy. 162 return new String(buffer, i, 65 - i, true); 163 } 164 165 /** 166 * Converts the <code>long</code> to a <code>String</code> assuming it is 167 * unsigned in base 16. 168 * 169 * @param l the <code>long</code> to convert to <code>String</code> 170 * @return the <code>String</code> representation of the argument 171 */ toHexString(long l)172 public static String toHexString(long l) 173 { 174 return toUnsignedString(l, 4); 175 } 176 177 /** 178 * Converts the <code>long</code> to a <code>String</code> assuming it is 179 * unsigned in base 8. 180 * 181 * @param l the <code>long</code> to convert to <code>String</code> 182 * @return the <code>String</code> representation of the argument 183 */ toOctalString(long l)184 public static String toOctalString(long l) 185 { 186 return toUnsignedString(l, 3); 187 } 188 189 /** 190 * Converts the <code>long</code> to a <code>String</code> assuming it is 191 * unsigned in base 2. 192 * 193 * @param l the <code>long</code> to convert to <code>String</code> 194 * @return the <code>String</code> representation of the argument 195 */ toBinaryString(long l)196 public static String toBinaryString(long l) 197 { 198 return toUnsignedString(l, 1); 199 } 200 201 /** 202 * Converts the <code>long</code> to a <code>String</code> and assumes 203 * a radix of 10. 204 * 205 * @param num the <code>long</code> to convert to <code>String</code> 206 * @return the <code>String</code> representation of the argument 207 * @see #toString(long, int) 208 */ toString(long num)209 public static String toString(long num) 210 { 211 return toString(num, 10); 212 } 213 214 /** 215 * Converts the specified <code>String</code> into an <code>int</code> 216 * using the specified radix (base). The string must not be <code>null</code> 217 * or empty. It may begin with an optional '-', which will negate the answer, 218 * provided that there are also valid digits. Each digit is parsed as if by 219 * <code>Character.digit(d, radix)</code>, and must be in the range 220 * <code>0</code> to <code>radix - 1</code>. Finally, the result must be 221 * within <code>MIN_VALUE</code> to <code>MAX_VALUE</code>, inclusive. 222 * Unlike Double.parseDouble, you may not have a leading '+'; and 'l' or 223 * 'L' as the last character is only valid in radices 22 or greater, where 224 * it is a digit and not a type indicator. 225 * 226 * @param s the <code>String</code> to convert 227 * @param radix the radix (base) to use in the conversion 228 * @return the <code>String</code> argument converted to </code>long</code> 229 * @throws NumberFormatException if <code>s</code> cannot be parsed as a 230 * <code>long</code> 231 */ parseLong(String str, int radix)232 public static long parseLong(String str, int radix) 233 { 234 return parseLong(str, radix, false); 235 } 236 237 /** 238 * Converts the specified <code>String</code> into a <code>long</code>. 239 * This function assumes a radix of 10. 240 * 241 * @param s the <code>String</code> to convert 242 * @return the <code>int</code> value of <code>s</code> 243 * @throws NumberFormatException if <code>s</code> cannot be parsed as a 244 * <code>long</code> 245 * @see #parseLong(String, int) 246 */ parseLong(String s)247 public static long parseLong(String s) 248 { 249 return parseLong(s, 10, false); 250 } 251 252 /** 253 * Creates a new <code>Long</code> object using the <code>String</code> 254 * and specified radix (base). 255 * 256 * @param s the <code>String</code> to convert 257 * @param radix the radix (base) to convert with 258 * @return the new <code>Long</code> 259 * @throws NumberFormatException if <code>s</code> cannot be parsed as a 260 * <code>long</code> 261 * @see #parseLong(String, int) 262 */ valueOf(String s, int radix)263 public static Long valueOf(String s, int radix) 264 { 265 return new Long(parseLong(s, radix, false)); 266 } 267 268 /** 269 * Creates a new <code>Long</code> object using the <code>String</code>, 270 * assuming a radix of 10. 271 * 272 * @param s the <code>String</code> to convert 273 * @return the new <code>Long</code> 274 * @throws NumberFormatException if <code>s</code> cannot be parsed as a 275 * <code>long</code> 276 * @see #Long(String) 277 * @see #parseLong(String) 278 */ valueOf(String s)279 public static Long valueOf(String s) 280 { 281 return new Long(parseLong(s, 10, false)); 282 } 283 284 /** 285 * Convert the specified <code>String</code> into a <code>Long</code>. 286 * The <code>String</code> may represent decimal, hexadecimal, or 287 * octal numbers. 288 * 289 * <p>The extended BNF grammar is as follows:<br> 290 * <pre> 291 * <em>DecodableString</em>: 292 * ( [ <code>-</code> ] <em>DecimalNumber</em> ) 293 * | ( [ <code>-</code> ] ( <code>0x</code> | <code>0X</code> 294 * | <code>#</code> ) <em>HexDigit</em> { <em>HexDigit</em> } ) 295 * | ( [ <code>-</code> ] <code>0</code> { <em>OctalDigit</em> } ) 296 * <em>DecimalNumber</em>: 297 * <em>DecimalDigit except '0'</em> { <em>DecimalDigit</em> } 298 * <em>DecimalDigit</em>: 299 * <em>Character.digit(d, 10) has value 0 to 9</em> 300 * <em>OctalDigit</em>: 301 * <em>Character.digit(d, 8) has value 0 to 7</em> 302 * <em>DecimalDigit</em>: 303 * <em>Character.digit(d, 16) has value 0 to 15</em> 304 * </pre> 305 * Finally, the value must be in the range <code>MIN_VALUE</code> to 306 * <code>MAX_VALUE</code>, or an exception is thrown. Note that you cannot 307 * use a trailing 'l' or 'L', unlike in Java source code. 308 * 309 * @param s the <code>String</code> to interpret 310 * @return the value of the String as a <code>Long</code> 311 * @throws NumberFormatException if <code>s</code> cannot be parsed as a 312 * <code>long</code> 313 * @throws NullPointerException if <code>s</code> is null 314 * @since 1.2 315 */ decode(String str)316 public static Long decode(String str) 317 { 318 return new Long(parseLong(str, 10, true)); 319 } 320 321 /** 322 * Return the value of this <code>Long</code> as a <code>byte</code>. 323 * 324 * @return the byte value 325 */ byteValue()326 public byte byteValue() 327 { 328 return (byte) value; 329 } 330 331 /** 332 * Return the value of this <code>Long</code> as a <code>short</code>. 333 * 334 * @return the short value 335 */ shortValue()336 public short shortValue() 337 { 338 return (short) value; 339 } 340 341 /** 342 * Return the value of this <code>Long</code> as an <code>int</code>. 343 * 344 * @return the int value 345 */ intValue()346 public int intValue() 347 { 348 return (int) value; 349 } 350 351 /** 352 * Return the value of this <code>Long</code>. 353 * 354 * @return the long value 355 */ longValue()356 public long longValue() 357 { 358 return value; 359 } 360 361 /** 362 * Return the value of this <code>Long</code> as a <code>float</code>. 363 * 364 * @return the float value 365 */ floatValue()366 public float floatValue() 367 { 368 return value; 369 } 370 371 /** 372 * Return the value of this <code>Long</code> as a <code>double</code>. 373 * 374 * @return the double value 375 */ doubleValue()376 public double doubleValue() 377 { 378 return value; 379 } 380 381 /** 382 * Converts the <code>Long</code> value to a <code>String</code> and 383 * assumes a radix of 10. 384 * 385 * @return the <code>String</code> representation 386 */ toString()387 public String toString() 388 { 389 return toString(value, 10); 390 } 391 392 /** 393 * Return a hashcode representing this Object. <code>Long</code>'s hash 394 * code is calculated by <code>(int) (value ^ (value >> 32))</code>. 395 * 396 * @return this Object's hash code 397 */ hashCode()398 public int hashCode() 399 { 400 return (int) (value ^ (value >>> 32)); 401 } 402 403 /** 404 * Returns <code>true</code> if <code>obj</code> is an instance of 405 * <code>Long</code> and represents the same long value. 406 * 407 * @param obj the object to compare 408 * @return whether these Objects are semantically equal 409 */ equals(Object obj)410 public boolean equals(Object obj) 411 { 412 return obj instanceof Long && value == ((Long) obj).value; 413 } 414 415 /** 416 * Get the specified system property as a <code>Long</code>. The 417 * <code>decode()</code> method will be used to interpret the value of 418 * the property. 419 * 420 * @param nm the name of the system property 421 * @return the system property as a <code>Long</code>, or null if the 422 * property is not found or cannot be decoded 423 * @throws SecurityException if accessing the system property is forbidden 424 * @see System#getProperty(String) 425 * @see #decode(String) 426 */ getLong(String nm)427 public static Long getLong(String nm) 428 { 429 return getLong(nm, null); 430 } 431 432 /** 433 * Get the specified system property as a <code>Long</code>, or use a 434 * default <code>long</code> value if the property is not found or is not 435 * decodable. The <code>decode()</code> method will be used to interpret 436 * the value of the property. 437 * 438 * @param nm the name of the system property 439 * @param val the default value 440 * @return the value of the system property, or the default 441 * @throws SecurityException if accessing the system property is forbidden 442 * @see System#getProperty(String) 443 * @see #decode(String) 444 */ getLong(String nm, long val)445 public static Long getLong(String nm, long val) 446 { 447 Long result = getLong(nm, null); 448 return result == null ? new Long(val) : result; 449 } 450 451 /** 452 * Get the specified system property as a <code>Long</code>, or use a 453 * default <code>Long</code> value if the property is not found or is 454 * not decodable. The <code>decode()</code> method will be used to 455 * interpret the value of the property. 456 * 457 * @param nm the name of the system property 458 * @param val the default value 459 * @return the value of the system property, or the default 460 * @throws SecurityException if accessing the system property is forbidden 461 * @see System#getProperty(String) 462 * @see #decode(String) 463 */ getLong(String nm, Long def)464 public static Long getLong(String nm, Long def) 465 { 466 if (nm == null || "".equals(nm)) 467 return def; 468 nm = System.getProperty(nm); 469 if (nm == null) 470 return def; 471 try 472 { 473 return decode(nm); 474 } 475 catch (NumberFormatException e) 476 { 477 return def; 478 } 479 } 480 481 /** 482 * Compare two Longs numerically by comparing their <code>long</code> 483 * values. The result is positive if the first is greater, negative if the 484 * second is greater, and 0 if the two are equal. 485 * 486 * @param l the Long to compare 487 * @return the comparison 488 * @since 1.2 489 */ compareTo(Long l)490 public int compareTo(Long l) 491 { 492 if (value == l.value) 493 return 0; 494 // Returns just -1 or 1 on inequality; doing math might overflow the long. 495 return value > l.value ? 1 : -1; 496 } 497 498 /** 499 * Behaves like <code>compareTo(Long)</code> unless the Object 500 * is not a <code>Long</code>. 501 * 502 * @param o the object to compare 503 * @return the comparison 504 * @throws ClassCastException if the argument is not a <code>Long</code> 505 * @see #compareTo(Long) 506 * @see Comparable 507 * @since 1.2 508 */ compareTo(Object o)509 public int compareTo(Object o) 510 { 511 return compareTo((Long) o); 512 } 513 514 /** 515 * Helper for converting unsigned numbers to String. 516 * 517 * @param num the number 518 * @param exp log2(digit) (ie. 1, 3, or 4 for binary, oct, hex) 519 */ toUnsignedString(long num, int exp)520 private static String toUnsignedString(long num, int exp) 521 { 522 // Use the Integer toUnsignedString for efficiency if possible. 523 // If NUM<0 then this particular optimization doesn't work 524 // properly. 525 if (num >= 0 && (int) num == num) 526 return Integer.toUnsignedString((int) num, exp); 527 528 // Use an array large enough for a binary number. 529 int mask = (1 << exp) - 1; 530 char[] buffer = new char[64]; 531 int i = 64; 532 do 533 { 534 buffer[--i] = digits[(int) num & mask]; 535 num >>>= exp; 536 } 537 while (num != 0); 538 539 // Package constructor avoids an array copy. 540 return new String(buffer, i, 64 - i, true); 541 } 542 543 /** 544 * Helper for parsing longs. 545 * 546 * @param str the string to parse 547 * @param radix the radix to use, must be 10 if decode is true 548 * @param decode if called from decode 549 * @return the parsed long value 550 * @throws NumberFormatException if there is an error 551 * @throws NullPointerException if decode is true and str is null 552 * @see #parseLong(String, int) 553 * @see #decode(String) 554 */ parseLong(String str, int radix, boolean decode)555 private static long parseLong(String str, int radix, boolean decode) 556 { 557 if (! decode && str == null) 558 throw new NumberFormatException(); 559 int index = 0; 560 int len = str.length(); 561 boolean isNeg = false; 562 if (len == 0) 563 throw new NumberFormatException(); 564 int ch = str.charAt(index); 565 if (ch == '-') 566 { 567 if (len == 1) 568 throw new NumberFormatException(); 569 isNeg = true; 570 ch = str.charAt(++index); 571 } 572 if (decode) 573 { 574 if (ch == '0') 575 { 576 if (++index == len) 577 return 0; 578 if ((str.charAt(index) & ~('x' ^ 'X')) == 'X') 579 { 580 radix = 16; 581 index++; 582 } 583 else 584 radix = 8; 585 } 586 else if (ch == '#') 587 { 588 radix = 16; 589 index++; 590 } 591 } 592 if (index == len) 593 throw new NumberFormatException(); 594 595 long max = MAX_VALUE / radix; 596 // We can't directly write `max = (MAX_VALUE + 1) / radix'. 597 // So instead we fake it. 598 if (isNeg && MAX_VALUE % radix == radix - 1) 599 ++max; 600 601 long val = 0; 602 while (index < len) 603 { 604 if (val < 0 || val > max) 605 throw new NumberFormatException(); 606 607 ch = Character.digit(str.charAt(index++), radix); 608 val = val * radix + ch; 609 if (ch < 0 || (val < 0 && (! isNeg || val != MIN_VALUE))) 610 throw new NumberFormatException(); 611 } 612 return isNeg ? -val : val; 613 } 614 } 615