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 using the numerictype and fimath objects.

Creation

Syntax

a = fi

a = fi(v)

a = fi(v,s)

a = fi(v,s,w)

a = fi(v,s,w,f)

a = fi(v,s, w,slope,bias)

a = fi(v,s, w,slopeadjustmentfactor,fixedexponent,bias)

a = fi(v,T)

a = fi(___,F)

a = fi(___,Name,Value)

Description

example

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

example

a = fi(v) returns a fixed-point object with value v and default property values.

example

a = fi(v,s) returns a fixed-point object with signedness (signed or unsigned) s.

example

a = fi(v,s,w) creates a fixed-point object with word length specified by w.

example

a = fi(v,s,w,f) creates a fixed-point object with fraction length specified by f.

example

a = fi(v,s, w,slope,bias) creates a fixed-point object using slope and bias scaling.

example

a = fi(v,s, w,slopeadjustmentfactor,fixedexponent,bias) creates a fixed-point object using slope and bias scaling.

example

a = fi(v,T) creates a fixed-point object with value v, and numeric type properties, T.

example

a = fi(___,F) creates a fixed-point object with math settings specified by fimath object F.

example

a = fi(___,Name,Value) creates a fixed-point object with property values specified by one or more Name,Value pair arguments. Name must appear inside single quotes (''). You can specify several name-value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Input Arguments

expand all

`v` — Value
scalar | vector | matrix | multi-dimensional array

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

The value of the output fi object is the value of the input quantized to the data type specified in the fi constructor.

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

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

`s` — Signedness
1 (default) | 0

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

Data Types: logical

`w` — Word length
16 (default) | scalar integer

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

`f` — Fraction length
15 (default) | scalar integer

Fraction length, in bits, 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.

`slope` — Slope
scalar integer

Slope of the scaling, specified as a scalar integer. The following equation represents the real-world value of a slope bias scaled number.

$r e a l - w o r l d v a l u e = (s l o p e \times i n t e g e r) + b i a s$

`bias` — Bias
scalar

Bias of the scaling, specified as a scalar. The following equation represents the real-world value of a slope bias scaled number.

$r e a l - w o r l d v a l u e = (s l o p e \times i n t e g e r) + b i a s$

`slopeadjustmentfactor` — Slope adjustment factor
scalar integer

The slope adjustment factor of a slope bias scaled number. The following equation demonstrates the relationship between the slope, fixed exponent, and slope adjustment factor.

$s l o p e = s l o p e a d j u s t m e n t f a c t o r \times 2^{f i x e d e x p o n e n t}$

`fixedexponent` — Fixed exponent
scalar integer

The fixed exponent of a slope bias scaled number. The following equation demonstrates the relationship between the slope, fixed exponent, and slope adjustment factor.

$s l o p e = s l o p e a d j u s t m e n t f a c t o r \times 2^{f i x e d e x p o n e n t}$

`T` — Numeric type properties
`numerictype` object

Numeric type properties of the fi object, specified as a numerictype object. For more information, see numerictype.

`F` — Fixed-point math properties
`fimath` object

Fixed-point math properties of the fi object, specified as a fimath object. For more information, see fimath.

Properties

fi Object Properties

Examples

collapse all

Create a `fi` object

Open Live Script

Create a signed fi object with a value of pi, a word length of eight 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

Open Live Script

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=3×3 object
    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

Create a `fi` object with Default Word Length and Fraction Length

Open Live Script

When you specify only the value and the signedness of the fi object, the word length defaults to 16 bits, and the fraction length is set to achieve the best precision possible without overflow.

a = fi(pi, 1)

a = 
    3.1416

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

Create a `fi` Object with Default Precision

Open Live Script

If you do not specify a fraction length, input argument f, the fraction length of the fi object defaults to the fraction length that offers the best precision.

a = fi(pi,1,8)

a = 
    3.1562

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

The fraction length of fi object a is five because three bits are required to represent the integer portion of the value when the data type is signed. If the fi object uses an unsigned data type, 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 `fi` Object with Slope and Bias Scaling

Open Live Script

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

$real world value = (slope \times 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.

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 slope and bias scaling.

Create a `fi` Object From a Non-Double Value

Open Live Script

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

Create a fi object from a 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 a fi object from a fi object

When the input value is a fi object, the output uses the same word length, fraction length, and signedness of 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 a fi object from a logical

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

v = true;
a = fi(v)

a = 
   1

          DataTypeMode: Boolean

Create a fi object from a single

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

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

a = 
    3.1416

          DataTypeMode: Single

Create a `fi` Object With an Associated `fimath` Object

Open Live Script

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

Create a `fi` Object From a `numerictype` Object

Open Live Script

A numerictype object contains all of the data type information of a fi object. By transitivity, 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

Create a `fi` Object With Fraction Length Greater Than Word Length

Open Live Script

When you use binary-point representation for a fixed-point number, the fraction length can be greater than the word length. In this case, there are implicit leading zeros (for positive numbers) or ones (for negative numbers) between the binary point and the first significant binary digit.

Consider a signed value with a word length of 8, fraction length of 10, and a stored integer value of 5. Calculate the real-world value using the following equation.

$real world value = stored integer \times 2^{- fraction length}$

realWorldValue = 5*2^(-10)

realWorldValue = 0.0049

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

a = fi(realWorldValue, 1, 8, 10)

a = 
    0.0049

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

Get the stored integer value of a using the int function.

int(a)

ans = int8
    5

Use the bin function to view the stored integer value in binary.

bin(a)

ans = 
'00000101'

Because the fraction length is two bits longer than the word length, the binary value of the stored integer is X.XX00000101, where X is a placeholder for implicit zeroes. 0.0000000101 (binary) is equivalent to 0.0049 (decimal).

Create a `fi` Object With Negative Fraction Length

Open Live Script

When you use binary-point representation for a fixed-point number, the fraction length can be negative. In this case, there are implicit trailing zeros (for positive numbers) or ones (for negative numbers) between the binary point and the first significant binary digit.

Consider a signed data type with a word length of 8, fraction length of -2 and a stored integer value of 5. Calculate the stored integer value using the following equation.

$real world value = stored integer \times 2^{- fraction length}$

realWorldValue = 5*2^(2)

realWorldValue = 20

Create a signed fi object with value realWorldValue, a word length of 8 bits, and a fraction length of -2 bits.

a = fi(realWorldValue, 1, 8, -2)

a = 
    20

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

Get the stored integer value of a using the int function.

int(a)

ans = int8
    5

Get the binary value of a using the bin function.

bin(a)

ans = 
'00000101'

Because the fraction length is negative, the binary value of the stored integer is 00000101XX, where X is a placeholder for implicit zeros. 0000010100 (binary) is equivalent to 20 (decimal).

Create a `fi` Object Specifying Rounding and Overflow Modes

Open Live Script

You can set math 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

Use `fi` as an Indexing Argument

Open Live Script

When using a fi object as an index, the value of the fi object must be an integer.

Set up an array to index into.

x = 10:-1:1;

Create an integer valued fi object and use it to index into x.

a = fi(3);
y = x(a)

y = 8

Use fi as the index in a for loop

Create fi objects to use as the index of a for loop. The values of the indices must be integers.

a = fi(1, 0, 8, 0);
b = fi(2, 0, 8, 0);
c = fi(10, 0, 8, 0);

for x = a:b:c
    x
end

x = 
     1

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

x = 
     3

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

x = 
     5

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

x = 
     7

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

x = 
     9

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

Set Data Type Override on a `fi` Object

Open Live Script

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

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

Turn on data type override to doubles and create a new fi object without specifying its DataTypeOverride property so that it uses the data type override settings specified using fipref.

fipref('DataTypeOVerride', 'TrueDoubles')

ans = 
                NumberDisplay: 'RealWorldValue'
           NumericTypeDisplay: 'full'
                FimathDisplay: 'full'
                  LoggingMode: 'Off'
             DataTypeOverride: 'TrueDoubles'
    DataTypeOverrideAppliesTo: 'AllNumericTypes'

a = fi(pi)

a = 
    3.1416

          DataTypeMode: Double

Now create a 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;

`fi` Behavior for `-Inf`, `Inf`, and `NaN`

Open Script

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

Compatibility Considerations

expand all

Change in default behavior of `fi` for `-Inf`, `Inf`, and `NaN`

Behavior changed in R2020b

In previous releases, fi would return an error when passed the non-finite input values -Inf, Inf, or NaN. fi now treats these inputs in the same way that MATLAB^® and Simulink^® handle -Inf, Inf, and NaN for integer data types.

When fi is specified as a fixed-point numeric type,

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.

For an example of this behavior, see fi Behavior for -Inf, Inf, and NaN.

Note

Best-precision scaling is not supported for input values of -Inf, Inf, or NaN.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

The default constructor syntax without any input arguments is not supported.
If the numerictype is not fully specified, the input to fi must be a constant, a fi, a single, or a built-in integer value. If the input is a built-in double value, it must be a constant. This limitation allows fi to autoscale its fraction length based on the known data type of the input.
All properties related to data type must be constant for code generation.
numerictype object information must be available for nonfixed-point Simulink inputs.

Documentation

fi

Description

Creation

Syntax

Description

Input Arguments

v — Value scalar | vector | matrix | multi-dimensional array

s — Signedness 1 (default) | 0

w — Word length 16 (default) | scalar integer

f — Fraction length 15 (default) | scalar integer

slope — Slope scalar integer

bias — Bias scalar

slopeadjustmentfactor — Slope adjustment factor scalar integer

fixedexponent — Fixed exponent scalar integer

T — Numeric type properties numerictype object

F — Fixed-point math properties fimath object

Properties

Examples

Create a fi object

Create an Array of fi Objects

Create a fi object with Default Word Length and Fraction Length

Create a fi Object with Default Precision

Create a fi Object with Slope and Bias Scaling

Create a fi Object From a Non-Double Value

Create a fi Object With an Associated fimath Object

Create a fi Object From a numerictype Object

Create a fi Object With Fraction Length Greater Than Word Length

Create a fi Object With Negative Fraction Length

Create a fi Object Specifying Rounding and Overflow Modes

Use fi as an Indexing Argument

Set Data Type Override on a fi Object

fi Behavior for -Inf, Inf, and NaN

Compatibility Considerations

Change in default behavior of fi for -Inf, Inf, and NaN

Extended Capabilities

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

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

See Also

Topics

Fixed-Point Designer Documentation

Support

`v` — Value
scalar | vector | matrix | multi-dimensional array

`s` — Signedness
1 (default) | 0

`w` — Word length
16 (default) | scalar integer

`f` — Fraction length
15 (default) | scalar integer

`slope` — Slope
scalar integer

`bias` — Bias
scalar

`slopeadjustmentfactor` — Slope adjustment factor
scalar integer

`fixedexponent` — Fixed exponent
scalar integer

`T` — Numeric type properties
`numerictype` object

`F` — Fixed-point math properties
`fimath` object

Create a `fi` object

Create an Array of `fi` Objects

Create a `fi` object with Default Word Length and Fraction Length

Create a `fi` Object with Default Precision

Create a `fi` Object with Slope and Bias Scaling

Create a `fi` Object From a Non-Double Value

Create a `fi` Object With an Associated `fimath` Object

Create a `fi` Object From a `numerictype` Object

Create a `fi` Object With Fraction Length Greater Than Word Length

Create a `fi` Object With Negative Fraction Length

Create a `fi` Object Specifying Rounding and Overflow Modes

Use `fi` as an Indexing Argument

Set Data Type Override on a `fi` Object

`fi` Behavior for `-Inf`, `Inf`, and `NaN`

Change in default behavior of `fi` for `-Inf`, `Inf`, and `NaN`

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

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