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

0.2.0

Release Notes

User-facing library changes

• We've split the unit definitions into individual files. Going
  forward, include "au/units/slugs.hh" to get the unit slugs.
  This lowers the barrier for defining new units, and also enables
  performance-focused users to include only the units they need on a
  per-file basis.

• New .data_in(unit) member for Quantity and QuantityPoint gives
  direct (reference) access to the underlying numeric value. You still
  need to name the unit at the callsite, though!

New units

• candelas
• katals
• lumens
• moles
• slugs
• steradians

Tooling/Doc changes

• Added support for GCC 10.

• Added (barebones) documentation website, and au-docs-serve tool to
  generate and serve website locally.

• Added make-single-file script to package the library as a single
  file. We automatically generate two "basic" versions when we generate
  the documentation website.

• Linked to CppCon talk in README.

Contributors

Thanks to those who authored or reviewed PRs! Alphabetically:

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

0.1.0

Release Notes

This is the initial version of the library ported from Aurora's AV repo.