retail.price-rounding

def round_price(price: Money, step: int, ending: int, direction: PriceDirection) -> Money

PriceDirection = Literal["up", "down", "nearest"]

from fune.retail.price_rounding import round_price  # retail.price-rounding@^1

from .math_round_div import round_div  ← from math.round-div ^1.0.0 · built alongside by fune
from .money_amount import Money, money  ← from money.amount ^1.0.0 · built alongside by fune
from .retail_price_rounding_types import PriceDirection


def _whole(value: object) -> bool:
    return isinstance(value, int) and not isinstance(value, bool)


def round_price(price: Money, step: int, ending: int, direction: PriceDirection) -> Money:
    """Snap a price to the points k x step - ending.

    Shifting by ``ending`` turns every point into a multiple of ``step``, so
    the whole policy is one integer division with the right rounding mode.
    """
    if not _whole(step) or step < 1:
        raise ValueError("step must be 1 or more, received %r" % (step,))
    if not _whole(ending) or ending < 0 or ending >= step:
        raise ValueError("ending must be from 0 to step - 1, received %r" % (ending,))
    if price.minor < 0:
        raise ValueError("price must not be negative, received %d" % price.minor)
    shifted = price.minor + ending
    if direction == "up":
        point = round_div(shifted, step, "up") * step - ending
    elif direction == "down":
        point = round_div(shifted, step, "down") * step - ending
        if point < 0:
            raise ValueError("no price point at or below %d" % price.minor)
    elif direction == "nearest":
        point = round_div(shifted, step, "half-up") * step - ending
        # Below the first point the only candidate is above.
        if point < 0:
            point = step - ending
    else:
        raise ValueError('unknown direction "%s"' % (direction,))
    return money(point, price.currency)

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 2 dependencies, pins them in fune.lock, downloads only the Python package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add retail.price-rounding

The manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./retail.price-rounding-1.0.0-python.fune, or fetch it from a terminal with fune pull retail.price-rounding@1.0.0:python.

The whole function, every language, is one file too: retail.price-rounding-1.0.0.fune, 13,055 bytes, sha256 d39029f0305ffe416736abd470d7272f7161efeb35839bc185a407b36c8df25e. It installs into a project of any language.

# fune: before retail.price-rounding

# fune: after retail.price-rounding

# fune: replace math.round-div in retail.price-rounding
# fune: replace money.amount in retail.price-rounding

# fune: step retail.price-rounding after <n|label>

More from the author

`up` gives the smallest point at or above the price, `down` the largest at or below, `nearest` whichever is closer. A tie (2.49 between 1.99 and 2.99) goes to the higher price, which is the usual retail choice and matches `math.round-div`'s half-up. A price already on a point is returned unchanged.

## Edge cases

- Points are never negative. `nearest` for a price below the first point (0.00 under charm .99) returns the first point, 0.99; `down` has no answer there and is an error. - The price must be 0 or more. Discounts and refunds are not rounded to price points. - Currency does not matter to the arithmetic, so the same rule works for yen (step 100, ending 20 gives ¥980, ¥1,080) as for pence.

This rounds a price someone is about to print on a shelf. It is not for tax or invoice arithmetic, which should use `math.round-div` or `money.apply-rate` directly.

Files