"Quote" names both a rate and a currency #16
Labels
No labels
kind
bug
kind
enhancement
kind
refactor
workflow
needs-info
workflow
needs-triage
workflow
ready-for-agent
workflow
ready-for-human
workflow
wontfix
No milestone
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
rosa/lucre#16
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Since
ExchangeRate::from/tobecamebase/quote(c723307), the noun "quote"names two different things in
exchange.rs. It is the currency a rate is pricedin —
ExchangeRate::quote()returns aCurrency— and it is also a whole rate,which is what
QuotesandIntoQuotes(src/exchange.rs:614,:666) yield andwhat 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), "oneExchangeRateper pair quoted"(
:591).The two senses met in one expression at the serde
Exchangeimpl, which readPair(quote.base(), quote.quote())before the loop variable was renamed torate. That spelling is gone, but nothing stops it coming back while bothsenses are live, and
Quotes' own doctest still bindslet quotes: Quotes<'_> = desk.iter()a few lines under a getter namedquote.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:
QuotesbecomesRates,IntoQuotesbecomesIntoRates, and the prose says "every rate thetable holds". Costs a rename of two public types, and gives up a name that
reads well for a table's contents.
Quotesiterator yielding
ExchangeRateis unsurprising and the getter is only everreached through a rate. Costs nothing now; the ambiguity stays.
Worth settling before release rather than after.
QuotesandIntoQuotesarepublic (
src/lib.rs:20), so the first option is a breaking change — but thebase/quoterename is itself unreleased, so taking both in the same versioncosts one break instead of two.
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 —
QuotesbecomesRates,IntoQuotesbecomesIntoRates, 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:
QuotesandIntoQuoteshave never shipped.v0.10.0exportedExchange,ExchangeRate, andInvalidRateError, andExchange::quotes()returned ananonymous
impl ExactSizeIterator; the named types arrived in the currentunreleased cycle. Renaming them is not a breaking change — it edits an
unreleased "Added" entry and nothing else.
it yields:
MoneyBag::balance()pairs withBalances/IntoBalances, bothyielding
Money.Exchange's accessors arerate,set_rate, andremove_rate, over aratesmap.Rates/IntoRatesrestores that pattern;Quoteswas 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-exportfollowing. Their
Itemtype, their iterator trait impls, and theIntoIteratorassociated types on
Exchangeand&Exchangechange in name only — nobehavior and no change to the shape of any signature.
ExchangeRate::quote(), thequotefield behind it, thequoteparameters onExchange::rateandExchange::remove_rate, and the serde"quote"field nametogether 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":
ExchangeandExchangeRatetype docs, and theDisplaydocset_rate,remove_rate,clear,len,is_empty, anditer, plus theFromIteratorandExtendimpl docsExchangeandExchangeRateimpl docsquotethat hold anExchangeRateexchange_displaces_an_earlier_quote_test,exchange_clears_every_quote_test,exchange_collects_from_quotes_test, andthe rest of that family
Changelog: only the
[Unreleased]section is edited. ItsQuotes/IntoQuotesbullet names
Rates/IntoRatesinstead, and its other bullets follow the samesweep. 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::quotesentry under[0.10.0].Acceptance criteria:
RatesandIntoRatesare the iterator types and are re-exported from thecrate root;
QuotesandIntoQuotesappear nowhere in the repository.ExchangeRate::quote()and the serde"quote"field are unchanged, and arate still travels as
{"base": "USD", "quote": "EUR", "rate": "0.9"}.src/and inREADME.mdis oneof: the
quotefield, getter, or parameter; the serde field name or itsconstant; or a verb form — "quotes", "quoted", "unquoted".
[Unreleased]changelog section namesRates/IntoRates, and the[0.10.0]section and everything below it are unchanged.mise run fmtcheck,mise run clippy, andmise run ciall pass, doctestsincluded.
Out of scope:
ExchangeRate::quote(), its field, or the serde field — that is thesense being kept.
Balances/IntoBalancesand the rest of the bag module, which the collisiondoes not reach.