convergent

Round toward nearest integer with ties rounding to nearest even integer

Syntax

`y = convergent(a)y = convergent(x)`

Description

`y = convergent(a)` rounds `fi` object `a` to the nearest integer. In the case of a tie, `convergent(a)` rounds to the nearest even integer.

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

When the `DataType` property 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.

`convergent` 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 = convergent(x)` rounds the elements of `x` to the nearest integer. In the case of a tie, `convergent(x)` rounds to the nearest even integer.

Examples

Example 1

The following example demonstrates how the `convergent` 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 Signedness: Signed WordLength: 8 FractionLength: 3 y = convergent(a) y = 3 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 6 FractionLength: 0 ```

Example 2

The following example demonstrates how the `convergent` 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 Signedness: Signed WordLength: 8 FractionLength: 12 y = convergent(a) y = 0 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed 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`.

aconvergent(a)nearest(a)round(a)
–3.5–4–3–4
–2.5–2–2–3
–1.5–2–1–2
–0.500–1
0.5011
1.5222
2.5233
3.5444