fi Objects and C Integer Data Types

Note

The sections in this topic compare the fi object with fixed-point data types and operations in C. In these sections, the information on ANSI^® C is adapted from Samuel P. Harbison and Guy L. Steele Jr., C: A Reference Manual, 3rd ed., Prentice Hall, 1991.

Integer Data Types

This section compares the numerical range of fi integer data types to the minimum numerical range of C integer data types, assuming a Two's Complement representation.

C Integer Data Types

Many C compilers support a two's complement representation of signed integer data types. The following table shows the minimum ranges of C integer data types using a two's complement representation. The integer ranges can be larger than or equal to the ranges shown, but cannot be smaller. The range of a long must be larger than or equal to the range of an int, which must be larger than or equal to the range of a short.

In the two's complement representation, a signed integer with n bits has a range from $- 2^{n - 1}$ to $2^{n - 1} - 1$ , inclusive. An unsigned integer with n bits has a range from 0 to $2^{n} - 1$ , inclusive. The negative side of the range has one more value than the positive side, and zero is represented uniquely.

Integer Type	Minimum	Maximum
`signed char`	–128	127
`unsigned char`	0	255
`short int`	–32,768	32,767
`unsigned short`	0	65,535
`int`	–32,768	32,767
`unsigned int`	0	65,535
`long int`	–2,147,483,648	2,147,483,647
`unsigned long`	0	4,294,967,295

fi Integer Data Types

The following table lists the numerical ranges of the integer data types of the fi object, in particular those equivalent to the C integer data types. The ranges are large enough to accommodate the two's complement representation, which is the only signed binary encoding technique supported by Fixed-Point Designer™ software.

Constructor	Signed	Word Length	Minimum	Maximum	Closest ANSI C Equivalent
`fi(x,1,n,0)`	Yes	n (2 to 65,535)	$- 2^{n - 1}$	$2^{n - 1} - 1$	Not applicable
`fi(x,0,n,0)`	No	n (2 to 65,535)	0	$2^{n} - 1$	Not applicable
`fi(x,1,8,0)`	Yes	8	–128	127	`signed char`
`fi(x,0,8,0)`	No	8	0	255	`unsigned char`
`fi(x,1,16,0)`	Yes	16	–32,768	32,767	`short int`
`fi(x,0,16,0)`	No	16	0	65,535	`unsigned short`
`fi(x,1,32,0)`	Yes	32	–2,147,483,648	2,147,483,647	`long int`
`fi(x,0,32,0)`	No	32	0	4,294,967,295	`unsigned long`

Unary Conversions

Unary conversions dictate whether and how a single operand is converted before an operation is performed. This section discusses unary conversions in ANSI C and of fi objects.

ANSI C Usual Unary Conversions

Unary conversions in ANSI C are automatically applied to the operands of the unary !, –, ~, and * operators, and of the binary << and >> operators, according to the following table:

Original Operand Type	ANSI C Conversion
`char` or `short`	`int`
`unsigned char` or `unsigned short`	`int` or `unsigned int`¹
`float`	`float`
Array of T	Pointer to T
Function returning T	Pointer to function returning T

¹If type int cannot represent all the values of the original data type without overflow, the converted type is unsigned int.

fi Usual Unary Conversions

The following table shows the fi unary conversions:

C Operator	fi Equivalent	fi Conversion
`!x`	~`x = not(x)`	Result is `logical`.
~`x`	`bitcmp(x)`	Result is same numeric type as operand.
`*x`	No equivalent	Not applicable
`x<<n`	`bitshift(x,n)`positive `n`	Result is same numeric type as operand. Round mode is always `floor`. Overflow mode is obeyed. 0-valued bits are shifted in on the right.
`x>>n`	`bitshift(x,-n)`	Result is same numeric type as operand. Round mode is always `floor`. Overflow mode is obeyed. 0-valued bits are shifted in on the left if the operand is unsigned or signed and positive. 1-valued bits are shifted in on the left if the operand is signed and negative.
`+x`	`+x`	Result is same numeric type as operand.
`-x`	`-x`	Result is same numeric type as operand. Overflow mode is obeyed. For example, overflow might occur when you negate an unsigned `fi` or the most negative value of a signed `fi`.

Binary Conversions

This section describes the conversions that occur when the operands of a binary operator are different data types.

ANSI C Usual Binary Conversions

In ANSI C, operands of a binary operator must be of the same type. If they are different, one is converted to the type of the other according to the first applicable conversion in the following table:

Type of One Operand	Type of Other Operand	ANSI C Conversion
`long double`	Any	`long double`
`double`	Any	`double`
`float`	Any	`float`
`unsigned long`	Any	`unsigned long`
`long`	`unsigned`	`long` or `unsigned long`¹
`long`	`int`	`long`
`unsigned`	`int` or `unsigned`	`unsigned`
`int`	`int`	`int`

¹Type long is only used if it can represent all values of type unsigned.

fi Usual Binary Conversions

When one of the operands of a binary operator (+, –, *, .*) is a fi object and the other is a MATLAB^® built-in numeric type, then the non-fi operand is converted to a fi object before the operation is performed, according to the following table:

Type of One Operand	Type of Other Operand	Properties of Other Operand After Conversion to a fi Object
`fi`	`double or single`	`Signed` = same as the original `fi` operand `WordLength` = same as the original `fi` operand `FractionLength` = set to best precision possible
`fi`	`int8`	`Signed` = `1` `WordLength` = `8` `FractionLength` = `0`
`fi`	`uint8`	`Signed` = `0` `WordLength` = `8` `FractionLength` = `0`
`fi`	`int16`	`Signed` = `1` `WordLength` = `16` `FractionLength` = `0`
`fi`	`uint16`	`Signed` = `0` `WordLength` = `16` `FractionLength` = `0`
`fi`	`int32`	`Signed` = `1` `WordLength` = `32` `FractionLength` = `0`
`fi`	`uint32`	`Signed` = `0` `WordLength` = `32` `FractionLength` = `0`
`fi`	`int64`	`Signed` = `1` `WordLength` = `64` `FractionLength` = `0`
`fi`	`uint64`	`Signed` = `0` `WordLength` = `64` `FractionLength` = `0`

Overflow Handling

The following sections compare how ANSI C and Fixed-Point Designer software handle overflows.

ANSI C Overflow Handling

In ANSI C, the result of signed integer operations is whatever value is produced by the machine instruction used to implement the operation. Therefore, ANSI C has no rules for handling signed integer overflow.

The results of unsigned integer overflows wrap in ANSI C.

fi Overflow Handling

Addition and multiplication with fi objects yield results that can be exactly represented by a fi object, up to word lengths of 65,535 bits or the available memory on your machine. This is not true of division, however, because many ratios result in infinite binary expressions. You can perform division with fi objects using the divide function, which requires you to explicitly specify the numeric type of the result.

The conditions under which a fi object overflows and the results then produced are determined by the associated fimath object. You can specify certain overflow characteristics separately for sums (including differences) and products. Refer to the following table:

fimath Object Properties Related to Overflow Handling	Property Value	Description
`OverflowAction`	`'saturate'`	Overflows are saturated to the maximum or minimum value in the range.
`OverflowAction`	`'wrap'`	Overflows wrap using modulo arithmetic if unsigned, two's complement wrap if signed.
`ProductMode`	`'FullPrecision'`	Full-precision results are kept. Overflow does not occur. An error is thrown if the resulting word length is greater than `MaxProductWordLength`. The rules for computing the resulting product word and fraction lengths are given in fimath Object Properties in the Property Reference.
	`'KeepLSB'`	The least significant bits of the product are kept. Full precision is kept, but overflow is possible. This behavior models the C language integer operations. The `ProductWordLength` property determines the resulting word length. If `ProductWordLength` is greater than is necessary for the full-precision product, then the result is stored in the least significant bits. If `ProductWordLength` is less than is necessary for the full-precision product, then overflow occurs. The rule for computing the resulting product fraction length is given in fimath Object Properties in the Property Reference.
	`'KeepMSB'`	The most significant bits of the product are kept. Overflow is prevented, but precision may be lost. The `ProductWordLength` property determines the resulting word length. If `ProductWordLength` is greater than is necessary for the full-precision product, then the result is stored in the most significant bits. If `ProductWordLength` is less than is necessary for the full-precision product, then rounding occurs. The rule for computing the resulting product fraction length is given in fimath Object Properties in the Property Reference.
	`'SpecifyPrecision'`	You can specify both the word length and the fraction length of the resulting product.
`ProductWordLength`	Positive integer	The word length of product results when `ProductMode` is `'KeepLSB'`, `'KeepMSB'`, or `'SpecifyPrecision'`.
`MaxProductWordLength`	Positive integer	The maximum product word length allowed when `ProductMode` is `'FullPrecision'`. The default is 65,535 bits. This property can help ensure that your simulation does not exceed your hardware requirements.
`ProductFractionLength`	Integer	The fraction length of product results when `ProductMode` is `'Specify Precision'`.
`SumMode`	`'FullPrecision'`	Full-precision results are kept. Overflow does not occur. An error is thrown if the resulting word length is greater than `MaxSumWordLength`. The rules for computing the resulting sum word and fraction lengths are given in fimath Object Properties in the Property Reference.
	`'KeepLSB'`	The least significant bits of the sum are kept. Full precision is kept, but overflow is possible. This behavior models the C language integer operations. The `SumWordLength` property determines the resulting word length. If `SumWordLength` is greater than is necessary for the full-precision sum, then the result is stored in the least significant bits. If `SumWordLength` is less than is necessary for the full-precision sum, then overflow occurs. The rule for computing the resulting sum fraction length is given in fimath Object Properties in the Property Reference.
	`'KeepMSB'`	The most significant bits of the sum are kept. Overflow is prevented, but precision may be lost. The `SumWordLength` property determines the resulting word length. If `SumWordLength` is greater than is necessary for the full-precision sum, then the result is stored in the most significant bits. If `SumWordLength` is less than is necessary for the full-precision sum, then rounding occurs. The rule for computing the resulting sum fraction length is given in fimath Object Properties in the Property Reference.
	`'SpecifyPrecision'`	You can specify both the word length and the fraction length of the resulting sum.
`SumWordLength`	Positive integer	The word length of sum results when `SumMode` is `'KeepLSB'`, `'KeepMSB'`, or `'SpecifyPrecision'`.
`MaxSumWordLength`	Positive integer	The maximum sum word length allowed when `SumMode` is `'FullPrecision'`. The default is 65,535 bits. This property can help ensure that your simulation does not exceed your hardware requirements.
`SumFractionLength`	Integer	The fraction length of sum results when `SumMode` is `'SpecifyPrecision'`.