Main Content

fi

Construct fixed-point numeric object

Description

To assign a fixed-point data type to a number or variable, create a fi object using the fi constructor. You can specify numeric attributes and math rules in the constructor or by using the numerictype and fimath objects.

Creation

Description

example

a = fi returns a signed fi object with no value, a 16-bit word length, and a 15-bit fraction length.

example

a = fi(v) returns a signed fi object with value v, a 16-bit word length, and best-precision fraction length.

example

a = fi(v,s) returns a fi object with value v, signedness s, a 16-bit word length, and best-precision fraction length.

example

a = fi(v,s,w) returns a fi object with value v, signedness s, and word length w.

example

a = fi(v,s,w,f) returns a fi object with value v, signedness s, word length w, and fraction length f.

example

a = fi(v,s,w,slope,bias) returns a fi object with value v, signedness s, slope, and bias.

example

a = fi(v,s,w,slopeadjustmentfactor,fixedexponent,bias) returns a fi object with value v, signedness s, slopeadjustmentfactor, fixedexponent, and bias.

example

a = fi(v,T) returns a fi object with value v and numerictype T.

example

a = fi(___,F) returns a fi object with fimath F.

example

a = fi(___,Name,Value) returns a fi object with property values specified by one or more name-value pair arguments.

Input Arguments

expand all

Value of the fi object, specified as a scalar, vector, matrix, or multidimensional array.

The value of the returned fi object is the value of the input v quantized to the data type specified in the fi constructor. When the input v is a non-double and you do not specify the word length or fraction length, the returned fi object retains the numerictype of the input. For an example, see Create fi Object From Non-double Value.

You can specify the non-finite values -Inf, Inf, and NaN as the value only if you fully specify the numerictype of the fi object. When fi is specified as a fixed-point numerictype,

  • NaN maps to 0.

  • When the 'OverflowAction' property of the fi object is set to 'Wrap', -Inf, and Inf map to 0.

  • When the 'OverflowAction' property of the fi object is set to 'Saturate', Inf maps to the largest representable value, and -Inf maps to the smallest representable value.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | fi

Signedness of the fi object, specified as a numeric or logical 1 (true) or 0 (false). A value of 1 (true) indicates a signed data type. A value of 0 (false) indicates an unsigned data type.

Data Types: logical

Word length in bits of the fi object, specified as a positive scalar integer.

The fi object has a word length limit of 65535 bits.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

Fraction length in bits of the stored integer value of the fi object, specified as a scalar integer.

If you do not specify a fraction length, the fi object automatically uses the fraction length that gives the best precision while avoiding overflow for the specified value, word length, and signedness.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

Slope of the scaling of the fi object, specified as a positive scalar.

This equation represents the real-world value of a slope bias scaled number.

real-world value=(slope×integer)+bias

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

Bias of the scaling of the fi object, specified as a scalar.

This equation represents the real-world value of a slope bias scaled number.

real-world value=(slope×integer)+bias

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

Slope adjustment factor of the fi object, specified as a scalar greater than or equal to 1 and less than 2.

The following equation demonstrates the relationship between the slope, fixed exponent, and slope adjustment factor.

slope=slope adjustment factor×2fixed exponent

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

Fixed exponent of the fi object, specified as a scalar.

The following equation demonstrates the relationship between the slope, fixed exponent, and slope adjustment factor.

slope=slope adjustment factor×2fixed exponent

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

Numeric type properties of the fi object, specified as a numerictype object.

Fixed-point math properties of the fi object, specified as a fimath object.

Properties

The fi object has three types of properties:

You can set these properties when you create a fi object. Use the data properties to access data in a fi object. The fimath properties and numerictype properties are, by transitivity, also properties of the fi object. fimath properties determine the rules for performing fixed-point arithmetic operations on fi objects. The numerictype object contains all the data type and scaling attributes of a fixed-point object.

Examples

collapse all

Create a fi object using the default constructor. The constructor returns a signed fi object with no value, a 16-bit word length, and a 15-bit fraction length.

a = fi
a = 

[]

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 16
        FractionLength: 15

Create a signed fi object with a value of pi, a 16-bit word length, and best-precision fraction length. The fraction length is automatically set to achieve the best precision possible without overflow.

a = fi(pi)
a = 
    3.1416

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 16
        FractionLength: 13

Create an unsigned fi object with a value of pi. When you specify only the value and the signedness of the fi object, the word length defaults to 16 bits with best-precision fraction length.

a = fi(pi,0)
a = 
    3.1416

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Unsigned
            WordLength: 16
        FractionLength: 14

Create a signed fi object with a word length of 8 bits and best-precision fraction length. In this example, the fraction length of a is 5 because three bits are required to represent the integer portion of the value when the data type is signed.

a = fi(pi,1,8)
a = 
    3.1562

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 8
        FractionLength: 5

If the fi object is unsigned, only two bits are needed to represent the integer portion, leaving six fractional bits.

b = fi(pi,0,8)
b = 
    3.1406

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Unsigned
            WordLength: 8
        FractionLength: 6

Create a signed fi object with a value of pi, a word length of 8 bits, and a fraction length of 3 bits.

a = fi(pi,1,8,3)
a = 
    3.1250

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 8
        FractionLength: 3

Create an array of fi objects with 16-bit word length and 12-bit fraction length.

a = fi((magic(3)/10),1,16,12)
a = 
    0.8000    0.1001    0.6001
    0.3000    0.5000    0.7000
    0.3999    0.8999    0.2000

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 16
        FractionLength: 12

The real-world value of a slope and bias scaled number is represented by

realworldvalue=(slope×integer)+bias.

To create a fi object that uses slope and bias scaling, include the slope and bias arguments after the word length in the constructor. For example, create a fi object with a slope of 3 and a bias of 2.

a = fi(pi,1,16,3,2)
a = 
     2

          DataTypeMode: Fixed-point: slope and bias scaling
            Signedness: Signed
            WordLength: 16
                 Slope: 3
                  Bias: 2

The DataTypeMode property of the fi object a is Fixed-point: slope and bias scaling.

Alternatively, you can specify the slope adjustment factor and fixed exponent where

slope=slopeadjustmentfactor×2fixedexponent.

For example, create a fi object with a slope adjustment factor of 1.5, a fixed exponent of 1, and a bias of 2.

a = fi(pi,1,16,1.5,1,2)
a = 
     2

          DataTypeMode: Fixed-point: slope and bias scaling
            Signedness: Signed
            WordLength: 16
                 Slope: 3
                  Bias: 2

A numerictype object contains all of the data type information of a fi object. numerictype properties are also properties of fi objects.

You can create a fi object that uses all of the properties of an existing numerictype object by specifying the numerictype object in the fi constructor.

T = numerictype(0,24,16)
T =


          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Unsigned
            WordLength: 24
        FractionLength: 16
a = fi(pi,T)
a = 
    3.1416

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Unsigned
            WordLength: 24
        FractionLength: 16

The arithmetic attributes of a fi object are defined by a fimath object which is attached to that fi object.

Create a fimath object and specify the OverflowAction, RoundingMethod, and ProductMode properties.

F = fimath('OverflowAction','Wrap',...
    'RoundingMethod','Floor',...
    'ProductMode','KeepMSB')
F = 
        RoundingMethod: Floor
        OverflowAction: Wrap
           ProductMode: KeepMSB
     ProductWordLength: 32
               SumMode: FullPrecision

Create a fi object and specify the fimath object F in the constructor.

a = fi(pi,F)
a = 
    3.1415

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 16
        FractionLength: 13

        RoundingMethod: Floor
        OverflowAction: Wrap
           ProductMode: KeepMSB
     ProductWordLength: 32
               SumMode: FullPrecision

Use the removefimath function to remove the associated fimath object and restore the math settings to their default values.

a = removefimath(a)
a = 
    3.1415

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 16
        FractionLength: 13

When the input argument v of a fi object is not a double and you do not specify the word length or fraction length properties, the returned fi object retains the numeric type of the input.

Create fi object from built-in integer

When the input is a built-in integer, the fixed-point attributes match the attributes of the integer type.

v1 = uint32(5);
a1 = fi(v1)
a1 = 
     5

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Unsigned
            WordLength: 32
        FractionLength: 0
v2 = int8(5);
a2 = fi(v2)
a2 = 
     5

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 8
        FractionLength: 0

Create fi object from fi object

When the input value is a fi object, the output uses the same word length, fraction length, and signedness as the input fi object.

v = fi(pi,1,24,12);
a = fi(v)
a = 
    3.1416

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 24
        FractionLength: 12

Create fi object from logical

When the input value is a logical, the DataTypeMode property of the output fi object is Boolean.

v = true;
a = fi(v)
a = 
   1

          DataTypeMode: Boolean

Create fi object from single

When the input value is single, the DataTypeMode property of the output is Single.

v = single(pi);
a = fi(v)
a = 
    3.1416

          DataTypeMode: Single

You can set fimath properties, such as rounding and overflow modes during the creation of the fi object.

a = fi(pi,'RoundingMethod','Floor',...
    'OverflowAction','Wrap')
a = 
    3.1415

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 16
        FractionLength: 13

        RoundingMethod: Floor
        OverflowAction: Wrap
           ProductMode: FullPrecision
               SumMode: FullPrecision

The RoundingMethod and OverflowAction properties are properties of the fimath object. Specifying these properties in the fi constructor associates a local fimath object with the fi object.

Use the removefimath function to remove the local fimath and set the math properties back to their default values.

a = removefimath(a)
a = 
    3.1415

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 16
        FractionLength: 13

This examples shows how to use the DataTypeOverride setting of the fipref object to override fi objects with doubles, singles, or scaled doubles. The fipref object defines the display and logging attributes for all fi objects.

Save the current fipref settings to restore later.

fp = fipref;
initialDTO = fp.DataTypeOverride;

Create a fi object with the default settings and original fipref settings.

a = fi(pi)
a = 
    3.1416

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 16
        FractionLength: 13

Use the fipref object to turn on data type override to doubles.

fipref('DataTypeOVerride','TrueDoubles')
ans = 
                NumberDisplay: 'RealWorldValue'
           NumericTypeDisplay: 'full'
                FimathDisplay: 'full'
                  LoggingMode: 'Off'
             DataTypeOverride: 'TrueDoubles'
    DataTypeOverrideAppliesTo: 'AllNumericTypes'

Create a new fi object without specifying its DataTypeOverride property so that it uses the data type override settings specified using fipref.

a = fi(pi)
a = 
    3.1416

          DataTypeMode: Double

Create another fi object and set its DataTypeOverride setting to off so that it ignores the data type override settings of the fipref object.

b = fi(pi,'DataTypeOverride','Off')
b = 
    3.1416

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 16
        FractionLength: 13

Restore the fipref settings saved at the start of the example.

fp.DataTypeOverride = initialDTO;

To use the non-numeric values -Inf, Inf, and NaN as fixed-point values with fi, you must fully specify the numeric type of the fixed-point object. Automatic best-precision scaling is not supported for these values.

Saturate on Overflow

When the numeric type of the fi object is specified to saturate on overflow, then Inf maps to the largest representable value of the specified numeric type, and -Inf maps to the smallest representable value. NaN maps to zero.

x = [-inf nan inf];
a = fi(x,1,8,0,'OverflowAction','Saturate')
b = fi(x,0,8,0,'OverflowAction','Saturate')
a = 

  -128     0   127

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 8
        FractionLength: 0

        RoundingMethod: Nearest
        OverflowAction: Saturate
           ProductMode: FullPrecision
               SumMode: FullPrecision

b = 

     0     0   255

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Unsigned
            WordLength: 8
        FractionLength: 0

        RoundingMethod: Nearest
        OverflowAction: Saturate
           ProductMode: FullPrecision
               SumMode: FullPrecision

Wrap on Overflow

When the numeric type of the fi object is specified to wrap on overflow, then -Inf, Inf, and NaN map to zero.

x = [-inf nan inf];
a = fi(x,1,8,0,'OverflowAction','Wrap')
b = fi(x,0,8,0,'OverflowAction','Wrap')
a = 

     0     0     0

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 8
        FractionLength: 0

        RoundingMethod: Nearest
        OverflowAction: Wrap
           ProductMode: FullPrecision
               SumMode: FullPrecision

b = 

     0     0     0

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Unsigned
            WordLength: 8
        FractionLength: 0

        RoundingMethod: Nearest
        OverflowAction: Wrap
           ProductMode: FullPrecision
               SumMode: FullPrecision

Tips

  • Use the fipref object to control the display, logging, and data type override preferences for fi objects.

Extended Capabilities

HDL Code Generation
Generate VHDL, Verilog and SystemVerilog code for FPGA and ASIC designs using HDL Coder™.

Version History

Introduced before R2006a

expand all