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
Description
returns a signed
a
= fifi
object with no value, a 16-bit word length, and a 15-bit fraction
length.
returns a
signed a
= fi(v
)fi
object with value v
, a 16-bit word
length, and best-precision fraction length.
returns a a
= fi(v
,s
,w
,slopeadjustmentfactor
,fixedexponent
,bias
)fi
object with value v
, signedness
s
, word length w
,
slopeadjustmentfactor
, fixedexponent
, and
bias
.
returns a a
= fi(v
,T
)fi
object with value v
and numerictype
T
.
returns a a
= fi(___,Name,Value
)fi
object with property values specified by one or more
name-value pair arguments.
Input Arguments
v
— Value
scalar | vector | matrix | multidimensional array
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 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
true
or 1
(default) | false
or 0
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
w
— Word length in bits
16 (default) | positive scalar integer
Word length in bits of the fi
object, specified as a positive
scalar integer.
The word length must be an integer in the range 1 ≤ w
≤ 65535.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
| logical
f
— Fraction length in bits
15 (default) | scalar integer
Fraction length in bits of the stored integer value of the fi
object, specified as a scalar integer. The fraction length must be an integer in the
range -65535 ≤ f
≤ 65535.
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
positive scalar
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.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
| logical
bias
— Bias
scalar
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.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
| logical
slopeadjustmentfactor
— Slope adjustment factor
scalar greater than or equal to 1
and less than
2
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.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
| logical
fixedexponent
— Fixed exponent
scalar
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.
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.
F
— Fixed-point math properties
fimath
object
Fixed-point math properties of the fi
object, specified as a
fimath
object.
If no fimath
properties are specified, the
fi
constructor uses nearest rounding and saturates on overflow
for the creation of the fi
object regardless of
globalfimath
settings. For an example of this behavior, see Specify Rounding and Overflow Modes in fi Object Constructor.
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
Create fi
Object
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
Create fi
Object with Slope and Bias Scaling
The real-world value of a slope and 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. 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
.
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
Create fi
Object from numerictype
Object
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
Create fi
Object with Associated fimath
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 fi
Object from Non-Double Value
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
Specify Rounding and Overflow Modes in fi
Object Constructor
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
Creating a fi
object with no properties set will use the default RoundingMethod
and OverflowAction
, regardless of any globalfimath
settings.
To observe this behavior, specify globalfimath
.
resetglobalfimath globalfimath('RoundingMethod','floor','OverflowAction','wrap')
ans = RoundingMethod: Floor OverflowAction: Wrap ProductMode: FullPrecision SumMode: FullPrecision
Construct a fi
object with no fimath
settings in the constructor.
b = fi([3.6 128],1,8,0)
b = 4 127 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 8 FractionLength: 0
The resulting value of b
is uses Nearest
rounding and Saturate
as the overflow action. If this behavior is not suitable for your application, see fi Constructor Does Not Follow globalfimath Rules for a workaround.
Reset the globalfimath to restore default values.
resetglobalfimath;
Set Data Type Override on fi
Object
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;
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
Tips
Use the
fipref
object to control the display, logging, and data type override preferences forfi
objects.
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 VHDL, Verilog and SystemVerilog code for FPGA and ASIC designs using HDL Coder™.
Version History
Introduced before 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
.
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)