stringifor_numbers
StringiFor, conversions between decimal and binary reals on 64 bit integers (internal module, not re-exported).
Fortran has no unsigned integer, and a signed overflow is not allowed: the 64 bit words are handled as bit patterns, and the arithmetic on them goes through 32 bit limbs that cannot overflow.
Source: src/lib/stringifor_numbers.F90
Dependencies
Contents
- significant_digits
- load_digits
- shift_decimal
- shift_binary
- multiply_small
- shortest_digits
- strip_zeros
- add
- multiply
- multiply32
- decimal_to_r8
- decimal_to_r4
- settle_r8
- settle_r4
- settle
- compare
- floor_shift
- BIAS_BITS
- round_to_odd
- eisel_lemire
Variables
| Name | Type | Attributes | Description |
|---|---|---|---|
LOW32 | integer(kind=I8P) | parameter | The low 32 bits. |
LIMB | integer(kind=I8P) | parameter | Base of the big integers of the exact comparison. |
Subroutines
significant_digits
Return the digits of the mantissa of a number, without the leading zeros and the point.
Attributes: pure
subroutine significant_digits(raw, digits, n)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
raw | character(len=*) | in | The number, as text. | |
digits | character(len=*) | out | The digits. | |
n | integer | out | Number of digits. |
Call graph
load_digits
Load decimal digits in a big integer, 9 digits per limb from the last.
Attributes: pure
subroutine load_digits(digits, big)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
digits | character(len=*) | in | The digits. | |
big | integer(kind=I8P) | out | The big integer, low limb first. |
Call graph
shift_decimal
Multiply a big integer by 10**power.
Attributes: pure
subroutine shift_decimal(big, power)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
big | integer(kind=I8P) | inout | The big integer. | |
power | integer | in | The power. |
Call graph
shift_binary
Multiply a big integer by 2**power.
Attributes: pure
subroutine shift_binary(big, power)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
big | integer(kind=I8P) | inout | The big integer. | |
power | integer | in | The power. |
Call graph
multiply_small
Multiply a big integer by a factor of at most 10**9: a limb times the factor stays far from the signed limit.
Attributes: pure
subroutine multiply_small(big, factor)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
big | integer(kind=I8P) | inout | The big integer. | |
factor | integer(kind=I8P) | in | The factor. |
Call graph
shortest_digits
Return the shortest decimal digits * 10**exponent that reads back as the binary float, the closest of them if more than one (Schubfach: Giulietti, The Schubfach way to render doubles, 2020). Finite and not zero; no trailing zeros.
The float is given by its fields, so one kernel serves R4P and R8P: every step only relies on the 128 bits of the power.
Attributes: elemental
subroutine shortest_digits(fraction, biased, mantissa_bits, digits, exponent)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
fraction | integer(kind=I8P) | in | Stored mantissa. | |
biased | integer | in | Biased exponent. | |
mantissa_bits | integer | in | Bits of the stored mantissa. | |
digits | integer(kind=I8P) | out | Decimal digits. | |
exponent | integer | out | Decimal exponent. |
Call graph
strip_zeros
Move the trailing zeros of the digits to the exponent.
Attributes: elemental
subroutine strip_zeros(digits, exponent)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
digits | integer(kind=I8P) | inout | Decimal digits, not zero. | |
exponent | integer | inout | Decimal exponent. |
Call graph
add
Add two words as unsigned integers.
Attributes: elemental
subroutine add(a, b, sum, carry)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
a | integer(kind=I8P) | in | First word. | |
b | integer(kind=I8P) | in | Second word. | |
sum | integer(kind=I8P) | out | Low 64 bits of the sum. | |
carry | integer(kind=I8P) | out | Carry, 0 or 1. |
Call graph
multiply
Multiply two words as unsigned integers, 64 x 64 = 128 bits.
Attributes: elemental
subroutine multiply(a, b, high, low)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
a | integer(kind=I8P) | in | First word. | |
b | integer(kind=I8P) | in | Second word. | |
high | integer(kind=I8P) | out | High word. | |
low | integer(kind=I8P) | out | Low word. |
Call graph
multiply32
Multiply two 32 bit limbs: a product of a limb and 16 bits fits in a signed word, a product of two limbs may not.
Attributes: elemental
subroutine multiply32(a, b, high, low)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
a | integer(kind=I8P) | in | First limb. | |
b | integer(kind=I8P) | in | Second limb. | |
high | integer(kind=I8P) | out | High limb. | |
low | integer(kind=I8P) | out | Low limb. |
Call graph
Functions
decimal_to_r8
Return the real nearest to mantissa * 10**exponent, ties to even (Eisel-Lemire). Mantissa not negative.
Attributes: elemental
Returns: real(kind=R8P)
function decimal_to_r8(mantissa, exponent) result(number)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
mantissa | integer(kind=I8P) | in | Digits, as an integer. | |
exponent | integer | in | Decimal exponent. |
Call graph
decimal_to_r4
Return the real nearest to mantissa * 10**exponent, ties to even (Eisel-Lemire). Mantissa not negative.
Attributes: elemental
Returns: real(kind=R4P)
function decimal_to_r4(mantissa, exponent) result(number)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
mantissa | integer(kind=I8P) | in | Digits, as an integer. | |
exponent | integer | in | Decimal exponent. |
Call graph
settle_r8
Return the real nearest to a number of more than 18 digits, when its first 18 digits leave two candidates.
See settle. raw is a number accepted by the parser, exponent its exponent for the first 18 digits, low the real nearest to those 18 digits, the lower candidate.
Attributes: elemental
Returns: real(kind=R8P)
function settle_r8(raw, exponent, low) result(number)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
raw | character(len=*) | in | The number, as text. | |
exponent | integer | in | Decimal exponent of the first 18 digits. | |
low | real(kind=R8P) | in | The lower candidate. |
Call graph
settle_r4
Return the real nearest to a number of more than 18 digits, when its first 18 digits leave two candidates.
Attributes: elemental
Returns: real(kind=R4P)
function settle_r4(raw, exponent, low) result(number)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
raw | character(len=*) | in | The number, as text. | |
exponent | integer | in | Decimal exponent of the first 18 digits. | |
low | real(kind=R4P) | in | The lower candidate. |
Call graph
settle
Return the bits of low or of the next float, comparing all the digits with the midpoint of the two, exactly.
The digits D, times 10q, against the midpoint (2m + 1) * 2p: each side takes the factors that would be negative powers on the other, so both are integers. In base 10**9 a power of ten is mostly a shift of limbs, so the cost is linear in the digits.
Attributes: pure
Returns: integer(kind=I8P)
function settle(raw, exponent, low, mantissa_bits, bias) result(bits)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
raw | character(len=*) | in | The number, as text. | |
exponent | integer | in | Decimal exponent of the first 18 digits. | |
low | integer(kind=I8P) | in | Bits of the lower candidate, sign clear. | |
mantissa_bits | integer | in | Bits of the stored mantissa. | |
bias | integer | in | Exponent bias. |
Call graph
compare
Return the sign of a - b, two big integers of the same size.
Attributes: pure
Returns: integer
function compare(a, b) result(order)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
a | integer(kind=I8P) | in | First big integer. | |
b | integer(kind=I8P) | in | Second big integer. |
Call graph
floor_shift
Return floor(value / 2**bits): nvfortran has no SHIFTA, and a right shift of a negative number needs the floor.
Attributes: elemental
Returns: integer
function floor_shift(value, bits) result(shifted)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
value | integer | in | The value. | |
bits | integer | in | The bits of the shift. |
Call graph
BIAS_BITS
Return the bits of the exponent field of a format.
Attributes: elemental
Returns: integer
function BIAS_BITS(mantissa_bits) result(bits)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
mantissa_bits | integer | in | Bits of the stored mantissa. |
Call graph
round_to_odd
Return the high word of g * cp (g of 128 bits) with its lowest bit set if any bit below is set.
Attributes: elemental
Returns: integer(kind=I8P)
function round_to_odd(g_high, g_low, cp) result(rounded)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
g_high | integer(kind=I8P) | in | High word of g. | |
g_low | integer(kind=I8P) | in | Low word of g. | |
cp | integer(kind=I8P) | in | The multiplier. |
Call graph
eisel_lemire
Return the bits of the positive binary float nearest to digits * 10**q, of the format with those parameters.
The 128 bits of the table are enough for every 64 bit digits, so this has no fallback (Mushtak, Lemire, Fast Number Parsing Without Fallback, 2023); the oracle checks it against exact arithmetic.
Attributes: elemental
Returns: integer(kind=I8P)
function eisel_lemire(digits, q, mantissa_bits, bias, infinity, even_min, even_max) result(bits)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
digits | integer(kind=I8P) | in | Decimal digits, not zero. | |
q | integer | in | Decimal exponent, in the range of the table. | |
mantissa_bits | integer | in | Bits of the stored mantissa. | |
bias | integer | in | Exponent bias. | |
infinity | integer | in | Biased exponent of the infinity. | |
even_min | integer | in | Lowest q where a product can be an exact tie. | |
even_max | integer | in | Highest q where a product can be an exact tie. |
Call graph