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,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(...'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.

• fimathfimath 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

• 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

• 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

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

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.

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