[Pocketgames-devel] SF.net SVN: pocketgames: [226] libraries/unsigned/src/org/pocketgames/ unsigned/UnsignedByte.java

[<ido...@us...>]

Revision: 226
          http://pocketgames.svn.sourceforge.net/pocketgames/?rev=226&view=rev
Author:   idominguez
Date:     2008-01-12 04:58:27 -0800 (Sat, 12 Jan 2008)

Log Message:
-----------
Javadoc comments and two minor changes

Modified Paths:
--------------
    libraries/unsigned/src/org/pocketgames/unsigned/UnsignedByte.java

Modified: libraries/unsigned/src/org/pocketgames/unsigned/UnsignedByte.java
===================================================================
--- libraries/unsigned/src/org/pocketgames/unsigned/UnsignedByte.java	2008-01-12 12:58:03 UTC (rev 225)
+++ libraries/unsigned/src/org/pocketgames/unsigned/UnsignedByte.java	2008-01-12 12:58:27 UTC (rev 226)
@@ -20,17 +20,43 @@
 package org.pocketgames.unsigned;
 
 /**
+ * This class represents an unsigned byte. It has methods to
+ * convert it to different values that can be used with Java's arithmetic
+ * operators.
+ *
  * @author Ivan Perez-Dominguez
  */
 public class UnsignedByte
     extends Number
     implements Comparable<UnsignedByte>
 {
+    /**
+     *  A constant holding the maximum value an <code>unsigned byte</code> can have, 2^8.
+     */
+    public static int MAX_VALUE = 256;
+
+    /**
+     *  A constant holding the minimum value an <code>unsigned byte</code> can have, 0.
+     */
     public static int MIN_VALUE = 0;
-    public static int MAX_VALUE = 256;
+
+    /**
+     * The number of bits used to represent an <code>UnsignedByte</code> value
+     * in two's complement binary form.
+     */
     public static int SIZE = Short.SIZE;
+
+    /**
+     * The value stored in this UnsignedByte.
+     */
     private final short val;
 
+    /**
+     * Creates an unsigned byte from a <code>byte</code>.
+     * Note that negative values are treated as positive values (ie., if <code>b</code> is negative,
+     * then the real value stored is <code>UnsignedByte.MAX_VALUE + b</code>).
+     * @param b the value to be stored, in signed format.
+     */
     public UnsignedByte (byte b)
     {
         if (b >= 0)
@@ -43,47 +69,89 @@
         }
     }
 
+    /**
+     * Creates an unsigned byte from a <code>short</code>.
+     * @param s the value to be stored, in signed format.
+     * @throws IllegalArgumentException if <code>s</code> is out of range.
+     */
     public UnsignedByte (short s)
+        throws IllegalArgumentException
     {
-        if (s < 0)
+        if (s < MIN_VALUE || s >= MAX_VALUE)
             throw new IllegalArgumentException();
         else
             this.val = s;
     }
 
-    public UnsignedByte (int i) throws IllegalArgumentException
+    /**
+     * Creates an unsigned byte from an <code>int</code>.
+     * @param i the value to be stored, in signed format.
+     * @throws IllegalArgumentException if <code>i</code> is out of range.
+     */
+    public UnsignedByte (int i)
+        throws IllegalArgumentException
     {
-        if (i < 0 || i >= 256)
+        if (i < MIN_VALUE || i >= MAX_VALUE)
             throw new IllegalArgumentException();
         else
             this.val = (short)i;
     }
 
+    /**
+     * Returns the value of this <code>UnsignedByte</code> as a <code>double</code>.
+     * @return the numeric value represented by this object after conversion to type <code>double</code>.
+     */
     public double doubleValue ()
     {
         return this.val;
     }
 
+    /**
+     * Returns the value of this <code>UnsignedByte</code> as a <code>float</code>.
+     * @return the numeric value represented by this object after conversion to type <code>float</code>.
+     */
     public float floatValue ()
     {
         return this.val;
     }
 
+    /**
+     * Returns the value of this <code>UnsignedByte</code> as a <code>long</code>.
+     * @return the numeric value represented by this object after conversion to type <code>long</code>.
+     */
     public long longValue ()
     {
         return this.val;
     }
 
+    /**
+     * Returns the value of this <code>UnsignedByte</code> as a <code>int</code>.
+     * @return the numeric value represented by this object after conversion to type <code>int</code>.
+     */
     public int intValue ()
     {
         return this.val;
     }
 
+    /**
+     * Returns the value of this <code>UnsignedByte</code> as a <code>byte</code>.
+     * @return the numeric value represented by this object after conversion to type <code>byte</code>.
+     */
     public byte byteValue ()
     {
         return (byte)this.val;
     }
 
+    /**
+     * Compares two <code>UnsignedByte</code> objects numerically.
+     * @param i the <code>UnsignedByte</code> to be compared.
+     * @return the value 0 if this <code>UnsignedByte</code> is equal to the
+     * argument <code>UnsignedByte</code>; a value less than 0 if this
+     * <code>UnsignedByte</code> is numerically less than the argument
+     * <code>UnsignedByte</code>; and a value greater than 0 if this
+     * <code>UnsignedByte</code> is numerically greater than the argument
+     * <code>UnsignedByte</code> (unsigned comparison).
+     */
     public int compareTo (UnsignedByte i)
     {
         if (this.val < i.val)


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.