better comments in BitVector

diff --git a/src/edu/berkeley/fleet/api/BitVector.java b/src/edu/berkeley/fleet/api/BitVector.java
index b84b17f..ae7f96b 100644 (file)
--- a/src/edu/berkeley/fleet/api/BitVector.java
+++ b/src/edu/berkeley/fleet/api/BitVector.java
@@ -3,7 +3,21 @@ package edu.berkeley.fleet.api;
 /**
  *  A sequence of bits with a fixed length.  This class performs
  *  important error-checking not found in the Java BitSet and
- *  BigInteger classes.
+ *  BigInteger classes.  Bits are numbered starting with LSB as "bit
+ *  zero".
+ *
+ *  The toLong(), set(long), and setAndSignExtend(long) methods offer
+ *  the following guarantee: for all i, unless an exception is thrown
+ *  the following identities will hold:
+ *
+ *     bv.set(i).toLong() == i
+ *     bv.equals(new BitVector(bv.length()).set(bv.toLong()))
+ *
+ *  An exception is thrown if the BitVector in question is more than
+ *  64 bits long (in which case it cannot be converted to a long with
+ *  toLong()) or the long in question cannot be represented as a two's
+ *  complement number using the number of bits allocated in the
+ *  BitVector.
  */
 public class BitVector {
 
@@ -38,6 +52,7 @@ public class BitVector {
         return this;
     }
 
+    /** returns the length of this BitVector */
     public int length() {
         return bits.length;
     }
@@ -49,6 +64,7 @@ public class BitVector {
         return this;
     }
 
+    /** returns the value of the specified bit */
     public boolean get(int bit) {
         return bits[bit];
     }
@@ -62,6 +78,7 @@ public class BitVector {
         return ret.toString();
     }
 
+    /** makes this BitVector immutable; cannot be undone */
     public void setImmutable() {
         immutable = true;
     }
@@ -89,7 +106,10 @@ public class BitVector {
         return true;
     }
 
-    /** WARNING: be careful -- future Fleets may be more than 64 bits wide! */
+    /**
+     *  Converts this BitVector to a long, sign-extending if
+     *  length()<64 and throwing an exception if length()>64
+     */
     public long toLong() {
         if (length() > 64)
             throw new RuntimeException("a " + length() + "-bit BitVector cannot fit in a Java long");