byucc.jhdl.util.BVFormat
Class BVFormat

java.lang.Object
  byucc.jhdl.util.BVFormat.BVFormat

public class BVFormat

extends java.lang.Object

This class is used to convert BVs into formatted strings for display purposes. The class can split a BV into several fields and display each field in its own radix. Specifiers for different radices are as follows:

• x - hexidecimal
• d - signed decimal
• u - unsigned decimal
• b - binary
• c - custom (see below)

A field is specified as follows (optional parameters are enclosed in []):

   %[width]{type}[extras]{bit specification}
   

An explanation of the parts of a field specification is given below:

• [width]: The optional width entry allows the user to specify a minimum width for the field. Please note that the field will be right justified when the field is extended to the minimum length.
• {type}: A type is one of the specifiers listed above.
• [extras]: The custom type (c) requires some extra information which is discussed below.
• {bit specification} There are two types of bit specifications:
  • Regular: [{range} | "*"]. This is used for specifying the range of an integer field. If you specify "*" here, it means take the entire width of the BV.
  • Fixed Point: [{range}.{range}]. This form is used to specify the ranges for the whole and fractional part of a fixed point number. Please note that custom fields cannot accept a fixed point specification.
  A range is specified as top:bottom or as a single index. Please note that the square brackets ([]) do not denote optional parameters here, but rather are required to enclose the bit specification.

Custom fields were added to allow some flexibility in how data is presented. A custom field takes extra arguments as follows:

   (classname,methodname)
   

The BVFormat class will use reflection to find the class and static method passed as parameters. The method must be static and accept a single BV as its parameter and return a String (ie. public static String methodname(BV field);). The BVFormat class will strip the specified range from the complete BV and pass this to the static method. The method will return the String to display. This type of field can be used to display state names for a state machine, etc.

Here are some example field formats:

%8d[15:8] - diplays bits 15 through 8 as a signed decimal number. The resulting String will be at least 8 characters long.

%u[7:4.3:0] - diplays a 4.4 fixed point number as in unsigned decimal. Bits 7 to 4 represent the whole part and bits 3 to 0 represent the fractional part.

%10c(StateMachine,StateNames)[4:0] - Passes bits 4 through 0 to the static method StateNames in the class StateMachine. The BVFormat class will add spaces as necessary to ensure that the resulting String is at least 10 characters in length.

%b[12] - diplays bit 12 as a binary number.

It is also possible to add arbitrary text to the format string (excluding the '%' character, as this is used to denote the start of a field specification). The characters will be added to the format string exactly as they are entered. For example, the first two examples above could be combined into the following format string:

   a: %8d[15:8] b: %u[7:4.3:0]
   

If passed a BV with the following binary value 0011010100110101, the above format would be displayed as:

   a:       53 b: 3.3125   
   

Field Summary

static BVFormat	BINARY
static BVFormat	HEXADECIMAL
static BVFormat	SIGNED_DECIMAL
static BVFormat	UNSIGNED_DECIMAL

Constructor Summary

BVFormat(int width, java.lang.String format)
Constructs a new BVFormat object with the given format.

Method Summary

java.lang.String	formatBV(BV number) Method takes a BV and returns a string according to the current format specified.
static java.lang.String	formatBV(java.lang.String format, BV number) Method takes a BV and a format specifier and formats the BV according to the specifier.
static void	main(java.lang.String[] args) Main method is used to test the BVFormat class.
void	setFormat(java.lang.String format) Method used to change the format for a given instance of a BVFormat object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

HEXADECIMAL

public static final BVFormat HEXADECIMAL

SIGNED_DECIMAL

public static final BVFormat SIGNED_DECIMAL

UNSIGNED_DECIMAL

public static final BVFormat UNSIGNED_DECIMAL

BINARY

public static final BVFormat BINARY

Constructor Detail

BVFormat

public BVFormat(int width,
                java.lang.String format)
         throws BVFormatException

Constructs a new BVFormat object with the given format.

Parameters:

width - Width of BVs that will be passed to this object. Passing a negative number for this parameter will cause the class to attempt to format all BVs passed to the fieldFormat() method, regardless of width. Please note: This may result in an ArrayIndexOutOfBoundsException which will not be caught.

format - String representing the format to use for this BVFormat object.

Throws:

BVFormatException - Throws a BVFormatException if the format string is not valid.

Method Detail

setFormat

public void setFormat(java.lang.String format)
               throws BVFormatException

Method used to change the format for a given instance of a BVFormat object.

Parameters:

format - String representing the format to use for this BVFormat object.

Throws:

BVFormatException - Throws a BVFormatException if the format string is not valid.

java.lang.IllegalArgumentException - if one of this classes' constants are changed.

formatBV

public java.lang.String formatBV(BV number)
                          throws BVFormatException

Method takes a BV and returns a string according to the current format specified.

Parameters:

number - BV to be formatted.

Returns:

String representing the BV with the currently specified format.

Throws:

BVFormatException - If width checking is enabled, throws a BVFormatException if the BV does not have the proper width.

formatBV

public static java.lang.String formatBV(java.lang.String format,
                                        BV number)
                                 throws BVFormatException

Method takes a BV and a format specifier and formats the BV according to the specifier.

Parameters:

format - Format to use.

number - BV to be formatted.

Returns:

String representing the BV with the specified format.

Throws:

BVFormatException - If width checking is enabled, throws a BVFormatException if the BV does not have the proper width.

main

public static void main(java.lang.String[] args)

Main method is used to test the BVFormat class. This test will construct the BVFormat object twice to make sure that the parser was not built as static.

Parameters:

args - Command line arguments. First argument is the format string all other arguments are binary representations of the BitVectors to test.