au 0.6.0

A C++14-compatible physical units library with no dependencies and a single-file delivery option. Emphasis on safety, accessibility, performance, and developer experience.

Release notes

Release Notes
=============

Upgrading from (0.5.1)
----------------------

:boom: This "upgrade guide" section collects all breaking changes we expect
users to encounter when upgrading from 0.5.1 (or 0.5.0) to 0.6.0.  We will give
guidance for how to handle each.

_**NOTE:** every breaking change has a syntax that works for both 0.5.x and
0.6.0.  Use this syntax to fix up individual callsites in your codebase.  After
you do, the commit that upgrades to 0.6.0 will be small and simple.  See our
[upgrade guide](https://aurora-opensource.github.io/au/0.6.0/howto/upgrade/) for
more details._

- `au::detail::UnitAvoidance` specializations are no longer permitted;
  specialize `au::UnitOrderTiebreaker` instead.  (#429, #718)

- Arithmetic results that are _exactly unitless_ (e.g., meters per meter;
  seconds times hertz) will **no longer produce a raw number**; instead, they
  produce a `Quantity`.  The simplest fix is to wrap these in an
  `as_raw_number(...)` call.  This works for both raw numbers and dimensionless
  quantities; see [as_raw_number] docs for more details.  (#185, #705)

- `coerce_as` and `coerce_in` are deprecated everywhere.  Instead of
  `coerce_as(u)`, use `as(u)`.  If it fails to compile, read the error, and use
  one of `as(u, ignore(TRUNCATION_RISK))`, `as(u, ignore(OVERFLOW_RISK))`, or
  `as(u, ignore(TRUNCATION_RISK | OVERFLOW_RISK))`, as appropriate.  See our
  [conversion risk docs] for more details.  (#481, #710, #711, #716)

- Explicit-rep overloads (e.g., `q.as<int>(u)` instead of `q.as(u)`) **no longer
  override safety checks**.  To fix new compiler errors, add a conversion risk
  policy parameter, as per our [conversion risk docs].  (#122, #708)

- Implicit-rep overloads (e.g., `q.as(u)`) no longer _necessarily_ return the
  same rep as the input; instead, they return the "natural" output of the
  underlying C++.  The only _existing_ code that should be affected is small
  integer types that are subject to integer promotion.  If this causes issues,
  you can write `q.as<au::SameRep>(u)` to request the same rep explicitly.
  (#679, #685, #712, #719)

- The `Quantity` constructor now performs an _implicit_ conversion on the
  underlying value, rather than a `static_cast`.  This means that your compiler
  warnings (say, `-Wconversion`) will fire in Au code in exactly the same
  situations where they would have fired in the equivalent raw-numeric code.  If
  this surfaces new warnings, they are warnings your raw-number program would
  also have produced; see our [compiler warnings policy] for the reasoning.
  (#528, #629, #631, #633)

- Unit labels for _prefixed, exponentiated_ units now use square brackets to
  disambiguate: `milli(inverse(bytes))` labels as `m[B^(-1)]`, rather than the
  ambiguous `mB^(-1)`.  Brackets are omitted where they'd add nothing (so
  `centi(meters / seconds)` is still `cm / s`).  If you have tests that assert
  on label text for prefixed powers, they may need updating.
  (#530, #605, #627)

If you find a problem upgrading from 0.5.1 to 0.6.0 that is not covered here,
please file an [issue](https://github.com/aurora-opensource/au/issues) to let us
know about it!

User-facing library changes
---------------------------

:sparkles: **Vector and matrix support** (#70, #484)

Au now supports vectors and matrices as the [rep] of a `Quantity`.  You can
write `meters(Eigen::Vector3d{1.0, 2.0, 3.0})` and get unit safety for the whole
vector, with all the core library operations --- arithmetic, comparison, unit
conversions --- working as you'd expect.

Getting there required rethinking some deep library foundations.  The biggest is
that a conversion which doesn't name its rep now returns the type the underlying
C++ would _naturally_ produce, rather than mechanically preserving the input rep
(#679, #685).  This is essential for expression-template libraries, and it's
also simply more correct: the core design goa…

Share this resource