[FIX-issue#99] Allowing negative logic index values

lib/src/logic.dart

@@ -449,40 +449,90 @@ class Logic {
   }
 
   /// Accesses the [index]th bit of this signal.
+  ///
+  /// Negative/Positive index values are allowed. (The negative indexing starts from the end=[width]-1)
+  /// -([width]) <= [index] < [width]
+  ///
+  /// ```dart
+  /// Logic nextVal = addOutput('nextVal', width: width);
+  /// // Example: val = 0xce, val.width = 8, bin(0xce) = "0b11001110"
+  /// // Positive Indexing
+  /// nextVal <= val[3]; // output: 1
+  ///
+  /// // Negative Indexing
+  /// nextVal <= val[-5]; // output: 1, also val[3] == val[-5]
+  ///
+  /// // Error cases
+  /// nextVal <= val[-9]; // Error!: allowed values [-8, 7]
+  /// nextVal <= val[8]; // Error!: allowed values [-8, 7]
+  /// ```
+  ///
   Logic operator [](int index) => slice(index, index);
 
   /// Accesses a subset of this signal from [startIndex] to [endIndex],
   /// both inclusive.
   ///
-  /// If [endIndex] is less than [startIndex], the returned value will be
-  /// reversed relative to the original signal.
-  Logic slice(int endIndex, int startIndex) =>
-      BusSubset(this, startIndex, endIndex).subset;
+  /// If [endIndex] comes before the [startIndex] on position, the returned
+  /// value will be reversed relative to the original signal.
+  /// Negative/Positive index values are allowed. (The negative indexing starts from where the array ends)
+  ///
+  /// ```dart
+  /// Logic nextVal = addOutput('nextVal', width: width);
+  /// // Example: val = 0xce, val.width = 8, bin(0xce) = "0b11001110"
+  /// // Negative Slicing
+  /// nextVal <= val.slice(val.width - 1, -3); // = val.slice(7,5) & output: 0b110, where the output.width=3
+  ///
+  /// // Positive Slicing
+  /// nextVal <= val.slice(5, 0); // = val.slice(-3, -8) & output: 0b001110, where the output.width=6
+  /// ```
+  ///
+  Logic slice(int endIndex, int startIndex) {
+    // Given start and end index, if either of them are seen to be -ve index
+    // value(s) then convert them to a +ve index value(s)
+    final modifiedStartIndex =
+        (startIndex < 0) ? width + startIndex : startIndex;
+    final modifiedEndIndex = (endIndex < 0) ? width + endIndex : endIndex;
+
+    // Create a new bus subset
+    return BusSubset(this, modifiedStartIndex, modifiedEndIndex).subset;
+  }
 
   /// Returns a version of this [Logic] with the bit order reversed.
   Logic get reversed => slice(0, width - 1);
 
   /// Returns a subset [Logic].  It is inclusive of [startIndex], exclusive of
   /// [endIndex].
   ///
-  /// [startIndex] must be less than [endIndex]. If [startIndex] and [endIndex]
-  /// are equal, then a zero-width signal is returned.
+  /// The [startIndex] must come before the [endIndex]. If [startIndex] and
+  /// [endIndex] are equal, then a zero-width signal is returned.
+  /// Negative/Positive index values are allowed. (The negative indexing starts from where the array ends)
+  ///
+  /// ```dart
+  /// Logic nextVal = addOutput('nextVal', width: width);
+  /// // Example: val = 0xce, val.width = 8, bin(0xce) = "0b11001110"
+  /// // Negative getRange
+  /// nextVal <= val.getRange(-3, val.width); // = val.getRange(5,8) & output: 0b110, where the output.width=3
+  ///
+  /// // Positive getRange
+  /// nextVal <= val.getRange(0, 6); // = val.slice(0, -2) & output: 0b001110, where the output.width=6
+  /// ```
+  ///
   Logic getRange(int startIndex, int endIndex) {
-    if (endIndex < startIndex) {
-      throw Exception(
-          'End ($endIndex) cannot be less than start ($startIndex).');
-    }
-    if (endIndex > width) {
-      throw Exception('End ($endIndex) must be less than width ($width).');
-    }
-    if (startIndex < 0) {
-      throw Exception(
-          'Start ($startIndex) must be greater than or equal to 0.');
-    }
     if (endIndex == startIndex) {
       return Const(0, width: 0);
     }
-    return slice(endIndex - 1, startIndex);
+
+    // Given start and end index, if either of them are seen to be -ve index
+    // value(s) then conver them to a +ve index value(s)
+    final modifiedStartIndex =
+        (startIndex < 0) ? width + startIndex : startIndex;
+    final modifiedEndIndex = (endIndex < 0) ? width + endIndex : endIndex;
+    if (modifiedEndIndex < modifiedStartIndex) {
+      throw Exception(
+          'End $modifiedEndIndex(=$endIndex) cannot be less than start'
+          ' $modifiedStartIndex(=$startIndex).');
+    }
+    return slice(modifiedEndIndex - 1, modifiedStartIndex);
   }
 
   /// Returns a new [Logic] with width [newWidth] where new bits added are zeros

lib/src/modules/bus.dart

@@ -38,13 +38,18 @@ class BusSubset extends Module with InlineSystemVerilog {
   BusSubset(Logic bus, this.startIndex, this.endIndex,
       {String name = 'bussubset'})
       : super(name: name) {
+    // If a converted index value is still -ve then it's an Index out of bounds
+    // on a Logic Bus
     if (startIndex < 0 || endIndex < 0) {
-      throw Exception('Cannot access negative indices!'
-          '  Indices $startIndex and/or $endIndex are invalid.');
+      throw Exception(
+          'Start ($startIndex) and End ($endIndex) must be greater than or '
+          'equal to 0.');
     }
+    // If the +ve indices are more than Logic bus width, Index out of bounds
     if (endIndex > bus.width - 1 || startIndex > bus.width - 1) {
-      throw Exception('Index out of bounds, indices $startIndex and'
-          ' $endIndex must be less than width-1');
+      throw Exception(
+          'Index out of bounds, indices $startIndex and $endIndex must be less'
+          ' than ${bus.width}');
     }
 
     // original name can't be unpreferred because you cannot do a bit slice

lib/src/utilities/simcompare.dart

@@ -204,7 +204,7 @@ abstract class SimCompare {
     Directory(dir).createSync(recursive: true);
     File(tmpTestFile).writeAsStringSync(testbench);
     final compileResult = Process.runSync('iverilog',
-        ['-g2012', tmpTestFile, '-o', tmpOutput] + iverilogExtraArgs);
+        ['-g2012', '-o', tmpOutput, ...iverilogExtraArgs, tmpTestFile]);
     bool printIfContentsAndCheckError(dynamic output) {
       if (output.toString().isNotEmpty) {
         print(output);

lib/src/values/logic_value.dart

@@ -298,12 +298,28 @@ abstract class LogicValue {
   }
 
   /// Returns the `i`th bit of this [LogicValue]
+  ///
+  /// The [index] provided can be positive or negative. For positive [index],
+  /// the indexing is performed from front of the LogicValue.
+  /// For negative [index], the indexing started from last index and
+  /// goes to front.
+  /// Note: the [index] value must follow, -[width] <= [index] < [width]
+  ///
+  /// ```dart
+  /// LogicValue.ofString('1111')[2];  // == LogicValue.one
+  /// LogicValue.ofString('0111')[-1]; // == LogicValue.zero
+  /// LogicValue.ofString('0100')[-2]; // == LogicValue.one
+  /// LogicValue.ofString('0101')[-5]; // Error - out of range
+  /// LogicValue.ofString('0101')[10]; // Error - out of range
+  /// ```
+  ///
   LogicValue operator [](int index) {
-    if (index >= width || index < 0) {
+    final modifiedIndex = (index < 0) ? width + index : index;
+    if (modifiedIndex >= width || modifiedIndex < 0) {
       throw IndexError(index, this, 'LogicValueIndexOutOfRange',
-          'Index out of range: $index.', width);
+          'Index out of range: $modifiedIndex(=$index).', width);
     }
-    return _getIndex(index);
+    return _getIndex(modifiedIndex);
   }
 
   /// Returns the `i`th bit of this [LogicValue].  Performs no boundary checks.
@@ -316,21 +332,39 @@ abstract class LogicValue {
   /// Returns a subset [LogicValue].  It is inclusive of [startIndex], exclusive
   /// of [endIndex].
   ///
-  /// [startIndex] must be less than [endIndex]. If [startIndex] and [endIndex]
-  /// are equal, then a zero-width value is returned.
+  /// [startIndex] must come before the [endIndex] on position. If [startIndex]
+  /// and [endIndex] are equal, then a zero-width value is returned.
+  /// Negative/Positive index values are allowed. (The negative indexing starts from the end=[width]-1)
+  ///
+  /// ```dart [TODO]
+  /// LogicValue.ofString('0101').getRange(0, 2);   // == LogicValue.ofString('01')
+  /// LogicValue.ofString('0101').getRange(1, -2);  // == LogicValue.zero
+  /// LogicValue.ofString('0101').getRange(-3, 4);  // == LogicValue.ofString('010')
+  /// LogicValue.ofString('0101').getRange(-1, -2); // Error - negative end index and start > end - error! start must be less than end
+  /// LogicValue.ofString('0101').getRange(2, 1);   // Error - bad inputs start > end
+  /// LogicValue.ofString('0101').getRange(0, 7);   // Error - bad inputs end > length-1
+  /// ```
+  ///
   LogicValue getRange(int startIndex, int endIndex) {
-    if (endIndex < startIndex) {
+    final modifiedStartIndex =
+        (startIndex < 0) ? width + startIndex : startIndex;
+    final modifiedEndIndex = (endIndex < 0) ? width + endIndex : endIndex;
+    if (modifiedEndIndex < modifiedStartIndex) {
       throw Exception(
-          'End ($endIndex) cannot be less than start ($startIndex).');
+          'End $modifiedEndIndex(=$endIndex) cannot be less than start '
+          '$modifiedStartIndex(=$startIndex).');
     }
-    if (endIndex > width) {
-      throw Exception('End ($endIndex) must be less than width ($width).');
+    if (modifiedEndIndex > width) {
+      throw Exception(
+          'End $modifiedEndIndex(=$endIndex) must be less than width'
+          ' ($width).');
     }
-    if (startIndex < 0) {
+    if (modifiedStartIndex < 0) {
       throw Exception(
-          'Start ($startIndex) must be greater than or equal to 0.');
+          'Start $modifiedStartIndex(=$startIndex) must be greater than or '
+          'equal to 0.');
     }
-    return _getRange(startIndex, endIndex);
+    return _getRange(modifiedStartIndex, modifiedEndIndex);
   }
 
   /// Returns a subset [LogicValue].  It is inclusive of [start], exclusive of
@@ -344,11 +378,22 @@ abstract class LogicValue {
   ///
   /// If [endIndex] is less than [startIndex], the returned value will be
   /// reversed relative to the original value.
+  ///
+  /// ```dart [TODO]
+  /// LogicValue.ofString('xz01').slice(2, 1);    // == LogicValue.ofString('z0')
+  /// LogicValue.ofString('xz01').slice(-2, -3);  // == LogicValue.ofString('z0')
+  /// LogicValue.ofString('xz01').slice(1, 3);    // == LogicValue.ofString('0zx')
+  /// LogicValue.ofString('xz01').slice(-3, -1);  // == LogicValue.ofString('0zx')
+  /// LogicValue.ofString('xz01').slice(-2, -2);  // == LogicValue.ofString('z')
+  /// ```
   LogicValue slice(int endIndex, int startIndex) {
-    if (startIndex <= endIndex) {
-      return getRange(startIndex, endIndex + 1);
+    final modifiedStartIndex =
+        (startIndex < 0) ? width + startIndex : startIndex;
+    final modifiedEndIndex = (endIndex < 0) ? width + endIndex : endIndex;
+    if (modifiedStartIndex <= modifiedEndIndex) {
+      return getRange(modifiedStartIndex, modifiedEndIndex + 1);
     } else {
-      return getRange(endIndex, startIndex + 1).reversed;
+      return getRange(modifiedEndIndex, modifiedStartIndex + 1).reversed;
     }
   }