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
Description
returns a a
= fifi
object with no value, 16-bit word length, and 15-bit fraction length.
creates a fixed-point object using slope and bias scaling.a
= fi(v
,s
,w
,slopeadjustmentfactor
,fixedexponent
,bias
)
creates a fixed-point object with property values specified by one or more
a
= fi(___,Name,Value
)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
v
— Value
scalar | vector | matrix | multi-dimensional array
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 to0
.When the
'OverflowAction'
property of thefi
object is set to'Wrap'
,-Inf
, andInf
map to0
.When the
'OverflowAction'
property of thefi
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
s
— Signedness
1 (default) | 0
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
w
— Word length
16 (default) | scalar integer
Word length, in bits, of the fi
object, specified as a 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
f
— Fraction length
15 (default) | scalar integer
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
— Slope
scalar integer
Slope of the scaling, specified as a scalar integer. The following equation represents the real-world value of a slope bias scaled number.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
| logical
bias
— Bias
scalar
Bias of the scaling, specified as a scalar. The following equation represents the real-world value of a slope bias scaled number.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
| logical
slopeadjustmentfactor
— Slope adjustment factor
scalar integer
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.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
| logical
fixedexponent
— Fixed exponent
scalar integer
The fixed exponent of a slope bias scaled number. The following equation demonstrates the relationship between the slope, fixed exponent, and slope adjustment factor.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
| logical
T
— Numeric type properties
numerictype
object
Numeric type properties of the fi
object, specified as a
numerictype
object. For more information, see numerictype
.
F
— Fixed-point math properties
fimath
object
Fixed-point math properties of the fi
object, specified as a
fimath
object. For more information, see fimath
.
Properties
Examples
Create a fi
object
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
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
Create a fi
object with Default Word Length and Fraction Length
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
Create a fi
Object with Default Precision
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
Create a fi
Object with Slope and Bias Scaling
The real-world value of a slope bias scaled number is represented by:
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
.
Create a fi
Object From a Non-Double Value
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
Create a fi
Object With an Associated fimath
Object
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
Create a fi
Object From a numerictype
Object
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
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. Calculate the real-world value using the following equation.
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).
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 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.
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).
Create a fi
Object Specifying Rounding and Overflow Modes
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
Use fi
as an Indexing Argument
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
Set Data Type Override on a fi
Object
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;
fi
Behavior for -Inf
, Inf
, and NaN
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
Extended Capabilities
C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.
Usage notes and limitations:
The default constructor syntax without any input arguments is not supported.
If the
numerictype
is not fully specified, the input tofi
must be a constant, afi
, a single, or a built-in integer value. If the input is a built-in double value, it must be a constant. This limitation allowsfi
to autoscale its fraction length based on the known data type of the input.All properties related to data type must be constant for code generation.
numerictype
object information must be available for nonfixed-point Simulink® inputs.
HDL Code Generation
Generate Verilog and VHDL code for FPGA and ASIC designs using HDL Coder™.
Version History
Introduced in R2006aR2021a: Inexact property names for fi
, fimath
, and
numerictype
objects not supported
In previous releases, inexact property names for fi
,
fimath
, and numerictype
objects would result in a
warning. In R2021a, support for inexact property names was removed. Use exact property names
instead.
R2020b: Change in default behavior of fi
for -Inf
, Inf
, and NaN
In previous releases, fi
would return an error when passed the
non-finite input values -Inf
, Inf
, or
NaN
. fi
now treats these inputs in the same way that
MATLAB® and Simulink handle -Inf
, Inf
, and
NaN
for integer data types.
When fi
is specified as a fixed-point numeric type,
NaN
maps to0
.When the
'OverflowAction'
property of thefi
object is set to'Wrap'
,-Inf
, andInf
map to0
.When the
'OverflowAction'
property of thefi
object is set to'Saturate'
,Inf
maps to the largest representable value, and-Inf
maps to the smallest representable value.
For an example of this behavior, see fi Behavior for -Inf, Inf, and NaN.
Note
Best-precision scaling is not supported for input values of -Inf
,
Inf
, or NaN
.
Open Example
You have a modified version of this example. Do you want to open this example with your edits?
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)