Fixed-Point Toolbox™

round - Round `fi` object toward nearest integer or round input data using `quantizer` object

Syntax

y = round(a) y = round(q,x)

Description

y = round(a) rounds fi object a to the nearest integer. In the case of a tie, round rounds values to the nearest integer with greater absolute value. The rounded value is returned in fi object y.

y and a have the same fimath object and DataType property.

When the DataType of a is single, double, or boolean, the numerictype of y is the same as that of a.

When the fraction length of a is zero or negative, a is already an integer, and the numerictype of y is the same as that of a.

When the fraction length of a is positive, the fraction length of y is 0, its sign is the same as that of a, and its word length is the difference between the word length and the fraction length of a, plus one bit. If a is signed, then the minimum word length of y is 2. If a is unsigned, then the minimum word length of y is 1.

For complex fi objects, the imaginary and real parts are rounded independently.

round does not support fi objects with nontrivial slope and bias scaling. Slope and bias scaling is trivial when the slope is an integer power of 2 and the bias is 0.

y = round(q,x) uses the RoundMode and FractionLength settings of q to round the numeric data x, but does not check for overflows during the operation. Compare to quantize.

Examples

Example 1

The following example demonstrates how the round function affects the numerictype properties of a signed fi object with a word length of 8 and a fraction length of 3.

a = fi(pi, 1, 8, 3) 

a =
 
    3.1250

DataTypeMode: Fixed-point: binary point scaling
Signed: true
WordLength: 8
FractionLength: 3

y = round(a) 

y =
 
     3

DataTypeMode: Fixed-point: binary point scaling
Signed: true
WordLength: 6
FractionLength: 0

Example 2

The following example demonstrates how the round function affects the numerictype properties of a signed fi object with a word length of 8 and a fraction length of 12.

a = fi(0.025,1,8,12) 

a =
 
    0.0249

          DataTypeMode: Fixed-point: binary point scaling
                Signed: true
            WordLength: 8
        FractionLength: 12

y = round(a) 

y =
 
     0

DataTypeMode: Fixed-point: binary point scaling
Signed: true
WordLength: 2
FractionLength: 0

Example 3

The functions convergent, nearest and round differ in the way they treat values whose least significant digit is 5:

The convergent function rounds ties to the nearest even integer
The nearest function rounds ties to the nearest integer toward positive infinity
The round function rounds ties to the nearest integer with greater absolute value

The following table illustrates these differences for a given fi object a.

a	convergent(a)	nearest(a)	round(a)
–3.5	–4	–3	–4
–2.5	–2	–2	–3
–1.5	–2	–1	–2
–0.5	0	0	–1
0.5	0	1	1
1.5	2	2	2
2.5	2	3	3
3.5	4	4	4

Example 4

Create a quantizer object, and use it to quantize input data. The quantizer object applies its properties to the input data to return quantized output.

q = quantizer('fixed', 'convergent', 'wrap', [3 2]);
x = (-2:eps(q)/4:2)';
y = round(q,x);
plot(x,[x,y],'.-'); axis square;

Applying quantizer object q to the data results in the staircase-shape output plot shown in the following figure. Linear data input results in output where y shows distinct quantization levels.

round - Round fi object toward nearest integer or round input data using quantizer object