Add forward declarations for individual units (#314)

Individual `"au/units/*.hh"` files still pull in some decently heavy
machinery.  The sensible, scalable solution is to provide a
`"au/units/*_fwd.hh"` file corresponding to each of them.  Each
"regular" units header will include its `_fwd.hh` header as the first
include (and we add a comment to that effect to prevent clang-format
from reordering them).

Happily, this enables us to write a somewhat meaningful test for the
forward declaraction machinery.  We can now make a header file that
provides an interface with only the forward declarations.  Then we call
that API inside of a test file.

Finally, this is worth updating the docs for:

- **Installation:** mention the `fwd.hh` files.
- **Alternatives:** mention this feature, as we're the first units
  library I know of that provides it.

All of these changes are in separate commits for the convenience of the
reviewer: I recommend starting at the first, and using `n` and `p` to
navigate them.

Fixes #232.

au/BUILD.bazel

@@ -47,6 +47,23 @@ cc_library(
     visibility = ["//visibility:public"],
 )
 
+cc_test(
+    name = "fwd_test",
+    size = "small",
+    srcs = [
+        "code/au/fwd_test.cc",
+        "code/au/fwd_test_lib.cc",
+        "code/au/fwd_test_lib.hh",
+    ],
+    deps = [
+        ":fwd",
+        ":io",
+        ":quantity",
+        ":units",
+        "@com_google_googletest//:gtest_main",
+    ],
+)
+
 cc_library(
     name = "io",
     hdrs = ["code/au/io.hh"],

au/code/au/CMakeLists.txt

@@ -48,60 +48,115 @@ header_only_library(
     stdx/type_traits.hh
     stdx/utility.hh
     units/amperes.hh
+    units/amperes_fwd.hh
     units/bars.hh
+    units/bars_fwd.hh
     units/becquerel.hh
+    units/becquerel_fwd.hh
     units/bits.hh
+    units/bits_fwd.hh
     units/bytes.hh
+    units/bytes_fwd.hh
     units/candelas.hh
+    units/candelas_fwd.hh
     units/celsius.hh
+    units/celsius_fwd.hh
     units/coulombs.hh
+    units/coulombs_fwd.hh
     units/days.hh
+    units/days_fwd.hh
     units/degrees.hh
+    units/degrees_fwd.hh
     units/fahrenheit.hh
+    units/fahrenheit_fwd.hh
     units/farads.hh
+    units/farads_fwd.hh
     units/fathoms.hh
+    units/fathoms_fwd.hh
     units/feet.hh
+    units/feet_fwd.hh
     units/furlongs.hh
+    units/furlongs_fwd.hh
     units/grams.hh
+    units/grams_fwd.hh
     units/grays.hh
+    units/grays_fwd.hh
     units/henries.hh
+    units/henries_fwd.hh
     units/hertz.hh
+    units/hertz_fwd.hh
     units/hours.hh
+    units/hours_fwd.hh
     units/inches.hh
+    units/inches_fwd.hh
     units/joules.hh
+    units/joules_fwd.hh
     units/katals.hh
+    units/katals_fwd.hh
     units/kelvins.hh
+    units/kelvins_fwd.hh
     units/knots.hh
+    units/knots_fwd.hh
     units/liters.hh
+    units/liters_fwd.hh
     units/lumens.hh
+    units/lumens_fwd.hh
     units/lux.hh
+    units/lux_fwd.hh
     units/meters.hh
+    units/meters_fwd.hh
     units/miles.hh
+    units/miles_fwd.hh
     units/minutes.hh
+    units/minutes_fwd.hh
     units/moles.hh
+    units/moles_fwd.hh
     units/nautical_miles.hh
+    units/nautical_miles_fwd.hh
     units/newtons.hh
+    units/newtons_fwd.hh
     units/ohms.hh
+    units/ohms_fwd.hh
     units/pascals.hh
+    units/pascals_fwd.hh
     units/percent.hh
+    units/percent_fwd.hh
     units/pounds_force.hh
+    units/pounds_force_fwd.hh
     units/pounds_mass.hh
+    units/pounds_mass_fwd.hh
     units/radians.hh
+    units/radians_fwd.hh
     units/revolutions.hh
+    units/revolutions_fwd.hh
     units/seconds.hh
+    units/seconds_fwd.hh
     units/siemens.hh
+    units/siemens_fwd.hh
     units/slugs.hh
+    units/slugs_fwd.hh
     units/standard_gravity.hh
+    units/standard_gravity_fwd.hh
     units/steradians.hh
+    units/steradians_fwd.hh
     units/tesla.hh
+    units/tesla_fwd.hh
     units/unos.hh
+    units/unos_fwd.hh
     units/us_gallons.hh
+    units/us_gallons_fwd.hh
     units/us_pints.hh
+    units/us_pints_fwd.hh
     units/us_quarts.hh
+    units/us_quarts_fwd.hh
     units/volts.hh
+    units/volts_fwd.hh
     units/watts.hh
+    units/watts_fwd.hh
     units/webers.hh
+    units/webers_fwd.hh
     units/yards.hh
+    units/yards_fwd.hh
     utility/factoring.hh
     utility/string_constant.hh
     utility/type_traits.hh

au/code/au/fwd_test.cc

@@ -0,0 +1,29 @@
+// 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/fwd_test_lib.hh"
+#include "au/quantity.hh"
+#include "au/units/meters.hh"
+#include "gmock/gmock.h"
+#include "gtest/gtest.h"
+
+using ::testing::StrEq;
+
+namespace au {
+
+TEST(Fwd, CanCallFunctionDeclaredWithOnlyFwdFiles) {
+    EXPECT_THAT(print_to_string(meters(1)), StrEq("1 m"));
+}
+
+}  // namespace au

au/code/au/fwd_test_lib.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/fwd_test_lib.hh"
+
+#include <sstream>
+#include <string>
+
+#include "au/io.hh"
+#include "au/quantity.hh"
+#include "au/units/meters.hh"
+
+namespace au {
+
+std::string print_to_string(const QuantityI<Meters> &q) {
+    std::ostringstream oss;
+    oss << q;
+    return oss.str();
+}
+
+}  // namespace au

au/code/au/fwd_test_lib.hh

@@ -0,0 +1,26 @@
+// 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 <string>
+
+#include "au/fwd.hh"
+#include "au/units/meters_fwd.hh"
+
+namespace au {
+
+std::string print_to_string(const QuantityI<Meters> &q);
+
+}  // namespace au

au/code/au/units/amperes.hh

@@ -14,6 +14,9 @@
 
 #pragma once
 
+#include "au/units/amperes_fwd.hh"
+// Keep corresponding `_fwd.hh` file on top.
+
 #include "au/quantity.hh"
 #include "au/unit_symbol.hh"
 

au/code/au/units/amperes_fwd.hh

@@ -0,0 +1,21 @@
+// 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
+
+namespace au {
+
+struct Amperes;
+
+}  // namespace au

au/code/au/units/bars.hh

@@ -14,6 +14,9 @@
 
 #pragma once
 
+#include "au/units/bars_fwd.hh"
+// Keep corresponding `_fwd.hh` file on top.
+
 #include "au/prefix.hh"
 #include "au/quantity.hh"
 #include "au/unit_symbol.hh"

au/code/au/units/bars_fwd.hh

@@ -0,0 +1,21 @@
+// 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
+
+namespace au {
+
+struct Bars;
+
+}  // namespace au

au/code/au/units/becquerel.hh

@@ -14,6 +14,9 @@
 
 #pragma once
 
+#include "au/units/becquerel_fwd.hh"
+// Keep corresponding `_fwd.hh` file on top.
+
 #include "au/quantity.hh"
 #include "au/unit_symbol.hh"
 #include "au/units/seconds.hh"

au/code/au/units/becquerel_fwd.hh

@@ -0,0 +1,21 @@
+// 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
+
+namespace au {
+
+struct Becquerel;
+
+}  // namespace au

au/code/au/units/bits.hh

@@ -14,6 +14,9 @@
 
 #pragma once
 
+#include "au/units/bits_fwd.hh"
+// Keep corresponding `_fwd.hh` file on top.
+
 #include "au/quantity.hh"
 #include "au/unit_symbol.hh"
 

au/code/au/units/bits_fwd.hh

@@ -0,0 +1,21 @@
+// 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
+
+namespace au {
+
+struct Bits;
+
+}  // namespace au

au/code/au/units/bytes.hh

@@ -14,6 +14,9 @@
 
 #pragma once
 
+#include "au/units/bytes_fwd.hh"
+// Keep corresponding `_fwd.hh` file on top.
+
 #include "au/quantity.hh"
 #include "au/unit_symbol.hh"
 #include "au/units/bits.hh"

au/code/au/units/bytes_fwd.hh

@@ -0,0 +1,21 @@
+// 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
+
+namespace au {
+
+struct Bytes;
+
+}  // namespace au

au/code/au/units/candelas.hh

@@ -14,6 +14,9 @@
 
 #pragma once
 
+#include "au/units/candelas_fwd.hh"
+// Keep corresponding `_fwd.hh` file on top.
+
 #include "au/quantity.hh"
 #include "au/unit_symbol.hh"