"Quote" names both a rate and a currency #16

Closed
opened 2026-08-14 23:23:16 +00:00 by rosa · 1 comment
Owner

Since ExchangeRate::from/to became base/quote (c723307), the noun "quote"
names two different things in exchange.rs. It is the currency a rate is priced
in — ExchangeRate::quote() returns a Currency — and it is also a whole rate,
which is what Quotes and IntoQuotes (src/exchange.rs:614, :666) yield and
what most of Exchange's prose means by the word: "Take a quote into the table"
(:382), "Withdraw a pair's quote" (:417), "Drop every quote" (:449),
"Every quote the table holds" (:561), "one ExchangeRate per pair quoted"
(:591).

The two senses met in one expression at the serde Exchange impl, which read
Pair(quote.base(), quote.quote()) before the loop variable was renamed to
rate. That spelling is gone, but nothing stops it coming back while both
senses are live, and Quotes' own doctest still binds let quotes: Quotes<'_> = desk.iter() a few lines under a getter named quote.

The verb is not the problem: "the table quotes a pair", "a pair quoted twice",
"nothing here quotes one for you" all read cleanly whichever way this goes, since
a rate is the only thing that can be quoted. Only the noun collides.

Two ways out:

  • Reserve the noun for the currency and call a rate a rate — Quotes becomes
    Rates, IntoQuotes becomes IntoRates, and the prose says "every rate the
    table holds". Costs a rename of two public types, and gives up a name that
    reads well for a table's contents.
  • Keep both senses and let context carry them, on the grounds that a Quotes
    iterator yielding ExchangeRate is unsurprising and the getter is only ever
    reached through a rate. Costs nothing now; the ambiguity stays.

Worth settling before release rather than after. Quotes and IntoQuotes are
public (src/lib.rs:20), so the first option is a breaking change — but the
base/quote rename is itself unreleased, so taking both in the same version
costs one break instead of two.

Since `ExchangeRate::from`/`to` became `base`/`quote` (c723307), the noun "quote" names two different things in `exchange.rs`. It is the currency a rate is priced in — `ExchangeRate::quote()` returns a `Currency` — and it is also a whole rate, which is what `Quotes` and `IntoQuotes` (`src/exchange.rs:614`, `:666`) yield and what most of `Exchange`'s prose means by the word: "Take a quote into the table" (`:382`), "Withdraw a pair's quote" (`:417`), "Drop every quote" (`:449`), "Every quote the table holds" (`:561`), "one `ExchangeRate` per pair quoted" (`:591`). The two senses met in one expression at the serde `Exchange` impl, which read `Pair(quote.base(), quote.quote())` before the loop variable was renamed to `rate`. That spelling is gone, but nothing stops it coming back while both senses are live, and `Quotes`' own doctest still binds `let quotes: Quotes<'_> = desk.iter()` a few lines under a getter named `quote`. The verb is not the problem: "the table quotes a pair", "a pair quoted twice", "nothing here quotes one for you" all read cleanly whichever way this goes, since a rate is the only thing that can be quoted. Only the noun collides. Two ways out: - Reserve the noun for the currency and call a rate a rate — `Quotes` becomes `Rates`, `IntoQuotes` becomes `IntoRates`, and the prose says "every rate the table holds". Costs a rename of two public types, and gives up a name that reads well for a table's contents. - Keep both senses and let context carry them, on the grounds that a `Quotes` iterator yielding `ExchangeRate` is unsurprising and the getter is only ever reached through a rate. Costs nothing now; the ambiguity stays. Worth settling before release rather than after. `Quotes` and `IntoQuotes` are public (`src/lib.rs:20`), so the first option is a breaking change — but the `base`/`quote` rename is itself unreleased, so taking both in the same version costs one break instead of two.
Author
Owner

This was generated by AI during triage.

Agent Brief

Category: enhancement

Summary: Reserve the noun "quote" for the currency a rate is priced in, and call a rate a rate everywhere else — Quotes becomes Rates, IntoQuotes becomes IntoRates, and the prose follows.

Decision: the issue's first option, taken with the prose sweep rather than the type rename alone. Two findings settled the cost question the issue body left open:

  • Quotes and IntoQuotes have never shipped. v0.10.0 exported Exchange,
    ExchangeRate, and InvalidRateError, and Exchange::quotes() returned an
    anonymous impl ExactSizeIterator; the named types arrived in the current
    unreleased cycle. Renaming them is not a breaking change — it edits an
    unreleased "Added" entry and nothing else.
  • The crate already names an iterator after the accessor rather than the element
    it yields: MoneyBag::balance() pairs with Balances/IntoBalances, both
    yielding Money. Exchange's accessors are rate, set_rate, and
    remove_rate, over a rates map. Rates/IntoRates restores that pattern;
    Quotes was the one departure from it.

Current behavior:
The noun carries two senses at once. It is the currency a rate is priced in —
what ExchangeRate::quote() returns, and what the serde "quote" field holds —
and it is also a whole rate, which is what the iterator types yield and what most
of Exchange's prose, its doctest bindings, and its test names mean by the word.

Desired behavior:
As a noun, "quote" means only the currency a rate is priced in. A rate is called
a rate. The verb is untouched: only a rate can be quoted, so no ambiguity arises
from it, and "the table quotes a pair", "a pair quoted twice", and "nothing here
quotes one for you" all stay as written.

Key interfaces:

  • Quotes → Rates, IntoQuotes → IntoRates, with the crate-root re-export
    following. Their Item type, their iterator trait impls, and the IntoIterator
    associated types on Exchange and &Exchange change in name only — no
    behavior and no change to the shape of any signature.
  • ExchangeRate::quote(), the quote field behind it, the quote parameters on
    Exchange::rate and Exchange::remove_rate, and the serde "quote" field name
    together with its field constant are all the currency sense. None of them move.

Scope of the sweep — every noun use of "quote"/"quotes" that means a rate
becomes "rate"/"rates":

  • the module-level docs, the Exchange and ExchangeRate type docs, and the
    Display doc
  • the method docs on set_rate, remove_rate, clear, len, is_empty, and
    iter, plus the FromIterator and Extend impl docs
  • the serde module's Exchange and ExchangeRate impl docs
  • doctest and unit-test bindings named quote that hold an ExchangeRate
  • test function names — exchange_displaces_an_earlier_quote_test,
    exchange_clears_every_quote_test, exchange_collects_from_quotes_test, and
    the rest of that family
  • README prose

Changelog: only the [Unreleased] section is edited. Its Quotes/IntoQuotes
bullet names Rates/IntoRates instead, and its other bullets follow the same
sweep. No "Changed" entry is added — the names never shipped, so there is nothing
to record as changed. Released sections are history and stay as they are,
including the Exchange::quotes entry under [0.10.0].

Acceptance criteria:

  • Rates and IntoRates are the iterator types and are re-exported from the
    crate root; Quotes and IntoQuotes appear nowhere in the repository.
  • ExchangeRate::quote() and the serde "quote" field are unchanged, and a
    rate still travels as {"base": "USD", "quote": "EUR", "rate": "0.9"}.
  • Every surviving occurrence of "quote" under src/ and in README.md is one
    of: the quote field, getter, or parameter; the serde field name or its
    constant; or a verb form — "quotes", "quoted", "unquoted".
  • No test name uses the noun for a rate.
  • The [Unreleased] changelog section names Rates/IntoRates, and the
    [0.10.0] section and everything below it are unchanged.
  • mise run fmtcheck, mise run clippy, and mise run ci all pass, doctests
    included.

Out of scope:

  • Renaming ExchangeRate::quote(), its field, or the serde field — that is the
    sense being kept.
  • Changing any verb form.
  • Any behavior change; this is a rename and a documentation sweep.
  • Balances/IntoBalances and the rest of the bag module, which the collision
    does not reach.
> *This was generated by AI during triage.* ## Agent Brief **Category:** enhancement **Summary:** Reserve the noun "quote" for the currency a rate is priced in, and call a rate a rate everywhere else — `Quotes` becomes `Rates`, `IntoQuotes` becomes `IntoRates`, and the prose follows. **Decision:** the issue's first option, taken with the prose sweep rather than the type rename alone. Two findings settled the cost question the issue body left open: - `Quotes` and `IntoQuotes` have never shipped. `v0.10.0` exported `Exchange`, `ExchangeRate`, and `InvalidRateError`, and `Exchange::quotes()` returned an anonymous `impl ExactSizeIterator`; the named types arrived in the current unreleased cycle. Renaming them is not a breaking change — it edits an unreleased "Added" entry and nothing else. - The crate already names an iterator after the accessor rather than the element it yields: `MoneyBag::balance()` pairs with `Balances`/`IntoBalances`, both yielding `Money`. `Exchange`'s accessors are `rate`, `set_rate`, and `remove_rate`, over a `rates` map. `Rates`/`IntoRates` restores that pattern; `Quotes` was the one departure from it. **Current behavior:** The noun carries two senses at once. It is the currency a rate is priced in — what `ExchangeRate::quote()` returns, and what the serde `"quote"` field holds — and it is also a whole rate, which is what the iterator types yield and what most of `Exchange`'s prose, its doctest bindings, and its test names mean by the word. **Desired behavior:** As a noun, "quote" means only the currency a rate is priced in. A rate is called a rate. The verb is untouched: only a rate can be quoted, so no ambiguity arises from it, and "the table quotes a pair", "a pair quoted twice", and "nothing here quotes one for you" all stay as written. **Key interfaces:** - `Quotes` → `Rates`, `IntoQuotes` → `IntoRates`, with the crate-root re-export following. Their `Item` type, their iterator trait impls, and the `IntoIterator` associated types on `Exchange` and `&Exchange` change in name only — no behavior and no change to the shape of any signature. - `ExchangeRate::quote()`, the `quote` field behind it, the `quote` parameters on `Exchange::rate` and `Exchange::remove_rate`, and the serde `"quote"` field name together with its field constant are all the currency sense. None of them move. **Scope of the sweep** — every noun use of "quote"/"quotes" that means a rate becomes "rate"/"rates": - the module-level docs, the `Exchange` and `ExchangeRate` type docs, and the `Display` doc - the method docs on `set_rate`, `remove_rate`, `clear`, `len`, `is_empty`, and `iter`, plus the `FromIterator` and `Extend` impl docs - the serde module's `Exchange` and `ExchangeRate` impl docs - doctest and unit-test bindings named `quote` that hold an `ExchangeRate` - test function names — `exchange_displaces_an_earlier_quote_test`, `exchange_clears_every_quote_test`, `exchange_collects_from_quotes_test`, and the rest of that family - README prose **Changelog:** only the `[Unreleased]` section is edited. Its `Quotes`/`IntoQuotes` bullet names `Rates`/`IntoRates` instead, and its other bullets follow the same sweep. No "Changed" entry is added — the names never shipped, so there is nothing to record as changed. Released sections are history and stay as they are, including the `Exchange::quotes` entry under `[0.10.0]`. **Acceptance criteria:** - [ ] `Rates` and `IntoRates` are the iterator types and are re-exported from the crate root; `Quotes` and `IntoQuotes` appear nowhere in the repository. - [ ] `ExchangeRate::quote()` and the serde `"quote"` field are unchanged, and a rate still travels as `{"base": "USD", "quote": "EUR", "rate": "0.9"}`. - [ ] Every surviving occurrence of "quote" under `src/` and in `README.md` is one of: the `quote` field, getter, or parameter; the serde field name or its constant; or a verb form — "quotes", "quoted", "unquoted". - [ ] No test name uses the noun for a rate. - [ ] The `[Unreleased]` changelog section names `Rates`/`IntoRates`, and the `[0.10.0]` section and everything below it are unchanged. - [ ] `mise run fmtcheck`, `mise run clippy`, and `mise run ci` all pass, doctests included. **Out of scope:** - Renaming `ExchangeRate::quote()`, its field, or the serde field — that is the sense being kept. - Changing any verb form. - Any behavior change; this is a rename and a documentation sweep. - `Balances`/`IntoBalances` and the rest of the bag module, which the collision does not reach.
rosa closed this issue 2026-08-14 23:46:24 +00:00
Sign in to join this conversation.
No milestone
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
rosa/lucre#16
No description provided.