1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 // BEGIN android-note 19 // Reimiplemented toString, bit-twiddling, etc. Faster and cleaner. 20 // BEGIN android-note 21 22 package java.lang; 23 24 /** 25 * The wrapper for the primitive type {@code long}. 26 * <p> 27 * Implementation note: The "bit twiddling" methods in this class use techniques 28 * described in <a href="http://www.hackersdelight.org/">Henry S. Warren, 29 * Jr.'s Hacker's Delight, (Addison Wesley, 2002)</a> and <a href= 30 * "http://graphics.stanford.edu/~seander/bithacks.html">Sean Anderson's 31 * Bit Twiddling Hacks.</a> 32 * 33 * @see java.lang.Integer 34 * @since 1.0 35 */ 36 public final class Long extends Number implements Comparable<Long> { 37 38 private static final long serialVersionUID = 4290774380558885855L; 39 40 /** 41 * The value which the receiver represents. 42 */ 43 private final long value; 44 45 /** 46 * Constant for the maximum {@code long} value, 2<sup>63</sup>-1. 47 */ 48 public static final long MAX_VALUE = 0x7FFFFFFFFFFFFFFFL; 49 50 /** 51 * Constant for the minimum {@code long} value, -2<sup>63</sup>. 52 */ 53 public static final long MIN_VALUE = 0x8000000000000000L; 54 55 /** 56 * The {@link Class} object that represents the primitive type {@code long}. 57 */ 58 @SuppressWarnings("unchecked") 59 public static final Class<Long> TYPE 60 = (Class<Long>) long[].class.getComponentType(); 61 // Note: Long.TYPE can't be set to "long.class", since *that* is 62 // defined to be "java.lang.Long.TYPE"; 63 64 /** 65 * Constant for the number of bits needed to represent a {@code long} in 66 * two's complement form. 67 * 68 * @since 1.5 69 */ 70 public static final int SIZE = 64; 71 72 /** 73 * Constructs a new {@code Long} with the specified primitive long value. 74 * 75 * @param value 76 * the primitive long value to store in the new instance. 77 */ 78 public Long(long value) { 79 this.value = value; 80 } 81 82 /** 83 * Constructs a new {@code Long} from the specified string. 84 * 85 * @param string 86 * the string representation of a long value. 87 * @throws NumberFormatException 88 * if {@code string} can not be decoded into a long value. 89 * @see #parseLong(String) 90 */ 91 public Long(String string) throws NumberFormatException { 92 this(parseLong(string)); 93 } 94 95 @Override 96 public byte byteValue() { 97 return (byte) value; 98 } 99 100 /** 101 * Compares this object to the specified long object to determine their 102 * relative order. 103 * 104 * @param object 105 * the long object to compare this object to. 106 * @return a negative value if the value of this long is less than the value 107 * of {@code object}; 0 if the value of this long and the value of 108 * {@code object} are equal; a positive value if the value of this 109 * long is greater than the value of {@code object}. 110 * @see java.lang.Comparable 111 * @since 1.2 112 */ 113 public int compareTo(Long object) { 114 long thisValue = this.value; 115 long thatValue = object.value; 116 return thisValue < thatValue ? -1 : (thisValue == thatValue ? 0 : 1); 117 } 118 119 /** 120 * Parses the specified string and returns a {@code Long} instance if the 121 * string can be decoded into a long value. The string may be an optional 122 * minus sign "-" followed by a hexadecimal ("0x..." or "#..."), octal 123 * ("0..."), or decimal ("...") representation of a long. 124 * 125 * @param string 126 * a string representation of a long value. 127 * @return a {@code Long} containing the value represented by {@code string}. 128 * @throws NumberFormatException 129 * if {@code string} can not be parsed as a long value. 130 */ 131 public static Long decode(String string) throws NumberFormatException { 132 int length = string.length(), i = 0; 133 if (length == 0) { 134 throw new NumberFormatException(); 135 } 136 char firstDigit = string.charAt(i); 137 boolean negative = firstDigit == '-'; 138 if (negative) { 139 if (length == 1) { 140 throw new NumberFormatException(string); 141 } 142 firstDigit = string.charAt(++i); 143 } 144 145 int base = 10; 146 if (firstDigit == '0') { 147 if (++i == length) { 148 return valueOf(0L); 149 } 150 if ((firstDigit = string.charAt(i)) == 'x' || firstDigit == 'X') { 151 if (i == length) { 152 throw new NumberFormatException(string); 153 } 154 i++; 155 base = 16; 156 } else { 157 base = 8; 158 } 159 } else if (firstDigit == '#') { 160 if (i == length) { 161 throw new NumberFormatException(string); 162 } 163 i++; 164 base = 16; 165 } 166 167 long result = parse(string, i, base, negative); 168 return valueOf(result); 169 } 170 171 @Override 172 public double doubleValue() { 173 return value; 174 } 175 176 /** 177 * Compares this instance with the specified object and indicates if they 178 * are equal. In order to be equal, {@code o} must be an instance of 179 * {@code Long} and have the same long value as this object. 180 * 181 * @param o 182 * the object to compare this long with. 183 * @return {@code true} if the specified object is equal to this 184 * {@code Long}; {@code false} otherwise. 185 */ 186 @Override 187 public boolean equals(Object o) { 188 return o instanceof Long && ((Long) o).value == value; 189 } 190 191 @Override 192 public float floatValue() { 193 return value; 194 } 195 196 /** 197 * Returns the {@code Long} value of the system property identified by 198 * {@code string}. Returns {@code null} if {@code string} is {@code null} 199 * or empty, if the property can not be found or if its value can not be 200 * parsed as a long. 201 * 202 * @param string 203 * the name of the requested system property. 204 * @return the requested property's value as a {@code Long} or {@code null}. 205 */ 206 public static Long getLong(String string) { 207 if (string == null || string.length() == 0) { 208 return null; 209 } 210 String prop = System.getProperty(string); 211 if (prop == null) { 212 return null; 213 } 214 try { 215 return decode(prop); 216 } catch (NumberFormatException ex) { 217 return null; 218 } 219 } 220 221 /** 222 * Returns the {@code Long} value of the system property identified by 223 * {@code string}. Returns the specified default value if {@code string} is 224 * {@code null} or empty, if the property can not be found or if its value 225 * can not be parsed as a long. 226 * 227 * @param string 228 * the name of the requested system property. 229 * @param defaultValue 230 * the default value that is returned if there is no long system 231 * property with the requested name. 232 * @return the requested property's value as a {@code Long} or the default 233 * value. 234 */ 235 public static Long getLong(String string, long defaultValue) { 236 if (string == null || string.length() == 0) { 237 return valueOf(defaultValue); 238 } 239 String prop = System.getProperty(string); 240 if (prop == null) { 241 return valueOf(defaultValue); 242 } 243 try { 244 return decode(prop); 245 } catch (NumberFormatException ex) { 246 return valueOf(defaultValue); 247 } 248 } 249 250 /** 251 * Returns the {@code Long} value of the system property identified by 252 * {@code string}. Returns the specified default value if {@code string} is 253 * {@code null} or empty, if the property can not be found or if its value 254 * can not be parsed as a long. 255 * 256 * @param string 257 * the name of the requested system property. 258 * @param defaultValue 259 * the default value that is returned if there is no long system 260 * property with the requested name. 261 * @return the requested property's value as a {@code Long} or the default 262 * value. 263 */ 264 public static Long getLong(String string, Long defaultValue) { 265 if (string == null || string.length() == 0) { 266 return defaultValue; 267 } 268 String prop = System.getProperty(string); 269 if (prop == null) { 270 return defaultValue; 271 } 272 try { 273 return decode(prop); 274 } catch (NumberFormatException ex) { 275 return defaultValue; 276 } 277 } 278 279 @Override 280 public int hashCode() { 281 return (int) (value ^ (value >>> 32)); 282 } 283 284 @Override 285 public int intValue() { 286 return (int) value; 287 } 288 289 /** 290 * Gets the primitive value of this long. 291 * 292 * @return this object's primitive value. 293 */ 294 @Override 295 public long longValue() { 296 return value; 297 } 298 299 /** 300 * Parses the specified string as a signed decimal long value. The ASCII 301 * character \u002d ('-') is recognized as the minus sign. 302 * 303 * @param string 304 * the string representation of a long value. 305 * @return the primitive long value represented by {@code string}. 306 * @throws NumberFormatException 307 * if {@code string} is {@code null}, has a length of zero or 308 * can not be parsed as a long value. 309 */ 310 public static long parseLong(String string) throws NumberFormatException { 311 return parseLong(string, 10); 312 } 313 314 /** 315 * Parses the specified string as a signed long value using the specified 316 * radix. The ASCII character \u002d ('-') is recognized as the minus sign. 317 * 318 * @param string 319 * the string representation of a long value. 320 * @param radix 321 * the radix to use when parsing. 322 * @return the primitive long value represented by {@code string} using 323 * {@code radix}. 324 * @throws NumberFormatException 325 * if {@code string} is {@code null} or has a length of zero, 326 * {@code radix < Character.MIN_RADIX}, 327 * {@code radix > Character.MAX_RADIX}, or if {@code string} 328 * can not be parsed as a long value. 329 */ 330 public static long parseLong(String string, int radix) throws NumberFormatException { 331 if (string == null || radix < Character.MIN_RADIX 332 || radix > Character.MAX_RADIX) { 333 throw new NumberFormatException(); 334 } 335 int length = string.length(), i = 0; 336 if (length == 0) { 337 throw new NumberFormatException(string); 338 } 339 boolean negative = string.charAt(i) == '-'; 340 if (negative && ++i == length) { 341 throw new NumberFormatException(string); 342 } 343 344 return parse(string, i, radix, negative); 345 } 346 347 private static long parse(String string, int offset, int radix, boolean negative) { 348 long max = Long.MIN_VALUE / radix; 349 long result = 0, length = string.length(); 350 while (offset < length) { 351 int digit = Character.digit(string.charAt(offset++), radix); 352 if (digit == -1) { 353 throw new NumberFormatException(string); 354 } 355 if (max > result) { 356 throw new NumberFormatException(string); 357 } 358 long next = result * radix - digit; 359 if (next > result) { 360 throw new NumberFormatException(string); 361 } 362 result = next; 363 } 364 if (!negative) { 365 result = -result; 366 if (result < 0) { 367 throw new NumberFormatException(string); 368 } 369 } 370 return result; 371 } 372 373 @Override 374 public short shortValue() { 375 return (short) value; 376 } 377 378 /** 379 * Converts the specified long value into its binary string representation. 380 * The returned string is a concatenation of '0' and '1' characters. 381 * 382 * @param v 383 * the long value to convert. 384 * @return the binary string representation of {@code v}. 385 */ 386 public static String toBinaryString(long v) { 387 return IntegralToString.longToBinaryString(v); 388 } 389 390 /** 391 * Converts the specified long value into its hexadecimal string 392 * representation. The returned string is a concatenation of characters from 393 * '0' to '9' and 'a' to 'f'. 394 * 395 * @param v 396 * the long value to convert. 397 * @return the hexadecimal string representation of {@code l}. 398 */ 399 public static String toHexString(long v) { 400 return IntegralToString.longToHexString(v); 401 } 402 403 /** 404 * Converts the specified long value into its octal string representation. 405 * The returned string is a concatenation of characters from '0' to '7'. 406 * 407 * @param v 408 * the long value to convert. 409 * @return the octal string representation of {@code l}. 410 */ 411 public static String toOctalString(long v) { 412 return IntegralToString.longToOctalString(v); 413 } 414 415 @Override 416 public String toString() { 417 return Long.toString(value); 418 } 419 420 /** 421 * Converts the specified long value into its decimal string representation. 422 * The returned string is a concatenation of a minus sign if the number is 423 * negative and characters from '0' to '9'. 424 * 425 * @param n 426 * the long to convert. 427 * @return the decimal string representation of {@code l}. 428 */ 429 public static String toString(long n) { 430 return IntegralToString.longToString(n); 431 } 432 433 /** 434 * Converts the specified signed long value into a string representation based on 435 * the specified radix. The returned string is a concatenation of a minus 436 * sign if the number is negative and characters from '0' to '9' and 'a' to 437 * 'z', depending on the radix. If {@code radix} is not in the interval 438 * defined by {@code Character.MIN_RADIX} and {@code Character.MAX_RADIX} 439 * then 10 is used as the base for the conversion. 440 * 441 * <p>This method treats its argument as signed. If you want to convert an 442 * unsigned value to one of the common non-decimal bases, you may find 443 * {@link #toBinaryString}, {@code #toHexString}, or {@link #toOctalString} 444 * more convenient. 445 * 446 * @param v 447 * the signed long to convert. 448 * @param radix 449 * the base to use for the conversion. 450 * @return the string representation of {@code v}. 451 */ 452 public static String toString(long v, int radix) { 453 return IntegralToString.longToString(v, radix); 454 } 455 456 /** 457 * Parses the specified string as a signed decimal long value. 458 * 459 * @param string 460 * the string representation of a long value. 461 * @return a {@code Long} instance containing the long value represented by 462 * {@code string}. 463 * @throws NumberFormatException 464 * if {@code string} is {@code null}, has a length of zero or 465 * can not be parsed as a long value. 466 * @see #parseLong(String) 467 */ 468 public static Long valueOf(String string) throws NumberFormatException { 469 return valueOf(parseLong(string)); 470 } 471 472 /** 473 * Parses the specified string as a signed long value using the specified 474 * radix. 475 * 476 * @param string 477 * the string representation of a long value. 478 * @param radix 479 * the radix to use when parsing. 480 * @return a {@code Long} instance containing the long value represented by 481 * {@code string} using {@code radix}. 482 * @throws NumberFormatException 483 * if {@code string} is {@code null} or has a length of zero, 484 * {@code radix < Character.MIN_RADIX}, 485 * {@code radix > Character.MAX_RADIX}, or if {@code string} 486 * can not be parsed as a long value. 487 * @see #parseLong(String, int) 488 */ 489 public static Long valueOf(String string, int radix) throws NumberFormatException { 490 return valueOf(parseLong(string, radix)); 491 } 492 493 /** 494 * Determines the highest (leftmost) bit of the specified long value that is 495 * 1 and returns the bit mask value for that bit. This is also referred to 496 * as the Most Significant 1 Bit. Returns zero if the specified long is 497 * zero. 498 * 499 * @param v 500 * the long to examine. 501 * @return the bit mask indicating the highest 1 bit in {@code v}. 502 * @since 1.5 503 */ 504 public static long highestOneBit(long v) { 505 // Hacker's Delight, Figure 3-1 506 v |= (v >> 1); 507 v |= (v >> 2); 508 v |= (v >> 4); 509 v |= (v >> 8); 510 v |= (v >> 16); 511 v |= (v >> 32); 512 return v - (v >>> 1); 513 } 514 515 /** 516 * Determines the lowest (rightmost) bit of the specified long value that is 517 * 1 and returns the bit mask value for that bit. This is also referred to 518 * as the Least Significant 1 Bit. Returns zero if the specified long is 519 * zero. 520 * 521 * @param v 522 * the long to examine. 523 * @return the bit mask indicating the lowest 1 bit in {@code v}. 524 * @since 1.5 525 */ 526 public static long lowestOneBit(long v) { 527 return v & -v; 528 } 529 530 /** 531 * Determines the number of leading zeros in the specified long value prior 532 * to the {@link #highestOneBit(long) highest one bit}. 533 * 534 * @param v 535 * the long to examine. 536 * @return the number of leading zeros in {@code v}. 537 * @since 1.5 538 */ 539 public static int numberOfLeadingZeros(long v) { 540 // After Hacker's Delight, Figure 5-6 541 if (v < 0) { 542 return 0; 543 } 544 if (v == 0) { 545 return 64; 546 } 547 // On a 64-bit VM, the two previous tests should probably be replaced by 548 // if (v <= 0) return ((int) (~v >> 57)) & 64; 549 550 int n = 1; 551 int i = (int) (v >>> 32); 552 if (i == 0) { 553 n += 32; 554 i = (int) v; 555 } 556 if (i >>> 16 == 0) { 557 n += 16; 558 i <<= 16; 559 } 560 if (i >>> 24 == 0) { 561 n += 8; 562 i <<= 8; 563 } 564 if (i >>> 28 == 0) { 565 n += 4; 566 i <<= 4; 567 } 568 if (i >>> 30 == 0) { 569 n += 2; 570 i <<= 2; 571 } 572 return n - (i >>> 31); 573 } 574 575 /** 576 * Determines the number of trailing zeros in the specified long value after 577 * the {@link #lowestOneBit(long) lowest one bit}. 578 * 579 * @param v 580 * the long to examine. 581 * @return the number of trailing zeros in {@code v}. 582 * @since 1.5 583 */ 584 public static int numberOfTrailingZeros(long v) { 585 int low = (int) v; 586 return low !=0 ? Integer.numberOfTrailingZeros(low) 587 : 32 + Integer.numberOfTrailingZeros((int) (v >>> 32)); 588 } 589 590 /** 591 * Counts the number of 1 bits in the specified long value; this is also 592 * referred to as population count. 593 * 594 * @param v 595 * the long to examine. 596 * @return the number of 1 bits in {@code v}. 597 * @since 1.5 598 */ 599 public static int bitCount(long v) { 600 // Combines techniques from several sources 601 v -= (v >>> 1) & 0x5555555555555555L; 602 v = (v & 0x3333333333333333L) + ((v >>> 2) & 0x3333333333333333L); 603 int i = ((int)(v >>> 32)) + (int) v; 604 i = (i & 0x0F0F0F0F) + ((i >>> 4) & 0x0F0F0F0F); 605 i += i >>> 8; 606 i += i >>> 16; 607 return i & 0x0000007F; 608 } 609 610 /* 611 * On a modern 64-bit processor with a fast hardware multiply, this is 612 * much faster (assuming you're running a 64-bit VM): 613 * 614 * // http://chessprogramming.wikispaces.com/Population+Count 615 * int bitCount (long x) { 616 * x -= (x >>> 1) & 0x5555555555555555L; 617 * x = (x & 0x3333333333333333L) + ((x >>> 2) & 0x3333333333333333L); 618 * x = (x + (x >>> 4)) & 0x0f0f0f0f0f0f0f0fL; 619 * x = (x * 0x0101010101010101L) >>> 56; 620 * return (int) x; 621 * } 622 * 623 * Really modern processors (e.g., Nehalem, K-10) have hardware popcount 624 * instructions. 625 */ 626 627 /** 628 * Rotates the bits of the specified long value to the left by the specified 629 * number of bits. 630 * 631 * @param v 632 * the long value to rotate left. 633 * @param distance 634 * the number of bits to rotate. 635 * @return the rotated value. 636 * @since 1.5 637 */ 638 public static long rotateLeft(long v, int distance) { 639 // Shift distances are mod 64 (JLS3 15.19), so we needn't mask -distance 640 return (v << distance) | (v >>> -distance); 641 } 642 643 /** 644 * Rotates the bits of the specified long value to the right by the 645 * specified number of bits. 646 * 647 * @param v 648 * the long value to rotate right. 649 * @param distance 650 * the number of bits to rotate. 651 * @return the rotated value. 652 * @since 1.5 653 */ 654 public static long rotateRight(long v, int distance) { 655 // Shift distances are mod 64 (JLS3 15.19), so we needn't mask -distance 656 return (v >>> distance) | (v << -distance); 657 } 658 659 /** 660 * Reverses the order of the bytes of the specified long value. 661 * 662 * @param v 663 * the long value for which to reverse the byte order. 664 * @return the reversed value. 665 * @since 1.5 666 */ 667 public static long reverseBytes(long v) { 668 // Hacker's Delight 7-1, with minor tweak from Veldmeijer 669 // http://graphics.stanford.edu/~seander/bithacks.html 670 v = ((v >>> 8) & 0x00FF00FF00FF00FFL) | ((v & 0x00FF00FF00FF00FFL) << 8); 671 v = ((v >>>16) & 0x0000FFFF0000FFFFL) | ((v & 0x0000FFFF0000FFFFL) <<16); 672 return ((v >>>32) ) | ((v ) <<32); 673 } 674 675 /** 676 * Reverses the order of the bits of the specified long value. 677 * 678 * @param v 679 * the long value for which to reverse the bit order. 680 * @return the reversed value. 681 * @since 1.5 682 */ 683 public static long reverse(long v) { 684 // Hacker's Delight 7-1, with minor tweak from Veldmeijer 685 // http://graphics.stanford.edu/~seander/bithacks.html 686 v = ((v >>> 1) & 0x5555555555555555L) | ((v & 0x5555555555555555L) << 1); 687 v = ((v >>> 2) & 0x3333333333333333L) | ((v & 0x3333333333333333L) << 2); 688 v = ((v >>> 4) & 0x0F0F0F0F0F0F0F0FL) | ((v & 0x0F0F0F0F0F0F0F0FL) << 4); 689 v = ((v >>> 8) & 0x00FF00FF00FF00FFL) | ((v & 0x00FF00FF00FF00FFL) << 8); 690 v = ((v >>>16) & 0x0000FFFF0000FFFFL) | ((v & 0x0000FFFF0000FFFFL) <<16); 691 return ((v >>>32) ) | ((v ) <<32); 692 } 693 694 /** 695 * Returns the value of the {@code signum} function for the specified long 696 * value. 697 * 698 * @param v 699 * the long value to check. 700 * @return -1 if {@code v} is negative, 1 if {@code v} is positive, 0 if 701 * {@code v} is zero. 702 * @since 1.5 703 */ 704 public static int signum(long v) { 705 // BEGIN android-changed 706 return v < 0 ? -1 : (v == 0 ? 0 : 1); 707 // END android-changed 708 // The following branch-free version is faster on modern desktops/servers 709 // return ((int)(v >> 63)) | (int) (-v >>> 63); // Hacker's delight 2-7 710 } 711 712 /** 713 * Returns a {@code Long} instance for the specified long value. 714 * <p> 715 * If it is not necessary to get a new {@code Long} instance, it is 716 * recommended to use this method instead of the constructor, since it 717 * maintains a cache of instances which may result in better performance. 718 * 719 * @param v 720 * the long value to store in the instance. 721 * @return a {@code Long} instance containing {@code v}. 722 * @since 1.5 723 */ 724 public static Long valueOf(long v) { 725 return v >= 128 || v < -128 ? new Long(v) 726 : SMALL_VALUES[((int) v) + 128]; 727 } 728 729 /** 730 * A cache of instances used by {@link Long#valueOf(long)} and auto-boxing. 731 */ 732 private static final Long[] SMALL_VALUES = new Long[256]; 733 734 static { 735 for(int i = -128; i < 128; i++) { 736 SMALL_VALUES[i + 128] = new Long(i); 737 } 738 } 739 } 740