src/share/classes/java/lang/Number.java
Print this page
@@ -1,7 +1,7 @@
/*
- * Copyright (c) 1994, 2001, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1994, 2011, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
@@ -24,85 +24,97 @@
*/
package java.lang;
/**
- * The abstract class <code>Number</code> is the superclass of classes
- * <code>BigDecimal</code>, <code>BigInteger</code>,
- * <code>Byte</code>, <code>Double</code>, <code>Float</code>,
- * <code>Integer</code>, <code>Long</code>, and <code>Short</code>.
- * <p>
- * Subclasses of <code>Number</code> must provide methods to convert
- * the represented numeric value to <code>byte</code>, <code>double</code>,
- * <code>float</code>, <code>int</code>, <code>long</code>, and
- * <code>short</code>.
+ * The abstract class {@code Number} is the superclass of platform
+ * classes representing numeric values that are convertible to the
+ * primitive types {@code byte}, {@code double}, {@code float}, {@code
+ * int}, {@code long}, and {@code short}.
+ *
+ * The specific semantics of the conversion from the numeric value of
+ * a particular {@code Number} implementation to a given primitive
+ * type is defined by the {@code Number} implementation in question.
+ *
+ * For platform classes, the conversion is often analogous to a
+ * narrowing primitive conversion or a widening primitive conversion
+ * as defining in <cite>The Java™ Language Specification</cite>
+ * for converting between primitive types. Therefore, conversions may
+ * lose information about the overall magnitude of a numeric value, may
+ * lose precision, and may even return a result of a different sign
+ * than the input.
+ *
+ * See the documentation of a given {@code Number} implementation for
+ * conversion details.
*
* @author Lee Boynton
* @author Arthur van Hoff
- * @see java.lang.Byte
- * @see java.lang.Double
- * @see java.lang.Float
- * @see java.lang.Integer
- * @see java.lang.Long
- * @see java.lang.Short
+ * @jls 5.1.2 Widening Primitive Conversions
+ * @jls 5.1.3 Narrowing Primitive Conversions
* @since JDK1.0
*/
public abstract class Number implements java.io.Serializable {
/**
- * Returns the value of the specified number as an <code>int</code>.
- * This may involve rounding or truncation.
+ * Returns the value of the specified number as an {@code int},
+ * which may involve rounding or truncation.
*
* @return the numeric value represented by this object after conversion
- * to type <code>int</code>.
+ * to type {@code int}.
*/
public abstract int intValue();
/**
- * Returns the value of the specified number as a <code>long</code>.
- * This may involve rounding or truncation.
+ * Returns the value of the specified number as a {@code long},
+ * which may involve rounding or truncation.
*
* @return the numeric value represented by this object after conversion
- * to type <code>long</code>.
+ * to type {@code long}.
*/
public abstract long longValue();
/**
- * Returns the value of the specified number as a <code>float</code>.
- * This may involve rounding.
+ * Returns the value of the specified number as a {@code float},
+ * which may involve rounding.
*
* @return the numeric value represented by this object after conversion
- * to type <code>float</code>.
+ * to type {@code float}.
*/
public abstract float floatValue();
/**
- * Returns the value of the specified number as a <code>double</code>.
- * This may involve rounding.
+ * Returns the value of the specified number as a {@code double},
+ * which may involve rounding.
*
* @return the numeric value represented by this object after conversion
- * to type <code>double</code>.
+ * to type {@code double}.
*/
public abstract double doubleValue();
/**
- * Returns the value of the specified number as a <code>byte</code>.
- * This may involve rounding or truncation.
+ * Returns the value of the specified number as a {@code byte},
+ * which may involve rounding or truncation.
+ *
+ * <p>This implementation returns the result of {@link #intValue} cast
+ * to a {@code byte}.
*
* @return the numeric value represented by this object after conversion
- * to type <code>byte</code>.
+ * to type {@code byte}.
* @since JDK1.1
*/
public byte byteValue() {
return (byte)intValue();
}
/**
- * Returns the value of the specified number as a <code>short</code>.
- * This may involve rounding or truncation.
+ * Returns the value of the specified number as a {@code short},
+ * which may involve rounding or truncation.
+ *
+ * <p>This implementation returns the result of {@link #intValue} cast
+ * to a {@code short}.
*
* @return the numeric value represented by this object after conversion
- * to type <code>short</code>.
+ * to type {@code short}.
* @since JDK1.1
*/
public short shortValue() {
return (short)intValue();
}