Construct fixed-point numeric object

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

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:

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

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.

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.

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.

For information about the display format of `fi`

objects,
refer to View Fixed-Point Data.

For examples of casting, see Cast fi Objects.

`fi`

ObjectCreate 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

`fi`

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

`fi`

Object With Default PrecisionIf 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

`fi`

Object With Default Word Length and PrecisionIf 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

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

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

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

`fi`

Object Specifying Rounding and OverflowYou 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

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

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

`fi`

in a Switch StatementYou 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 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

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

`fi`

in a For LoopUse 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 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;

`fimath`

| `fipref`

| `isfimathlocal`

| `numerictype`

| `quantizer`

| `sfi`

| `ufi`