String Conversion and Formatting¶

When you need to generate a string representation of a FixedPoint number (such as stimulus generation for a test), you can use standard string conversion (via str()) or a more advanced string formatting using a standard format specifier with str.format(), format(), or f-strings. These methods are described below.

String Conversion¶

Calling str() on a FixedPoint generates a decimal, binary, octal, or hexadecimal string based on the FixedPoint.bits. The latter 3 of which are 0-padded (if necessary) to the bit length of the FixedPoint number. No radix is included.

>>> init = '0b11001'
>>> b = FixedPoint(init, 1, 3, 2, str_base=2)
>>> str(b)
'11001'
>>> o = FixedPoint(init, 1, 3, 2, str_base=8)
>>> str(o)
'31'
>>> d = FixedPoint(init, 1, 3, 2, str_base=10)
>>> str(d)
'25'
>>> h = FixedPoint(init, 1, 3, 2, str_base=16)
>>> str(h)
'19'

String Formatting¶

A FixedPoint can be formatted as a str, float, or int would, depending on the format string syntax.

Table 8 Standard Format Specifier Parsing Summary¶

format_spec

type

Formatted Type

Formatted Value

(given x = FixedPoint(...))

's'

str

str(x)

(depends on x.str_base)

'q'

x.qformat

'b'

(binary)

int

x.bits

'd'

(decimal)

'o'

(octal)

'x'

(lowercase

hexadecimal)

'X'

(uppercase

hexadecimal)

'...m' ¹

x.bits['int']

(integer bits only)

'...n' ¹

x.bits['frac']

(fractional bits only)

'e'

float

float(x)

'E'

'f'

'F'

'g'

'G'

'%'

¹ Append to the specifier of another formatted int. E.g., 'bn' would format the fractional bits of x in binary.

str() Output¶

As described above, str() generates a str from the FixedPoint.bits in the base specified by FixedPoint.str_base. This can be further formatted with the format specification mini language using the format_spec type 's'.

The example below uses a formatted string literal (or f-string) to further format the output of str().

>>> x = FixedPoint(0b1010_0101_1111, str_base=2)
>>> str(x) # This is the str() output
'101001011111'

>>> f"{x:_^16s}" # Center str(x) in a field of underscores 16 characters wide
'__101001011111__'

>>> x.str_base = 16
>>> f"{x:_^16s}" # Same thing but uses hex instead of binary due to str_base
'______a5f_______'

The same thing can be done using str.format():

>>> x.str_base = 8 # octal
>>> '{:-^16s}'.format(x)
'------5137------'

or format():

>>> x.str_base = 10
>>> format(x, '~>6s')
'~~2655'

The remaining examples will be done using f-strings, but the same syntax applies to str.format() and format().

Q Format¶

Using the format_spec type 'q' allows you to format the FixedPoint.qformat output as a string.

>>> a = FixedPoint(-12345.678)
>>> f"{a:q}"
'Q15.36'

>>> f"{a: ^10q}"
'  Q15.36  '

FixedPoint.bits¶

Using the format_spec type 'b', 'o', 'd', 'x', or 'X' allow you to format the FixedPoint.bits as an int.

>>> a = FixedPoint(0b1111_0000_1011, m=14)
>>> f"{a:#0{2 + len(a) // 4 + len(a)}_b}" # add 2 for radix, // 4 for seperators
'0b00_1111_0000_1011'

>>> f"{a:010,d}"
'00,003,851'

>>> f"{a:=^+#10X}"
'==+0XF0B=='

Integer and Fractional Bits¶

Using the format_spec type 'm' or 'n' allows you to format the integer and fractional bits as an int. Precede these types with other standard types like 'b', 'o', 'd', 'n', 'x', or 'X'.

>>> a = FixedPoint('0b11001100', signed=0, m=4, n=5)
>>> f"{a:#0{a.m+2}bm}.{a:0{a.n}bn}" # Show the binary point
'0b0110.01100'

Float Equivalent¶

Using the format_spec type 'e', 'E', 'f', 'F', 'g', 'G', or '%' allow you to format the FixedPoint as a float.

>>> a = FixedPoint(1.125, rounding='up')
>>> f"{a:#0{2+a.m}bm}.{a:0{a.n}bn} ==> {a:.3f}"
'0b1.001 ==> 1.125'

>>> f"{a:.2f}" # Show 2 decimal points
'1.12'

Attention

Convergent rounding is used for rounding floats in the example above, which is the default rounding method specified by IEEE 754. This will be the case regardless of the FixedPoint.rounding property specified.

>>> f"{a:.3%}"
'112.500%'

>>> f"{a - 1:.2%}"
'12.50%'

>>> import sys
>>> b = FixedPoint(2**sys.float_info.min_exp)
>>> f"{b:+e}"
'+4.450148e-308'