Use cases
---------

1. Provide easy-to-use and efficient round-ties-to-away behaviour in Python 3.
2. Provide a wider selection of rounding modes for floats.
3. Versions of math.floor and math.ceil that allow a number of digits to
   be specified. (Subcase of 2.)
4. Improved formatting options for floats (e.g., allowing manipulation of
   an intermediate representation that provides the digits, exponent and sign,
   to answer all the Stack Overflow questions about with/without trailing zeros,
   with/without decimal point
5. Allow formatting that doesn't implicitly use round-ties-to-even
6. Decimal formatting for fractions.Fraction instances.
7. Round to a given number of significant digits rather than to a given
   number of places after the point.
8. Hybrid rounding to a number of significant digits, but with a minimum
   decimal exponent.
9. Provide easy-to-string-together pieces that together provide more extensive
   and flexible formatting solutions.
10. Stretch goal: add "do-what-I-mean" rounding - rounding where the
    discontinuities lie at the closest binary approximations to the actual
    mathematical discontinuities. (So e.g., rounding the float value 2.8 *down*
    to the nearest tenth doesn't produce `2.7`, on the basis that the actual
    value being rounded is
    2.79999999999999982236431605997495353221893310546875)
11. Make extensible for custom types that want to register (e.g., BigFloat)
12. Rounding to number of significant digits instead of to given decimal place.
    (This is currently awkward to do both for floats and for Decimal.)
13. Mixed-mode formatting that has both a minimum exponent *and* a number
    of significant digits. (E.g., formatting a float to 17 significant digits,
    but not going beyond E-324)


Issues with Python's rounding functionality
-------------------------------------------

Summary: inconsistent, not unified.

Then lots of details:

- Decimal: two-argument round uses the rounding mode from context; one-argument round
  ignores context(!).
- Decimal: two-argument round fails if the result has more digits than the current
  context precision.
- String formatting effectively does round to significant figures, round does not.
- String formatting does round to places, but only for positive places.
- `ceil`, `floor` and `trunc` are polymorphic and round to int, but provide no way to do the efficient
  rounds-to-same-type operation. No support for rounding to a number of places.
- round itself only supports one rounding mode (and that mode is different in Python 3
  from Python 2).
- No builtin way to get the Python 2 rounding mode back.


Components
----------

Components of the solution space.

- Rounding modes: 13 available (6 directed, 6 to-nearest, plus one
  odd-ball from Decimal)

- Converters from numeric values of various different types to "sign and
  quarters" or "plus-two-bits" representation, using round-to-odd.

- Rounders round that sign-and-quarters representation to a
  (sign, significand, exponent) triple, for a given rounding mode.

- Converters from the (sign, significand, exponent) back to the target type.


From the original README

The goal of the "rounders" package is to provide a more unified, consistent
and complete approach to decimal rounding in Python.

Particular goals include:

* Allow a rounding mode to be used when rounding; in particular, allow "round"
  to do standard "high school" rounding (using the round-ties-to-away mode)
  rather than the default "Banker's rounding" (round-ties-to-even).
* Provide a comprehensive selection of rounding modes (currently 13 different
  rounding modes are provided).
* Provide variants of `math.floor` and `math.ceil` that support operating to a given
  number of places.
* Make it easy to round to a given number of significant figures as well as to
  a given number of decimal places.
* Support all built-in numeric types, and provide an extension mechanism to allow
  third-party types to be easily supported.
* Provide a basis for more flexible string formatting for numeric types, including
  the `fractions.Fraction` type (which doesn't currently support float formatting).
