0.5.1

Release Notes

Upgrading from (0.5.0)

This patch release contains only bug fixes, and should present no
difficulties when upgrading from 0.5.0.

User-facing library changes

Issues fixed:

• Fixed ambiguous two-parameter constructor for Quantity and
  QuantityPoint (#525)
• Improved efficiency (fewer assembly instructions) of mean()
  implementation (#526)
• Make N in mag<N>() a std::uintmax_t, not size_t, improving
  compatibility on architectures where size_t is 32 bits (#542)
• Fix various compiler errors on GCC 5.3 (#548)
• Support constexpr use of data_in() for Quantity and
  QuantityPoint (#556)

Future-proofing releases

• 🚀 0.5.1-future-122: release covering #122

  • This commit opts-in all of our "explicit rep" APIs to the conversion
    safety checks. To fix build errors, read the error to see what risk
    set the library has flagged. Then, refer to our conversion risk
    guide
    https://aurora-opensource.github.io/au/0.5.1/troubleshooting/#risk-too-high
    and carefully consider how to handle this specific instance.

• 🚀 0.5.1-future-185: release covering #185

  • This commit makes it so that Quantity operations always return a
    Quantity, never a raw number. To fix build errors, wrap the
    Quantity operation inside of a call to as_raw_number().

• 🚀 0.5.1-future-429: release covering #429

  • This commit deletes the UnitAvoidance construct. To fix build
    errors, instead of specializing ::au::detail::UnitAvoidance,
    specialize ::au::UnitOrderTiebreaker.

• 🚀 0.5.1-future-481: release covering #481

  • This commit removes all APIs with the word "coerce" in their name.
    To fix build errors, first, delete the coerce_ part of the name.
    Then, if you get a compiler error, read the error to see what risk
    set the library has flagged, and refer to our conversion risk guide
    https://aurora-opensource.github.io/au/0.5.1/troubleshooting/#risk-too-high
    to see how to handle this specific instance.

Closed Issues

This patch release contains cherry-picked fixes, rather than a
date-based range of commits on the main branch. Therefore, see the
milestone page for a list of closed issues:

https://github.com/aurora-opensource/au/milestone/10?closed=1

Contributors

Thanks to those who authored or reviewed PRs, or filed or participated
in Issues! Alphabetically:

• @chiphogg
• @geoffviola
• @hoffbrinkle
• @to-s

Artifacts and SHA256 sums

Artifact	Role	SHA256 sum
au-0.5.1.tar.gz	Main release	65675096bab253f81813760a5643810cb60c662a4fb2944bb49d77d9c11c85e8
au-0.5.1-future-122.tar.gz	Future-proof for #122	5a15828421587ca643f3ae73c2c34529d50a16eaca2f361da8fa8b43569d0573
au-0.5.1-future-185.tar.gz	Future-proof for #185	fdc19e4afccb3b84156dcea6ea17ba5dad0f8deb2959c2aadad7aec14e972731
au-0.5.1-future-429.tar.gz	Future-proof for #429	1b0363488b283cc8300746f4db69cfa9a922f747bc3dfe56597c56a76b13735e
au-0.5.1-future-481.tar.gz	Future-proof for #481	ca0b6e074ce09d025bce936b99398976d034c5f57e73876cb542ea46830f154b
au-0.5.1-future.tar.gz	Complete future-proof release	0d5bca2fa817a08bf5e36d9a1af65a8d600526f4f3cf596b58df4f8488bd4e8e

0.5.0

Release Notes

Upgrading from (0.4.1)

💥 This "upgrade guide" section collects all breaking changes we expect
users to encounter when upgrading from 0.4.1 to 0.5.0. We will give guidance
for how to handle each. See also our how-to Upgrade Au guide,
https://aurora-opensource.github.io/au/0.5.0/howto/upgrade/, for more details.

• Removed deprecated items: PI, pascal, integer_quotient. (#496)

  • To replace PI, add constexpr auto PI = Magnitude<Pi>{}; as needed.
  • To replace pascal, add
    constexpr auto pascal = SingularNameFor<Pascals>{}; as needed.
  • To replace integer_quotient, just do regular division, but wrap the
    denominator in unblock_int_div(...). Better yet, carefully read our
    newly updated integer division docs,
    https://aurora-opensource.github.io/au/0.5.0/troubleshooting/#integer-division-forbidden,
    and double check that you're not accidentally masking a serious bug.

• Signed/unsigned integer comparisons are now automatically done correctly.
  (#432)

  • If this "breaks", it likely means your code was previously silently
    returning incorrect results, and this breakage has exposed a pre-existing
    bug. Carefully inspect the failure and surrounding logic to see how to
    fix it.

• Narrow the conversion policy carveout for integer promotion: apply only to
  the exact promoted type. (#473)

  • We expect breakages to be very rare. If you see new errors in operations
    involving small integral types, it might be due to this change. To fix
    this, read our conversion risk docs,
    https://aurora-opensource.github.io/au/0.5.0/troubleshooting/#risk-too-high
    and follow the instructions, as you would for any other risky conversion.

• OriginDisplacement now returns a shapeshifter type, rather than a quantity:
  either a Constant<U> for some unit U, or else Zero. (#421)

  • We expect breakages to be very rare, because most or all users would not
    be using this utility anyway. If you encounter a problem, please file an
    issue for more specific guidance.

• (Updated 2025-08-21:) In rare cases, you may see "call of overloaded '...'
  is ambiguous", where the ... is some function name. This can happen if one
  overload takes a quantity type, another takes a struct whose first member is
  that quantity type, and the callsite passes an anonymous braced list. This is
  a bug (#525) discovered after release that we will fix in the next release.
  See also https://godbolt.org/z/r6Wjqnvnz for an example.

  • To work around this bug, name the struct that you are passing at the
    callsite: pass MyStruct{...} instead of {...}.

If you find a problem upgrading from 0.4.1 to 0.5.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

✨ New foundations for unit conversions: Abstract Operations

Under the hood, this lets us reason about conversions in a unified way: both
their implementations, and their conversion risks. We create abstract
operations for static casting, multiplying, dividing-by-integer, and any
sequences thereof. Each operation (including operation sequences) can be
assessed for the overall risk of overflow or truncation. They can also assess
whether a particular input will overflow or truncate. This makes our runtime
conversion checkers more efficient: for example, the overflow checkers now
simply compare to a lower and upper bound for the holistic conversion.

This change has a major effect on our unit conversion interfaces: now that we're
separately assessing overflow and truncation risks, we can separately turn them
off. Every unit conversion --- including constructors --- accepts a second
argument, such as ignore(TRUNCATION_RISK) or ignore(OVERFLOW_RISK), to
disable that risk alone. If you fail a risk check, the compiler error will tell
you exactly which one you failed, and link to the detailed discussion in our
troubleshooting guide. This new interface is both safer (as we retain the
un-named check), and better communicates intent.

Because of this change, we will both get rid of our "coerce" interfaces, and
turn on safety checks for "explicit rep" interfaces, in the next release. In
the meantime, we recommend you switch to the new interfaces right away (and see
our future proof section below for tools to help with that).

Implemented in:

• #450, #452, #454, #455, #456, #457, #458, #459, #460, #462, #463, #464,
  #465, #466, #468, #469, #472, #474, #476, #477, #478, #482, #498, #499,

✨ Support for {fmt} and std::format

Au now includes a generic formatter, ::au::QuantityFormatter<U, R> for
formatting a Quantity<U, R>, which serves as the basis of implementations for
both {fmt} and std::format. To use with std::format, simply include
"au/std_format.hh" (assuming, of course, that your toolchain supports
std::format in the first place!). To use with {fmt}, follow our format
docs, https://aurora-opensource.github.io/au/0.5.0/reference/format/.

Any format string that applies to the underlying rep R of a Quantity<U, R>
will automatically apply to that quantity, with the same effects! The unit
label will be printed right afterwards, separated by a space. You may also
set a consistent (right) padding for the unit label by inserting a string like
U##;, where ## is some integer (so: U5;, U12;, etc.). This goes right
after the :, and before the rest of the string. (#505)

✨ Automatically correct signed/unsigned quantity (and point) comparisons

Signed/unsigned comparison is a common "gotcha" of the C++ language: for
example, -1 < 0u is actually false, because -1 gets converted to unsigned,
and wraps around! Formerly, Au was vulnerable to this kind of edge case. Now,
we automatically handle comparisons correctly for any combination of signed and
unsigned integer types. (#432, #433, #434, #517)

✨ Negative Magnitudes, Units, and Constants

You can now negate a Magnitude using the unary - operator: -mag<1>() is
just what it looks like! For a magnitude M, we now provide new traits:

• Abs<M> to take its absolute value (#402)
• IsPositive<M> to check whether it's positive (#402)
• Sign<M> gives either mag<1>() or -mag<1>() (#431)

Negative magnitudes will have a natural effect on units and constants, too.
Constants can be negated (#407), although units cannot, because a "unit" can be
any arbitrary type. Conversions (#403) and comparison operators (#406) work
correctly: so, for example, something like neginches(1) < neginches(2) will
return false.

✨ Maximum efficiency common point units

Our common unit computations for QuantityPoint used to depend on the units
chosen for the origin. This resulted in excessively fine-grained units, which
in turn meant our underlying numbers were larger than necessary (increasing
overflow risk). For example, we use Centi<Kelvins> for the origin of
Celsius, which made our numbers for common point operations with Kelvins
5x bigger than they needed to be. (mp-units uses millikelvins, so this penalty
is currently 50x for them!)

To resolve this, we treat the origin displacement between every pair of units as
an ad hoc "unit". It simply participates with all the other units on equal
footing in the Greatest Common Factor algorithm for common units. Now, it
doesn't matter what units we use for the origin; the common point units will
always be maximally efficient. (#410, #420, #421)

✨ Math Functions and Upgrades

• Power helpers (sqrt(...), pow<N>(...), etc.) can now be applied to
  Constant and SymbolFor instances (#376)
• Add type-based versions of the above (Sqrt<...>, Inverse<...>,
  Cubed<...>, etc.) (#400)
• New math functions:
  • cbrt (#389)
  • hypot (#384)
  • lerp (C++20 only) (#430)
  • mean (#507)

✨ Other enhancements, bugfixes, and refactorings

• Streaming output now supported for Magnitude, Constant, and SymbolFor
  instances (#380)
• SingularNameFor instances can now be passed to unit slots (#374)
• Library now clean under -Wsign-conversion (#394), -Wconversion (#444), and
  -Wsign-compare (#398)
• get_value<T>(m) can now handle a Magnitude m that is the lowest signed
  value of T (#447)
• Zero can participate in common_unit computations (it's a no-op), and can
  "act like a constant" if it is passed to make_constant(...) (also a no-op)
  (#409)
• Flattened unit labels for "common unit of common point units", removing some
  ridiculous nested EQUIV instances (#422)
• Removed empty glob of srcs (#446)
• Placated overly fussy Green Hills compiler errors (#475, #479, #515)
• Added ::au::UnitOrderTiebreaker as a replacement for
  ::au::detail::UnitAvoidance, which should be used in every case (#483)
• Quantity::data_in now fully supports unit slot arguments (#490)
• In default QuantityPoint constructor, default-construct rep (#502)

Compile time impact

(Updated 2025-08-01:) We measured the compile time impact, but forgot to
include it in the initial release notes. What we found was that the cost to
simply include the file was barely affected at all: it ranged from unmeasurable
in some files, to at most about 15 ms.

Files with very many unit conversions did show a measurable but uneven increase.
Some mixed-unit quantity point operations were twice as expensive, adding over
100 ms. Other mixed-unit operations didn't show any increase.

Overall, the compile time increase was barely or not at all measurabl...

0.4.1

Release Notes

This was mainly a bugfix release, focused on some small breakages in
CMake and MSVC. We've added CI coverage to prevent these kinds of
errors robustly going forward.

User-facing library changes

New common unit utilities (#362)

• common_unit(...) utility computes an instance of the common unit of
  the inputs. Arguments are unit slots, so you can pass not just units
  (Meters{}), but also quantity makers (meters), unit symbols (m),
  and so on.
• make_common(...) is like common_unit(...), except that the inputs
  all have to be the same "kind" of thing, and the output will be that
  same "kind" of thing, not just a simple unit. For example,
  make_common(mm, in) gives a unit symbol, and you can multiply it by
  a number just as you could with the inputs mm or in.
• We also have common_point_unit(...) and make_common_point(...) if
  you want to get the "for points" flavor of the common unit.

Other changes

• Error messages are cleaner when you try passing a Quantity or
  QuantityPoint to any kind of unit slot (#366).
• Used more specific feature test macro for C++20 operator<=> support
  (#358).

Documentation updates

• Added a new troubleshooting entry for passing a Quantity to a unit
  slot (#366).

Repo updates

• Added CI coverage for CMake client libraries (360).
• Expanded CI coverage for MSVC (#363, #365).

Closed Issues

Here are all of the issues that were closed between these releases.
(Note that the resolution is at the level of days, so some of these
issues might show up in the notes for more than one release.)

NOTE: change dates below!

https://github.com/aurora-opensource/au/issues?q=is%3Aissue+closed%3A2024-12-12..2024-12-20

Contributors

Thanks to those who authored or reviewed PRs, or filed or participated
in Issues! Alphabetically:

• @chiphogg
• @geoffviola
• @hoffbrinkle
• @matthew-reynolds
• @timhirsh

0.4.0

0.4.0

Release Notes

User-facing library changes

Potentially breaking changes 💥

• Old-style .in and .as APIs are finally removed (#350). (These
  have been deprecated for the entire public existence of the library,
  so these callsites really shouldn't exist!) If you have
  q.in<Meters>(), replace with q.in(meters), and so on.
• Greatly consolidated and simplified our CMake target breakdown: thus,
  many targets disappeared, and were combined into Au::au (#300)
• Certain qualified function calls (e.g., au::min(a, b)) will now
  cause compiler errors (#330). The fix is to replace them with
  unqualified calls (e.g., min(a, b)). This was always the guidance,
  but now it is mandatory for these functions.
• Deprecated pascal (#285)

⚠️ The following is not a breaking change, but prepares for a
future breaking change. We have added the as_raw_number(...)
utility (#333). Pass it any dimensionless quantity to have it safely
convert to the equivalent (unitless) raw number. If you pass it a raw
number, it's a no-op. We recommend using this wherever you have a
Quantity calculation that you want to result in a raw number. In the
future (#185), all Quantity calculations will produce Quantity, not
raw numbers, and this function will become necessary --- start using it
today to get ahead of the curve.

Library-included constants

Au now includes certain exactly-defined physical constants out of the
box! Each one can be found in the new "au/constants/..." folder. The
name of the constant will be in all-caps (e.g., SPEED_OF_LIGHT), and
the name of the file will be the snake-case version (e.g.,
speed_of_light.hh). They can be included in a single-file packaging
via --constants (#335). See our constants docs for a full list.

Explicit-rep runtime conversion checkers

We now provide utilities to check every Quantity conversion in the
library! (At least, those whose rep is a fundamental arithmetic type.)
You can call will_conversion_overflow<T>(q, target),
will_conversion_truncate<T>(q, target), or
is_conversion_lossy<T>(q, target) (which is the disjunction of the
first two). As far as we know, runtime conversion checkers (#347, #351)
are a first for any units library!

Integer division updates

Integer division generally has undergone a huge overhaul. We switched
to a much more user friendly API, replacing the integer_quotient(a, b)
pattern with the much more flexible a / unblock_int_div(b) pattern
(#315). We also expanded the set of cases that work out of the box:
quantity-equivalent units no longer require any manual override for
integer division (#275).

Improved unit labels

We have eliminated virtually all instances of the dreaded
[UNLABELED_UNIT]!

First, when scaling a unit by a magnitude, we automatically generate a
new label (#332) that combines the magnitude label (#331) and the input
unit label.

Next, common units will now "do the math for you": the automatically
generated label will express the magnitude in terms of every unique
input unit: instead of COM[in, cm], you get
EQUIV{[(1 / 50) cm], [(1 / 127) in]} (#334). This works for common
point-units as well (#339).

We also removed sources of redundancy from common units, and now
simplify them as much as possible (#310, #338).

Forward declarations

We now provide authoritative forward declarations for core library
features (#312), individual units (#314), and compound units (#342).
See our how-to guide for more on how (and when) to use this feature.

Quantity template parameters

If your Quantity has an integral rep, you can now safely emulate using
values of it as template parameters! This is generally a C++20
feature, but we have provided a C++14 compatible workaround (#318). See
template param docs for a how-to guide on this feature.

CMake, conan, vcpkg updates

This is the first release since we gained community support for both
conan and vcpkg, the two most popular C++ package managers! We updated
the installation instructions to reflect this (#302, #305).

For CMake, we made some changes to make packaging future versions for
conan and vcpkg easier. We consolidated our targets so that most end
users only need to depend on Au::au (#300). We also provided new
options: AU_ENABLE_TESTING (#303) can be disabled to avoid building
tests, and AU_EXCLUDE_GTEST_DEPENDENCY (#311) can be disabled to avoid
the GTest dependency completely (which also disables the testing).
These new options gained CI tests, too (#313).

Improved factoring

We have greatly expanded the set of values N that can be used with our
mag<N>() utility! Instead of naive trial division, we now use two
advanced algorithms. First, the Baillie-PSW fast primality test
(#320, 321, #322, #323, #324) can quickly identify when a number is
prime. (This test is known to be deterministic on all 64-bit inputs.)
Next, for a number known to be composite, we use Pollard's rho algorithm
(#325, #326, #329) as a much faster way to find non-trivial factors.
There are still numbers we cannot factor at compile time, but we do not
know of any that are actually relevant for quantity use cases.

Other enhancements, bugfixes, and refactorings:

• Several math functions (including min, max, clamp, and %) now
  work with Constant instances; moreover, more overloads of these work
  with Zero than was formerly the case (#330)
• When any chrono duration auto-converts to an au::Quantity, it'll end
  up with the correct named unit instead of an anonymous scaled unit
  (#276)
• Added partial support for complex rep types, including std::complex
  (#278)
• Improved compiler errors when trying to make a Quantity from
  something that is already a Quantity, and similar for
  QuantityPoint (#294)
• Default-constructed Quantity now explicitly default-constructs its
  value, by policy (#296)
• Unit symbols can now be scaled by a magnitude (#341)
• UIToA<uint64_t> generates compile-time string versions of unsigned
  integer types (#337)

Compile time impact

Compile time impact varies depending on the target (and depending on
which features get used). Overall, compile times have increased by
about 100 ms on our test configuration. While this shouldn't be
noticeable for most end users --- for example, it's easily smaller than
the variation in building a single version of the code --- it is around
the upper limit of what we would accept.

It's hard to root cause the slowdown precisely to individual features,
but here are the changes that appear to be the biggest culprits. These
numbers are very rough, but should be in the right ballpark relative
to that 100 ms total:

• Quantity template parameters: 30 to 50 ms.
• EQUIV label generation: 10 to 20 ms.
• Improved factoring: 0 to 30 ms.
• Mixed Constant/Quantity math: 0 to 20 ms.
• Magnitude labels and scaled units: 0 to 20 ms.
• Simplify common unit: 0 to 20 ms.

The individual feature measurements vary from file to file, but the
overall cost is pretty consistent (although 1 out of 4 files experienced
only 60 ms overall regression, not 100 ms).

New units and constants

Units:

• us_gallons (#308)
• us_pints (#308)
• us_quarts (#308)

Constants:

• avogadro_constant (#336)
• boltzmann_constant (#336)
• cesium_hyperfine_transition_frequency (#336)
• elementary_charge (#336)
• luminous_efficacy_540_terahertz (#336)
• planck_constant (#336)
• reduced_planck_constant (#336)
• speed_of_light (#308)
• standard_gravity (#348)

Tooling updates

• Single-file script supports constants, individually via --constants,
  or all at once via --all-constants (#335)

Documentation updates

• Documented constants (#340)
• Refreshed installation instructions in light of CMake, conan, vcpkg
  support (#302)
• Added how-to guide for Quantity template parameters (#343)
• Explained why we do not provide a raw number constructor (#309)
• Added quantity template params to alternatives guide (#356)
• Added a new section to troubleshooting guide, and refreshed contents
  (#319)
• Updated godbolt link so that it automatically includes <iostream>
  (#291)
• Updated Au's logo, consistent with Aurora's brand refresh (#277)

Repo updates

• Updated GitHub actions versions (#279, #280, #281, #282, #293, #306)
• Changed gcc toolchain fetch URL to be more robust (#287)
• Changed the naming scheme for MSVC compiler versions (#286)
• Updated to latest version of python packages for generating docs
  (#345)
• Added a new CI modality that explicitly runs all the tests in C++20
  mode, alongside new C++20-specific use cases (#354)

Closed Issues

Here are all of the issues that were closed between these releases.
(Note that the resolution is at the level of days, so some of these
issues might show up in the notes for more than one release.)

https://github.com/aurora-opensource/au/issues?q=is%3Aissue+closed%3A2024-07-23..2024-12-12

Contributors

Thanks to those who authored or reviewed PRs, or filed or participated
in Issues! Alphabetically:

• @1040170566
• @AbrilRBS
• @andre-nguyen
• @Cazadorro
• @chiphogg
• @connorjak
• @ericriff
• @geoffviola
• @hoffbrinkle
• @MatthiasJeuthe
• @nkiraly
• @StefanoD
• @Tehfor...

0.3.5

Release Notes

User-facing library changes

Potentially breaking changes:

• au::PI is deprecated (see more details below in Arduino section)
• Core library files have moved from au to au/code/au, but this change
  should be transparent

CMake support (#254, #258, #262, #263, #264, #265, #259, #266, #268, #270)

Au now natively supports building with CMake! This was a huge effort that
should unlock much broader usability. Major thanks to @Cazadorro for getting
the ball rolling and continuing to support --- without their efforts, this would
never have happened. See CMake section in our installation docs for more
details.

Arduino support (partial) (#247, #250)

We have our first Arduino support! Note: this does not mean the "official"
Arduino IDE, which is still C++11. Rather, it means we've removed conflicts
with cores/arduino/Arduino.h, which has atrociously broad macro definitions
such as B1 and PI. This also means that we are deprecating au::PI in
order to avoid this collision; users can define their own instead using
au::Magnitude<au::Pi>{}.

Math function enhancements (#236, #237, #251)

• QuantityPoint now works with a wider variety of math functions, including
  isnan and the various rounding functions (the round, floor, and ceil
  families of function).
• min and max now support constexpr

Rep handling refinements (#218, #223, #229, #234)

• We now handle signed and unsigned integral reps more carefully in
  QuantityPoint.
• If the rep happens to be equivalent to char, we stream the output as a
  number, not a char, because Quantity is always numeric
• Partial progress in supporting complex number reps (both std::complex and
  others), although there is more work to do here (tracked in #228).

Other enhancements, bugfixes, and refactorings:

• For API designers, we now have two different types of "unit slot" APIs: those
  for Quantity, and those for QuantityPoint (#235)
• Fix an MSVC warning we found as part of the CMake work (#267)

New units

No new units in Au 0.3.5.

Tooling updates

• Rename pip_deps to au_pip_deps (#214)
• Migrate to new home for LLVM toolchain (#225)
• Update actions/checkout to v4.1.5 (#261)
• Updated the make-single-file tool to adapt to new repo structure

Documentation updates

The unit slot documentation now discusses how to handle QuantityPoint, and
explains the difference between the traits AssociatedUnitT and
AssociatedUnitForPointsT.

Repo updates

• CMake support! Including a CI job.
• Updated the python dependencies to fix more dependabot issues

Closed Issues

Here are all of the issues that were closed between these releases. (Note that
the resolution is at the level of days, so some of these issues might show up in
the notes for more than one release.)

https://github.com/aurora-opensource/au/issues?q=is%3Aissue+closed%3A2023-12-20..2024-07-23

Contributors

Thanks to those who authored or reviewed PRs, or filed or participated in
Issues! Alphabetically:

• @AbrilRBS
• @avrahamshukron
• @Cazadorro
• @chillywillysoft
• @chiphogg
• @geoffviola
• @hoffbrinkle
• @MatthiasJeuthe
• @pdaoust
• @philsc
• @pirgia
• @StefanoD
• @Tehforsch
• @timhirsh
• @tsjung75

0.3.4

Release Notes

User-facing library changes

Potentially breaking changes:

• New approach to applying magnitudes (#176)
  • The good news: conversions are in some cases faster (at runtime)
    than before!
  • The bad news: this can change results very slightly for floating
    point types. This is just the "usual floating point error": that
    is, the new result might be one or two representable floating point
    numbers away from the old one. (Well-written code should not break,
    because relying on exact results for floating point computations is
    inconsistent with standard best practices.)
  • See the brand new Applying Magnitudes docs to understand the
    change in detail!

Unit Symbols: (#194, #196, #197)

Finally, a concise way to make a Quantity. Like user-defined
literals, only better!

using ::au::symbols::m;
using ::au::symbols::s;

constexpr auto a1 = (meters / squared(second))(9.8f);  // Old
constexpr auto a2 = 9.8f * m / s / s;                  // New!

Note how easy it is to work with alternative rep, such as float;
user-defined literals would really struggle here. They also support
unit slot APIs, so you can write .as(m / s / s).

Check out the Unit Symbol section in our units docs for more details.

Constants (feature preview): (#194, #200, #204, #207)

If you have a constant of nature, such as the speed of light or Planck's
constant, this new feature will let you use it much more effectively and
efficiently. You can instantaneously multiply or divide it with any
number or quantity: the operation happens at compile time, so there
is no runtime cost! You can also convert it to any desired Quantity
type, and take advantage of our perfect conversion policy: we allow
the conversion if it can be exactly represented in the type, and forbid
it otherwise. See the Constant docs for more details.

(This is only a "feature preview" because we haven't actually included
any constant values yet. We will use the new feature internally at
Aurora for a while, and we expect to begin adding constants in the next
release.)

Runtime conversion checkers (feature preview): (#208, #212)

The gold standard for dealing with unit conversions that might overflow
integer types is to check every unit conversion at runtime. Au is now
the first units library (that we know of!) which provides a boolean
conversion checker for every individual unit conversion, which can check
whether it will be lossy for a specific runtime value. Now it's very
easy for users to lean on these utilities to do the "heavy lifting", and
write a generic "checked conversion" function using their project's
preferred error handling mechanism. See the "Check every conversion at
runtime" section of the Overflow docs for more details.

(This is only a "feature preview" because we haven't added explicit-rep
APIs, and we haven't added support for QuantityPoint yet.)

Other enhancements, bugfixes, and refactorings:

• New function, as_chrono_duration(Quantity), to turn any Au duration
  into an exactly-equivalent std::chrono::duration type (#199)
• New function, remainder(Quantity): a unit-aware analogue for
  std::remainder (basically a zero-centered fmod) (#188)
• New function, representable_in<T>(m), to indicate whether
  a magnitude m can be exactly represented in the type T (#183)
• ZERO now works as users would expect in min, max, and clamp
  (#182)
• Make Quantity in/as APIs into full-fledged unit slots (#195)
• inverse_as was too strict, preventing some valid use cases; we used
  constants to safely relax its underlying policy (#202)
• Let u in unit_label(u) be a unit slot (#206)
• Enable checking representability of Magnitude that can't fit in
  std::uintmax_t (#211)
• We can now compute a value for every representable magnitude, even
  those with fractional powers! (#213)
• The chrono interoperation utilities now get their own bazel target
  (#201)

New units

No new units in Au 0.3.4.

Tooling updates

• make-single-file has new --all-units option (#178)

Documentation updates

Here are the brand new and/or significantly updated docs, shown by their
place in the hierarchy:

• Discussion
  • Concepts
    • Overflow (#203)
  • Implementation
    • Applying Magnitudes (#176)
• Reference
  • Constant (#200)
  • Unit: Unit Symbol section (#196, #198)

Au now has explicit support for Compiler Explorer (a.k.a. "godbolt")!

• Automatically generate "godbolt friendly" single-file scripts with
  every unit (#178)
• Make a "canonical" Au godbolt link, and feature it on our README
  (#193)

We also made the following other doc changes:

• All links are now underlined, in order to improve accessibility (#191)
• Updated comparison table to reflect mp-units improvements (#175)
• RELEASE.md includes instructions to test commented-out cases, and
  check compile time impact (#180)
• Fix legacy internal links to point to main version of docs (#192)

Repo updates

• Update python deps to fix dependabot alert 5 (#181) and 6 (since
  withdrawn; #184)
• Add -Wshadow to our regular compiler options (#205)
• Add -pedantic to our EXTRA_COPTS compiler options (#210)

Closed Issues

Here are all of the issues that were closed between these releases.
(Note that the resolution is at the level of days, so some of these
issues might show up in the notes for more than one release.)

https://github.com/aurora-opensource/au/issues?q=is%3Aissue+closed%3A2023-09-01..2023-12-20

Contributors

Thanks to those who authored or reviewed PRs, or filed or participated
in Issues! Alphabetically:

• @avrahamshukron
• @chiphogg
• @geoffviola
• @jaskij
• @johnzoppina
• @matthew-reynolds
• @timhirsh
• @tobin

0.3.3

Release Notes

User-facing library changes

Here are some of the most notable changes. We'll list potentially
breaking changes first, then give sections for a few highlighted
changes, and finally group the remaining changes together.

Potentially breaking changes:

• Magnitude trait updates (#138)
  • numerator(m) and denominator(m) no longer apply only to
    the integer part; they now apply to "everything on top of
    (numerator) or below (denominator) the bar" when the
    magnitude is written as a fraction
  • To get the old behaviour, you can use the new integer_part
    trait: for example, writing numerator(integer_part(m)) to
    replace what would previously have been numerator(m)
• Label for Fahrenheit changed from "F" to "degF" (#141)
• Tightened up integer division safeguards: the new policy is to prevent
  this any time the denominator has units (even if the numerator is a
  raw number) (#142)

First official Windows support!

• We found and fixed some compiler errors on several versions of MSVC
  (#146, #151)
• Added CI jobs for Windows too (#151)

New, intent-based APIs for "forcing" unit conversions (#171)

• coerce is a new vocabulary word which means "ignore safety checks
  for truncation and overflow". Before this, we used "explicit rep" to
  express this (e.g., the <int> in inches(24).as<int>(feet)). But
  now we can write inches(24).coerce_as(feet) to do the same thing.
  It's both clearer in its intent, and it doesn't force you to repeat
  the rep!
• For now, we're providing only coerce_in and coerce_as member
  functions to complement in and as member functions, in both
  Quantity and QuantityPoint. Later on, we may add the "coerce"
  word to more APIs where it could be useful.
• You can still provide an explicit rep if you want to control the rep
  of the result: for example, inches(25.8).coerce_as<int>(feet)
  produces feet(2).

Other Enhancements:

• New function clamp(v, lo, hi): a unit-aware analogue of
  std::clamp() from C++17 (#165)
• sqrt, cbrt, inverse, squared, and cubed can now be applied
  to dimensions and magnitudes, not just units (#136)
• New trait integer_part(m) picks out the integer part of a magnitude
  (#138)
• New rep-named aliases for int (QuantityI, QuantityPointI) and
  unsigned int (QuantityU, QuantityPointU) (#150)
• Improved dimensionless unit support in our nholthaus library
  interoperation (#161)
• Made "dangerous conversion" error messages less confusing (#158)
• Enable compatibility with -Wconversion: Au will not add any
  violations (#166)
• Made most unit traits compatible with unit slots (e.g., you can now
  write unit_ratio(micro(meters), inches)) (#168)

New units

• becquerel (#157)
• farads (#157)
• grays (#157)
• henries (#157)
• lux (#157)
• siemens (#157)
• tesla (#157)

Tooling updates

• Fixed tools au-docs-serve, buildifier, and clang-format for
  people who do not use direnv, making the library much easier for
  everyone to start using (#148)

Documentation updates

This release had a major impact on documentation. Here are all of the
new and significantly updated docs, listed in their place in the
hierarchy:

• Discussion
  • Generic Concepts (#135)
    • Arithmetic Operations (#135)
    • Common Units (#135)
    • Dimensionless Units and Quantities (#135)
    • Quantity Point (#135)
    • Zero (#135)
  • Au Idioms (#135)
    • Unit slots (#135)
• How-to guides
  • Defining new dimensions (#153)
  • Inter-library Interoperation (#162)
    • nholthaus/units Interoperation (#162)
• Reference
  • Corresponding Quantity (#135)
  • Math functions (#135)
  • Prefix (was a stub) (#135)
  • Quantity (was a stub) (#135)
  • QuantityPoint (was a stub) (#152)
  • Unit (some sections were stubs) (#135)
  • Zero (#135)

Additionally, we had the following documentation updates:

• Documentation is now versioned, using
  mike (#132, #133)
• Added CONTRIBUTING.md guidelines (#129)
  • Included style guide (#164)
• Clarified our tiers of support for different compilers (#156)
• We significantly refreshed our alternatives matrix: (#147)
  • Added the bernedom/SI library
  • Solicited input from units library authors
  • Added new rows to our comparison: "Unit-aware I/O", "Unit-aware
    math", "Linear algebra", and "Physical constants"
• Refreshed troubleshooting page (#158, #172)
  • Added MSVC compiler errors (#163)

Repo updates

• Added CI jobs for Windows (#151)
• Renamed BUILD to BUILD.bazel, unblocking usage on case-insensitive
  filesystems such as MacOS (#170)
• Added status badges (#154, #155)
• Fixed security alerts:
  • Any file can be included with the pymdown-snippets extension
    (#134)
  • Unintended leak of Proxy-Authorization header in requests (#134)
  • Removal of e-Tugra root certificate (since withdrawn) (#159)

Closed Issues

Here are all of the issues that were closed between these releases.
(Note that the resolution is at the level of days, so some of these
issues might show up in the notes for more than one release.)

https://github.com/aurora-opensource/au/issues?q=is%3Aissue+closed%3A2023-03-20..2023-09-01

Contributors

Thanks to those who authored or reviewed PRs, or filed or participated
in Issues! Alphabetically:

• @chiphogg
• @connorjak
• @geoffviola
• @jasonbeach
• @johnzoppina
• @kbwilliams17
• @mortenfyhn
• @mpusz
• @nitishthatte
• @sgayda2
• @timhirsh
• @tobin

0.3.2

Release Notes

User-facing library changes

• Bugfix: replace copy initialization with direct initialization inside
  the Quantity implementation. This improves support for some
  obscure, non-arithmetic Rep types.

Repo updates

Fixed security alert due to untrusted TrustCor certificate.

Closed Issues

Here are all of the issues that were closed between these releases.
(Note that the resolution is at the level of days, so some of these
issues might show up in the notes for more than one release.)

https://github.com/aurora-opensource/au/issues?q=is%3Aissue+closed%3A2023-03-18..2023-03-20

Contributors

Thanks to those who authored or reviewed PRs, or filed or participated
in Issues! Alphabetically:

• @chiphogg
• @geoffviola
• @philsc
• @timhirsh

0.3.1

Release Notes

User-facing library changes

Here are the most notable changes:

New thresholds for inverses and conversions (#69):

• The inverse_as family now safeguards conversions whose factor is
  less than 1,000,000, instead of 1,000. So for example,
  inverse_as(hertz, milli(seconds)(5)) won't compile anymore without
  an explicit Rep; you would need micro(seconds) or smaller. This
  makes inversion fully lossless for integral values up to 1,000! As
  always, this doesn't affect floating point Rep; these are always
  permitted.

• We slightly loosened the overflow safety surface to permit signed
  32-bit integer conversions with a factor of 1,000,000. For example,
  mega(hertz)(1u).as(hertz) has always worked, but
  mega(hertz)(1).as(hertz) previously didn't. Now it does.

Improve QuantityMaker and SingularNameFor composition (#72):

• It is now possible to compose units such as hertz, whose singular
  name is identical to its plural name. Compositions generally should
  be much easier overall. The downside is that we now permit
  grammatically incorrect combinations, such as (meters / seconds)
  rather than (meters / second), but making that an error was probably
  too heavy handed anyway.

Easy compatibility with nholthaus units:

• In #112, we added a file which users can add to their project, to set
  up a correspondence between types in the nholthaus/units library, and
  Au. This means you can pass an Au quantity to an API expecting an
  equivalent nholthaus type, and vice versa! Formal documentation is
  still pending (see #107 to follow along). However, interested users
  can read the comments in the files added in #112 to see how to set it
  up.

Here are the remaining library changes:

• Bugfix (#98): inverse_as<Rep>(...) did not have the correct Rep.
• Bugfix (#100): QuantityPoint conversion could change Rep for small
  integral types.
• Bugfix (#119): Make default Quantity and QuantityPoint
  constructors noexcept, enabling std::atomic usage on gcc-9.

New units

• fathoms
• furlongs
• knots
• nautical_miles

Thanks to Randall Munroe for supplying the use case:
https://xkcd.com/2585/

Additionally, we added support for these new SI prefixes:

• quetta
• ronna
• ronto
• quecto

Tooling updates

• Added buildifier 5.1.0.
• Upgraded bazel to 6.0.0.
• Tools that wrap bazel commands now give a (transient) message
  explaining why they're slow on the first execution.
• bazel test now shows output for failed tests by default.
• We now compile with -Wextra. (Its absence was an oversight.)
• Warnings are treated as errors, but only in CI (to facilitate
  test-driven development).

Documentation updates

This was a major release for the documentation website. We added the
following pages:

• Development Setup
• Troubleshooting Guide
• Comparison of Alternatives
• Tutorials
  • Au 101: Quantity Makers
  • Au 102: API Types
  • Au 103: Unit Conversions
• Reference Docs

Additionally, we made the following changes:

• Doc website now gets updated automatically on every push to main.
• Main landing page and README have public facing content, not
  placeholders.

Repo updates

• Added Apache 2.0 license.
• Added security policy.
• Enabled automatic enforcement for:
  • copyright headers
  • buildifier linting
  • SHA-pinned GitHub actions (for security)
• Upgraded bazelisk to 1.16.0, fixing deprecation warning.

Closed Issues

Here are all of the issues that were closed between these releases.
(Note that the resolution is at the level of days, so some of these
issues might show up in the notes for more than one release.)

https://github.com/aurora-opensource/au/issues?q=is%3Aissue+closed%3A2022-12-20..2023-03-18

Contributors

Thanks to those who authored or reviewed PRs, or filed or participated
in Issues! Alphabetically:

• @avrahamshukron
• @chiphogg
• @geoffviola
• @johnzoppina
• @kbwilliams17
• @mweeksaurora
• @nkiraly
• @philsc
• @timhirsh
• @tobin

0.3.0

Release Notes

User-facing library changes

• Single-file installations of the library now contain a manifest
  comment at the top! This makes it crystal clear which version and
  options were used to generate the file.

• We've formally deprecated the old-style .in / .as APIs. Users who
  try to use them will get a readable compiler warning telling them what
  to do instead.

• We also deprecated all callables whose names are units which have
  nonzero offsets. The only two such callables were celsius() and
  fahrenheit(). These are ambiguous between Quantity and
  QuantityPoint, and that ambiguity is dangerous in ways that it's not
  for other kinds of units. To replace these names, we added a _qty
  suffix for quantity makers of such units, analogous to _pt. This
  _qty suffix is omitted on all other units for readability.

Tooling/Doc changes

• Added installation instructions.

• As part of the move to aurora-opensource/au, we lost access to the
  Aurora-internal buildkite agents we had been using, so we migrated to
  GitHub Actions for the foreseeable future.

Contributors

Thanks to those who authored or reviewed PRs! Alphabetically:

• @chiphogg
• @geoffviola
• @johnzoppina
• @philsc
• @timhirsh
• @tobin