# 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

### Syntax

### Description

returns a signed
`a`

= fi`fi`

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

returns a
signed `a`

= fi(`v`

)`fi`

object with value `v`

, a 16-bit word
length, and best-precision fraction length.

returns a `a`

= fi(`v`

,`s`

,`w`

,`slopeadjustmentfactor`

,`fixedexponent`

,`bias`

)`fi`

object with value `v`

, signedness
`s`

, word length `w`

,
`slopeadjustmentfactor`

, `fixedexponent`

, and
`bias`

.

returns a `a`

= fi(`v`

,`T`

)`fi`

object with value `v`

and `numerictype`

`T`

.

returns a `a`

= fi(___,`Name,Value`

)`fi`

object with property values specified by one or more
name-value pair arguments.

### Input Arguments

`v`

— Value

scalar | vector | matrix | multidimensional array

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`

`s`

— Signedness

`true`

or `1`

(default) | `false`

or `0`

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`

`w`

— Word length in bits

16 (default) | positive scalar integer

Word length in bits of the `fi`

object, specified as a positive
scalar integer.

The word length must be an integer in the range 1 ≤ `w`

≤ 65535.

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `uint8`

| `uint16`

| `uint32`

| `uint64`

| `logical`

`f`

— Fraction length in bits

15 (default) | scalar integer

Fraction length in bits of the stored integer value of the `fi`

object, specified as a scalar integer. The fraction length must be an integer in the
range -65535 ≤ `f`

≤ 65535.

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`

— Slope

positive scalar

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-worldvalue=(slope\times integer)+bias$$

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `uint8`

| `uint16`

| `uint32`

| `uint64`

| `logical`

`bias`

— Bias

scalar

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-worldvalue=(slope\times integer)+bias$$

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `uint8`

| `uint16`

| `uint32`

| `uint64`

| `logical`

`slopeadjustmentfactor`

— Slope adjustment factor

scalar greater than or equal to `1`

and less than
`2`

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=slopeadjustmentfactor\times {2}^{fixedexponent}$$

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `uint8`

| `uint16`

| `uint32`

| `uint64`

| `logical`

`fixedexponent`

— Fixed exponent

scalar

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=slopeadjustmentfactor\times {2}^{fixedexponent}$$

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `uint8`

| `uint16`

| `uint32`

| `uint64`

| `logical`

`T`

— Numeric type properties

`numerictype`

object

Numeric type properties of the `fi`

object, specified as a
`numerictype`

object.

`F`

— Fixed-point math properties

`fimath`

object

Fixed-point math properties of the `fi`

object, specified as a
`fimath`

object.

If no `fimath`

properties are specified, the
`fi`

constructor uses nearest rounding and saturates on overflow
for the creation of the `fi`

object regardless of
`globalfimath`

settings. For an example of this behavior, see Specify Rounding and Overflow Modes in fi Object Constructor.

## 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

### Create `fi`

Object

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

### Create `fi `

Object with Slope and Bias Scaling

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

$$\mathrm{real}\text{\hspace{0.17em}}\mathrm{world}\text{\hspace{0.17em}}\mathrm{value}=\left(\mathrm{slope}\times \mathrm{integer}\right)+\mathrm{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

$\mathit{s}\mathrm{lope}\text{\hspace{0.17em}}=\text{\hspace{0.17em}}\mathrm{slopeadjustmentfactor}\times \text{\hspace{0.17em}}{2}^{\mathrm{fixedexponent}}$.

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

### Create `fi`

Object from `numerictype`

Object

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

### Create `fi`

Object with Associated `fimath`

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 `fi`

Object from Non-Double Value

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

### Specify Rounding and Overflow Modes in `fi`

Object Constructor

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

Creating a `fi`

object with no properties set will use the default `RoundingMethod`

and `OverflowAction`

, regardless of any `globalfimath`

settings.

To observe this behavior, specify `globalfimath`

.

resetglobalfimath globalfimath('RoundingMethod','floor','OverflowAction','wrap')

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

Construct a `fi`

object with no `fimath`

settings in the constructor.

b = fi([3.6 128],1,8,0)

b = 4 127 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 8 FractionLength: 0

The resulting value of `b`

is uses `Nearest`

rounding and `Saturate`

as the overflow action. If this behavior is not suitable for your application, see fi Constructor Does Not Follow globalfimath Rules for a workaround.

Reset the globalfimath to restore default values.

resetglobalfimath;

### Set Data Type Override on `fi`

Object

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;

`fi`

Behavior for `-Inf`

, `Inf`

, and `NaN`

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

### 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.

### HDL Code Generation

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

## Version History

**Introduced before R2006a**

### R2021a: Inexact property names for `fi`

, `fimath`

, and
`numerictype`

objects not supported

In previous releases, inexact property names for `fi`

,
`fimath`

, and `numerictype`

objects would result in a
warning. In R2021a, support for inexact property names was removed. Use exact property names
instead.

### R2020b: Change in default behavior of `fi`

for `-Inf`

, `Inf`

, and `NaN`

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`

.

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)