From fc6b874b20d5c526e10415ba95b0c75d5eeea37c Mon Sep 17 00:00:00 2001 From: darcy Date: Thu, 23 Jun 2011 14:57:57 -0700 Subject: [PATCH] 6253144: Long narrowing conversion should describe the algorithm used and implied "risks" Reviewed-by: mduigou, alanb --- src/share/classes/java/lang/Byte.java | 27 ++++--- src/share/classes/java/lang/Double.java | 30 ++++--- src/share/classes/java/lang/Float.java | 29 ++++--- src/share/classes/java/lang/Integer.java | 27 ++++--- src/share/classes/java/lang/Long.java | 27 ++++--- src/share/classes/java/lang/Number.java | 80 +++++++++++-------- src/share/classes/java/lang/Short.java | 27 ++++--- .../util/concurrent/atomic/AtomicInteger.java | 19 +++++ .../util/concurrent/atomic/AtomicLong.java | 19 +++++ 9 files changed, 182 insertions(+), 103 deletions(-) diff --git a/src/share/classes/java/lang/Byte.java b/src/share/classes/java/lang/Byte.java index 2ab00f8f9..cb260f803 100644 --- a/src/share/classes/java/lang/Byte.java +++ b/src/share/classes/java/lang/Byte.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2009, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1996, 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 @@ -324,40 +324,45 @@ public final class Byte extends Number implements Comparable { } /** - * Returns the value of this {@code Byte} as a - * {@code short}. + * Returns the value of this {@code Byte} as a {@code short} after + * a widening primitive conversion. + * @jls 5.1.2 Widening Primitive Conversions */ public short shortValue() { return (short)value; } /** - * Returns the value of this {@code Byte} as an - * {@code int}. + * Returns the value of this {@code Byte} as an {@code int} after + * a widening primitive conversion. + * @jls 5.1.2 Widening Primitive Conversions */ public int intValue() { return (int)value; } /** - * Returns the value of this {@code Byte} as a - * {@code long}. + * Returns the value of this {@code Byte} as a {@code long} after + * a widening primitive conversion. + * @jls 5.1.2 Widening Primitive Conversions */ public long longValue() { return (long)value; } /** - * Returns the value of this {@code Byte} as a - * {@code float}. + * Returns the value of this {@code Byte} as a {@code float} after + * a widening primitive conversion. + * @jls 5.1.2 Widening Primitive Conversions */ public float floatValue() { return (float)value; } /** - * Returns the value of this {@code Byte} as a - * {@code double}. + * Returns the value of this {@code Byte} as a {@code double} + * after a widening primitive conversion. + * @jls 5.1.2 Widening Primitive Conversions */ public double doubleValue() { return (double)value; diff --git a/src/share/classes/java/lang/Double.java b/src/share/classes/java/lang/Double.java index 1f6c9d4ca..6f8cdaf1e 100644 --- a/src/share/classes/java/lang/Double.java +++ b/src/share/classes/java/lang/Double.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1994, 2010, 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 @@ -634,11 +634,12 @@ public final class Double extends Number implements Comparable { } /** - * Returns the value of this {@code Double} as a {@code byte} (by - * casting to a {@code byte}). + * Returns the value of this {@code Double} as a {@code byte} + * after a narrowing primitive conversion. * * @return the {@code double} value represented by this object * converted to type {@code byte} + * @jls 5.1.3 Narrowing Primitive Conversions * @since JDK1.1 */ public byte byteValue() { @@ -646,11 +647,12 @@ public final class Double extends Number implements Comparable { } /** - * Returns the value of this {@code Double} as a - * {@code short} (by casting to a {@code short}). + * Returns the value of this {@code Double} as a {@code short} + * after a narrowing primitive conversion. * * @return the {@code double} value represented by this object * converted to type {@code short} + * @jls 5.1.3 Narrowing Primitive Conversions * @since JDK1.1 */ public short shortValue() { @@ -658,8 +660,9 @@ public final class Double extends Number implements Comparable { } /** - * Returns the value of this {@code Double} as an - * {@code int} (by casting to type {@code int}). + * Returns the value of this {@code Double} as an {@code int} + * after a narrowing primitive conversion. + * @jls 5.1.3 Narrowing Primitive Conversions * * @return the {@code double} value represented by this object * converted to type {@code int} @@ -669,22 +672,24 @@ public final class Double extends Number implements Comparable { } /** - * Returns the value of this {@code Double} as a - * {@code long} (by casting to type {@code long}). + * Returns the value of this {@code Double} as a {@code long} + * after a narrowing primitive conversion. * * @return the {@code double} value represented by this object * converted to type {@code long} + * @jls 5.1.3 Narrowing Primitive Conversions */ public long longValue() { return (long)value; } /** - * Returns the {@code float} value of this - * {@code Double} object. + * Returns the value of this {@code Double} as a {@code float} + * after a narrowing primitive conversion. * * @return the {@code double} value represented by this object * converted to type {@code float} + * @jls 5.1.3 Narrowing Primitive Conversions * @since JDK1.0 */ public float floatValue() { @@ -692,8 +697,7 @@ public final class Double extends Number implements Comparable { } /** - * Returns the {@code double} value of this - * {@code Double} object. + * Returns the {@code double} value of this {@code Double} object. * * @return the {@code double} value represented by this object */ diff --git a/src/share/classes/java/lang/Float.java b/src/share/classes/java/lang/Float.java index 612888f32..fa4bfb738 100644 --- a/src/share/classes/java/lang/Float.java +++ b/src/share/classes/java/lang/Float.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1994, 2010, 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 @@ -556,22 +556,24 @@ public final class Float extends Number implements Comparable { } /** - * Returns the value of this {@code Float} as a {@code byte} (by - * casting to a {@code byte}). + * Returns the value of this {@code Float} as a {@code byte} after + * a narrowing primitive conversion. * * @return the {@code float} value represented by this object * converted to type {@code byte} + * @jls 5.1.3 Narrowing Primitive Conversions */ public byte byteValue() { return (byte)value; } /** - * Returns the value of this {@code Float} as a {@code short} (by - * casting to a {@code short}). + * Returns the value of this {@code Float} as a {@code short} + * after a narrowing primitive conversion. * * @return the {@code float} value represented by this object * converted to type {@code short} + * @jls 5.1.3 Narrowing Primitive Conversions * @since JDK1.1 */ public short shortValue() { @@ -579,22 +581,24 @@ public final class Float extends Number implements Comparable { } /** - * Returns the value of this {@code Float} as an {@code int} (by - * casting to type {@code int}). + * Returns the value of this {@code Float} as an {@code int} after + * a narrowing primitive conversion. * * @return the {@code float} value represented by this object * converted to type {@code int} + * @jls 5.1.3 Narrowing Primitive Conversions */ public int intValue() { return (int)value; } /** - * Returns value of this {@code Float} as a {@code long} (by - * casting to type {@code long}). + * Returns value of this {@code Float} as a {@code long} after a + * narrowing primitive conversion. * * @return the {@code float} value represented by this object * converted to type {@code long} + * @jls 5.1.3 Narrowing Primitive Conversions */ public long longValue() { return (long)value; @@ -610,11 +614,12 @@ public final class Float extends Number implements Comparable { } /** - * Returns the {@code double} value of this {@code Float} object. + * Returns the value of this {@code Float} as a {@code double} + * after a widening primitive conversion. * * @return the {@code float} value represented by this - * object is converted to type {@code double} and the - * result of the conversion is returned. + * object converted to type {@code double} + * @jls 5.1.2 Widening Primitive Conversions */ public double doubleValue() { return (double)value; diff --git a/src/share/classes/java/lang/Integer.java b/src/share/classes/java/lang/Integer.java index a87e4b1ab..605918c83 100644 --- a/src/share/classes/java/lang/Integer.java +++ b/src/share/classes/java/lang/Integer.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1994, 2010, 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 @@ -678,16 +678,18 @@ public final class Integer extends Number implements Comparable { } /** - * Returns the value of this {@code Integer} as a - * {@code byte}. + * Returns the value of this {@code Integer} as a {@code byte} + * after a narrowing primitive conversion. + * @jls 5.1.3 Narrowing Primitive Conversions */ public byte byteValue() { return (byte)value; } /** - * Returns the value of this {@code Integer} as a - * {@code short}. + * Returns the value of this {@code Integer} as a {@code short} + * after a narrowing primitive conversion. + * @jls 5.1.3 Narrowing Primitive Conversions */ public short shortValue() { return (short)value; @@ -702,24 +704,27 @@ public final class Integer extends Number implements Comparable { } /** - * Returns the value of this {@code Integer} as a - * {@code long}. + * Returns the value of this {@code Integer} as a {@code long} + * after a widening primitive conversion. + * @jls 5.1.2 Widening Primitive Conversions */ public long longValue() { return (long)value; } /** - * Returns the value of this {@code Integer} as a - * {@code float}. + * Returns the value of this {@code Integer} as a {@code float} + * after a widening primitive conversion. + * @jls 5.1.2 Widening Primitive Conversions */ public float floatValue() { return (float)value; } /** - * Returns the value of this {@code Integer} as a - * {@code double}. + * Returns the value of this {@code Integer} as a {@code double} + * after a widening primitive conversion. + * @jls 5.1.2 Widening Primitive Conversions */ public double doubleValue() { return (double)value; diff --git a/src/share/classes/java/lang/Long.java b/src/share/classes/java/lang/Long.java index bee7da361..2c5905a40 100644 --- a/src/share/classes/java/lang/Long.java +++ b/src/share/classes/java/lang/Long.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1994, 2009, 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 @@ -703,24 +703,27 @@ public final class Long extends Number implements Comparable { } /** - * Returns the value of this {@code Long} as a - * {@code byte}. + * Returns the value of this {@code Long} as a {@code byte} after + * a narrowing primitive conversion. + * @jls 5.1.3 Narrowing Primitive Conversions */ public byte byteValue() { return (byte)value; } /** - * Returns the value of this {@code Long} as a - * {@code short}. + * Returns the value of this {@code Long} as a {@code short} after + * a narrowing primitive conversion. + * @jls 5.1.3 Narrowing Primitive Conversions */ public short shortValue() { return (short)value; } /** - * Returns the value of this {@code Long} as an - * {@code int}. + * Returns the value of this {@code Long} as an {@code int} after + * a narrowing primitive conversion. + * @jls 5.1.3 Narrowing Primitive Conversions */ public int intValue() { return (int)value; @@ -735,16 +738,18 @@ public final class Long extends Number implements Comparable { } /** - * Returns the value of this {@code Long} as a - * {@code float}. + * Returns the value of this {@code Long} as a {@code float} after + * a widening primitive conversion. + * @jls 5.1.2 Widening Primitive Conversions */ public float floatValue() { return (float)value; } /** - * Returns the value of this {@code Long} as a - * {@code double}. + * Returns the value of this {@code Long} as a {@code double} + * after a widening primitive conversion. + * @jls 5.1.2 Widening Primitive Conversions */ public double doubleValue() { return (double)value; diff --git a/src/share/classes/java/lang/Number.java b/src/share/classes/java/lang/Number.java index 216ce8d7f..d90160957 100644 --- a/src/share/classes/java/lang/Number.java +++ b/src/share/classes/java/lang/Number.java @@ -1,5 +1,5 @@ /* - * 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 @@ -26,69 +26,78 @@ package java.lang; /** - * The abstract class Number is the superclass of classes - * BigDecimal, BigInteger, - * Byte, Double, Float, - * Integer, Long, and Short. - *

- * Subclasses of Number must provide methods to convert - * the represented numeric value to byte, double, - * float, int, long, and - * short. + * 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 The Java™ Language Specification + * 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 int. - * 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 int. + * to type {@code int}. */ public abstract int intValue(); /** - * Returns the value of the specified number as a long. - * 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 long. + * to type {@code long}. */ public abstract long longValue(); /** - * Returns the value of the specified number as a float. - * 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 float. + * to type {@code float}. */ public abstract float floatValue(); /** - * Returns the value of the specified number as a double. - * 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 double. + * to type {@code double}. */ public abstract double doubleValue(); /** - * Returns the value of the specified number as a byte. - * This may involve rounding or truncation. + * Returns the value of the specified number as a {@code byte}, + * which may involve rounding or truncation. + * + *

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 byte. + * to type {@code byte}. * @since JDK1.1 */ public byte byteValue() { @@ -96,11 +105,14 @@ public abstract class Number implements java.io.Serializable { } /** - * Returns the value of the specified number as a short. - * This may involve rounding or truncation. + * Returns the value of the specified number as a {@code short}, + * which may involve rounding or truncation. + * + *

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 short. + * to type {@code short}. * @since JDK1.1 */ public short shortValue() { diff --git a/src/share/classes/java/lang/Short.java b/src/share/classes/java/lang/Short.java index 5ff010da0..15a00e17f 100644 --- a/src/share/classes/java/lang/Short.java +++ b/src/share/classes/java/lang/Short.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2009, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1996, 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 @@ -321,8 +321,9 @@ public final class Short extends Number implements Comparable { } /** - * Returns the value of this {@code Short} as a - * {@code byte}. + * Returns the value of this {@code Short} as a {@code byte} after + * a narrowing primitive conversion. + * @jls 5.1.3 Narrowing Primitive Conversions */ public byte byteValue() { return (byte)value; @@ -337,32 +338,36 @@ public final class Short extends Number implements Comparable { } /** - * Returns the value of this {@code Short} as an - * {@code int}. + * Returns the value of this {@code Short} as an {@code int} after + * a widening primitive conversion. + * @jls 5.1.2 Widening Primitive Conversions */ public int intValue() { return (int)value; } /** - * Returns the value of this {@code Short} as a - * {@code long}. + * Returns the value of this {@code Short} as a {@code long} after + * a widening primitive conversion. + * @jls 5.1.2 Widening Primitive Conversions */ public long longValue() { return (long)value; } /** - * Returns the value of this {@code Short} as a - * {@code float}. + * Returns the value of this {@code Short} as a {@code float} + * after a widening primitive conversion. + * @jls 5.1.2 Widening Primitive Conversions */ public float floatValue() { return (float)value; } /** - * Returns the value of this {@code Short} as a - * {@code double}. + * Returns the value of this {@code Short} as a {@code double} + * after a widening primitive conversion. + * @jls 5.1.2 Widening Primitive Conversions */ public double doubleValue() { return (double)value; diff --git a/src/share/classes/java/util/concurrent/atomic/AtomicInteger.java b/src/share/classes/java/util/concurrent/atomic/AtomicInteger.java index 0d8a7a1ae..ec68acd78 100644 --- a/src/share/classes/java/util/concurrent/atomic/AtomicInteger.java +++ b/src/share/classes/java/util/concurrent/atomic/AtomicInteger.java @@ -246,18 +246,37 @@ public class AtomicInteger extends Number implements java.io.Serializable { } + /** + * Returns the value of this {@code AtomicInteger} as an + * {@code int}. + */ public int intValue() { return get(); } + /** + * Returns the value of this {@code AtomicInteger} as a {@code long} + * after a widening primitive conversion. + * @jls 5.1.2 Widening Primitive Conversions + */ public long longValue() { return (long)get(); } + /** + * Returns the value of this {@code AtomicInteger} as a {@code float} + * after a widening primitive conversion. + * @jls 5.1.2 Widening Primitive Conversions + */ public float floatValue() { return (float)get(); } + /** + * Returns the value of this {@code AtomicInteger} as a {@code double} + * after a widening primitive conversion. + * @jls 5.1.2 Widening Primitive Conversions + */ public double doubleValue() { return (double)get(); } diff --git a/src/share/classes/java/util/concurrent/atomic/AtomicLong.java b/src/share/classes/java/util/concurrent/atomic/AtomicLong.java index 4fc4c904b..bf2c71a34 100644 --- a/src/share/classes/java/util/concurrent/atomic/AtomicLong.java +++ b/src/share/classes/java/util/concurrent/atomic/AtomicLong.java @@ -260,18 +260,37 @@ public class AtomicLong extends Number implements java.io.Serializable { } + /** + * Returns the value of this {@code AtomicLong} as an {@code int} + * after a narrowing primitive conversion. + * @jls 5.1.3 Narrowing Primitive Conversions + */ public int intValue() { return (int)get(); } + /** + * Returns the value of this {@code AtomicLong} as a {@code long} + * value. + */ public long longValue() { return get(); } + /** + * Returns the value of this {@code AtomicLong} as a {@code float} + * after a widening primitive conversion. + * @jls 5.1.2 Widening Primitive Conversions + */ public float floatValue() { return (float)get(); } + /** + * Returns the value of this {@code AtomicLong} as a {@code + * double} after a widening primitive conversion. + * @jls 5.1.2 Widening Primitive Conversions + */ public double doubleValue() { return (double)get(); } -- GitLab