diff --git a/docs/trigonometry/angle.md b/docs/trigonometry/angle.md index b4b4670..4100d37 100644 --- a/docs/trigonometry/angle.md +++ b/docs/trigonometry/angle.md @@ -3,8 +3,8 @@ > Header: `omath/trigonometry/angle.hpp` > Namespace: `omath` > Template: `Angle` -> Requires: `std::is_arithmetic_v` -> Formatters: `std::formatter` for `char`, `wchar_t`, `char8_t` → `"{}deg"` +> Requires: `std::is_floating_point_v` +> Formatters: `std::formatter` for `char` and `wchar_t` → `"{}deg"` --- @@ -14,7 +14,7 @@ Two behaviors via `AngleFlags`: -* `AngleFlags::Normalized` (default): values are wrapped into `[min, max]` using `angles::wrap_angle`. +* `AngleFlags::Normalized` (default): values are wrapped into `[min, max)` using `angles::wrap_angle`. * `AngleFlags::Clamped`: values are clamped to `[min, max]` using `std::clamp`. --- @@ -28,12 +28,16 @@ enum class AngleFlags { Normalized = 0, Clamped = 1 }; template -requires std::is_arithmetic_v +requires std::is_floating_point_v class Angle { public: // Construction static constexpr Angle from_degrees(const Type& deg) noexcept; static constexpr Angle from_radians(const Type& rad) noexcept; + static constexpr Angle from_asin(const Type& value) noexcept; + static constexpr Angle from_acos(const Type& value) noexcept; + static constexpr Angle from_atan(const Type& value) noexcept; + static constexpr Angle from_atan2(const Type& y, const Type& x) noexcept; constexpr Angle() noexcept; // 0 deg, adjusted by flags/range // Accessors / conversions (degrees stored internally) @@ -45,10 +49,9 @@ public: Type sin() const noexcept; Type cos() const noexcept; Type tan() const noexcept; - Type atan() const noexcept; // atan(as_radians()) (rarely used) Type cot() const noexcept; // cos()/sin() (watch sin≈0) - // Arithmetic (wraps or clamps per flags and [min,max]) + // Arithmetic (wraps or clamps per flags and configured range) constexpr Angle& operator+=(const Angle&) noexcept; constexpr Angle& operator-=(const Angle&) noexcept; constexpr Angle operator+(const Angle&) noexcept; @@ -68,7 +71,7 @@ public: std::format("{}", Angle::from_degrees(45)); // "45deg" ``` -Formatters exist for `char`, `wchar_t`, and `char8_t`. +Formatters exist for `char` and `wchar_t`. --- @@ -116,10 +119,9 @@ float deg = *yaw; // same as yaw.as_degrees() ## Semantics & notes * **Storage & units:** Internally stores **degrees** (`Type m_angle`). `as_radians()`/`from_radians()` use the project helpers in `omath::angles`. -* **Arithmetic honors policy:** `operator+=`/`-=` and the binary `+`/`-` apply **wrap** or **clamp** in `[min,max]`, mirroring construction behavior. -* **`atan()`**: returns `std::atan(as_radians())` (the arctangent of the *radian value*). This is mathematically unusual for an angle type and is rarely useful; prefer `tan()`/`atan2` in client code when solving geometry problems. +* **Arithmetic honors policy:** `operator+=`/`-=` and the binary `+`/`-` apply **wrap** or **clamp**, mirroring construction behavior. * **`cot()` / `tan()` singularities:** Near multiples where `sin() ≈ 0` or `cos() ≈ 0`, results blow up. Guard in your usage if inputs can approach these points. -* **Comparison:** `operator<=>` is defaulted. With normalization, distinct representatives can compare as expected (e.g., `-180` vs `180` in signed ranges are distinct endpoints). +* **Comparison:** `operator<=>` is defaulted. Normalization canonicalizes the maximum endpoint to the minimum endpoint. * **No implicit numeric conversion:** There’s **no `operator Type()`**. Use `as_degrees()`/`as_radians()` (or `*angle`) explicitly—this intentional friction avoids unit mistakes. --- diff --git a/docs/trigonometry/angles.md b/docs/trigonometry/angles.md index afef6cb..53f3aa8 100644 --- a/docs/trigonometry/angles.md +++ b/docs/trigonometry/angles.md @@ -4,7 +4,7 @@ > Namespace: `omath::angles` > All functions are `[[nodiscard]]` and `noexcept` where applicable. -A small set of constexpr-friendly utilities for converting between degrees/radians, converting horizontal/vertical field of view, and wrapping angles into a closed interval. +A small set of constexpr-friendly utilities for converting between degrees/radians, converting horizontal/vertical field of view, and wrapping angles into a half-open interval. --- @@ -29,9 +29,9 @@ template requires std::is_floating_point_v Type vertical_fov_to_horizontal(const Type& vertical_fov, const Type& aspect) noexcept; -// Wrap angle into [min, max] (any arithmetic type) +// Wrap angle into [min, max) (floating-point types) template -requires std::is_arithmetic_v +requires std::is_floating_point_v Type wrap_angle(const Type& angle, const Type& min, const Type& max) noexcept; ``` @@ -66,10 +66,10 @@ Formulas (in radians): ### Wrapping angles (or any periodic value) -Wrap any numeric `angle` into `[min, max]`: +Wrap any floating-point `angle` into `[min, max)`: ```cpp -// Wrap degrees into [0, 360] +// Wrap degrees into [0, 360) float a = omath::angles::wrap_angle( 370.0f, 0.0f, 360.0f); // 10 float b = omath::angles::wrap_angle( -15.0f, 0.0f, 360.0f); // 345 // Signed range [-180,180] @@ -83,10 +83,10 @@ float c = omath::angles::wrap_angle( 200.0f, -180.0f, 180.0f); // -160 * **Type requirements** * Converters & FOV helpers require **floating-point** `Type`. - * `wrap_angle` accepts any arithmetic `Type` (floats or integers). + * `wrap_angle` accepts floating-point types. * **Aspect ratio** must be **positive** and finite. For `aspect == 0` the FOV helpers are undefined. * **Units**: FOV functions accept/return **degrees** but compute internally in radians. -* **Wrapping interval**: Behavior assumes `max > min`. The result lies in the **closed interval** `[min, max]` with modulo arithmetic; if you need half-open behavior (e.g., `[min,max)`), adjust your range or post-process endpoint cases. +* **Wrapping interval**: Behavior assumes `max > min`. The result lies in the half-open interval `[min, max)`. * **constexpr**: Converters are `constexpr`; FOV helpers are runtime constexpr-compatible except for `std::atan/std::tan` constraints on some standard libraries. --- @@ -103,5 +103,5 @@ float v = horizontal_fov_to_vertical(90.0f, 16.0f/9.0f); float h = vertical_fov_to_horizontal(v, 16.0f/9.0f); assert(std::abs(h - 90.0f) < 1e-5f); -assert(wrap_angle(360.0f, 0.0f, 360.0f) == 0.0f || wrap_angle(360.0f, 0.0f, 360.0f) == 360.0f); +assert(wrap_angle(360.0f, 0.0f, 360.0f) == 0.0f); ``` diff --git a/include/omath/trigonometry/angle.hpp b/include/omath/trigonometry/angle.hpp index 22902b8..43d9f24 100644 --- a/include/omath/trigonometry/angle.hpp +++ b/include/omath/trigonometry/angle.hpp @@ -6,7 +6,9 @@ #include "omath/internal/constexpr_math.hpp" #include "omath/trigonometry/angles.hpp" #include +#include #include +#include #include namespace omath @@ -18,7 +20,7 @@ namespace omath }; template - requires std::is_arithmetic_v + requires std::is_floating_point_v class Angle { Type m_angle; @@ -43,7 +45,7 @@ namespace omath { return Angle{degrees}; } - constexpr Angle() noexcept: m_angle(0) + constexpr Angle() noexcept: Angle(Type{0}) { } [[nodiscard]] @@ -52,6 +54,30 @@ namespace omath return Angle{angles::radians_to_degrees(degrees)}; } + [[nodiscard]] + constexpr static Angle from_asin(const Type& value) noexcept + { + return from_radians(internal::asin(value)); + } + + [[nodiscard]] + constexpr static Angle from_acos(const Type& value) noexcept + { + return from_radians(internal::acos(value)); + } + + [[nodiscard]] + constexpr static Angle from_atan(const Type& value) noexcept + { + return from_radians(internal::atan(value)); + } + + [[nodiscard]] + constexpr static Angle from_atan2(const Type& y, const Type& x) noexcept + { + return from_radians(internal::atan2(y, x)); + } + [[nodiscard]] constexpr const Type& operator*() const noexcept { @@ -88,12 +114,6 @@ namespace omath return internal::tan(as_radians()); } - [[nodiscard]] - constexpr Type atan() const noexcept - { - return internal::atan(as_radians()); - } - [[nodiscard]] constexpr Type cot() const noexcept { @@ -121,7 +141,8 @@ namespace omath constexpr Angle& operator-=(const Angle& other) noexcept { - return operator+=(-other); + *this = Angle{m_angle - other.m_angle}; + return *this; } [[nodiscard]] @@ -142,7 +163,7 @@ namespace omath [[nodiscard]] constexpr Angle operator-(const Angle& other) const noexcept { - return operator+(-other); + return Angle{m_angle - other.m_angle}; } [[nodiscard]] @@ -172,7 +193,6 @@ struct std::formatter, char> final // NOLINT(*-dc return std::format_to(ctx.out(), "{}deg", a.as_degrees()); } }; - // wchar_t formatter template struct std::formatter, wchar_t> final // NOLINT(*-dcl58-cpp) @@ -193,24 +213,3 @@ struct std::formatter, wchar_t> final // NOLINT(* return std::format_to(ctx.out(), L"{}deg", a.as_degrees()); } }; - -// wchar_t formatter -template -struct std::formatter, char8_t> final // NOLINT(*-dcl58-cpp) -{ - using AngleT = omath::Angle; - - [[nodiscard]] - static constexpr auto parse(std::wformat_parse_context& ctx) - { - return ctx.begin(); - } - - template - [[nodiscard]] - auto format(const AngleT& a, FormatContext& ctx) const - { - static_assert(std::is_same_v); - return std::format_to(ctx.out(), u8"{}deg", a.as_degrees()); - } -}; diff --git a/include/omath/trigonometry/angles.hpp b/include/omath/trigonometry/angles.hpp index c88e421..61642ad 100644 --- a/include/omath/trigonometry/angles.hpp +++ b/include/omath/trigonometry/angles.hpp @@ -48,10 +48,10 @@ namespace omath::angles } template - requires std::is_arithmetic_v + requires std::is_floating_point_v [[nodiscard]] constexpr Type wrap_angle(const Type& angle, const Type& min, const Type& max) noexcept { - if (angle <= max && angle >= min) + if (angle < max && angle >= min) return angle; const Type range = max - min; diff --git a/tests/general/unit_test_angle.cpp b/tests/general/unit_test_angle.cpp index edbe361..240d989 100644 --- a/tests/general/unit_test_angle.cpp +++ b/tests/general/unit_test_angle.cpp @@ -14,9 +14,14 @@ namespace // Handy aliases (defaults: Type=float, [0,360], Normalized) using Deg = Angle(0), static_cast(360), AngleFlags::Normalized>; + using Fov = Angle(0), static_cast(180), AngleFlags::Clamped>; + using Offset = Angle(10), static_cast(20), AngleFlags::Clamped>; using Pitch = Angle(-90), static_cast(90), AngleFlags::Clamped>; using Turn = Angle(-180), static_cast(180), AngleFlags::Normalized>; + template + concept SupportedAngleType = requires { typename Angle; }; + constexpr float k_eps = 1e-5f; constexpr bool close_to(const float actual, const float expected, const float epsilon) @@ -36,6 +41,12 @@ TEST(UnitTestAngle, DefaultConstructor_IsZeroDegrees) EXPECT_FLOAT_EQ(a.as_degrees(), 0.0f); } +TEST(UnitTestAngle, DefaultConstructor_AppliesRangePolicy) +{ + constexpr Offset a; + EXPECT_FLOAT_EQ(a.as_degrees(), 10.0f); +} + TEST(UnitTestAngle, FromDegrees_Normalized_WrapsAboveMax) { const Deg a = Deg::from_degrees(370.0f); @@ -66,6 +77,14 @@ TEST(UnitTestAngle, FromRadians_And_AsRadians) EXPECT_NEAR(b.as_radians(), std::numbers::pi_v, 1e-6f); } +TEST(UnitTestAngle, FromInverseTrigonometricFunctions) +{ + EXPECT_NEAR(Pitch::from_asin(0.5f).as_degrees(), 30.0f, k_eps); + EXPECT_NEAR(Pitch::from_acos(0.5f).as_degrees(), 60.0f, k_eps); + EXPECT_NEAR(Pitch::from_atan(1.0f).as_degrees(), 45.0f, k_eps); + EXPECT_NEAR(Turn::from_atan2(-1.0f, -1.0f).as_degrees(), -135.0f, k_eps); +} + // ---------- Unary minus & deref ---------- TEST(UnitTestAngle, UnaryMinus_Normalized) @@ -101,17 +120,6 @@ TEST(UnitTestAngle, SinCosTanCot_BasicCases) EXPECT_NEAR(a90.cos(), 0.0f, 1e-4f); } -TEST(UnitTestAngle, Atan_IsAtanOfRadians) -{ - // atan(as_radians). For 0° -> atan(0)=0. - const Deg a0 = Deg::from_degrees(0.0f); - EXPECT_NEAR(a0.atan(), 0.0f, k_eps); - - const Deg a45 = Deg::from_degrees(45.0f); - // atan(pi/4) ≈ 0.665773... - EXPECT_NEAR(a45.atan(), 0.66577375f, 1e-6f); -} - // ---------- Compound arithmetic ---------- TEST(UnitTestAngle, PlusEquals_Normalized_Wraps) @@ -142,6 +150,16 @@ TEST(UnitTestAngle, MinusEquals_Clamped_Clamps) EXPECT_FLOAT_EQ(p.as_degrees(), -90.0f); } +TEST(UnitTestAngle, Subtraction_ClampedNonSymmetricRange) +{ + Fov compound = Fov::from_degrees(90.0f); + compound -= Fov::from_degrees(10.0f); + EXPECT_FLOAT_EQ(compound.as_degrees(), 80.0f); + + const Fov binary = Fov::from_degrees(90.0f) - Fov::from_degrees(10.0f); + EXPECT_FLOAT_EQ(binary.as_degrees(), 80.0f); +} + // ---------- Alternative ranges ---------- TEST(UnitTestAngle, NormalizedRange_Neg180To180) @@ -205,5 +223,12 @@ static_assert(close_to(Pitch::from_degrees(45.0f).tan(), 1.0f, 1e-4f), "Tan should be constexpr with embedded constexpr math"); static_assert(close_to(Pitch::from_degrees(45.0f).cot(), 1.0f, 1e-4f), "Cot should be constexpr with embedded constexpr math"); -static_assert(close_to(Pitch::from_degrees(45.0f).atan(), 0.66577375f, 1e-6f), - "Atan should be constexpr with embedded constexpr math"); +static_assert(close_to(Pitch::from_asin(0.5f).as_degrees(), 30.0f, k_eps), + "From asin should be constexpr with embedded constexpr math"); +static_assert(close_to(Pitch::from_acos(0.5f).as_degrees(), 60.0f, k_eps), + "From acos should be constexpr with embedded constexpr math"); +static_assert(close_to(Pitch::from_atan(1.0f).as_degrees(), 45.0f, k_eps), + "From atan should be constexpr with embedded constexpr math"); +static_assert(close_to(Turn::from_atan2(-1.0f, -1.0f).as_degrees(), -135.0f, k_eps), + "From atan2 should be constexpr with embedded constexpr math"); +static_assert(!SupportedAngleType, "Angle should only accept floating-point types"); diff --git a/tests/general/unit_test_angles.cpp b/tests/general/unit_test_angles.cpp index 42f8174..29180a8 100644 --- a/tests/general/unit_test_angles.cpp +++ b/tests/general/unit_test_angles.cpp @@ -46,4 +46,11 @@ TEST(unit_test_angles, wrap_angle_negative_range) const float wrapped = omath::angles::wrap_angle(-90.f, 0.f, 360.f); EXPECT_NEAR(wrapped, 270.f, 0.01f); -} \ No newline at end of file +} + +TEST(unit_test_angles, wrap_angle_maximum_maps_to_minimum) +{ + const float wrapped = omath::angles::wrap_angle(360.f, 0.f, 360.f); + + EXPECT_FLOAT_EQ(wrapped, 0.f); +}