Add support for US gallons, quarts, and pints (#308)

I ended up going for `US_gal` style symbols, rather than `USgal` style,
because I think it's more readable.

Fixes #307.

au/code/au/CMakeLists.txt

@@ -94,6 +94,9 @@ header_only_library(
     units/steradians.hh
     units/tesla.hh
     units/unos.hh
+    units/us_gallons.hh
+    units/us_pints.hh
+    units/us_quarts.hh
     units/volts.hh
     units/watts.hh
     units/webers.hh
@@ -261,6 +264,9 @@ gtest_based_test(
     units/test/steradians_test.cc
     units/test/tesla_test.cc
     units/test/unos_test.cc
+    units/test/us_gallons_test.cc
+    units/test/us_pints_test.cc
+    units/test/us_quarts_test.cc
     units/test/volts_test.cc
     units/test/watts_test.cc
     units/test/webers_test.cc

au/code/au/units/test/us_gallons_test.cc

@@ -0,0 +1,37 @@
+// Copyright 2024 Aurora Operations, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include "au/units/us_gallons.hh"
+
+#include "au/testing.hh"
+#include "au/units/inches.hh"
+#include "au/units/liters.hh"
+#include "gtest/gtest.h"
+
+namespace au {
+
+TEST(USGallons, HasExpectedLabel) { expect_label<USGallons>("US_gal"); }
+
+TEST(USGallons, EquivalentTo231CubicInches) { EXPECT_EQ(us_gallons(1), cubed(inches)(231)); }
+
+TEST(USGallons, WithinExpectationComparedToLiters) {
+    EXPECT_THAT(us_gallons(1), IsNear(liters(3.785), milli(liters)(1)));
+}
+
+TEST(USGallons, HasExpectedSymbol) {
+    using symbols::US_gal;
+    EXPECT_THAT(5 * US_gal, SameTypeAndValue(us_gallons(5)));
+}
+
+}  // namespace au

au/code/au/units/test/us_pints_test.cc

@@ -0,0 +1,32 @@
+// Copyright 2024 Aurora Operations, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include "au/units/us_pints.hh"
+
+#include "au/testing.hh"
+#include "au/units/us_gallons.hh"
+#include "gtest/gtest.h"
+
+namespace au {
+
+TEST(USPints, HasExpectedLabel) { expect_label<USPints>("US_pt"); }
+
+TEST(USPints, EightInAGallon) { EXPECT_EQ(us_pints(8), us_gallons(1)); }
+
+TEST(USPints, HasExpectedSymbol) {
+    using symbols::US_pt;
+    EXPECT_THAT(5 * US_pt, SameTypeAndValue(us_pints(5)));
+}
+
+}  // namespace au

au/code/au/units/test/us_quarts_test.cc

@@ -0,0 +1,32 @@
+// Copyright 2024 Aurora Operations, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include "au/units/us_quarts.hh"
+
+#include "au/testing.hh"
+#include "au/units/us_gallons.hh"
+#include "gtest/gtest.h"
+
+namespace au {
+
+TEST(USQuarts, HasExpectedLabel) { expect_label<USQuarts>("US_qt"); }
+
+TEST(USQuarts, FourInAGallon) { EXPECT_EQ(us_quarts(4), us_gallons(1)); }
+
+TEST(USQuarts, HasExpectedSymbol) {
+    using symbols::US_qt;
+    EXPECT_THAT(5 * US_qt, SameTypeAndValue(us_quarts(5)));
+}
+
+}  // namespace au

au/code/au/units/us_gallons.hh

@@ -0,0 +1,39 @@
+// Copyright 2024 Aurora Operations, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#pragma once
+
+#include "au/units/inches.hh"
+
+namespace au {
+
+// DO NOT follow this pattern to define your own units.  This is for library-defined units.
+// Instead, follow instructions at (https://aurora-opensource.github.io/au/main/howto/new-units/).
+template <typename T>
+struct USGallonsLabel {
+    static constexpr const char label[] = "US_gal";
+};
+template <typename T>
+constexpr const char USGallonsLabel<T>::label[];
+struct USGallons : decltype(cubed(Inches{}) * mag<231>()), USGallonsLabel<void> {
+    using USGallonsLabel<void>::label;
+};
+constexpr auto us_gallon = SingularNameFor<USGallons>{};
+constexpr auto us_gallons = QuantityMaker<USGallons>{};
+
+namespace symbols {
+constexpr auto US_gal = SymbolFor<USGallons>{};
+}
+
+}  // namespace au

au/code/au/units/us_pints.hh

@@ -0,0 +1,39 @@
+// Copyright 2024 Aurora Operations, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#pragma once
+
+#include "au/units/inches.hh"
+
+namespace au {
+
+// DO NOT follow this pattern to define your own units.  This is for library-defined units.
+// Instead, follow instructions at (https://aurora-opensource.github.io/au/main/howto/new-units/).
+template <typename T>
+struct USPintsLabel {
+    static constexpr const char label[] = "US_pt";
+};
+template <typename T>
+constexpr const char USPintsLabel<T>::label[];
+struct USPints : decltype(cubed(Inches{}) * (mag<231>() / mag<8>())), USPintsLabel<void> {
+    using USPintsLabel<void>::label;
+};
+constexpr auto us_pint = SingularNameFor<USPints>{};
+constexpr auto us_pints = QuantityMaker<USPints>{};
+
+namespace symbols {
+constexpr auto US_pt = SymbolFor<USPints>{};
+}
+
+}  // namespace au

au/code/au/units/us_quarts.hh

@@ -0,0 +1,39 @@
+// Copyright 2024 Aurora Operations, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#pragma once
+
+#include "au/units/inches.hh"
+
+namespace au {
+
+// DO NOT follow this pattern to define your own units.  This is for library-defined units.
+// Instead, follow instructions at (https://aurora-opensource.github.io/au/main/howto/new-units/).
+template <typename T>
+struct USQuartsLabel {
+    static constexpr const char label[] = "US_qt";
+};
+template <typename T>
+constexpr const char USQuartsLabel<T>::label[];
+struct USQuarts : decltype(cubed(Inches{}) * (mag<231>() / mag<4>())), USQuartsLabel<void> {
+    using USQuartsLabel<void>::label;
+};
+constexpr auto us_quart = SingularNameFor<USQuarts>{};
+constexpr auto us_quarts = QuantityMaker<USQuarts>{};
+
+namespace symbols {
+constexpr auto US_qt = SymbolFor<USQuarts>{};
+}
+
+}  // namespace au