Refactored BitVector methods to resolve ambiguity

[Mograsim.git] / net.mograsim.logic.core / src / net / mograsim / logic / core / types / BitVector.java

diff --git a/net.mograsim.logic.core/src/net/mograsim/logic/core/types/BitVector.java b/net.mograsim.logic.core/src/net/mograsim/logic/core/types/BitVector.java
index f92401f..cce83f4 100644 (file)
--- a/net.mograsim.logic.core/src/net/mograsim/logic/core/types/BitVector.java
+++ b/net.mograsim.logic.core/src/net/mograsim/logic/core/types/BitVector.java
@@ -13,7 +13,6 @@ import java.util.function.UnaryOperator;
 /**
  * Immutable class representing a {@link Bit}Vector
  *
- *
  * @author Christian Femers
  *
  */
@@ -23,7 +22,10 @@ public final class BitVector implements StrictLogicType<BitVector>, Iterable<Bit
 
        private BitVector(Bit[] bits)
        {
-               this.bits = Objects.requireNonNull(bits);
+               this.bits = Objects.requireNonNull(bits); // do this first to "catch" bits==null before the foreach loop
+               for (Bit bit : bits)
+                       if (bit == null)
+                               throw new NullPointerException();
        }
 
        public static BitVector of(Bit... bits)
@@ -41,11 +43,22 @@ public final class BitVector implements StrictLogicType<BitVector>, Iterable<Bit
                return BitVectorMutator.of(this);
        }
 
-       public Bit getBit(int bitIndex)
+       /**
+        * Returns the most significant bit at <code>bitIndex</code>. (leftmost bit of a binary number at the given index)
+        */
+       public Bit getMSBit(int bitIndex)
        {
                return bits[bitIndex];
        }
 
+       /**
+        * Returns the least significant bit at <code>bitIndex</code>. (rightmost bit of a binary number at the given index)
+        */
+       public Bit getLSBit(int bitIndex)
+       {
+               return bits[bits.length - bitIndex - 1];
+       }
+
        public Bit[] getBits()
        {
                return bits.clone();
@@ -221,16 +234,38 @@ public final class BitVector implements StrictLogicType<BitVector>, Iterable<Bit
                        return this;
                }
 
-               public void setBit(int bitIndex, Bit bit)
+               /**
+                * Set the most significant bit at <code>bitIndex</code>. (leftmost bit of a binary number at the given index)
+                */
+               public void setMSBit(int bitIndex, Bit bit)
                {
                        bits[bitIndex] = bit;
                }
 
-               public Bit getBit(int bitIndex)
+               /**
+                * Set the least significant bit at <code>bitIndex</code>. (rightmost bit of a binary number at the given index)
+                */
+               public void setLSBit(int bitIndex, Bit bit)
+               {
+                       bits[bits.length - bitIndex - 1] = bit;
+               }
+
+               /**
+                * Returns the most significant bit at <code>bitIndex</code>. (leftmost bit of a binary number at the given index)
+                */
+               public Bit getMSBit(int bitIndex)
                {
                        return bits[bitIndex];
                }
 
+               /**
+                * Returns the least significant bit at <code>bitIndex</code>. (rightmost bit of a binary number at the given index)
+                */
+               public Bit getLSBit(int bitIndex)
+               {
+                       return bits[bits.length - bitIndex - 1];
+               }
+
                public int length()
                {
                        return bits.length;
@@ -284,7 +319,7 @@ public final class BitVector implements StrictLogicType<BitVector>, Iterable<Bit
        }
 
        /**
-        * All {@link Bit}s symbols concatenated together
+        * All {@link Bit}s symbols concatenated together (MSB first)
         * 
         * @see #parse(String)
         */
@@ -298,7 +333,7 @@ public final class BitVector implements StrictLogicType<BitVector>, Iterable<Bit
        }
 
        /**
-        * Parses a String containing solely {@link Bit} symbols
+        * Parses a String containing solely {@link Bit} symbols (MSB first)
         * 
         * @see #toString()
         */
@@ -312,6 +347,9 @@ public final class BitVector implements StrictLogicType<BitVector>, Iterable<Bit
                return new BitVector(values);
        }
 
+       /**
+        * Iterate over the {@link Bit}s of the BitVector <b>from MSB to LSB</b> (left to right).
+        */
        @Override
        public Iterator<Bit> iterator()
        {
@@ -324,7 +362,7 @@ public final class BitVector implements StrictLogicType<BitVector>, Iterable<Bit
                        {
                                if (!hasNext())
                                        throw new NoSuchElementException();
-                               return getBit(pos++);
+                               return getMSBit(pos++);
                        }
 
                        @Override