001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package java.lang;
019:
020: /**
021: * <p>
022: * Long is the wrapper for the primitive type <code>long</code>.
023: * </p>
024: *
025: * <p>
026: * As with the specification, this implementation relied on code laid out in <a
027: * href="http://www.hackersdelight.org/">Henry S. Warren, Jr.'s Hacker's
028: * Delight, (Addison Wesley, 2002)</a> as well as <a
029: * href="http://aggregate.org/MAGIC/">The Aggregate's Magic Algorithms</a>.
030: * </p>
031: *
032: * @see java.lang.Number
033: * @since 1.0
034: */
035: public final class Long extends Number implements Comparable<Long> {
036:
037: private static final long serialVersionUID = 4290774380558885855L;
038:
039: /**
040: * The value which the receiver represents.
041: */
042: private final long value;
043:
044: /**
045: * <p>
046: * Constant for the maximum <code>long</code> value, 2<sup>63</sup>-1.
047: * </p>
048: */
049: public static final long MAX_VALUE = 0x7FFFFFFFFFFFFFFFL;
050:
051: /**
052: * <p>
053: * Constant for the minimum <code>long</code> value, -2<sup>31</sup>.
054: * </p>
055: */
056: public static final long MIN_VALUE = 0x8000000000000000L;
057:
058: /**
059: * The java.lang.Class that represents this class.
060: */
061: @SuppressWarnings("unchecked")
062: public static final Class<Long> TYPE = (Class<Long>) new long[0]
063: .getClass().getComponentType();
064:
065: // Note: This can't be set to "long.class", since *that* is
066: // defined to be "java.lang.Long.TYPE";
067:
068: /**
069: * <p>
070: * Constant for the number of bits to represent a <code>long</code> in
071: * two's compliment form.
072: * </p>
073: *
074: * @since 1.5
075: */
076: public static final int SIZE = 64;
077:
078: /**
079: * Constructs a new instance of the receiver which represents the long
080: * valued argument.
081: *
082: * @param value
083: * the long to store in the new instance.
084: */
085: public Long(long value) {
086: this .value = value;
087: }
088:
089: /**
090: * Constructs a new instance of this class given a string.
091: *
092: * @param string
093: * a string representation of an long quantity.
094: * @exception NumberFormatException
095: * if the argument could not be parsed as a long quantity.
096: */
097: public Long(String string) throws NumberFormatException {
098: this (parseLong(string));
099: }
100:
101: /**
102: * Answers the byte value which the receiver represents
103: *
104: * @return byte the value of the receiver.
105: */
106: @Override
107: public byte byteValue() {
108: return (byte) value;
109: }
110:
111: /**
112: * <p>
113: * Compares this <code>Long</code> to the <code>Long</code> passed. If
114: * this instance's value is equal to the value of the instance passed, then
115: * 0 is returned. If this instance's value is less than the value of the
116: * instance passed, then a negative value is returned. If this instance's
117: * value is greater than the value of the instance passed, then a positive
118: * value is returned.
119: * </p>
120: *
121: * @param object
122: * The instance to compare to.
123: * @throws NullPointerException
124: * if <code>object</code> is <code>null</code>.
125: * @since 1.2
126: */
127: public int compareTo(Long object) {
128: return value > object.value ? 1 : (value < object.value ? -1
129: : 0);
130: }
131:
132: /**
133: * Parses the string argument as if it was a long value and returns the
134: * result. Throws NumberFormatException if the string does not represent a
135: * long quantity. The string may be a hexadecimal ("0x..."), octal ("0..."),
136: * or decimal ("...") representation of a long.
137: *
138: * @param string
139: * a string representation of an long quantity.
140: * @return Long the value represented by the argument
141: * @exception NumberFormatException
142: * if the argument could not be parsed as an long quantity.
143: */
144: public static Long decode(String string)
145: throws NumberFormatException {
146: int length = string.length(), i = 0;
147: if (length == 0) {
148: throw new NumberFormatException();
149: }
150: char firstDigit = string.charAt(i);
151: boolean negative = firstDigit == '-';
152: if (negative) {
153: if (length == 1) {
154: throw new NumberFormatException(string);
155: }
156: firstDigit = string.charAt(++i);
157: }
158:
159: int base = 10;
160: if (firstDigit == '0') {
161: if (++i == length) {
162: return valueOf(0L);
163: }
164: if ((firstDigit = string.charAt(i)) == 'x'
165: || firstDigit == 'X') {
166: if (i == length) {
167: throw new NumberFormatException(string);
168: }
169: i++;
170: base = 16;
171: } else {
172: base = 8;
173: }
174: } else if (firstDigit == '#') {
175: if (i == length) {
176: throw new NumberFormatException(string);
177: }
178: i++;
179: base = 16;
180: }
181:
182: long result = parse(string, i, base, negative);
183: return valueOf(result);
184: }
185:
186: /**
187: * Answers the double value which the receiver represents
188: *
189: * @return double the value of the receiver.
190: */
191: @Override
192: public double doubleValue() {
193: return value;
194: }
195:
196: /**
197: * Compares the argument to the receiver, and answers true if they represent
198: * the <em>same</em> object using a class specific comparison.
199: * <p>
200: * In this case, the argument must also be an Long, and the receiver and
201: * argument must represent the same long value.
202: *
203: * @param o
204: * the object to compare with this object
205: * @return <code>true</code> if the object is the same as this object
206: * <code>false</code> if it is different from this object
207: * @see #hashCode
208: */
209: @Override
210: public boolean equals(Object o) {
211: return (o instanceof Long) && (value == ((Long) o).value);
212: }
213:
214: /**
215: * Answers the float value which the receiver represents
216: *
217: * @return float the value of the receiver.
218: */
219: @Override
220: public float floatValue() {
221: return value;
222: }
223:
224: /**
225: * Answers a Long representing the long value of the property named by the
226: * argument. If the property could not be found, or its value could not be
227: * parsed as a long, answer null.
228: *
229: * @param string
230: * The name of the desired integer property.
231: * @return Long A Long representing the value of the property.
232: */
233: public static Long getLong(String string) {
234: if (string == null || string.length() == 0) {
235: return null;
236: }
237: String prop = System.getProperty(string);
238: if (prop == null) {
239: return null;
240: }
241: try {
242: return decode(prop);
243: } catch (NumberFormatException ex) {
244: return null;
245: }
246: }
247:
248: /**
249: * Answers a Long representing the long value of the property named by the
250: * argument. If the property could not be found, or its value could not be
251: * parsed as a long, answer a Long representing the second argument.
252: *
253: * @param string
254: * The name of the desired long property.
255: * @return Long An Long representing the value of the property.
256: */
257: public static Long getLong(String string, long defaultValue) {
258: if (string == null || string.length() == 0) {
259: return valueOf(defaultValue);
260: }
261: String prop = System.getProperty(string);
262: if (prop == null) {
263: return valueOf(defaultValue);
264: }
265: try {
266: return decode(prop);
267: } catch (NumberFormatException ex) {
268: return valueOf(defaultValue);
269: }
270: }
271:
272: /**
273: * Answers an Long representing the long value of the property named by the
274: * argument. If the property could not be found, or its value could not be
275: * parsed as an long, answer the second argument.
276: *
277: * @param string
278: * The name of the desired long property.
279: * @return Long An Long representing the value of the property.
280: */
281: public static Long getLong(String string, Long defaultValue) {
282: if (string == null || string.length() == 0) {
283: return defaultValue;
284: }
285: String prop = System.getProperty(string);
286: if (prop == null) {
287: return defaultValue;
288: }
289: try {
290: return decode(prop);
291: } catch (NumberFormatException ex) {
292: return defaultValue;
293: }
294: }
295:
296: /**
297: * Answers an integer hash code for the receiver. Any two objects which
298: * answer <code>true</code> when passed to <code>equals</code> must
299: * answer the same value for this method.
300: *
301: * @return the receiver's hash
302: *
303: * @see #equals
304: */
305: @Override
306: public int hashCode() {
307: return (int) (value ^ (value >>> 32));
308: }
309:
310: /**
311: * Answers the int value which the receiver represents
312: *
313: * @return int the value of the receiver.
314: */
315: @Override
316: public int intValue() {
317: return (int) value;
318: }
319:
320: /**
321: * Answers the long value which the receiver represents
322: *
323: * @return long the value of the receiver.
324: */
325: @Override
326: public long longValue() {
327: return value;
328: }
329:
330: /**
331: * Parses the string argument as if it was a long value and returns the
332: * result. Throws NumberFormatException if the string does not represent a
333: * long quantity.
334: *
335: * @param string
336: * a string representation of a long quantity.
337: * @return long the value represented by the argument
338: * @exception NumberFormatException
339: * if the argument could not be parsed as a long quantity.
340: */
341: public static long parseLong(String string)
342: throws NumberFormatException {
343: return parseLong(string, 10);
344: }
345:
346: /**
347: * Parses the string argument as if it was an long value and returns the
348: * result. Throws NumberFormatException if the string does not represent an
349: * long quantity. The second argument specifies the radix to use when
350: * parsing the value.
351: *
352: * @param string
353: * a string representation of an long quantity.
354: * @param radix
355: * the base to use for conversion.
356: * @return long the value represented by the argument
357: * @exception NumberFormatException
358: * if the argument could not be parsed as an long quantity.
359: */
360: public static long parseLong(String string, int radix)
361: throws NumberFormatException {
362: if (string == null || radix < Character.MIN_RADIX
363: || radix > Character.MAX_RADIX) {
364: throw new NumberFormatException();
365: }
366: int length = string.length(), i = 0;
367: if (length == 0) {
368: throw new NumberFormatException(string);
369: }
370: boolean negative = string.charAt(i) == '-';
371: if (negative && ++i == length) {
372: throw new NumberFormatException(string);
373: }
374:
375: return parse(string, i, radix, negative);
376: }
377:
378: private static long parse(String string, int offset, int radix,
379: boolean negative) {
380: long max = Long.MIN_VALUE / radix;
381: long result = 0, length = string.length();
382: while (offset < length) {
383: int digit = Character.digit(string.charAt(offset++), radix);
384: if (digit == -1) {
385: throw new NumberFormatException(string);
386: }
387: if (max > result) {
388: throw new NumberFormatException(string);
389: }
390: long next = result * radix - digit;
391: if (next > result) {
392: throw new NumberFormatException(string);
393: }
394: result = next;
395: }
396: if (!negative) {
397: result = -result;
398: if (result < 0) {
399: throw new NumberFormatException(string);
400: }
401: }
402: return result;
403: }
404:
405: /**
406: * Answers the short value which the receiver represents
407: *
408: * @return short the value of the receiver.
409: */
410: @Override
411: public short shortValue() {
412: return (short) value;
413: }
414:
415: /**
416: * Answers a string containing '0' and '1' characters which describe the
417: * binary representation of the argument.
418: *
419: * @param l
420: * a long to get the binary representation of
421: * @return String the binary representation of the argument
422: */
423: public static String toBinaryString(long l) {
424: int count = 1;
425: long j = l;
426:
427: if (l < 0) {
428: count = 64;
429: } else {
430: while ((j >>= 1) != 0) {
431: count++;
432: }
433: }
434:
435: char[] buffer = new char[count];
436: do {
437: buffer[--count] = (char) ((l & 1) + '0');
438: l >>= 1;
439: } while (count > 0);
440: return new String(0, buffer.length, buffer);
441: }
442:
443: /**
444: * Answers a string containing characters in the range 0..7, a..f which
445: * describe the hexadecimal representation of the argument.
446: *
447: * @param l
448: * a long to get the hex representation of
449: * @return String the hex representation of the argument
450: */
451: public static String toHexString(long l) {
452: int count = 1;
453: long j = l;
454:
455: if (l < 0) {
456: count = 16;
457: } else {
458: while ((j >>= 4) != 0) {
459: count++;
460: }
461: }
462:
463: char[] buffer = new char[count];
464: do {
465: int t = (int) (l & 15);
466: if (t > 9) {
467: t = t - 10 + 'a';
468: } else {
469: t += '0';
470: }
471: buffer[--count] = (char) t;
472: l >>= 4;
473: } while (count > 0);
474: return new String(0, buffer.length, buffer);
475: }
476:
477: /**
478: * Answers a string containing characters in the range 0..7 which describe
479: * the octal representation of the argument.
480: *
481: * @param l
482: * a long to get the octal representation of
483: * @return String the octal representation of the argument
484: */
485: public static String toOctalString(long l) {
486: int count = 1;
487: long j = l;
488:
489: if (l < 0) {
490: count = 22;
491: } else {
492: while ((j >>>= 3) != 0) {
493: count++;
494: }
495: }
496:
497: char[] buffer = new char[count];
498: do {
499: buffer[--count] = (char) ((l & 7) + '0');
500: l >>>= 3;
501: } while (count > 0);
502: return new String(0, buffer.length, buffer);
503: }
504:
505: /**
506: * Answers a string containing a concise, human-readable description of the
507: * receiver.
508: *
509: * @return a printable representation for the receiver.
510: */
511: @Override
512: public String toString() {
513: return Long.toString(value);
514: }
515:
516: /**
517: * Answers a string containing characters in the range 0..9 which describe
518: * the decimal representation of the argument.
519: *
520: * @param l
521: * a long to get the representation of
522: * @return String the representation of the argument
523: */
524: public static String toString(long l) {
525: return toString(l, 10);
526: }
527:
528: /**
529: * Answers a string containing characters in the range 0..9, a..z (depending
530: * on the radix) which describe the representation of the argument in that
531: * radix.
532: *
533: * @param l
534: * a long to get the representation of
535: * @param radix
536: * the base to use for conversion.
537: * @return String the representation of the argument
538: */
539: public static String toString(long l, int radix) {
540: if (radix < Character.MIN_RADIX || radix > Character.MAX_RADIX) {
541: radix = 10;
542: }
543: if (l == 0) {
544: return "0"; //$NON-NLS-1$
545: }
546:
547: int count = 2;
548: long j = l;
549: boolean negative = l < 0;
550: if (!negative) {
551: count = 1;
552: j = -l;
553: }
554: while ((l /= radix) != 0) {
555: count++;
556: }
557:
558: char[] buffer = new char[count];
559: do {
560: int ch = 0 - (int) (j % radix);
561: if (ch > 9) {
562: ch = ch - 10 + 'a';
563: } else {
564: ch += '0';
565: }
566: buffer[--count] = (char) ch;
567: } while ((j /= radix) != 0);
568: if (negative) {
569: buffer[0] = '-';
570: }
571: return new String(0, buffer.length, buffer);
572: }
573:
574: /**
575: * Parses the string argument as if it was an long value and returns the
576: * result. Throws NumberFormatException if the string does not represent an
577: * long quantity.
578: *
579: * @param string
580: * a string representation of an long quantity.
581: * @return Long the value represented by the argument
582: * @exception NumberFormatException
583: * if the argument could not be parsed as an long quantity.
584: */
585: public static Long valueOf(String string)
586: throws NumberFormatException {
587: return valueOf(parseLong(string));
588: }
589:
590: /**
591: * Parses the string argument as if it was an long value and returns the
592: * result. Throws NumberFormatException if the string does not represent an
593: * long quantity. The second argument specifies the radix to use when
594: * parsing the value.
595: *
596: * @param string
597: * a string representation of an long quantity.
598: * @param radix
599: * the base to use for conversion.
600: * @return Long the value represented by the argument
601: * @exception NumberFormatException
602: * if the argument could not be parsed as an long quantity.
603: */
604: public static Long valueOf(String string, int radix)
605: throws NumberFormatException {
606: return valueOf(parseLong(string, radix));
607: }
608:
609: /**
610: * <p>
611: * Determines the highest (leftmost) bit that is 1 and returns the value
612: * that is the bit mask for that bit. This is sometimes referred to as the
613: * Most Significant 1 Bit.
614: * </p>
615: *
616: * @param lng
617: * The <code>long</code> to interrogate.
618: * @return The bit mask indicating the highest 1 bit.
619: * @since 1.5
620: */
621: public static long highestOneBit(long lng) {
622: lng |= (lng >> 1);
623: lng |= (lng >> 2);
624: lng |= (lng >> 4);
625: lng |= (lng >> 8);
626: lng |= (lng >> 16);
627: lng |= (lng >> 32);
628: return (lng & ~(lng >>> 1));
629: }
630:
631: /**
632: * <p>
633: * Determines the lowest (rightmost) bit that is 1 and returns the value
634: * that is the bit mask for that bit. This is sometimes referred to as the
635: * Least Significant 1 Bit.
636: * </p>
637: *
638: * @param lng
639: * The <code>long</code> to interrogate.
640: * @return The bit mask indicating the lowest 1 bit.
641: * @since 1.5
642: */
643: public static long lowestOneBit(long lng) {
644: return (lng & (-lng));
645: }
646:
647: /**
648: * <p>
649: * Determines the number of leading zeros in the <code>long</code> passed
650: * prior to the {@link #highestOneBit(long) highest one bit}.
651: * </p>
652: *
653: * @param lng
654: * The <code>long</code> to process.
655: * @return The number of leading zeros.
656: * @since 1.5
657: */
658: public static int numberOfLeadingZeros(long lng) {
659: lng |= lng >> 1;
660: lng |= lng >> 2;
661: lng |= lng >> 4;
662: lng |= lng >> 8;
663: lng |= lng >> 16;
664: lng |= lng >> 32;
665: return bitCount(~lng);
666: }
667:
668: /**
669: * <p>
670: * Determines the number of trailing zeros in the <code>long</code> passed
671: * after the {@link #lowestOneBit(long) lowest one bit}.
672: * </p>
673: *
674: * @param lng
675: * The <code>long</code> to process.
676: * @return The number of trailing zeros.
677: * @since 1.5
678: */
679: public static int numberOfTrailingZeros(long lng) {
680: return bitCount((lng & -lng) - 1);
681: }
682:
683: /**
684: * <p>
685: * Counts the number of 1 bits in the <code>long</code> value passed; this
686: * is sometimes referred to as a population count.
687: * </p>
688: *
689: * @param lng
690: * The <code>long</code> value to process.
691: * @return The number of 1 bits.
692: * @since 1.5
693: */
694: public static int bitCount(long lng) {
695: lng = (lng & 0x5555555555555555L)
696: + ((lng >> 1) & 0x5555555555555555L);
697: lng = (lng & 0x3333333333333333L)
698: + ((lng >> 2) & 0x3333333333333333L);
699: // adjust for 64-bit integer
700: int i = (int) ((lng >>> 32) + lng);
701: i = (i & 0x0F0F0F0F) + ((i >> 4) & 0x0F0F0F0F);
702: i = (i & 0x00FF00FF) + ((i >> 8) & 0x00FF00FF);
703: i = (i & 0x0000FFFF) + ((i >> 16) & 0x0000FFFF);
704: return i;
705: }
706:
707: /**
708: * <p>
709: * Rotates the bits of <code>lng</code> to the left by the
710: * <code>distance</code> bits.
711: * </p>
712: *
713: * @param lng
714: * The <code>long</code> value to rotate left.
715: * @param distance
716: * The number of bits to rotate.
717: * @return The rotated value.
718: * @since 1.5
719: */
720: public static long rotateLeft(long lng, int distance) {
721: if (distance == 0) {
722: return lng;
723: }
724: /*
725: * According to JLS3, 15.19, the right operand of a shift is always
726: * implicitly masked with 0x3F, which the negation of 'distance' is
727: * taking advantage of.
728: */
729: return ((lng << distance) | (lng >>> (-distance)));
730: }
731:
732: /**
733: * <p>
734: * Rotates the bits of <code>lng</code> to the right by the
735: * <code>distance</code> bits.
736: * </p>
737: *
738: * @param lng
739: * The <code>long</code> value to rotate right.
740: * @param distance
741: * The number of bits to rotate.
742: * @return The rotated value.
743: * @since 1.5
744: */
745: public static long rotateRight(long lng, int distance) {
746: if (distance == 0) {
747: return lng;
748: }
749: /*
750: * According to JLS3, 15.19, the right operand of a shift is always
751: * implicitly masked with 0x3F, which the negation of 'distance' is
752: * taking advantage of.
753: */
754: return ((lng >>> distance) | (lng << (-distance)));
755: }
756:
757: /**
758: * <p>
759: * Reverses the bytes of a <code>long</code>.
760: * </p>
761: *
762: * @param lng
763: * The <code>long</code> to reverse.
764: * @return The reversed value.
765: * @since 1.5
766: */
767: public static long reverseBytes(long lng) {
768: long b7 = lng >>> 56;
769: long b6 = (lng >>> 40) & 0xFF00L;
770: long b5 = (lng >>> 24) & 0xFF0000L;
771: long b4 = (lng >>> 8) & 0xFF000000L;
772: long b3 = (lng & 0xFF000000L) << 8;
773: long b2 = (lng & 0xFF0000L) << 24;
774: long b1 = (lng & 0xFF00L) << 40;
775: long b0 = lng << 56;
776: return (b0 | b1 | b2 | b3 | b4 | b5 | b6 | b7);
777: }
778:
779: /**
780: * <p>
781: * Reverses the bytes of a <code>long</code>.
782: * </p>
783: *
784: * @param lng
785: * The <code>long</code> to reverse.
786: * @return The reversed value.
787: * @since 1.5
788: */
789: public static long reverse(long lng) {
790: // From Hacker's Delight, 7-1, Figure 7-1
791: lng = (lng & 0x5555555555555555L) << 1 | (lng >> 1)
792: & 0x5555555555555555L;
793: lng = (lng & 0x3333333333333333L) << 2 | (lng >> 2)
794: & 0x3333333333333333L;
795: lng = (lng & 0x0F0F0F0F0F0F0F0FL) << 4 | (lng >> 4)
796: & 0x0F0F0F0F0F0F0F0FL;
797: return reverseBytes(lng);
798: }
799:
800: /**
801: * <p>
802: * The <code>signum</code> function for <code>long</code> values. This
803: * method returns -1 for negative values, 1 for positive values and 0 for
804: * the value 0.
805: * </p>
806: *
807: * @param lng
808: * The <code>long</code> value.
809: * @return -1 if negative, 1 if positive otherwise 0.
810: * @since 1.5
811: */
812: public static int signum(long lng) {
813: return (lng == 0 ? 0 : (lng < 0 ? -1 : 1));
814: }
815:
816: /**
817: * <p>
818: * Returns a <code>Long</code> instance for the <code>long</code> value
819: * passed. This method is preferred over the constructor, as this method may
820: * maintain a cache of instances.
821: * </p>
822: *
823: * @param lng
824: * The long value.
825: * @return A <code>Long</code> instance.
826: * @since 1.5
827: */
828: public static Long valueOf(long lng) {
829: if (lng < -128 || lng > 127) {
830: return new Long(lng);
831: }
832: return valueOfCache.CACHE[128 + (int) lng];
833: }
834:
835: static class valueOfCache {
836: /**
837: * <p>
838: * A cache of instances used by {@link Long#valueOf(long)} and auto-boxing.
839: * </p>
840: */
841: static final Long[] CACHE = new Long[256];
842:
843: static {
844: for (int i = -128; i <= 127; i++) {
845: CACHE[i + 128] = new Long(i);
846: }
847: }
848: }
849: }
|