From 6e65cecd2fe6963de272aa3d4e1387fda0f84727 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?joseLu=C3=ADs?= Date: Fri, 14 Feb 2025 18:34:06 +0100 Subject: [PATCH] update `num::geom::metric::angle` - rename `AngleDirection` variants: `CounterClockwise` to `Positive` and `Clockwise` to `Negative`. - add aliases from common jargons. - update docs. --- DOCS/CHANGELOG.md | 6 +++- src/num/geom/metric/angle/impl/float.rs | 12 +++---- src/num/geom/metric/angle/impl/int.rs | 22 ++++++------- src/num/geom/metric/angle/impl/test_int.rs | 22 ++++++------- src/num/geom/metric/angle/kind.rs | 4 +-- src/num/geom/metric/angle/mod.rs | 38 +++++++++++++++++----- 6 files changed, 65 insertions(+), 39 deletions(-) diff --git a/DOCS/CHANGELOG.md b/DOCS/CHANGELOG.md index 5bb134e0..c8357f90 100644 --- a/DOCS/CHANGELOG.md +++ b/DOCS/CHANGELOG.md @@ -9,7 +9,9 @@ - sys: `AppEnv`, `ExtLog` - ui: `MiniquadEventHandlerExt`, `UiService`. - work: `ExtProcess`. -- new consts: `FONT_3_3`, `FONT_3_5`, `FONT_5_6`. +- new consts: + - media::font: `FONT_3_3`, `FONT_3_5`, `FONT_5_6`. + - `AngleDirection::{CounterClockwise, CCW, RightHandRule, RHR, Clockwise, CW, LeftHandRule, LHR}` - new types: - code: `ScopeGuard`. - data: @@ -72,6 +74,8 @@ - `LoggerConfig` to `LogConfig`. - `TextWrite` trait to `FmtWrite`. - re-exports: `Layout` to `MemLayout`, `LayoutError` to `MemLayoutError`. +- rename variants: + - `AngleDirection`: `CounterClockwise` to `Positive`, `Clockwise` to `Negative`. - rename/move fns/methods: - from prngs: `next_state` method to `peek_next_state`. - `fmt_write`, `fmt_format` and `format_buf_args` to `Fmt::{write, format, format_buf`, respectively. diff --git a/src/num/geom/metric/angle/impl/float.rs b/src/num/geom/metric/angle/impl/float.rs index b42bcd5f..f54a198f 100644 --- a/src/num/geom/metric/angle/impl/float.rs +++ b/src/num/geom/metric/angle/impl/float.rs @@ -100,8 +100,8 @@ macro_rules! impl_angle { /// Since the floating-point representation always maintains the sign /// the direction can't be undefined. pub const fn direction(self) -> AngleDirection { - use AngleDirection::{Clockwise, CounterClockwise}; - if Float(self.turn).is_sign_negative() { Clockwise } else { CounterClockwise } + use AngleDirection::{Negative, Positive}; + if Float(self.turn).is_sign_negative() { Negative } else { Positive } } /// Returns `true` if the angle has the given `direction`. @@ -119,8 +119,8 @@ macro_rules! impl_angle { pub const fn with_direction(self, direction: AngleDirection) -> Self { use AngleDirection as D; match direction { - D::CounterClockwise | D::Undefined => Self::new(Float(self.turn).abs().0), - D::Clockwise => Self::new(Float(self.turn).neg_abs().0), + D::Positive | D::Undefined => Self::new(Float(self.turn).abs().0), + D::Negative => Self::new(Float(self.turn).neg_abs().0), } } @@ -130,8 +130,8 @@ macro_rules! impl_angle { pub const fn set_direction(&mut self, direction: AngleDirection) { use AngleDirection as D; match direction { - D::CounterClockwise | D::Undefined => self.turn = Float(self.turn).abs().0, - D::Clockwise => self.turn = Float(self.turn).neg_abs().0, + D::Positive | D::Undefined => self.turn = Float(self.turn).abs().0, + D::Negative => self.turn = Float(self.turn).neg_abs().0, } } diff --git a/src/num/geom/metric/angle/impl/int.rs b/src/num/geom/metric/angle/impl/int.rs index 8329a3b4..fc579028 100644 --- a/src/num/geom/metric/angle/impl/int.rs +++ b/src/num/geom/metric/angle/impl/int.rs @@ -206,9 +206,9 @@ macro_rules! impl_angle { if self.turn == 0 { D::Undefined } else if self.turn > 0 { - D::CounterClockwise + D::Positive } else { - D::Clockwise + D::Negative } } @@ -218,8 +218,8 @@ macro_rules! impl_angle { pub const fn with_direction(self, direction: AngleDirection) -> Self { use AngleDirection as D; match direction { - D::CounterClockwise | D::Undefined => Self::new(self.turn.saturating_abs()), - D::Clockwise => Self::new(-self.turn.saturating_abs()), + D::Positive | D::Undefined => Self::new(self.turn.saturating_abs()), + D::Negative => Self::new(-self.turn.saturating_abs()), } } @@ -229,8 +229,8 @@ macro_rules! impl_angle { pub fn set_direction(&mut self, direction: AngleDirection) { use AngleDirection as D; match direction { - D::CounterClockwise | D::Undefined => self.turn = self.turn.saturating_abs(), - D::Clockwise => self.turn = -self.turn.saturating_abs(), + D::Positive | D::Undefined => self.turn = self.turn.saturating_abs(), + D::Negative => self.turn = -self.turn.saturating_abs(), } } @@ -268,22 +268,22 @@ macro_rules! impl_angle { /// Returns the angle direction. /// - /// For unsigned integers the direction is always `CounterClockwise`. - pub const fn direction(self) -> AngleDirection { AngleDirection::CounterClockwise } + /// For unsigned integers the direction is always `Positive`. + pub const fn direction(self) -> AngleDirection { AngleDirection::Positive } /// Returns a version of the angle with the given `direction` (no-op for unsigned). /// - /// Unsigned integers can only have `CounterClockwise` direction. + /// Unsigned integers can only have `Positive` direction. pub const fn with_direction(self, _direction: AngleDirection) -> Self { self } /// Returns a version of the angle with the given `direction` (no-op for unsigned). /// - /// Unsigned integers can only have `CounterClockwise` direction. + /// Unsigned integers can only have `Positive` direction. pub const fn set_direction(self, _direction: AngleDirection) {} /// Returns a version of the angle with inverted direction (no-op for unsigned). /// - /// Unsigned integers can only have `CounterClockwise` direction. + /// Unsigned integers can only have `Positive` direction. pub const fn invert_direction(self) -> Self { self } /// Returns the negative version of the angle (no-op for unsigned). diff --git a/src/num/geom/metric/angle/impl/test_int.rs b/src/num/geom/metric/angle/impl/test_int.rs index 88844eb0..6f6c26c8 100644 --- a/src/num/geom/metric/angle/impl/test_int.rs +++ b/src/num/geom/metric/angle/impl/test_int.rs @@ -52,13 +52,13 @@ mod angle_i16 { #[test] fn signed_angle_direction() { let angle = Angle::new(-i16::MAX / 4); - assert_eq!(angle.direction(), AngleDirection::Clockwise); + assert_eq!(angle.direction(), AngleDirection::Negative); - let positive_angle = angle.with_direction(AngleDirection::CounterClockwise); - assert_eq!(positive_angle.direction(), AngleDirection::CounterClockwise); + let positive_angle = angle.with_direction(AngleDirection::Positive); + assert_eq!(positive_angle.direction(), AngleDirection::Positive); let inverted = positive_angle.invert_direction(); - assert_eq!(inverted.direction(), AngleDirection::Clockwise); + assert_eq!(inverted.direction(), AngleDirection::Negative); } /// Test conversion of angle to degrees using integer scaling. @@ -94,14 +94,14 @@ mod angle_i16 { #[test] fn angle_set_direction() { let mut angle = Angle::::new(-i16::MAX / 3); - assert_eq!(angle.direction(), AngleDirection::Clockwise); + assert_eq!(angle.direction(), AngleDirection::Negative); - angle.set_direction(AngleDirection::CounterClockwise); - assert_eq!(angle.direction(), AngleDirection::CounterClockwise); + angle.set_direction(AngleDirection::Positive); + assert_eq!(angle.direction(), AngleDirection::Positive); // Undefined should be treated as counterclockwise. angle.set_direction(AngleDirection::Undefined); - assert_eq!(angle.direction(), AngleDirection::CounterClockwise); + assert_eq!(angle.direction(), AngleDirection::Positive); } } @@ -124,10 +124,10 @@ mod angle_u16 { #[test] fn unsigned_angle_direction() { let unsigned_angle = Angle::::new(u16::MAX / 4); - assert_eq!(unsigned_angle.direction(), AngleDirection::CounterClockwise); + assert_eq!(unsigned_angle.direction(), AngleDirection::Positive); // Setting direction should have no effect. - let same_angle = unsigned_angle.with_direction(AngleDirection::Clockwise); - assert_eq!(same_angle.direction(), AngleDirection::CounterClockwise); + let same_angle = unsigned_angle.with_direction(AngleDirection::Negative); + assert_eq!(same_angle.direction(), AngleDirection::Positive); } } diff --git a/src/num/geom/metric/angle/kind.rs b/src/num/geom/metric/angle/kind.rs index d18459dd..6d2d2523 100644 --- a/src/num/geom/metric/angle/kind.rs +++ b/src/num/geom/metric/angle/kind.rs @@ -1,11 +1,11 @@ // devela::num::geom::metric::angle::kind // -//! Definitions related to angles. +//! Defines [`AngleKind`]. // use crate::{ExtFloatConst, Interval}; -/// The angle kind, based on its normalized magnitude. +/// The kind of [`Angle`], based on its normalized turn. /// /// The variant values are normalized to the full range of an u8. #[must_use] diff --git a/src/num/geom/metric/angle/mod.rs b/src/num/geom/metric/angle/mod.rs index 47968f47..585a44dc 100644 --- a/src/num/geom/metric/angle/mod.rs +++ b/src/num/geom/metric/angle/mod.rs @@ -69,6 +69,9 @@ pub use kind::AngleKind; /// - Kind: /// - [`kind`](Self::kind), *( /// [`is_`](Self::is_kind). )* +/// +/// This type does **not enforce normalization**, but it is expected +/// to be normalized in most use cases. #[must_use] #[repr(transparent)] pub struct Angle { @@ -83,7 +86,7 @@ impl Angle { } } -/// The angle direction. +/// The direction of rotation of an angle. /// /// In mathematics and most graphics programming contexts, the default direction /// for angle measurements is counterclockwise from a defined zero point (usually @@ -97,16 +100,35 @@ impl Angle { #[repr(i8)] #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)] pub enum AngleDirection { - /// By convention, positive angles represent a counterclockwise rotation. + /// By convention, **positive** angles represent a **counterclockwise** rotation. + /// + /// Also known as the Right-Handed Rule. /// - /// This is the default direction. + /// This is the default direction of rotation. #[default] - CounterClockwise = 1, + Positive = 1, - /// By convention, negative angles represent a counterclockwise rotation. - Clockwise = -1, + /// By convention, **negative** angles represent a **clockwise** rotation. + /// + /// Also known as the Left-Hand Rule. + Negative = -1, - /// An undefined direction can happen when a full turn angle is normalized - /// to an unsigned 0, like when using primitive signed integers. + /// An undefined direction can occur when a full-turn angle is normalized + /// to an unsigned `0`, such as when working with primitive signed integers. Undefined = 0, } + +#[allow(missing_docs, non_upper_case_globals)] +impl AngleDirection { + /// Alias of **positive** angle direction. + pub const CounterClockwise: AngleDirection = AngleDirection::Positive; + pub const CCW: AngleDirection = AngleDirection::Positive; + pub const RightHandRule: AngleDirection = AngleDirection::Positive; + pub const RHR: AngleDirection = AngleDirection::Positive; + + /// Alias of **negative** angle direction. + pub const Clockwise: AngleDirection = AngleDirection::Negative; + pub const CW: AngleDirection = AngleDirection::Negative; + pub const LeftHandRule: AngleDirection = AngleDirection::Positive; + pub const LHR: AngleDirection = AngleDirection::Positive; +}