Tags: aurora-opensource/au
Tags
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`. - :rocket: `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
0.5.0 Release Notes ============= Upgrading from (0.4.1) ---------------------- :boom: 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. - 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/main/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. 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 --------------------------- :sparkles: **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, :sparkles: **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) :sparkles: **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`. :sparkles: **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) :sparkles: **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) New units and constants ----------------------- - `arcminutes` (#377) - `arcseconds` (#377) - `football_fields` (#401) Tooling updates --------------- - Added a "fuzz-inspired" tool to explore unit conversion lossiness, and check our runtime conversion checkers (#461, #488) - Single-file script now supports `--std-format` option to automatically include a quantity formatter (#505) Documentation updates --------------------- - Updated docs around constants (#371, #372) - Document `cbrt` (#399) - Negative magnidues (#408) - Document conversion risk policy approach (#500, #503) - Document simplified common point units (#501) - Document new policy for `QuantityPoint` default constructor (#502) - Cleaned up how-to docs w.r.t. namespaces (#509) - Misc doc updates, including `hypot`, raw number conversions, and more (#510) - Docs now include a "with `std::format` support!" version of every pre-built single file, doubling from 4 to 8 such files (#511) - Updated assessment of library alternatives, including a new row for negative units (#512) - Updated troubleshooting guide to include new conversion risk policies (#513) - Update release instructions: include release branch and future proof artifacts (#514) - Add how-to guide for upgrading Au, and using future proof releases (#518) Repo updates ------------ - **Major structure change:** all code has been moved _back_ to `au/`, eliminating the awkward `au/code/au/` subdirectory that #266 added (#440) - Removed MSVC 2019, as it has been eliminated by GitHub (#441) - All tests now use `EXPECT_THAT` and matchers consistently, to conform to modern Googletest best practices (#405, #413, #415, #416, #417, #423, #424, #425, #426, #435, #436) - New CI coverage: - Make sure CMake isn't missing any headers (#379, #381) - Add build with `-Wsign-conversion` (#393) - Alt-text for <https://xkcd.com/3038/> now covered by unit tests (#377) - Upgraded python packages (#437, #497) Future-proofing releases ------------------------ - 🚀 `0.5.0-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.0/troubleshooting/#risk-too-high> and carefully consider how to handle this specific instance. - 🚀 `0.5.0-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.0-future-429`: release covering #429 - This commit deletes the `UnitAvoidance` construct. To fix build errors, instead of specializing `::au::detail::UnitAvoidance`, specialize `::au::UnitOrderTiebreaker`. - :rocket: `0.5.0-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.0/troubleshooting/#risk-too-high> to see how to handle this specific instance. 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-12-20..2025-08-20 Contributors ------------ Thanks to those who authored or reviewed PRs, or filed or participated in Issues! Alphabetically: - @andre-nguyen - @axelatharva - @catskul - @chiphogg - @djehuti - @drinkdhmo - @geoffviola - @hoffbrinkle - @justin-kottinger - @matthew-reynolds - @natecheadle - @pdaoust - @spayne-pgh - @StefanoD - @timhirsh [format docs]: https://aurora-opensource.github.io/au/0.5.0/reference/format/
0.5.0-future-481 This is a future proofing version of the 0.5.0 release, preparing the way to resolve #481 in the following release. 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.0/troubleshooting/#risk-too-high> to see how to handle this specific instance.
0.5.0-future-429 This is a future proofing version of the 0.5.0 release, preparing the way to resolve #429 in the following release. This commit deletes the `UnitAvoidance` construct. To fix build errors, instead of specializing `::au::detail::UnitAvoidance`, specialize `::au::UnitOrderTiebreaker`.
0.5.0-future-185 This is a future proofing version of the 0.5.0 release, preparing the way to resolve #185 in the following release. 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()`.
PreviousNext