# 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

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`

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`

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

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

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.

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

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

`$real-worldvalue=\left(slope×integer\right)+bias$`

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

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

`$real-worldvalue=\left(slope×integer\right)+bias$`

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

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.

`$slope=slopeadjustmentfactor×{2}^{fixedexponent}$`

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

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

`$slope=slopeadjustmentfactor×{2}^{fixedexponent}$`

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. For more information, see `numerictype`.

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

## Examples

collapse all

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

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

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

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

`$\mathrm{real}\text{\hspace{0.17em}}\mathrm{world}\text{\hspace{0.17em}}\mathrm{value}=\left(\mathrm{slope}×\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.

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

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

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

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

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.

`$\mathrm{real}\text{\hspace{0.17em}}\mathrm{world}\text{\hspace{0.17em}}\mathrm{value}=\mathrm{stored}\text{\hspace{0.17em}}\mathrm{integer}×{2}^{-\mathrm{fraction}\text{\hspace{0.17em}}\mathrm{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).

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.

`$\mathrm{real}\text{\hspace{0.17em}}\mathrm{world}\text{\hspace{0.17em}}\mathrm{value}=\mathrm{stored}\text{\hspace{0.17em}}\mathrm{integer}×{2}^{-\mathrm{fraction}\text{\hspace{0.17em}}\mathrm{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).

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

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

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

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

Behavior changed in R2020b