# 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

``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 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-worldvalue=\left(slope×integer\right)+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-worldvalue=\left(slope×integer\right)+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=slopeadjustmentfactor×{2}^{fixedexponent}$`

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

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

$\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. 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}×\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 ```

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.

## Version History

Introduced before R2006a

expand all