home *** CD-ROM | disk | FTP | other *** search
/ DOS/V Power Report 1998 February / VPR9802A.ISO / APP_DEMO / VC / MAIN.BIN / Long.java < prev    next >
Text File  |  1997-10-27  |  19KB  |  562 lines
  1. /*
  2.  * @(#)Long.java    1.31 97/02/03
  3.  * 
  4.  * Copyright (c) 1995, 1996 Sun Microsystems, Inc. All Rights Reserved.
  5.  * 
  6.  * This software is the confidential and proprietary information of Sun
  7.  * Microsystems, Inc. ("Confidential Information").  You shall not
  8.  * disclose such Confidential Information and shall use it only in
  9.  * accordance with the terms of the license agreement you entered into
  10.  * with Sun.
  11.  * 
  12.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
  13.  * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  14.  * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  15.  * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
  16.  * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
  17.  * THIS SOFTWARE OR ITS DERIVATIVES.
  18.  * 
  19.  * CopyrightVersion 1.1_beta
  20.  * 
  21.  */
  22.  
  23. package java.lang;
  24.  
  25. /**
  26.  * The Long class wraps a value of the primitive type <code>long</code> 
  27.  * in an object. An object of type <code>Long</code> contains a single 
  28.  * field whose type is <code>long</code>. 
  29.  * <p>
  30.  * In addition, this class provides several methods for converting a 
  31.  * <code>long</code> to a <code>String</code> and a 
  32.  * <code>String</code> to a <code>long</code>, as well as other 
  33.  * constants and methods useful when dealing with a 
  34.  * <code>long</code>. 
  35.  *
  36.  * @author  Lee Boynton
  37.  * @author  Arthur van Hoff
  38.  * @version 1.31, 02/03/97
  39.  * @since   JDK1.0
  40.  */
  41. public final
  42. class Long extends Number {
  43.     /**
  44.      * The smallest value of type <code>long</code>. 
  45.      *
  46.      * @since   JDK1.0
  47.      */
  48.     public static final long MIN_VALUE = 0x8000000000000000L;
  49.  
  50.     /**
  51.      * The largest value of type <code>long</code>. 
  52.      *
  53.      * @since   JDK1.0
  54.      */
  55.     public static final long MAX_VALUE = 0x7fffffffffffffffL;
  56.  
  57.     /**
  58.      * The Class object representing the primitive type long.
  59.      *
  60.      * @since   JDK1.1
  61.      */
  62.     public static final Class    TYPE = Class.getPrimitiveClass("long");
  63.  
  64.     /**
  65.      * Creates a string representation of the first argument in the 
  66.      * radix specified by the second argument. 
  67.      * <p>
  68.      * If the radix is smaller than <code>Character.MIN_RADIX</code> or 
  69.      * larger than <code>Character.MAX_RADIX</code>, then the radix 
  70.      * <code>10</code> is used instead. 
  71.      * <p>
  72.      * If the first argument is negative, the first element of the 
  73.      * result is the ASCII minus sign <code>'-'</code>. If the first 
  74.      * argument is not negative, no sign character appears in the result. 
  75.      * The following ASCII characters are used as digits: 
  76.      * <ul><code>
  77.      *   0123456789abcdefghijklmnopqrstuvwxyz
  78.      * </code></ul>
  79.      *
  80.      * @param   i       a long.
  81.      * @param   radix   the radix.
  82.      * @return  a string representation of the argument in the specified radix.
  83.      * @see     java.lang.Character#MAX_RADIX
  84.      * @see     java.lang.Character#MIN_RADIX
  85.      * @since   JDK1.0
  86.      */
  87.     public static String toString(long i, int radix) {
  88.         if (radix < Character.MIN_RADIX || radix > Character.MAX_RADIX)
  89.         radix = 10;
  90.     StringBuffer buf = new StringBuffer(radix >= 8 ? 23 : 65);
  91.     boolean negative = (i < 0);
  92.         if (!negative)
  93.         i = -i;
  94.     while (i <= -radix) {
  95.         buf.append(Character.forDigit((int)(-(i % radix)), radix));
  96.         i = i / radix;
  97.     }
  98.     buf.append(Character.forDigit((int)(-i), radix));
  99.     if (negative)
  100.         buf.append('-');
  101.         return buf.reverse().toString();
  102.     }
  103.  
  104.     /**
  105.      * Creates a string representation of the long argument as an 
  106.      * unsigned integer in base 16. 
  107.      * <p>
  108.      * The unsigned long value is the argument plus 2<sup>64</sup> if 
  109.      * the argument is negative; otherwise, it is equal to the argument. 
  110.      * This value is converted to a string of ASCII digits in hexadecimal 
  111.      * (base 16) with no extra leading <code>0</code>s. 
  112.      *
  113.      * @param   i   a <code>long</code>.
  114.      * @return  the string representation of the unsigned long value
  115.      *          represented by the argument in hexadecimal (base 16).
  116.      * @since   JDK 1.0.2
  117.      */
  118.     public static String toHexString(long i) {
  119.     return toUnsignedString(i, 4);
  120.     }
  121.  
  122.     /**
  123.      * Creates a string representation of the long argument as an 
  124.      * unsigned integer in base 8. 
  125.      * <p>
  126.      * The unsigned long value is the argument plus 2<sup>64</sup> if 
  127.      * the argument is negative; otherwise, it is equal to the argument. 
  128.      * This value is converted to a string of ASCII digits in octal 
  129.      * (base 8) with no extra leading <code>0</code>s. 
  130.      *
  131.      * @param   i   a <code>long</code>.
  132.      * @return  the string representation of the unsigned long value
  133.      *          represented by the argument in octal (base 8).
  134.      * @since   JDK 1.0.2
  135.      */
  136.     public static String toOctalString(long i) {
  137.     return toUnsignedString(i, 3);
  138.     }
  139.  
  140.     /**
  141.      * Creates a string representation of the long argument as an 
  142.      * unsigned integer in base 2. 
  143.      * <p>
  144.      * The unsigned long value is the argument plus 2<sup>64</sup> if 
  145.      * the argument is negative; otherwise, it is equal to the argument. 
  146.      * This value is converted to a string of ASCII digits in binary 
  147.      * (base 2) with no extra leading <code>0</code>s. 
  148.      *
  149.      * @param   i   a long.
  150.      * @return  the string representation of the unsigned long value
  151.      *          represented by the argument in binary (base 2).
  152.      * @since   JDK 1.0.2
  153.      */
  154.     public static String toBinaryString(long i) {
  155.     return toUnsignedString(i, 1);
  156.     }
  157.  
  158.     /** 
  159.      * Convert the integer to an unsigned number.
  160.      */
  161.     private static String toUnsignedString(long i, int shift) {
  162.     StringBuffer buf = new StringBuffer(shift >= 3 ? 22 : 64);
  163.     int radix = 1 << shift;
  164.     long mask = radix - 1;
  165.     do {
  166.         buf.append(Character.forDigit((int)(i & mask), radix));
  167.         i >>>= shift;
  168.     } while (i != 0);
  169.         return buf.reverse().toString();
  170.     }
  171.  
  172.     /**
  173.      * Returns a new String object representing the specified integer. The radix
  174.      * is assumed to be 10.
  175.      *
  176.      * @param   i   a <code>long</code> to be converted.
  177.      * @return  a string representation of the argument in base 10.
  178.      * @since   JDK1.0
  179.      */
  180.     public static String toString(long i) {
  181.     return toString(i, 10);
  182.     }
  183.  
  184.     /**
  185.      * Parses the string argument as a signed <code>long</code> in the 
  186.      * radix specified by the second argument. The characters in the 
  187.      * string must all be digits of the specified radix (as determined by 
  188.      * whether <code>Character.digit</code> returns a 
  189.      * nonnegative value), except that the first character may be an 
  190.      * ASCII minus sign <code>'-'</code> to indicate a negative value. 
  191.      * The resulting <code>long</code> value is returned. 
  192.      *
  193.      * @param      s       the <code>String</code> containing the
  194.      *                     <code>long</code>.
  195.      * @param      radix   the radix to be used.
  196.      * @return     the <code>long</code> represented by the string argument in
  197.      *             the specified radix.
  198.      * @exception  NumberFormatException  if the string does not contain a
  199.      *               parsable integer.
  200.      * @since      JDK1.0
  201.      */
  202.     public static long parseLong(String s, int radix) 
  203.               throws NumberFormatException 
  204.     {
  205.         if (s == null) {
  206.             throw new NumberFormatException("null");
  207.         }
  208.     long result = 0;
  209.     boolean negative = false;
  210.     int i = 0, max = s.length();
  211.     long limit;
  212.     long multmin;
  213.     int digit;
  214.  
  215.     if (max > 0) {
  216.         if (s.charAt(0) == '-') {
  217.         negative = true;
  218.         limit = Long.MIN_VALUE;
  219.         i++;
  220.         } else {
  221.         limit = -Long.MAX_VALUE;
  222.         }
  223.         multmin = limit / radix;
  224.             if (i < max) {
  225.                 digit = Character.digit(s.charAt(i++),radix);
  226.         if (digit < 0) {
  227.             throw new NumberFormatException(s);
  228.         } else {
  229.             result = -digit;
  230.         }
  231.         }    
  232.         while (i < max) {
  233.         // Accumulating negatively avoids surprises near MAX_VALUE
  234.         digit = Character.digit(s.charAt(i++),radix);
  235.         if (digit < 0) {
  236.             throw new NumberFormatException(s);
  237.         }
  238.         if (result < multmin) {
  239.             throw new NumberFormatException(s);
  240.         }
  241.         result *= radix;
  242.         if (result < limit + digit) {
  243.             throw new NumberFormatException(s);
  244.         }
  245.         result -= digit;
  246.         }
  247.     } else {
  248.         throw new NumberFormatException(s);
  249.     }
  250.     if (negative) {
  251.         if (i > 1) {
  252.         return result;
  253.         } else {    /* Only got "-" */
  254.         throw new NumberFormatException(s);
  255.         }
  256.     } else {
  257.         return -result;
  258.     }
  259.     }
  260.  
  261.     /**
  262.      * Parses the string argument as a signed decimal <code>long</code>. 
  263.      * The characters in the string must all be decimal digits, except 
  264.      * that the first character may be an ASCII minus sign 
  265.      * <code>'-'</code> to indicate a negative value. 
  266.      *
  267.      * @param      s   a string.
  268.      * @return     the <code>long</code> represented by the argument in decimal.
  269.      * @exception  NumberFormatException  if the string does not contain a
  270.      *               parsable <code>long</code>.
  271.      * @since      JDK1.0
  272.      */
  273.     public static long parseLong(String s) throws NumberFormatException {
  274.     return parseLong(s, 10);
  275.     }
  276.  
  277.     /**
  278.      * Returns a new long object initialized to the value of the
  279.      * specified String. Throws an exception if the String cannot be
  280.      * parsed as a long.
  281.      *
  282.      * @param      s       the <code>String</code> containing the
  283.      *                     <code>long</code>.
  284.      * @param      radix   the radix to be used. 
  285.      * @return     a newly constructed <code>Long</code> initialized to the
  286.      *             value represented by the string argument in the specified
  287.      *             radix.
  288.      * @exception  NumberFormatException  If the <code>String</code> does not
  289.      *               contain a parsable <code>long</code>.
  290.      * @since      JDK1.0
  291.      */
  292.     public static Long valueOf(String s, int radix) throws NumberFormatException {
  293.     return new Long(parseLong(s, radix));
  294.     }
  295.  
  296.     /**
  297.      * Returns a new long object initialized to the value of the
  298.      * specified String. Throws an exception if the String cannot be
  299.      * parsed as a long. The radix is assumed to be 10.
  300.      *
  301.      * @param      s   the string to be parsed.
  302.      * @return     a newly constructed <code>Long</code> initialized to the
  303.      *             value represented by the string argument.
  304.      * @exception  NumberFormatException  If the <code>String</code> does not
  305.      *               contain a parsable <code>long</code>.
  306.      * @since   JDK1.0
  307.      */
  308.     public static Long valueOf(String s) throws NumberFormatException 
  309.     {
  310.     return new Long(parseLong(s, 10));
  311.     }
  312.  
  313.     /**
  314.      * The value of the Long.
  315.      */
  316.     private long value;
  317.  
  318.     /**
  319.      * Constructs a newly allocated <code>Long</code> object that 
  320.      * represents the primitive <code>long</code> argument. 
  321.      *
  322.      * @param   value   the value to be represented by the <code>Long</code>.
  323.      * @since   JDK1.0
  324.      */
  325.     public Long(long value) {
  326.     this.value = value;
  327.     }
  328.  
  329.     /**
  330.      * Constructs a newly allocated <code>Long</code> object that 
  331.      * represents the value represented by the string. The string is 
  332.      * converted to an <code>long</code> value as if by the 
  333.      * <code>valueOf</code> method. 
  334.      *
  335.      * @param      s   the string to be converted to a <code>Long</code>.
  336.      * @exception  NumberFormatException  if the <code>String</code> does not
  337.      *               contain a parsable long integer.
  338.      * @see        java.lang.Long#valueOf(java.lang.String)
  339.      * @since      JDK1.0
  340.      */
  341.     public Long(String s) throws NumberFormatException {
  342.     this.value = parseLong(s, 10);
  343.     }
  344.  
  345.     /**
  346.      * Returns the value of this Long as a byte.
  347.      *
  348.      * @since   JDK1.1
  349.      */
  350.     public byte byteValue() {
  351.     return (byte)value;
  352.     }
  353.  
  354.     /**
  355.      * Returns the value of this Long as a short.
  356.      *
  357.      * @since   JDK1.1
  358.      */
  359.     public short shortValue() {
  360.     return (short)value;
  361.     }
  362.  
  363.     /**
  364.      * Returns the value of this Long as an int.
  365.      *
  366.      * @return  the <code>long</code> value represented by this object is
  367.      *          converted to type <code>int</code> and the result of the
  368.      *          conversion is returned.
  369.      * @since   JDK1.0
  370.      */
  371.     public int intValue() {
  372.     return (int)value;
  373.     }
  374.  
  375.     /**
  376.      * Returns the value of this Long as a long.
  377.      *
  378.      * @return  the <code>long</code> value represented by this object.
  379.      * @since   JDK1.0
  380.      */
  381.     public long longValue() {
  382.     return (long)value;
  383.     }
  384.  
  385.     /**
  386.      * Returns the value of this Long as a float.
  387.      *
  388.      * @return  the <code>long</code> value represented by this object is
  389.      *          converted to type <code>float</code> and the result of
  390.      *          the conversion is returned.
  391.      * @since   JDK1.0
  392.      */
  393.     public float floatValue() {
  394.     return (float)value;
  395.     }
  396.  
  397.     /**
  398.      * Returns the value of this Long as a double.
  399.      *
  400.      * @return  the <code>long</code> value represented by this object that
  401.      *          is converted to type <code>double</code> and the result of
  402.      *          the conversion is returned.
  403.      * @since   JDK1.0
  404.      */
  405.     public double doubleValue() {
  406.     return (double)value;
  407.     }
  408.  
  409.     /**
  410.      * Returns a String object representing this Long's value.
  411.      *
  412.      * @return  a string representation of this object in base 10.
  413.      * @since   JDK1.0
  414.      */
  415.     public String toString() {
  416.     return String.valueOf(value);
  417.     }
  418.  
  419.     /**
  420.      * Computes a hashcode for this Long.
  421.      *
  422.      * @return  a hash code value for this object. 
  423.      * @since   JDK1.0
  424.      */
  425.     public int hashCode() {
  426.     return (int)(value ^ (value >> 32));
  427.     }
  428.  
  429.     /**
  430.      * Compares this object against the specified object.
  431.      * The result is <code>true</code> if and only if the argument is 
  432.      * not <code>null</code> and is a <code>Long</code> object that 
  433.      * contains the same <code>long</code> value as this object. 
  434.      *
  435.      * @param   obj   the object to compare with.
  436.      * @return  <code>true</code> if the objects are the same;
  437.      *          <code>false</code> otherwise.
  438.      * @since   JDK1.0
  439.      */
  440.     public boolean equals(Object obj) {
  441.     if ((obj != null) && (obj instanceof Long)) {
  442.         return value == ((Long)obj).longValue();
  443.     }
  444.     return false;
  445.     }
  446.  
  447.     /**
  448.      * Determines the <code>long</code> value of the system property 
  449.      * with the specified name. 
  450.      * <p>
  451.      * The first argument is treated as the name of a system property. 
  452.      * System properties are accessible through <code>getProperty</code>  
  453.      * and , a method defined by the <code>System</code> class. The 
  454.      * string value of this property is then interpreted as a long value 
  455.      * and a <code>Long</code> object representing this value is returned. 
  456.      * Details of possible numeric formats can be found with the 
  457.      * definition of <code>getProperty</code>. 
  458.      * <p>
  459.      * If there is no property with the specified name, or if the 
  460.      * property does not have the correct numeric format, then 
  461.      * <code>null</code> is returned. 
  462.      *
  463.      * @param   nm   property name.
  464.      * @return  the <code>Long</code> value of the property.
  465.      * @see     java.lang.System#getProperty(java.lang.String)
  466.      * @see     java.lang.System#getProperty(java.lang.String, java.lang.String)
  467.      * @since   JDK1.0
  468.      */
  469.     public static Long getLong(String nm) {
  470.     return getLong(nm, null);
  471.     }
  472.  
  473.     /**
  474.      * Determines the <code>long</code> value of the system property 
  475.      * with the specified name. 
  476.      * <p>
  477.      * The first argument is treated as the name of a system property. 
  478.      * System properties are accessible through <code>getProperty</code>  
  479.      * and , a method defined by the <code>System</code> class. The 
  480.      * string value of this property is then interpreted as a long value 
  481.      * and a <code>Long</code> object representing this value is returned. 
  482.      * Details of possible numeric formats can be found with the 
  483.      * definition of <code>getProperty</code>. 
  484.      * <p>
  485.      * If there is no property with the specified name, or if the 
  486.      * property does not have the correct numeric format, then a 
  487.      * <code>Long</code> object that represents the value of the second 
  488.      * argument is returned. 
  489.      *
  490.      * @param   nm    property name.
  491.      * @param   val   default value.
  492.      * @return  the <code>Long</code> value of the property.
  493.      * @see     java.lang.System#getProperty(java.lang.String)
  494.      * @see     java.lang.System#getProperty(java.lang.String, java.lang.String)
  495.      * @since   JDK1.0
  496.      */
  497.     public static Long getLong(String nm, long val) {
  498.         Long result = Long.getLong(nm, null);
  499.         return (result == null) ? new Long(val) : result;
  500.     }
  501.  
  502.     /**
  503.      * Determines the <code>long</code> value of the system property 
  504.      * with the specified name. 
  505.      * <p>
  506.      * The first argument is treated as the name of a system property. 
  507.      * System properties are accessible through <code>getProperty</code>  
  508.      * and , a method defined by the <code>System</code> class. The 
  509.      * string value of this property is then interpreted as a long value 
  510.      * and a <code>Long</code> object representing this value is returned. 
  511.      * <p>
  512.      * If the property value begins with "<code>0x</code>" or 
  513.      * "<code>#</code>", not followed by a minus sign, the rest 
  514.      * of it is parsed as a hexadecimal integer exactly as for the method 
  515.      * <code>Long.valueOf</code> with radix 16. 
  516.      * <p>
  517.      * If the property value begins with "<code>0</code>", 
  518.      * then it is parsed as an octal integer exactly as for the method 
  519.      * <code>Long.valueOf</code> with radix 8. 
  520.      * <p>
  521.      * Otherwise the property value is parsed as a decimal integer 
  522.      * exactly as for the method <code>Long.valueOf</code> with radix 10. 
  523.      * <p>
  524.      * Note that, in every case, neither <code>L</code> nor 
  525.      * <code>l</code> is permitted to appear at the end of the string. 
  526.      * <p>
  527.      * The second argument is the default value. If there is no property 
  528.      * of the specified name, or if the property does not have the 
  529.      * correct numeric format, then the second argument is returned. 
  530.      *
  531.      * @param   nm    the property name.
  532.      * @param   val   the default <code>Long</code> value.
  533.      * @return  the <code>long</code> value of the property.
  534.      * @see     java.lang.Long#valueOf(java.lang.String, int)
  535.      * @see     java.lang.System#getProperty(java.lang.String)
  536.      * @see     java.lang.System#getProperty(java.lang.String, java.lang.String)
  537.      * @since   JDK1.0
  538.      */
  539.     public static Long getLong(String nm, Long val) {
  540.     String v = System.getProperty(nm);
  541.     if (v != null) {
  542.         try {
  543.         if (v.startsWith("0x")) {
  544.             return Long.valueOf(v.substring(2), 16);
  545.         }
  546.         if (v.startsWith("#")) {
  547.             return Long.valueOf(v.substring(1), 16);
  548.         }
  549.         if (v.startsWith("0") && v.length() > 1) {
  550.             return Long.valueOf(v.substring(1), 8);
  551.         }
  552.         return Long.valueOf(v);
  553.         } catch (NumberFormatException e) {
  554.         }
  555.     }    
  556.     return val;
  557.     }
  558.  
  559.     /** use serialVersionUID from JDK 1.0.2 for interoperability */
  560.     private static final long serialVersionUID = 4290774380558885855L;
  561. }
  562.