Documentation

# fi

Construct fixed-point numeric object

## 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(v,F) b = fi(a,F) a = fi(v,T,F) a = fi(v,s,F) a = fi(v,s,w,F) a = fi(v,s,w,f,F) a = fi(v,s,w,slope,bias,F) a = fi(v,s,w,slopeadjustmentfactor,fixedexponent,bias,F) a = fi(...'PropertyName',PropertyValue...) a = fi('PropertyName',PropertyValue...) ```

## Description

You can use the `fi` constructor function in the following ways:

• `a = fi` is the default constructor and returns a `fi` object with no value, 16-bit word length, and 15-bit fraction length.

• `a = fi(v)` returns a signed fixed-point object with value `v`, 16-bit word length, and best-precision fraction length when `v` is a double. When `v` is not a double, the `fi` constructor preserves the `numerictype` of `v`, see Create a fi Object From a Non-Double Value.

• `a = fi(v,s)` returns a fixed-point object with value `v`, `Signed` property value `s`, 16-bit word length, and best-precision fraction length. `s` can be `0` (false) for unsigned or `1` (true) for signed.

• `a = fi(v,s,w)` returns a fixed-point object with value `v`, `Signed` property value `s`, word length `w`, and best-precision fraction length.

• `a = fi(v,s,w,f)` returns a fixed-point object with value `v`, `Signed` property value `s`, word length `w`, and fraction length `f`. Fraction length can be greater than word length or negative, see Create a fi Object With Fraction Length Greater Than Word Length and Create a fi Object With Negative Fraction Length.

• `a = fi(v,s,w,slope,bias)` returns a fixed-point object with value `v`, `Signed` property value `s`, word length `w`, `slope`, and `bias`.

• `a = fi(v,s,w,slopeadjustmentfactor,fixedexponent,bias)` returns a fixed-point object with value `v`, `Signed` property value `s`, word length `w`, `slopeadjustmentfactor`, `fixedexponent`, and `bias`.

• `a = fi(v,T)` returns a fixed-point object with value `v` and `embedded.numerictype` `T`. Refer to numerictype Object Construction for more information on `numerictype` objects.

• `a = fi(v,F)` returns a fixed-point object with value `v`, `embedded.fimath` `F`, 16-bit word length, and best-precision fraction length. Refer to fimath Object Construction for more information on `fimath` objects.

• `b = fi(a,F)` allows you to maintain the value and `numerictype` object of `fi` object `a`, while changing its `fimath` object to `F`.

• `a = fi(v,T,F)` returns a fixed-point object with value `v`, `embedded.numerictype` `T`, and `embedded.fimath` `F`. The syntax ```a = fi(v,T,F)``` is equivalent to `a = fi(v,F,T)`.

• `a = fi(v,s,F)` returns a fixed-point object with value `v`, `Signed` property value `s`, 16-bit word length, best-precision fraction length, and `embedded.fimath` `F`.

• `a = fi(v,s,w,F)` returns a fixed-point object with value `v`, `Signed` property value `s`, word length `w`, best-precision fraction length, and `embedded.fimath` `F`.

• `a = fi(v,s,w,f,F)` returns a fixed-point object with value `v`, `Signed` property value `s`, word length `w`, fraction length `f`, and `embedded.fimath` `F`.

• `a = fi(v,s,w,slope,bias,F)` returns a fixed-point object with value `v`, `Signed` property value `s`, word length `w`, `slope`, `bias`, and `embedded.fimath` `F`.

• `a = fi(v,s,w,slopeadjustmentfactor,fixedexponent,bias,F)` returns a fixed-point object with value `v`, `Signed` property value `s`, word length `w`, `slopeadjustmentfactor`, `fixedexponent`, `bias`, and `embedded.fimath` `F`.

• `a = fi(...'PropertyName',PropertyValue...)` and ```a = fi('PropertyName',PropertyValue...)``` allow you to set fixed-point objects for a `fi` object by property name/property value pairs.

The `fi` object has the following three general types of properties:

### Note

These properties are described in detail in fi Object Properties in the Properties Reference.

### Data Properties

The data properties of a `fi` object are always writable.

• `bin` — Stored integer value of a `fi` object in binary

• `data` — Numerical real-world value of a `fi` object

• `dec` — Stored integer value of a `fi` object in decimal

• `double` — Real-world value of a `fi` object, stored as a MATLAB® `double`

• `hex` — Stored integer value of a `fi` object in hexadecimal

• `int` — Stored integer value of a `fi` object, stored in a built-in MATLAB integer data type

• `oct` — Stored integer value of a `fi` object in octal

• `Value` — Full-precision real-world value of a `fi` object, stored as a character vector

These properties are described in detail in fi Object Properties.

### fimath Properties

When you create a `fi` object and specify `fimath` object properties in the `fi` constructor, a `fimath` object is created as a property of the `fi` object. If you do not specify any `fimath` properties in the `fi` constructor, the resulting `fi` has no attached `fimath` object.

• `fimath``fimath` properties associated with a `fi` object

The following `fimath` properties are, by transitivity, also properties of a `fi` object. The properties of the `fimath` object listed below are always writable.

• `CastBeforeSum` — Whether both operands are cast to the sum data type before addition

### Note

This property is hidden when the `SumMode` is set to `FullPrecision`.

• `MaxProductWordLength` — Maximum allowable word length for the product data type

• `MaxSumWordLength` — Maximum allowable word length for the sum data type

• `OverflowAction` — Overflow mode

• `ProductBias` — Bias of the product data type

• `ProductFixedExponent` — Fixed exponent of the product data type

• `ProductFractionLength` — Fraction length, in bits, of the product data type

• `ProductMode` — Defines how the product data type is determined

• `ProductSlope` — Slope of the product data type

• `ProductSlopeAdjustmentFactor` — Slope adjustment factor of the product data type

• `ProductWordLength` — Word length, in bits, of the product data type

• `RoundingMethod` — Rounding mode

• `SumBias` — Bias of the sum data type

• `SumFixedExponent` — Fixed exponent of the sum data type

• `SumFractionLength` — Fraction length, in bits, of the sum data type

• `SumMode` — Defines how the sum data type is determined

• `SumSlope` — Slope of the sum data type

• `SumSlopeAdjustmentFactor` — Slope adjustment factor of the sum data type

• `SumWordLength` — The word length, in bits, of the sum data type

These properties are described in detail in fimath Object Properties.

### numerictype Properties

When you create a `fi` object, a `numerictype` object is also automatically created as a property of the `fi` object.

`numerictype` — Object containing all the data type information of a `fi` object, Simulink® signal or model parameter

The following `numerictype` properties are, by transitivity, also properties of a `fi` object. The properties of the `numerictype` object become read only after you create the `fi` object. However, you can create a copy of a `fi` object with new values specified for the `numerictype` properties.

• `Bias` — Bias of a `fi` object

• `DataType` — Data type category associated with a `fi` object

• `DataTypeMode` — Data type and scaling mode of a `fi` object

• `DataTypeOverride` — Data type override for applying `fipref` data type override settings to `fi` objects. This property provides a convenient way to ignore a global `fipref` data type override setting. Note that this property is not visible when its value is the default, `Inherit`. When this property is set to `Off`, the `fi` object uses the `numerictype` data type settings and ignores `fipref` settings.

• `FixedExponent` — Fixed-point exponent associated with a `fi` object

• `SlopeAdjustmentFactor` — Slope adjustment associated with a `fi` object

• `FractionLength` — Fraction length of the stored integer value of a `fi` object in bits

• `Scaling` — Fixed-point scaling mode of a `fi` object

• `Signed` — Whether a `fi` object is signed or unsigned

• `Signedness` — Whether a `fi` object is signed or unsigned

### Note

`numerictype` objects can have a `Signedness` of `Auto`, but all `fi` objects must be `Signed` or `Unsigned`. If a `numerictype` object with `Auto` `Signedness` is used to create a `fi` object, the `Signedness` property of the `fi` object automatically defaults to `Signed`.

• `Slope` — Slope associated with a `fi` object

• `WordLength` — Word length of the stored integer value of a `fi` object in bits

For further details on these properties, see numerictype Object Properties.

## Examples

### Note

For information about the display format of `fi` objects, refer to View Fixed-Point Data.

For examples of casting, see Cast fi Objects.

### Create a `fi` Object

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

```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 a `fi` Object With Default Precision

If you omit the argument `f`, the fraction length is set automatically to achieve the best precision possible.

``` a = fi(pi, 1, 8) a = 3.1563 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 8 FractionLength: 5 ```

### Create a `fi` Object With Default Word Length and Precision

If you omit `w` and `f`, the word length is set automatically to 16 bits and the fraction length is set to achieve the best precision possible.

```a = fi(pi, 1) ```
```a = 3.1416 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 16 FractionLength: 13 ```

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

When you create a `fi` object using the default constructor and a non-double input value, `v`, the constructor retains the `numerictype` of `v`.

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

```v = uint32(5); a = fi(v)```
```a = 5 DataTypeMode: Fixed-point: binary point scaling Signedness: Unsigned WordLength: 32 FractionLength: 0 ```

The output `a` is a `fi` object that uses the word length, fraction length, and signedness of the input `v`.

When the input 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 ```

When the input `v` is logical, then the output `a` has `DataTypeMode: Boolean`.

```v = true; a = fi(v)```
```a = 1 DataTypeMode: Boolean ```

When the input is single, the output `a` has `DataTypeMode: Single`.

```v = single(pi); a = fi(v)```
```a = 3.1416 DataTypeMode: Single ```

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

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. We can calculate the real-world value.

```RealWorldValue = StoredInteger * 2 ^ -FractionLength RealWorldValue = 5 * 2 ^ -10 = 0.0049 ```

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

`a = fi(0.0048828125, true, 8, 10)`
```a = 0.0049 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 8 FractionLength: 10 ```

Get the stored integer value of `a`.

`a.int`
```ans = int8 5 ```

Get the binary value of the stored integer.

`a.bin`
```ans = '00000101' ```

Because the fraction length is 2 bits longer than the word length, the binary value of the stored integer is `x.xx00000101` , where `x` is a placeholder for implicit zeros. `0.0000000101` (binary) is equivalent to `0.0049` (decimal).

### Create a fi Object With Negative Fraction Length

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 value with a word length of 8, fraction length of –2 and a stored integer value of 5. We can calculate the real-world value.

```RealWorldValue = StoredInteger * 2 ^ -FractionLength RealWorldValue = 5 * 2 ^ 2 = 20 ```

Create a signed `fi` object with a value of `20`, a word length of 8 bits, and a fraction length of –2 bits.

`a = fi(20, true, 8, -2)`
```a = 20 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 8 FractionLength: -2 ```

Get the stored integer value of `a`.

`a.int`
```ans = int8 5 ```

Get the binary value of the stored integer.

`a.bin`
```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. `000000010100` (binary) is equivalent to `20` (decimal).

### Create a `fi` Object Specifying Rounding and Overflow

You can use property name/property value pairs to set `fi` properties, such as rounding method and overflow action, when you create the 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 ```

### Remove Local `fimath`

You can remove a local `fimath` object from a `fi` object at any time using the `removefimath` function.

```a = fi(pi, 'RoundingMethod', 'Floor', 'OverflowAction', 'Wrap') a = removefimath(a)```
```a = 3.1415 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 16 FractionLength: 13 RoundingMethod: Floor OverflowAction: Wrap ProductMode: FullPrecision SumMode: FullPrecision a = 3.1415 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 16 FractionLength: 13```

`fi` object `a` now has no local `fimath`. To reassign it a local `fimath` object, use the `setfimath` function.

`a = setfimath(a, fimath('ProductMode', 'KeepLSB'))`
```a = 3.1415 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 16 FractionLength: 13 RoundingMethod: Nearest OverflowAction: Saturate ProductMode: KeepLSB ProductWordLength: 32 SumMode: FullPrecision ```

`fi` object `a` now has a local `fimath` object with a `ProductMode` of `KeepLSB`. The values of the remaining `fimath` object properties are default fimath values.

### Use fi as an Indexing Argument

Set up an array to be indexed.

`x = 10:-1:1`
```x = 1×10 10 9 8 7 6 5 4 3 2 1 ```

Create a `fi` object and use it to index into `x`.

```k = fi(3); y = x(k)```
```y = 8 ```

### Use `fi` in a Switch Statement

You can use a `fi` object as the switch condition and as one or more of the cases in the switch expression.

```function y = test_switch(u, v) cExpr = fi(u + v, 0, 2, 0); t = 1; switch cExpr % condition expression type: ufix2 case 0 y = t * 2; case fi(1,0,2,0) y = t * 3; case 2 y = t * 4; case 3 y = t * 3; otherwise y = 0; end end ```
```y = test_switch(1,2.0) ```
```y = 3 ```

### Use fi as a Colon Operator

Use a `fi` object as a colon operator.

When you use `fi` as a colon operator, all colon operands must have integer values.

```a=fi(1,0,3,0); b=fi(2,0,8,0); c=fi(12,0,8,0); x=a:b:c```
```x = 1 3 5 7 9 11 DataTypeMode: Fixed-point: binary point scaling Signedness: Unsigned WordLength: 8 FractionLength: 0 ```

### Create Fixed-point Vector With Non-integer Spacing

To create a fixed-point vector with non-integer spacing, first create the vector, then cast the vector to fixed-point.

`x = fi(0:0.1:10);`

Alternatively, use the `linspace` function.

`x = fi(linspace(0,10, 101));`

The following code, where one of the colon operands is not an integer, generates an error.

```a = fi(0); b = fi(0.1); c = fi(10); z = a:b:c```

### Use `fi` in a For Loop

Use a `fi` object as the index of a for-loop.

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

### Set Data Type Override on a fi Object

Set the `DataTypeOverride` property of a `fi` object so that the `fi` object does not use the data type override settings of the `fipref` object.

Save the current `fipref` settings to restore later.

```fp = fipref; initialDTOSetting = fp.DataTypeOverride;```

Set up `fipref` with data type override set to `'TrueDoubles'` for all numeric types.

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

`x = fi(pi, 1, 16, 13)`
```x = 3.1416 DataTypeMode: Double ```

Now create a `fi` object and set its `DataTypeOverride` property to `'Off'` so that it ignores the data type override settings specified using `fipref`.

`y = fi(pi, 1, 16, 13, 'DataTypeOverride','Off')`
```y = 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 = initialDTOSetting;`

## See Also

### Topics

#### Introduced before R2006a

##### Support Get trial now