DOLLARDE

What it does

DOLLARDE(fractional_dollar, fraction)

DOLLARDE(fractional_dollar, fraction) converts a price written in fractional notation — the form US bond and note markets have quoted in for two centuries — into an ordinary decimal number.

A quote of 1.02 in thirty-seconds is not "one and two hundredths". It is one dollar and two thirty-seconds, and the .02 is a two-digit field holding the numerator. DOLLARDE(1.02, 32) is therefore 1 + 2/32 = 1.0625.

The transformation is:

whole      = trunc(fractional_dollar)
frac_field = fractional_dollar − whole
result     = whole + frac_field × scale / fraction

where fraction is the denominator (truncated to an integer) and scale is the power of ten that shifts the digit field up to a whole numerator. The value of scale is determined by how many decimal digits the denominator has, and that is the whole subtlety of the function:

So the number of digits you write after the point is not free notation — it must match the width the denominator implies. DOLLARDE(1.2, 32) is 1 + 20/32, not 1 + 2/32, because the field is two digits wide and .2 means 20. This is the single most common misreading of the function, and it produces a plausible wrong answer rather than an error.

Range: for a well-formed quote the fractional field is in [0, fraction) and the result lies between whole and whole + 1. Nothing enforces that. DOLLARDE(1.99, 32) computes 1 + 99/32 ≈ 4.094 without complaint: the "fraction" was larger than the denominator, and the function has no notion of a malformed quote.

Negative inputs work by symmetry, because both the truncation and the subtraction are toward zero: DOLLARDE(−1.02, 32) = −1.0625.

Arguments

Microsoft documents that if fraction is not an integer, it is truncated. In practice this means DOLLARDE(1.02, 16.9) is read as sixteenths.

fraction is not restricted to powers of two by anything in the function, even though halves, quarters, eighths, sixteenths, thirty-seconds and sixty-fourths are the only denominators the market convention uses. A denominator of 3 or 7 is accepted and produces arithmetic that is internally consistent but does not correspond to any quotation.

Both slots are numeric and go through this family's own coercion, which is narrower than the general rule — see Result and edge cases.

Try it

Quirks

Result and edge cases

Returns Number.

• The digit-width rule above is the edge case that bites. A quote whose fractional field is narrower than the denominator's digit count is a different price, not a formatting variant.
• Fractional field larger than the denominator is accepted and rolls over into the whole part.
• fraction is truncated, not rounded, so 15.99 reads as 15, not as 16. Truncation is toward zero.
• A blank denominator therefore reaches the kernel as 0 and produces #DIV/0! rather than a missing-argument diagnosis.
• Array arguments: DOLLARDE is declared as lifting natively over arrays, while its inverse DOLLARFR is declared with an explicit broadcast over both argument positions. See DOLLARFR — the asymmetry between two functions that are inverses of each other is itself a finding.

Errors

As documented on Microsoft's DOLLARDE page:

How to implement

Numerical notes

The arithmetic is exact for the cases that matter, and the one interesting question is not rounding but specification.

For DOLLARDE(1.5, 10) the first rule gives 1 + 0.5·100/10 = 6 and the second gives 1 + 0.5·10/10 = 1.5. That is not a last-bit difference; it is a different function. Which one Excel implements is not settled by this page, and DOLLARDE(1.5, 10) is the cheapest probe in this whole batch. Power-of-ten denominators are outside market convention, which is presumably why the ambiguity has survived.

Rust code

28 dollarde_fn "DOLLARDE" (2, 2) [V "fractional_dollar", V "fraction"] |s, a, sv| {
    if a.iter().any(CalcValue::is_missing) {
        return fail(W::NA);
    }
    out(s, dollar::dollarde_kernel(dollar_num(s, a, 0)?, dollar_num(s, a, 1)?))
}

pub fn dollarde_kernel(number: f64, fraction: f64) -> Result<f64, WorksheetErrorCode> {
    let denominator = normalized_fraction_denominator(fraction)?;
    let scale = decimal_scale(denominator);
    let whole = number.trunc();
    let fractional = number - whole;
    Ok(whole + fractional * scale / denominator)
}

No implementation has been published with a Handbook test suite for this function.

Version differences

The recorded environments below distinguish a reading from a same-input comparison. Counts describe captured inputs in each environment; overlapping captures and comparisons are not totals of unique worksheet calls.

The record contains no same-input comparison between these environments. Reading different inputs on different builds does not establish either a version change or cross-build agreement.

Recorded environments and comparison details.

Alternatives

Relationships

• DOLLARFR — the exact inverse, and the only other member of this family. DOLLARFR(DOLLARDE(x, f), f) should return x up to floating-point rounding, and the round trip is a good self-test of the scaling rule.
• DOLLAR — unrelated despite the name. DOLLAR formats a number as currency text; DOLLARDE returns a number. They share four letters and nothing else.
• TEXT — the general formatter, and the tool you actually want if the goal is to display a price in fractional notation rather than to compute with one. Excel's # ?/32 number formats cover the display direction.
• PRICE / PRICEDISC — the bond-pricing functions whose output is a decimal price per 100. DOLLARFR is what turns their answer into a market quote; DOLLARDE turns a market quote into something they can consume.

Named variants

No named variants are recorded yet.