Make "def width" a private API; expose isWidthKnown instead (#257)

* Make "def width" a private API; expose isWidthKnown instead

Resolves #256.

Since width was used to determine whether getWidth would succeed, I added

    def isWidthKnown: Boolean

but another option would be to expose something like

    def widthOption: Option[Int]

...thoughts?

* Document getWidth/isWidthKnown

* Add widthOption for more idiomatic Scala manipulation of widths

3 files changed, 11 insertions, 4 deletions

diff --git a/chiselFrontend/src/main/scala/chisel3/core/Aggregate.scala b/chiselFrontend/src/main/scala/chisel3/core/Aggregate.scala
index f2774a8d..15643ac8 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Aggregate.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Aggregate.scala
@@ -16,7 +16,7 @@ import chisel3.internal.sourceinfo.{SourceInfo, DeprecatedSourceInfo, VecTransfo
   */
 sealed abstract class Aggregate(dirArg: Direction) extends Data(dirArg) {
   private[core] def cloneTypeWidth(width: Width): this.type = cloneType
-  def width: Width = flatten.map(_.width).reduce(_ + _)
+  private[core] def width: Width = flatten.map(_.width).reduce(_ + _)
 }
 
 object Vec {
@@ -373,5 +373,6 @@ class Bundle extends Aggregate(NO_DIR) {
 }
 
 private[core] object Bundle {
-  val keywords = List("flip", "asInput", "asOutput", "cloneType", "toBits")
+  val keywords = List("flip", "asInput", "asOutput", "cloneType", "toBits",
+                      "widthOption")
 }
diff --git a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
index 9cca5d9d..015b9dfb 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
@@ -14,7 +14,7 @@ import chisel3.internal.firrtl.PrimOp._
 /** Element is a leaf data type: it cannot contain other Data objects. Example
   * uses are for representing primitive data types, like integers and bits.
   */
-abstract class Element(dirArg: Direction, val width: Width) extends Data(dirArg)
+abstract class Element(dirArg: Direction, private[core] val width: Width) extends Data(dirArg)
 
 /** A data type for values represented by a single bitvector. Provides basic
   * bitwise operations.
diff --git a/chiselFrontend/src/main/scala/chisel3/core/Data.scala b/chiselFrontend/src/main/scala/chisel3/core/Data.scala
index d31e50ff..8826af51 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Data.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Data.scala
@@ -56,6 +56,7 @@ abstract class Data(dirArg: Direction) extends HasId {
   private[chisel3] def ref: Arg = if (isLit) litArg.get else lref
   private[core] def cloneTypeWidth(width: Width): this.type
   private[chisel3] def toType: String
+  private[core] def width: Width
 
   def := (that: Data)(implicit sourceInfo: SourceInfo): Unit = this badConnect that
 
@@ -66,8 +67,13 @@ abstract class Data(dirArg: Direction) extends HasId {
   def litValue(): BigInt = litArg.get.num
   def isLit(): Boolean = litArg.isDefined
 
-  def width: Width
+  /** Returns the width, in bits, if currently known.
+    * @throws java.util.NoSuchElementException if the width is not known. */
   final def getWidth: Int = width.get
+  /** Returns whether the width is currently known. */
+  final def isWidthKnown: Boolean = width.known
+  /** Returns Some(width) if the width is known, else None. */
+  final def widthOption: Option[Int] = if (isWidthKnown) Some(getWidth) else None
 
   // While this being in the Data API doesn't really make sense (should be in
   // Aggregate, right?) this is because of an implementation limitation: